MCP — Tesserae を Claude Code、Codex、Cursor に接続する

<!-- translations:start -->

English · 한국어 · 中文 · Русский · Español · Français · Deutsch

<!-- translations:end -->

Tesserae は Model Context Protocol の stdio サーバーを同梱しており、コンパイル済みの型付きグラフを任意の MCP 対応クライアント（Claude Code、Codex CLI、Cursor、Claude Desktop など）に公開します。サーバーは MCP の 3 つの完全な面 — tools、resources、prompts — を提供するため、クライアントはオンデマンドでグラフを問い合わせることも、正規化された URI から低コストでコンテキストを供給することもできます。

前提条件

サーバーは .tesserae/graph.json を読み込むため、最初に一度コンパイルしておく必要があります:

cd /path/to/your-project
tesserae project setup    # interactive; or --yes for non-interactive
tesserae project compile  # deterministic, no LLM calls, no API keys

ソースが変わったらいつでも再コンパイルしてください。サーバーは再起動なしで次回の tool 呼び出し時に新しいグラフを読み込みます。

1) クライアント設定を生成する

tesserae project mcp-config

おおよそ次のような JSON スニペットを出力します:

{
  "mcpServers": {
    "tesserae": {
      "command": "python3",
      "args": [
        "-m", "tesserae.mcp_server",
        "--graph", "/path/to/your-project/.tesserae/graph.json"
      ]
    }
  }
}

正確なパスは現在のプロジェクトから補完されます。サーバーエントリー名を tesserae 以外にしたい場合は --name <alias> を渡してください。

2) MCP クライアントに貼り付ける

編集後はクライアントを再起動してください。次のセッションで接続され、Tesserae のサーフェスが検出されます。

3) クライアントから見えるもの

Tools — モデルから呼び出される

Resources — モデルのコンテキストへ自動的に読み込まれる

クライアントが tool turn を消費せずに resource picker から取り込める URI:

• tesserae://graph/schema — schema tool と同じペイロードを静的コンテキストとして提供
• tesserae://graph/summary — アクティブなプロジェクトのサマリー
• tesserae://lint-report — 直近の lint レポートを markdown として提供

加えて、クライアントがオンデマンドで構築できる URI テンプレート:

• tesserae://wiki/{kind}/{slug} — コンパイル済み wiki ページ本文
• tesserae://raw/{source_path} — 任意の生ソース markdown

Prompts — ワンクリックのリサーチテンプレート

これらはクライアントのスラッシュメニュー（例: Claude Code の / パレット）に表示されます:

各 prompt は単一のユーザーメッセージにレンダリングされ、モデルに対してどの Tesserae tool をどう連鎖させるかを正確に伝えるため、モデルが毎回サーフェスを再発見する必要はありません。

マルチプロジェクト: 1 つのサーバーに複数のヴォルトを登録する

~/.tesserae/registry.json の永続レジストリにより、同じ MCP サーバーが任意の登録済みプロジェクトを名前で解決できます:

tesserae register-project /path/to/research --name research
tesserae register-project /path/to/notes    --name notes

これ以降、project または graph_path を受け取るすべての tool は、フルパスを必要とせず project: "research" をレジストリで解決します。サーバーは登録済みの graph_path がまだ存在するかも検証し、再コンパイルが必要な場合は明確なエラーを返します。

登録済みすべてのヴォルトへのファンアウト

ask tool は scope: "all-registered" を受け取り、登録済みのすべてのプロジェクトに並列でクエリして集約結果を返します:

{
  "name": "ask",
  "arguments": {
    "question": "Where is splatting used?",
    "scope": "all-registered"
  }
}

scope_aliases: ["research", "notes"] で対象を絞り込めます。

マルチアカウントの Claude CLI

ask tool が Claude CLI 経由でルーティングされ、複数アカウント（例: ~/.claude と ~/.claude-personal2）を使っている場合は、呼び出しごとに claude_config_dir を渡してください:

{
  "name": "ask",
  "arguments": {
    "question": "...",
    "claude_config_dir": "/Users/you/.claude-personal2"
  }
}

サーバーはその呼び出しの間だけ CLAUDE_CONFIG_DIR をエクスポートし、終了後に元の値を復元します。呼び出し間でリークしません。

動作確認

MCP クライアントを再起動した後、接続を確認します:

• Claude Code: /mcp に tesserae が tool 数とともに表示されるはずです。
• Cursor: チャットバーの MCP アイコンに tesserae: connected と tool/resource/prompt の件数が表示されるはずです。
• Codex / Hermes: 任意の tool（例: schema）を名前で呼び出してレスポンスを確認してください。

何も現れない場合、--graph が既存の .tesserae/graph.json を指しているか再確認してください — サーバーは起動時および各 tool 呼び出し時にこれを検証するようになり、サイレントな 500 ではなく明確なエラーメッセージが表示されます。

どこに位置づけられるか

MCP サーバーは型付きグラフへの読み取りインタフェースです。書き込み経路（ソースの取り込み、再コンパイル、RAG-Anything や Understand-Anything のような連携ツールの更新）には CLI を直接使ってください。両者は疎結合です: CLI が .tesserae/ を更新し、MCP サーバーは次の tool 呼び出しでそこにあるものを読み取ります。