Legesher

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:

# The server (pulls legesher-core and legesher-i18n, packs included)

uvx legesher-mcp

Inside the monorepo workspace every shipped pack is already installed:

uv run legesher-mcp

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):

{

"mcpServers": { "legesher": { "command": "uvx", "args": ["legesher-mcp"], "env": { "LEGESHER_MCP_LOG_LEVEL": "DEBUG" } } } }

Claude Code

claude mcp add legesher -- uvx legesher-mcp

with troubleshooting logs

claude mcp add legesher --env LEGESHER_MCP_LOG_LEVEL=DEBUG -- uvx legesher-mcp

Cursor

.cursor/mcp.json (project) or ~/.cursor/mcp.json (global):

{

"mcpServers": { "legesher": { "command": "uvx", "args": ["legesher-mcp"], "env": { "LEGESHER_MCP_LOG_LEVEL": "DEBUG" } } } }

VS Code

.vscode/mcp.json (workspace) or the user-level mcp.json (Command Palette: *MCP: Open User Configuration*):

{

"servers": { "legesher": { "type": "stdio", "command": "uvx", "args": ["legesher-mcp"], "env": { "LEGESHER_MCP_LOG_LEVEL": "DEBUG" } } } }

Zed

settings.json → context_servers:

{

"context_servers": { "legesher": { "command": { "path": "uvx", "args": ["legesher-mcp"], "env": { "LEGESHER_MCP_LOG_LEVEL": "DEBUG" } } } } }

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:

legesher-mcp --transport streamable-http                # 127.0.0.1:8000/mcp

legesher-mcp --transport streamable-http --port 9000 legesher-mcp --transport streamable-http --host 192.0.2.7

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

cd libs/mcp

uv run pytest # the per-commit suite (every tool, through MCP) uv run pytest -m scheduled # release-tier: all-packs sweep + wheel spawn uv run ruff check . # lint uv run mypy legesher_mcp # types

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.
• **Cle