io.github.MukundaKatta/agentsnap

agentsnap-mcp

An MCP server that gives AI assistants the ability to inspect, normalize, diff, and validate agent tool-call traces.

Built on top of @mukundakatta/agentsnap. Works with Claude Desktop, Cursor, Cline, Windsurf, Zed, and any other MCP client.

Tools exposed

normalize_trace

Coerce a raw tool-call trace into the canonical agentsnap Trace shape and compute a deterministic SHA-256 fingerprint hash. Use this to compare runs cheaply or feed downstream diff tools.

{
  "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

Diff a baseline trace against a current run. Returns a uniform additions / removals / changes vocabulary plus the agentsnap status code (PASSED, OUTPUT_DRIFT, TOOLS_REORDERED, TOOLS_CHANGED, REGRESSION). Use ignore_paths to silence noisy fields before classification.

{
  "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

Sanity-check a snapshot against the agentsnap Trace schema. Verifies required fields, tool-entry shape, and surfaces actionable issues. Returns valid=true on success or a list of human-readable problems.

Install

Claude Desktop

Add to claude_desktop_config.json:

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

Cursor / Cline / Windsurf / Zed

Same shape, in the appropriate mcp.json for your client. Most clients auto-discover via npx -y @mukundakatta/agentsnap-mcp.

Local install

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

Why this matters

Agents that call tools drift silently. A tool argument changes shape, a nondeterministic result flips a downstream branch, an extra tool sneaks in between releases — none of it shows up in unit tests. agentsnap captures the trace; this MCP server lets your assistant inspect and reason about traces directly: normalize one, diff two, or validate a saved snapshot, all from the model's tool-use surface.

License

MIT.