Legesher

legesher-mcp

Legesher の Model Context Protocol サーバーです。 エンジンの翻訳機能を、MCP 対応クライアント（Claude、 IDE アシスタント、エージェントフレームワークなど）で利用できるようにする、 タスクに合わせた大まかな 6 つのツールを提供します。

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	記録前に、提案された識別子の翻訳をチェックします。不正な識別子、安全でないテキスト、パックで予約されている名前、既存の用語集およびバッチ内のほかの項目とのずれ（1 つの概念に 2 つの用語）や衝突（2 つの概念に 1 つの用語）を検出します。比較には 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	1 つの言語の用語辞書全体（キーワード、組み込み要素、例外、予約語）です。デフォルトの 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

モノレポのワークスペース内では、同梱されているすべてのパックがすでにインストールされています。

uv run legesher-mcp

サーバーはデフォルトでは静かに動作します（ログレベルは WARNING）。問題の調査には、 LEGESHER_MCP_LOG_LEVEL（DEBUG、INFO、WARNING、ERROR、 CRITICAL）を設定してください。認識されない値を指定した場合は、静かなデフォルトに戻ります。GUI クライアントはシェルを実行しないため、この変数はクライアント独自の設定に記述する必要があります。以下の各ブロックに設定場所を示しています。

クライアントの設定

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 です。 各リクエストは自己完結しており、サーバー側にセッションは保持されません。また、レスポンスは SSE ではなく application/json です。
• Origin が存在する場合は検証されます。 別のオリジンからのブラウザーページ（DNS リバインディング攻撃の経路）は 403 で拒否されます。許可リストはバインドされたインターフェースに基づきます。Origin ヘッダーを送信しない MCP クライアントには影響しません。

実行せずに組み込む場合：legesher_mcp.server.create_server() は Backend とエンタイトルメントゲートから完全なサーバーを構築し、 create_http_app() は独自のミドルウェア（TLS、認証、ゲート用のリクエストコンテキスト。legesher_mcp.gate.request_context を参照）の背後にマウントできる ASGI アプリとして返します。ゲートはデフォルトで許可されます。この実装のデプロイコードでゲートが設定されることはなく、ゲート対象のツールは常に一覧に表示されます。また、権限のない呼び出しには不透明な失敗ではなく、次に取るべき行動がわかるメッセージを返します。validate_identifier_translations は設計上、常に無料で利用できます。

エージェントのセッションをローカライズされた状態に保つ

サーバーは決定論的な部分を担い、同梱されている2つのアーティファクトがエージェントセッション向けのポリシーと手引きを担います。

• templates/AGENTS-template.md — 言語ポリシーの宣言です。 これをリポジトリのルートに AGENTS.md としてコピーし、宣言する言語を記入すると、AGENTS.md を読み込むすべてのエージェント（Codex、Cursor、Claude Code、Antigravity、Windsurf）が同じ8つのルールを適用します。ネイティブに記述すること、キーワードを手作業で翻訳しないこと、プロジェクトの用語集に基づいて1つの概念に1つの用語を使う命名、そしてバイト単位で同一のラウンドトリップ保証です。このファイルは宣言です。長時間のセッションではルールファイルがコンテキストから追い出されます。だからこそ、ファイルではなく決定論的なツールが保証を担います。
• skills/legesher-localized-code/ — 安定した知識を提供するスキルです （Agent Skills 形式。Claude Code、Claude アプリ、API 間で利用できます）。メンタルモデル（実行形式 ↔ ネイティブ、決定論的な層とファジーな層）、状況に応じて呼び出すツール、書く → ラウンドトリップ → 検証のワークフロー、命名規律を説明します。Claude Code では、このディレクトリをプロジェクトの .claude/skills/ にコピーしてください。スキルは安定した手引きを担い、MCP サーバーはライブな利用面を担います。この分担は意図的なものです。

プライバシー

• このバージョンではテレメトリを収集しません。 サーバーから送信される情報はありません。今後のリリースでは、メンテナーがどのツールがどれくらい使われているかを確認できるよう、任意の使用状況レポートが追加されます。この README の以前のバージョンでは、サーバーはテレメトリを決して送信しないと約束していましたが、その約束は撤回されました。レポートがリリースされた場合：
  • デフォルトではオフです。 サーバーの環境（上記の例のように、クライアント設定の env ブロックまたは --env フラグ）で LEGESHER_MCP_TELEMETRY=on を設定しない限り、何も送信されません。
  • DO_NOT_TRACK=1 または LEGESHER_TELEMETRY_DISABLED=1 が常に優先され、他のすべての設定を上書きします。
  • 送信する情報は、ツール名、呼び出し回数、エラークラス、サーバーとエンジンのバージョン、ランダムなインストール ID のみです（インストールごとに保持され、同じレポートが複数回カウントされないようにします。マシン、アカウント、コードから生成されるものではありません）。ソースコード、ファイルの内容、識別子、翻訳テキスト、プロンプト、ファイルパス、その他個人を特定できる情報は決して送信しません。
  • リクエスト処理経路の外で実行されます。ツール呼び出しがレポートを待つことも、レポートが原因で失敗することもありません。配信できないレポートは破棄されます。
  • MCP の標準入出力ストリームには決して触れません。
• ツール呼び出し時にネットワーク通信はありません。 すべてのツール呼び出しはローカルエンジンで処理されます。上記の使用状況レポートがリリースされた場合、それを有効にしたときに限り、このパッケージが開始するよう設計されている外向きの通信はそれだけです。
• コードは保存されません。 送信されたソースはメモリ内で処理されます。map_existing_codebase に渡されたファイル パス はレポート用のラベルであり、あなたに返されますが、ログに記録されたり、ファイルシステムへのアクセスに使われたりすることはありません。そのため、validate_identifier_translations は用語集を 内容 として受け取り、受理したエントリを保存せずに返します。記録するかどうかはあなた次第です。リポジトリ内の .legesher/identifier_map.json に保存することも、すでにそのファイルを管理している legesher CLI を使うこともできます。セッション終了後も残り、複数のリポジトリやチームメイトと共有される永続的な用語集は、記録の基盤となるため、ローカルのサブプロセスではなく、ホスト型 API の背後に置くべきです。
• 宣言だけでなく、実際に明示されています。 6 つすべてのツールに、readOnlyHint: true、idempotentHint: true、destructiveHint: false、openWorldHint: false という MCP アノテーションが付いています。アノテーションを読み取るクライアント（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

テストは 2 つの階層に分かれています。デフォルトの実行では、実際の MCP クライアントセッションを通じてすべてのツールをテストし、短時間で完了します。scheduled 階層はデフォルトの実行から除外されており、リリース前に実行します。

• 全パックの往復スイープ — インストール済みのすべてのパックと構文要素のコーパス全体について、バイト単位で同一になることを保証します（コミットごとの実行では 3 つのパックをサンプリングします）。既知のエンジン／パックの失敗は tests/test_roundtrip_sweep.py に厳密な xfail として記載されており、修正があればテストで検知できます。

• クリーン環境での起動 — wheel をビルドし、空のディレクトリにある新しい仮想環境へインストールして、環境変数を最小限にした状態で標準入出力セッションを実行します。ホストが実際に起動するのと同じ方法で成果物をテストする唯一のテストです。ワークスペースの外で、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 ハンドシェイクで、配布パッケージに含まれていないバージョン番号が報告されることはありません。

1.0.0 より前は、互換性を破る変更でマイナーバージョンを上げます（0.1.0 → 0.2.0）。major_on_zero はオフになっているため、1.0.0 への移行はコミット1つの副産物ではなく、意図的な決定となります。

掲載情報

server.json は公式 MCP レジストリが読み取るマニフェストで、この README の冒頭にある mcp-name コメントによって、レジストリは PyPI パッケージが掲載情報に属することを確認します。docs/registry-listings.md には、掲載情報の正式な文面と各ディレクトリが読み取る内容が記載されているため、どの掲載情報も同じ内容になります。tests/test_registry_manifest.py は、マニフェストに記載されたこのパッケージの名前、バージョン、環境変数を固定します。

ライセンス

Apache-2.0 です。LICENSE を参照してください。