legesher-mcp
The Legesher Model Context Protocol server:
the engine's translation capability inside every MCP-capable client — Claude,
IDE assistants, agent frameworks — as six coarse, task-shaped tools.
Using the MCP server is free forever (Apache-2.0). The local server runs
entirely against the locally installed Legesher engine: it needs no account,
and every tool call is served locally. Optional usage telemetry is planned
and will be off unless you turn it on; the Privacy section below says
exactly what it would send. Some capabilities require a Legesher account on
the hosted instance. What the server does is defined by this open package
and nothing else.
Tools
Notes on shape, straight from the design:
- Translation X→Y pivots through English (packs are authored against
English). The engine has no direct X→Y path; when the pivot is taken the
result says so via
pivoted: true rather than failing.
- Validation is static only —
compile(), never exec() — submitted
code is parsed, never executed.
- Error results carry a machine code (
unsupported_language,
language_pack_not_found, invalid_source) and a generic message: no
stack traces, no filesystem paths, no echoed source.
Resources
Prompts
explain-in — scaffolds "explain the selected code in {language}",
steering the model to explain_in_language first and keeping engine facts
distinct from narration.translate-review — walks a source/translated pair: translate, validate,
then summarize what changed and what did not map.legibility-report — drives map_existing_codebase over pasted files and
renders the coverage report as a stakeholder-readable summary.
Install
The server needs the Legesher engine. Every language pack ships inside
legesher-i18n, so nothing else is installed:
Inside the monorepo workspace every shipped pack is already installed:
The server is quiet by default (log level WARNING). For troubleshooting,
set LEGESHER_MCP_LOG_LEVEL (DEBUG, INFO, WARNING, ERROR,
CRITICAL); unrecognized values fall back to the quiet default. GUI
clients do not run your shell, so the variable has to go in the client's
own config — every block below shows where.
Client configuration
Claude Desktop
claude_desktop_config.json (Settings → Developer → Edit Config):
Claude Code
Cursor
.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):
VS Code
.vscode/mcp.json (workspace) or the user-level mcp.json (Command
Palette: MCP: Open User Configuration):
Zed
settings.json → context_servers:
The env block is optional in every case — drop it to keep the quiet
default.
Serving over HTTP (self-host / single-user)
stdio is the default and what every client config above spawns. The same
server also speaks the MCP streamable HTTP transport, for running it as a
long-lived local service or on a machine you control:
The posture, deliberately:
- Loopback by default, never a wildcard.
--host defaults to
127.0.0.1, and wildcard binds (0.0.0.0, ::) are refused: this
entry ships no authentication, so it binds exactly one interface
you name. To serve beyond a machine you trust end to end, put your own
auth in front (below).
- Stateless, plain JSON. Every request is self-contained — no
server-held session — and responses are
application/json, not SSE.
Origin validated when present. A browser page from another
origin (the DNS-rebinding vector) is rejected with 403; the allowlist
derives from the bound interface. MCP clients that send no Origin
header are unaffected.
Embedding instead of running: legesher_mcp.server.create_server() builds
the complete server from a Backend and an entitlement gate, and
create_http_app() returns it as an ASGI app to mount behind your own
middleware (TLS, auth, request context for the gate — see
legesher_mcp.gate.request_context). The gate is default-open: no
deployment code here installs one, gated tools always stay listed, and an
unentitled call answers with an actionable message rather than an opaque
failure. validate_identifier_translations is permanently free by
construction.
Making agent sessions stay localized
The server is the deterministic half; two shipped artifacts carry the
policy and playbook half for agent sessions:
templates/AGENTS-template.md — the language-policy declaration.
Copy it into a repository root as AGENTS.md, fill in the declared
language, and every AGENTS.md-reading agent (Codex, Cursor, Claude
Code, Antigravity, Windsurf) picks up the same eight rules: write
natively, never hand-translate keywords, one-concept-one-term naming
via the project glossary, and the byte-identical round-trip guarantee.
The file is the declaration; long sessions evict rules files from
context, which is exactly why the deterministic tools — not the file —
are the guarantee.skills/legesher-localized-code/ — the stable-knowledge skill
(Agent Skills format: portable across Claude
Code, Claude apps, and the API). It teaches the mental model
(run form ↔ native, deterministic vs fuzzy layers), which tool to call
when, the write → round-trip → validate workflow, and the naming
discipline. Claude Code: copy the directory into your project's
.claude/skills/. Skills carry the stable playbook; the MCP server
stays the live surface — that split is deliberate.
Privacy
- No telemetry in this version. The server sends nothing. A coming
release adds an optional usage report so the maintainers can see which
tools are used and how often; earlier versions of this README promised
that the server would never emit telemetry, and that promise is
withdrawn. When the report ships:
- It is off by default. Nothing is sent unless you set
LEGESHER_MCP_TELEMETRY=on in the server's environment (the env
block or --env flag of your client config, as in the examples
above).
DO_NOT_TRACK=1 or LEGESHER_TELEMETRY_DISABLED=1 always wins and
overrides every other setting.- It sends only: tool name, call count, error class, server and engine
versions, and a random install id (kept per install so repeated
reports count once; not derived from your machine, account or code).
Never source code, file contents, identifiers, translated text,
prompts, file paths, or anything that identifies you personally.
- It runs off the request path: a tool call never waits on it or fails
because of it, and a report that cannot be delivered is dropped.
- It never touches the MCP stdio stream.
- No network on a tool call. Every tool call is served by the local
engine. The usage report above, once it ships and only if you enable
it, is the only outbound traffic this package is designed to initiate.
- Your code is not stored. Submitted source is processed in memory; file paths
passed to
map_existing_codebase are report labels — echoed back to you,
never logged, never used to touch the filesystem. This is why
validate_identifier_translations takes your glossary as content and
hands back the accepted entries rather than saving them: recording is
yours to do, whether that is .legesher/identifier_map.json in your repo
or the legesher CLI, which already maintains that file. A durable
glossary that outlives the session and is shared across repos and
teammates is a system of record, and belongs behind the hosted API — not
in a local subprocess.
- Declared, not just claimed. All six tools carry MCP annotations
saying so:
readOnlyHint: true, idempotentHint: true,
destructiveHint: false, openWorldHint: false. Clients that read the
hints (Claude Code among them) can reduce or skip approval prompts,
because no tool call writes a file, executes submitted code (validation
is compile() only), or opens a socket. A surface-lock test asserts the
annotations, so a future tool that does any of those has to change them
deliberately.
Development
Two test tiers. The default run exercises every tool through a real MCP
client session and stays fast. The scheduled tier is excluded from it and
run before a release:
-
All-packs round-trip sweep — the byte-identical guarantee across every
installed pack and the whole construct corpus (the per-commit run samples
three packs). Known engine/pack failures are listed as strict xfails in
tests/test_roundtrip_sweep.py, so a fix announces itself.
-
Clean-environment spawn — builds the wheels, installs them into a
fresh virtualenv in an empty directory, and drives a stdio session with a
stripped environment. It is the only test that exercises the artifact the
way a host actually starts it: outside the workspace, with no
PYTHONPATH and no repo checkout.
It gates the release. release-mcp.yml runs make test-mcp-scheduled
before the version step, so a failure means no version bump, no tag, and
no GitHub release — nothing to un-publish. Run it locally with
make test-mcp-scheduled before you expect a release to go out.
Scope, so the guarantee isn't overread: it gates cutting a version. The
push to a package index is the mcp target of publish-pypi.yml, which is
dispatch-only and runs after foundation has reached the same index
(CORE-626).
Versioning
legesher-mcp releases on its own train, independent of the foundation
suite: tags are mcp-v{version}, cut by release-mcp.yml when something
under libs/mcp/ lands on main. The version in pyproject.toml is the
single source — __version__ reads it back through importlib.metadata, so
the initialize handshake cannot report a number the wheel does not have.
Pre-1.0, a breaking change bumps the minor (0.1.0 → 0.2.0);
major_on_zero is off, so reaching 1.0.0 is a deliberate decision rather
than a side effect of one commit.
Listings
server.json is the manifest the official MCP registry reads, and the
mcp-name comment at the top of this README is how that registry confirms
the PyPI package belongs to the listing. docs/registry-listings.md holds
the canonical listing copy and what each directory reads, so every listing
says the same thing. tests/test_registry_manifest.py pins the manifest to
this package's name, version and environment variables.
License
Apache-2.0. See LICENSE.
