Trailmark MCP Server

Trailmark MCP Serverは、のスタンドアロンMCPラッパーです。

ToBによるでの使用法は理解していますが、私のユースケースでは、複数のグラフを分析および提供できるMCPサーバーが必要です。このサーバーは複数のリポジトリをスキャンでき、LLMはそれぞれから個別に情報を要求できます。

主にVS CodeのGithub Copilot経由でOpenAI GPT-5.5を使用して作成されました。ドキュメントおよび開発サポートについては、LLMをai-docsディレクトリに向けてください。

要件

• Python 3.12+

• uv

プロジェクトメタデータ:

• パッケージ名: trailmark-mcp

• CLIコマンド: trailmark-mcp

インストール

ランタイムおよび開発依存関係をインストールします:

uv sync --group dev

クイックスタート

stdio経由でサーバーを起動します:

uv run trailmark-mcp serve --transport stdio

MCPクライアントなしで直接スキャンパスをスモークテストします:

uv run trailmark-mcp scan /path/to/repo

必要な場合にスキャン中の事前分析をスキップします:

uv run trailmark-mcp scan /path/to/repo --skip-preanalysis

サーバーの仕組み

プライマリライフサイクルエントリーポイントは open_repository(...) です。

動作の概要:

• スナップショットが存在しない場合、サーバーはソースをスキャンし、オプションで事前分析を実行し、最初のスナップショットを保存します

• スナップショットが存在し rescan=False の場合、サーバーは最新のスナップショットをライブセッションに再読み込みします

• rescan=True の場合、サーバーはソースから再構築し、新しいスナップショットを保存します

つまり、一般的なフローは以下の通りです:

1. open_repository を呼び出す

2. 返されたセッションに対してグラフツールを使用する

3. 永続化が必要なメモリ内での重要な変更後に save_snapshot を呼び出す

セッションモデル

session_id はMCPラッパーの状態であり、Trailmarkコアの状態ではありません。

現在のセマンティクス:

• 各 open_repository(...) 呼び出しは新しいセッションIDを作成します

• 複数のライブセッションが共存可能です

• ツールは特定のグラフをターゲットにするために session_id を受け入れます

• session_id が省略された場合、最後に開かれた、まだ開いているセッションが使用されます

• デフォルトセッションを閉じると、最後に開かれた残りのセッションが昇格されます

セッションがどのリポジトリを指しているかを確認するには current_repository(session_id=...) を使用してください。

公開MCPツール

ライフサイクル:

• open_repository

• current_repository

• close_repository

• save_snapshot

ナビゲーション:

• graph_summary

• diff_graphs

• search_nodes

• callers_of

• callees_of

• ancestors_of

• reachable_from

• paths_between

• entrypoint_paths_to

• attack_surface

• complexity_hotspots

• functions_that_raise

コンテキストと変更:

• subgraph

• annotations_of

• findings

• nodes_with_annotation

• run_preanalysis

• annotate_node

• clear_annotations

• augment_findings

注意:

• diff_graphs(before_session_id, after_session_id) は after を新しい状態として扱います

• search_nodes は contains、exact、suffix をサポートしています

• scan_repository や tool_manifest のような削除されたヘルパーサーフェスは、意図的に公開ランタイムの一部ではなくなりました

スナップショットの動作

スナップショットはこのサーバーリポジトリの下ではなく、分析されたリポジトリの下に書き込まれます:

<target-repo>/.trailmark/snapshots/<timestamp>/

現在のスナップショットアーティファクトには以下が含まれます:

• graph.json

• summary.json

• entrypoints.json

• hotspots.json

• subgraphs.json

• scan-metadata.json

スナップショットはライブセッションへの再読み込みをサポートしています。ソースからの新しい再構築が明示的に必要な場合は rescan=True を使用してください。

リポジトリレイアウト

主要ファイル:

• src/trailmark_mcp/cli.py: scan および serve 用のCLIエントリーポイント

• src/trailmark_mcp/mcp_app.py: MCPツール登録

• src/trailmark_mcp/tool_catalog.py: 公開ツール用の宣言的メタデータ

• src/trailmark_mcp/services/registry.py: セッション追跡

• src/trailmark_mcp/services/runtime.py: Trailmarkベースのメインランタイム動作

開発

フォーカスされたテストスイートを実行します:

uv run --group dev pytest tests/test_tool_catalog.py tests/test_registry.py tests/test_stdio_server.py

現在のCIは、Python 3.12で同じフォーカスされたスイートを実行します。

拡張ルール:

1. ランタイム動作を追加または変更する

2. mcp_app.py にツールを登録する

3. tool_catalog.py のメタデータを更新する

4. テストを更新する

5. 公開動作が変更された場合はドキュメントを更新する

VS Codeでの使用

VS Codeは、ワークスペースレベルの mcp.json ファイルを使用して、MCP経由でこのサーバーを直接起動できます。

一般的なセットアップ:

1. このリポジトリをVS Codeで開く

2. uv sync --group dev で依存関係がインストールされていることを確認する

3. サーバー定義を .vscode/mcp.json に保持する

4. MCPクライアントに stdio 経由でサーバーを起動させる

このリポジトリには、ローカル使用のための .vscode/mcp.json が既に含まれています。

mcp.json の例:

{
  "servers": {
    "trailmark-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": [
        "run",
        "trailmark-mcp",
        "serve",
        "--transport",
        "stdio"
      ]
    }
  }
}

より大きなマルチプロジェクトワークスペースからこのサーバーを使用する場合は、同じ定義をそのワークスペースルートの .vscode/mcp.json にコピーし、コマンドが uv とこのプロジェクトが利用可能な環境で実行されることを確認してください。