agentsnap

agentsnap-mcp

AI アシスタントがエージェントのツール呼び出しトレースを 検査、正規化、差分比較、検証できるようにする MCP サーバーです。

@mukundakatta/agentsnap を基盤に構築されています。 Claude Desktop、Cursor、Cline、Windsurf、Zed、およびその他すべての MCP クライアントで動作します。

公開されるツール

normalize_trace

生のツール呼び出しトレースを標準的な agentsnap Trace 形式に 変換し、決定論的な SHA-256 フィンガープリントハッシュを計算します。実行結果の 手軽な比較や、後続の差分比較ツールへの入力に使用します。

{
  "trace": [
    { "name": "search", "args": { "q": "cats" } },
    { "name": "fetch",  "args": "https://example.com" }
  ],
  "input": "find cats",
  "model": "claude-opus-4-7"
}

→

{
  "normalized": {
    "version": 1,
    "model": "claude-opus-4-7",
    "input": "find cats",
    "output": null,
    "tools": [
      { "name": "search", "args": { "q": "cats" } },
      { "name": "fetch",  "args": "https://example.com" }
    ],
    "error": null,
    "fingerprint": { "node": "v22.0.0", "agentsnap": "0.1.0" }
  },
  "hash": "sha256:..."
}

diff_traces

ベースラインのトレースと現在の実行結果を差分比較します。一貫した 追加／削除／変更の形式と、agentsnap のステータスコード （PASSED、OUTPUT_DRIFT、TOOLS_REORDERED、TOOLS_CHANGED、REGRESSION）を返します。 分類の前にノイズの多いフィールドを無視するには、ignore_paths を使用します。

{
  "baseline": { "version": 1, "tools": [{ "name": "search", "args": { "q": "cats" }, "result_hash": "sha256:aaa" }], "error": null, "fingerprint": {...} },
  "current":  { "version": 1, "tools": [{ "name": "search", "args": { "q": "cats" }, "result_hash": "sha256:bbb" }], "error": null, "fingerprint": {...} },
  "ignore_paths": ["tools[].result_hash"]
}

→ { "same": true, "status": "PASSED", "additions": [], "removals": [], "changes": [] }

validate_snapshot

スナップショットが agentsnap Trace スキーマに準拠しているかをチェックします。必須 フィールド、ツールエントリーの形式を検証し、対処可能な問題を提示します。成功時は valid=true を返し、失敗時は人が読める問題の一覧を返します。

インストール

Claude Desktop

claude_desktop_config.json に追加します：

{
  "mcpServers": {
    "agentsnap": {
      "command": "npx",
      "args": ["-y", "@mukundakatta/agentsnap-mcp"]
    }
  }
}

Cursor / Cline / Windsurf / Zed

クライアントに応じた mcp.json に、同じ形式で追加します。ほとんどのクライアントは npx -y @mukundakatta/agentsnap-mcp を通じて自動検出します。

ローカルインストール

npm install -g @mukundakatta/agentsnap-mcp
mcp-agentsnap        # listens on stdio

なぜ重要なのか

ツールを呼び出すエージェントでは、気付かないうちに挙動が変化します。ツールの引数の形式が変わる、 非決定的な結果によって後続の分岐が切り替わる、リリース間に余分なツールが紛れ込むなど、 こうした変化はどれもユニットテストには現れません。agentsnap はトレースを記録し、 この MCP サーバーを使えばアシスタントがトレースを直接検査して推論できます。モデルの ツール使用インターフェースから、トレースの正規化、2 つのトレースの差分比較、保存済みスナップショットの検証を行えます。

ライセンス

MIT。