Legesher

legesher-mcp

Legesher 模型上下文协议 服务： 将引擎的翻译能力带入每个支持 MCP 的客户端——Claude、 IDE 助手、Agent 框架——并以六种面向任务的粗粒度工具提供。

使用 MCP 服务永远免费（Apache-2.0）。 本地服务完全依托本地安装的 Legesher 引擎运行：无需账户， 每次工具调用都在本地处理。我们计划加入可选的使用情况遥测，默认关闭；下方的“隐私”部分会 准确说明它将发送哪些信息。部分功能需要在托管实例上使用 Legesher 账户。服务的行为由这个开源软件包定义， 除此之外别无其他。

工具

工具	功能
translate_to_native	将 Python 源代码翻译成你的母语。完整文件和代码片段均可接受，无需单独的片段模式。
translate_to_source	将母语代码翻译回使用英语关键字的 Python——这是解释器、工具链和上游协作者使用的形式。
explain_in_language	返回助手用你的语言解释代码所需的引擎事实：逐个结构的关键字映射、静态验证结果，以及（可选）翻译后的源代码。由模型撰写说明文字；工具本身不会撰写。
lookup_keyword_mapping	快速参考查询：查看特定术语（或完整映射）在某种语言中的呈现方式。
map_existing_codebase	可读性报告：给定一组文件，展示将此代码库翻译成某种语言的效果——按文件统计覆盖情况、未映射结构，并可选择返回翻译后的文件。
validate_identifier_translations	在记录建议的标识符翻译前进行检查：格式错误的标识符、不安全文本、语言包预留名称、术语不一致（一个概念对应两个术语）和冲突（两个概念对应一个术语）——同时检查现有术语表和本批次的其他条目。比较采用 NFKC+casefold，因此大小写变体和分解形式会视为同一术语。返回无冲突的子集，已规范化为 NFC，可直接记录。

设计说明：

• X→Y 翻译会经由英语中转（语言包以英语为基准编写）。引擎不支持直接的 X→Y 路径；采用中转时，结果会通过 pivoted: true 说明，而不会报错。
• 验证仅为静态验证——调用 compile()，绝不调用 exec()——提交的代码只会被解析，不会执行。
• 错误结果包含机器代码（unsupported_language、 language_pack_not_found、invalid_source）和通用消息：不会包含堆栈跟踪、文件系统路径或回显的源代码。

资源

URI	内容
legesher://languages	包含语言包可用情况的语言目录。
legesher://languages/{lang}/terms	某种语言的完整术语字典（关键字、内置项、异常、保留字），使用默认 Python 版本。
legesher://languages/{lang}/terms/{python_version}	固定到某个 Python 版本的同一字典，供使用非默认语法的调用方使用。

提示词

• explain-in — 为“用 {language} 解释选中的代码”提供框架， 引导模型优先调用 explain_in_language，并将引擎事实与讲解内容 区分开来。
• translate-review — 逐步处理源代码与译文：先翻译、再验证， 然后总结变更内容及未能映射的部分。
• legibility-report — 驱动 map_existing_codebase 处理粘贴的文件， 并将覆盖情况报告整理成便于利益相关者阅读的摘要。

安装

该服务端需要 Legesher 引擎。每个语言包都随 legesher-i18n 一同提供，因此无需安装其他内容：

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

在 monorepo 工作区中，所有随附的语言包都已安装：

uv run legesher-mcp

该服务端默认保持安静（日志级别为 WARNING）。如需排查问题， 请设置 LEGESHER_MCP_LOG_LEVEL（DEBUG、INFO、WARNING、ERROR、 CRITICAL）；无法识别的值会回退到安静的默认设置。GUI 客户端不会运行你的 shell，因此必须在客户端自己的配置中设置该变量——下面的每个配置块都展示了设置位置。

客户端配置

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（项目级）或 ~/.cursor/mcp.json（全局）：

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

VS Code

.vscode/mcp.json（工作区级）或用户级 mcp.json（命令面板：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" }
      }
    }
  }
}

所有情况下，env 块都是可选的——删除它即可保持安静的默认设置。

通过 HTTP 提供服务（自托管／单用户）

stdio 是默认传输方式，也是上述所有客户端配置启动服务端时使用的方式。同一服务端也支持 MCP 可流式 HTTP 传输，可将其作为长期运行的本地服务，或部署在你控制的机器上：

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

其安全策略如下：

• 默认绑定回环地址，绝不绑定通配地址。 --host 默认值为 127.0.0.1，并且不允许通配地址绑定（0.0.0.0、::）：此条目不提供身份验证，因此只会绑定到你指定的一个接口。若要在完全信任的机器之外提供服务，请在前面配置你自己的身份验证（见下文）。
• 无状态，使用纯 JSON。 每个请求都是独立完整的——服务端不保存会话——响应为 application/json，而非 SSE。
• 存在 Origin 时进行验证。 来自其他源的浏览器页面（DNS 重绑定攻击途径）会被拒绝并返回 403；允许列表根据绑定的接口生成。未发送 Origin 标头的 MCP 客户端不受影响。

如需嵌入而非运行：legesher_mcp.server.create_server() 会根据 Backend 和授权门构建完整服务端，create_http_app() 会将其作为 ASGI 应用返回，以便挂载在你自己的中间件之后（TLS、身份验证、供授权门使用的请求上下文——参见 legesher_mcp.gate.request_context）。授权门采用默认放行策略：此处没有部署代码会安装授权门；受限工具始终会列出；未获授权的调用会返回可执行的提示信息，而不是含糊的失败。validate_identifier_translations 从设计上就是永久免费的。

让 Agent 会话保持本地化

该服务端负责确定性部分；两个随附的构件则为 Agent 会话提供策略和操作指南：

• templates/AGENTS-template.md——语言策略声明。 将其复制到代码库根目录并命名为 AGENTS.md，填写所声明的语言；所有读取 AGENTS.md 的 Agent（Codex、Cursor、Claude Code、Antigravity、Windsurf）都会采用相同的八条规则：以母语写作，绝不手动翻译关键字，通过项目术语表实行一概念一术语命名，以及保证往返转换后的字节完全相同。 该文件是声明；长时间会话会将规则文件从上下文中移除，而这正是确定性工具——而非文件——成为保障的原因。
• skills/legesher-localized-code/——稳定知识技能 （Agent Skills 格式：可在 Claude Code、Claude apps 和 API 之间移植）。它讲解思维模型（运行形式 ↔ 母语、确定性层与模糊层）、何时调用哪个工具、编写 → 往返转换 → 验证的工作流，以及命名规范。Claude Code 用户：将该目录复制到项目的 .claude/skills/。技能承载稳定的操作指南；MCP 服务保持为实时操作界面——这种分工是有意为之。

隐私

• 此版本不包含遥测功能。 服务不会发送任何内容。即将发布的版本将新增可选使用情况报告，以便维护者了解哪些工具被使用以及使用频率；本 README 的早期版本曾承诺服务绝不会发送遥测数据，现在这一承诺已撤回。报告发布后：
  • 默认关闭。除非在服务的环境中设置 LEGESHER_MCP_TELEMETRY=on（如上方示例所示，在客户端配置的 env 块或 --env 标志中设置），否则不会发送任何内容。
  • DO_NOT_TRACK=1 或 LEGESHER_TELEMETRY_DISABLED=1 始终优先，并会覆盖其他所有设置。
  • 报告仅发送：工具名称、调用次数、错误类别、服务和引擎版本，以及随机安装 ID（每次安装保留一个，因此重复报告只计一次；不会根据你的设备、账户或代码生成）。绝不会发送源代码、文件内容、标识符、翻译文本、提示词、文件路径或任何可识别你个人身份的信息。
  • 报告在请求处理路径之外运行：工具调用绝不会等待报告，也不会因报告而失败；无法送达的报告会被丢弃。
  • 报告绝不会触及 MCP stdio 流。
• 工具调用不会访问网络。 每次工具调用都由本地引擎处理。上文提及的使用情况报告一旦发布，且仅在你启用后，才是此程序包设计为主动发起的唯一出站流量。
• 你的代码不会被存储。 提交的源代码仅在内存中处理；传递给 map_existing_codebase 的文件路径只是报告标签——会原样返回给你，不会记录，也不会用于访问文件系统。因此，validate_identifier_translations 会将你的词汇表作为内容接收，并返回已接受的条目，而不是将其保存下来：记录工作由你负责，可以保存到仓库中的 .legesher/identifier_map.json，也可以使用 legesher CLI，该命令行工具已经会维护此文件。能够跨会话保留，并在不同仓库和团队成员之间共享的持久词汇表属于权威记录系统，应由托管 API 提供，而不是放在本地子进程中。
• 有声明，不只是口头承诺。 六个工具都带有表明这一点的 MCP 注解：readOnlyHint: true、idempotentHint: true、destructiveHint: false、openWorldHint: false。能够读取这些提示的客户端（包括 Claude Code）可以减少或跳过审批提示，因为工具调用不会写入文件、执行提交的代码（验证仅使用 compile()），也不会打开套接字。表面锁定测试会断言这些注解，因此未来如果有工具会执行上述任一操作，就必须有意识地修改这些注解。

开发

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

有两个测试层级。默认运行会通过真实的 MCP 客户端会话测试每个工具，并且速度很快。scheduled 层级不包含在默认运行中，而是在发布前运行：

• 所有程序包往返扫描——验证每个已安装程序包和整个构造语料库的字节完全一致保证（每次提交运行只抽样三个程序包）。已知的引擎／程序包故障会在 tests/test_roundtrip_sweep.py 中列为严格 xfail，因此修复会自动显示出来。

• 干净环境启动测试——构建 wheel，将其安装到空目录中的全新虚拟环境，并在精简后的环境变量下运行 stdio 会话。这是唯一一个以宿主实际启动方式测试构建产物的测试：在工作区之外运行，不设置 PYTHONPATH，也不检出仓库。

  此测试决定能否发布。 release-mcp.yml 会在版本步骤之前运行 make test-mcp-scheduled，因此测试失败就意味着不会提升版本号、不会打标签，也不会发布 GitHub 版本——无需撤回任何发布内容。预计发布前，请在本地运行 make test-mcp-scheduled。

  范围说明，避免对保证范围产生误解：此测试决定的是是否切出一个版本。推送到程序包索引由 publish-pypi.yml 中的 mcp 目标负责，该目标只能通过手动触发运行，并且会在 foundation 已发布到同一索引后运行（CORE-626）。

版本管理

legesher-mcp 按自己的发布节奏发布，独立于基础套件：标签格式为 mcp-v{version}，当 libs/mcp/ 下的内容合并到 main 时，由 release-mcp.yml 创建。pyproject.toml 中的版本号是唯一数据源——__version__ 通过 importlib.metadata 读取该版本号，因此 initialize 握手不会报告 wheel 中不存在的版本号。

在 1.0 之前，破坏性变更会提升次版本号（0.1.0 → 0.2.0）；major_on_zero 处于关闭状态，因此达到 1.0.0 是一项有意为之的决定，而非某次提交带来的附带结果。

列表条目

官方 MCP 注册表会读取 server.json 清单，而本 README 顶部的 mcp-name 注释则用于让该注册表确认 PyPI 包属于此列表条目。docs/registry-listings.md 保存了规范的列表条目文案，以及每个目录会读取的内容，确保每个列表条目表述一致。tests/test_registry_manifest.py 会将清单中的包名、版本号和环境变量与此包保持一致。

许可证

Apache-2.0。请参阅 LICENSE。