Symvanta

Claude Code 向け Symvanta プラグイン

Symvanta でインデックス化されたコードベースで作業するためのワンステップセットアップです。このプラグインをインストールすると、次のことが行われます。

• Symvanta MCP サーバー（デフォルトは https://mcp.symvanta.com/mcp。オンプレミス／セルフホスト可能な環境向けに設定でき、初回接続時に OAuth を使用）を登録するため、.mcp.json を手動で編集する必要がありません。
• 各セッションの開始時に一度、常時適用されるコンテキストを注入します。これにより、エージェントはシェル検索ではなく Symvanta のコードグラフツールを使用します。
• ツールの選択基準と規約をすべて記載した symvanta スキルを提供します。
• よく使うグラフのワークフローを実行するスラッシュコマンドを追加します。

コマンド

各コマンドは適切な Symvanta MCP ツールを呼び出すため、ツール名を覚える必要はありません。

• /symvanta:ask [question]：動作に関する質問（X はどのように動作するか、Y はなぜ起きるか）に、ask_codebase を使ってファイルの引用付きで回答します。
• /symvanta:blast [symbol]：シンボルを編集する前に、影響範囲の安全性を確認します。
• /symvanta:trace [symbol]：関数の呼び出しチェーン、呼び出し元、依存関係をマッピングします。
• /symvanta:route [METHOD /path]：HTTP ルートのハンドラーを探します。
• /symvanta:status：接続とインデックスの健全性をスナップショットで確認します（プロジェクト、リポジトリ、鮮度、エッジ数）。
• /symvanta:architecture：map view:"architecture" を使って、モジュールの概要を確認します（Louvain による機能モジュール、PageRank のハブ、モジュール間の結合、リポジトリ全体で重要な関数）。
• /symvanta:scope [symbol or change]：変更の規模を見積もる前に、事前に範囲と影響を見積もります（estimate_scope）。
• /symvanta:branch [name | clear]：このセッションの読み取り対象を追跡中の機能ブランチに固定するか、固定を解除します（ref）。
• /symvanta:working-tree：コミットしていない編集内容を重ねて、プッシュしていない変更をグラフに反映します（ref op:"index_working_tree"）。
• /symvanta:tests [symbol]：シンボルをカバーするテストを探します（list_tests_for）。
• /symvanta:recent [path]：最近変更されたファイルと最近のコミットを表示します（history）。
• /symvanta:setup [local]：プロジェクトの CLAUDE.md（local を指定した場合は CLAUDE.local.md）に Symvanta のルーティングブロックを書き込みます。再実行すると、マークされたブロックが同じ場所で置き換えられます。サブエージェントも CLAUDE.md を読むため、ルーティングはサブエージェントにも適用されます。

インストール

Claude Code で次を実行します。

/plugin marketplace add https://symvanta.com/plugin/marketplace.json
/plugin install symvanta@symvanta

初回接続時にプロンプトが表示されたら、OAuth でサインインしてください。Symvanta ダッシュボードのワークスペースの「Getting Started」ページに、アカウント用の正確なマーケットプレイス URL が記載されています。

設定

このプラグインはデフォルトで Symvanta Cloud（https://mcp.symvanta.com/mcp）に接続するため、Cloud ユーザーは設定不要です。別の Symvanta サーバーを指定するには、プラグインオプションの Symvanta MCP server URL（mcpUrl）を設定します。プラグインを有効にするときに受け入れるか変更するか、後から /plugin インターフェイス（Symvanta -> configure）で変更してください。空欄のままにすると、Cloud のデフォルト設定が使用されます。

末尾にスラッシュを付けず、/mcp パスを含む完全なエンドポイント URL を指定してください。たとえば、https://mcp.your-company.com/mcp です。ホスト名のみ、または末尾にスラッシュがある場合、接続に失敗します。

認証。 すべての Symvanta MCP サーバー（Cloud、staging、オンプレミス）はそれぞれ独自の OAuth エンドポイントを公開するため、mcpUrl の指定先にかかわらず、Claude Code は初回接続時に OAuth でサインインします。プラグインでの設定は不要です。オンプレミスでも同じ OAuth フローを使用します。ゲートウェイが Symvanta Cloud／ライセンスに対するサインインを完了し、サーバーが発行されたトークンを検証します。ヘッドレス自動化向けには静的な API キー／ベアラートークン認証も利用できますが、プラグインではなく、サーバーまたは独自の MCP 設定で構成します。

更新

/plugin update symvanta@symvanta

その後、Claude Code を再起動してください。Claude Code はプラグイン（hooks/hooks.json を含む）を起動時に読み込み、継続的には読み込みません。そのため、実行中のセッションでは再起動するまで以前に読み込んだバージョンが使われます。それまでは、/plugin update を実行してダウンロードしても有効になりません。

マシン上で実行されるもの

このプラグインは、読みやすい小さな Node フックスクリプトをローカルで実行します。

• session-start.js：セッション開始時に、定常的なコンテキストを一度だけ表示します。チェックアウトの Git リモート（owner/name）を読み取り、エージェントに repository をその値に設定して init を呼び出すよう指示します。これにより、ワークスペースのデフォルトではなく、このチェックアウトを含むプロジェクトにセッションが紐付けられます。どこにも送信しません。
• 拡張フック群（デフォルトで有効）：5 つのフックが 1 つのコア（lib.js）を共有します。いずれもコンテキストを追加するだけで、処理をブロックすることはありません。エラー、タイムアウト、トークンの欠落はすべてそのまま通過し、インターセプトされたツールは常に変更されずに実行されます。各フックはまず、実行先のチェックアウトが Symvanta プロジェクトに紐付いているか確認します（チェックアウトごとに 10 分間で init は 1 回だけ呼び出し、結果をメモ化します）。どのプロジェクトにも紐付いていないチェックアウトや、リモートのない Git チェックアウトではフックは何も表示しないため、インデックス化されていない場所で作業しているときに、別のコードベースのシンボルが表示されることはありません。
  • grep-augment.js：Grep／Glob の実行時に、一致するインデックス済みシンボルの定義を検索し（検索対象のリポジトリに限定し、パターン内の識別子を最大 2 つ並列で検索、キャッシュは 60 秒）、生の検索結果とあわせて追加します。
  • edit-augment.js：コードファイルに対する Edit／Write の実行時に、変更が反映される前に、編集対象のシンボルの影響範囲（上流シンボル数、ファイル、レイヤー、リポジトリ間のエッジ、リスク層）を挿入します。既存ファイルへの Write では、上書きによって置き換えられる定義を一覧表示します。新規ファイルとコード以外のファイルでは何も表示しません。
  • read-augment.js：セッションごとに、コードファイルの最初の Read で、そのファイルのシンボルスケルトン（名前、種類、行の範囲）と、ファイルに紐付くアーキテクチャ決定記録を挿入します。2 回目以降の読み取りでは即座に終了します。
  • grep-rescue.js：結果が見つからなかった Grep の後に、グラフ上の候補（テキスト／セマンティック検索を自動実行）を提案し、行き止まりを手がかりに変えます。結果が見つかった場合は、標準入力の解析直後に終了し、読み取りもネットワーク通信も行いません。
  • prompt-augment.js：メッセージ内の識別子形式のトークン（バッククォートで囲まれた部分、snake_case、camelCase）を、ターン開始時にインデックス済みの定義へ解決します。通常の文章は対象にならないため、会話形式のプロンプトでは何も表示されません。

拡張機能が読み取り、送信し、書き込む内容の詳細

グラフを呼び出すには、Symvanta MCP トークンが必要です。接続時に Claude Code がすでに保存したトークンを再利用するため、設定は不要です。読み取り範囲は 意図的に限定されており、各スクリプトは数分で監査できるほど短くなっています。

• ~/.claude/.credentials.json から読み取るのは、唯一 mcpOAuth[<the Symvanta entry>].accessToken です（macOS では、Claude Code は代わりに ログイン Keychain のサービス Claude Code-credentials に保存するため、ファイルがない場合は フックがそちらを読み取ります）。Anthropic トークン （claudeAiOauth）や、Symvanta 以外のサーバーのトークンは決して読み取りません。
• このトークンの送信先は、発行元と同じ Symvanta MCP サーバーのみです。
• 検索ごとに端末から送信されるもの：抽出された識別子の用語、一致した シンボル名、リポジトリ相対のファイルパス、およびチェックアウトの GitHub リモートの**owner/name**（紐付け確認用）です。ファイルの内容は送信されず、 メッセージ本文も送信されません（プロンプトフックが送信する識別子トークンは最大 2 つで、プロンプト自体は送信しません）。
• ~/.symvanta/ 以下にローカルファイルを書き込みます。どこにもアップロードされません。 grep-cache/（60 秒間の結果キャッシュ。キーごとに小さなファイル 1 つ）、 repo-cache.json（パスとリポジトリの対応メモ）、 workspace-cache.json（チェックアウトごとの紐付けメモ。10 分間）、 keychain-cache.json（macOS のみ：Keychain 読み取りの 5 分間のメモ。セッション中に ツールを呼び出すたびに security をシェルから実行しなくて済みます）、 read-seen/（セッションごとの初回読み取りマーカー）、および grep-augment.log（実行ごとに 1 行の JSONL。フック、用語、リポジトリ、 一致数、レイテンシ、キャッシュヒットを記録）です。このログは /symvanta:status でフックの動作を確認するためのものです。これらのファイルはいつでも削除できます。

スイッチ（変更後は Claude Code を再起動してください）：

# Supply your own token instead (dashboard -> Settings -> MCP connection ->
# regenerate gives a Passport mcp:read token); the credentials file is then
# never read:
export SYMVANTA_MCP_TOKEN="<token>"

# Turn the whole family off (no reads, no network on any tool call):
export SYMVANTA_AUGMENT=off        # the legacy SYMVANTA_GREP_AUGMENT=off also works

# Or turn off individual hooks:
export SYMVANTA_EDIT_AUGMENT=off   # Edit/Write blast radius
export SYMVANTA_READ_AUGMENT=off   # first-read skeleton + ADRs
export SYMVANTA_GREP_RESCUE=off    # empty-grep suggestions
export SYMVANTA_PROMPT_AUGMENT=off # prompt term lookup

フックを完全に削除するには、hooks/hooks.json から そのフックのブロックを削除することもできます。

Bash と、上記のフックがないすべてのツールは変更されずに実行されます。コードナビゲーションは すべて、OAuth で保護された HTTPS 経由で Symvanta MCP サーバーを通じて行われます。テレメトリも、 バックグラウンドプロセスもありません。

Grep/Glob 拡張機能の動作

どのゲートも安全側に倒れて同じパススルーとなり、パススルーも成功時も「Grep を通常どおり実行」に進みます。フックが追加できるのはコンテキストだけで、検索をブロックしたり、失敗するまで遅延させたりすることはありません。SYMVANTA_GREP_AUGMENT=off を設定すると、何かを読み取ったり送信したりする前に処理を短絡します。

flowchart TD
    A["Agent runs Grep or Glob"] --> B{{"Claude Code fires the PreToolUse hook"}}
    B --> D{"SYMVANTA_GREP_AUGMENT = off?"}
    D -->|yes| RUN["Grep/Glob runs normally; results unchanged"]
    D -->|no, default| TX["Extract up to 2 identifiers from the pattern; derive the repo from the search path"]
    TX --> CACHE{"Fresh 60s cache hit?"}
    CACHE -->|yes| F["Format matching definitions as additionalContext"]
    CACHE -->|no| TOK["Token: SYMVANTA_MCP_TOKEN, else the stored Symvanta token from ~/.claude/.credentials.json (macOS: login Keychain)"]
    TOK --> C["quick_lookup per term, in parallel, repo-scoped, hard cap 1.5s; falls back to locate mode:symbol"]

    subgraph cloud["Symvanta cloud (only the search TERMs leave your machine)"]
        C --> M["mcp.symvanta.com"]
        M --> DB[("Code graph in Postgres")]
        DB --> M
    end

    C --> OK{"Token valid and matches, in time?"}
    OK -->|no, error, or timeout| LOG["Append one line to ~/.symvanta/grep-augment.log"]
    OK -->|yes| CW["Cache for 60s"] --> F
    F --> EM["Emit JSON to Claude Code"] --> LOG
    LOG --> RUN
    RUN --> O["Agent sees its grep results PLUS the Symvanta definitions, then reaches for find_node / relate / ask_codebase"]

アンインストール

/plugin uninstall symvanta@symvanta
/plugin marketplace remove symvanta

構成

.claude-plugin/plugin.json   manifest + MCP server registration
hooks/hooks.json             SessionStart + augment family wiring (PreToolUse, PostToolUse, UserPromptSubmit)
hooks/session-start.js       standing-context injector
hooks/lib.js                 shared augment core (auth, transport, cache, log)
hooks/grep-augment.js        Grep/Glob definition augmenter
hooks/edit-augment.js        Edit/Write blast-radius augmenter
hooks/read-augment.js        first-read file skeleton + ADR augmenter
hooks/grep-rescue.js         empty-grep graph suggestions (PostToolUse)
hooks/prompt-augment.js      prompt identifier lookup (UserPromptSubmit)
hooks/augment-stats.js       local activity summary for /symvanta:status
commands/                    slash commands (ask, blast, trace, route, status, architecture, scope, branch, working-tree, tests, recent)
skills/symvanta/SKILL.md     tool decision matrix and conventions
scripts/                     sync-skill.mjs (SKILL from source) + check-tool-prefixes.mjs (CI guard)

ライセンス

MIT