pyscope-mcp

A deployable MCP server that exposes Python function- and module-level call graphs over any Python repo, for use by agentic coding clients (Claude Code, etc.).

What it gives an agent

Instead of grepping blindly:

• callers_of(fqn, depth) — who calls this function, transitively

• callees_of(fqn, depth) — what does this function reach

• module_callers(module) / module_callees(module) — module-level dependency edges

• neighborhood(symbol, depth, token_budget) — bounded bidirectional subgraph around a symbol, rank-truncated to fit a token budget

• file_skeleton(path) — all top-level functions, classes, and methods defined in a file

• search(query) — substring search over all FQNs

• stats() — sanity-check the loaded index

• reload() — re-read the index from disk after running pyscope-mcp build

• build() — trigger a rebuild via subprocess and reload the in-process index in one call

The graph is precomputed and saved — pyscope-mcp build runs the analyzer once and writes a JSON index; pyscope-mcp serve loads that index and answers MCP queries without re-running analysis.

Install

pip install pyscope-mcp

Build the index

pyscope-mcp build --root /path/to/repo --package my_pkg

Writes to .pyscope-mcp/index.json inside the repo by default. Override with --output or $PYSCOPE_MCP_INDEX.

Serve

pyscope-mcp serve --root /path/to/repo

Errors out if no index exists. Env-var equivalents: PYSCOPE_MCP_ROOT, PYSCOPE_MCP_INDEX.

Register with Claude Code

{
  "mcpServers": {
    "pyscope": {
      "command": "pyscope-mcp",
      "args": ["serve"],
      "env": {
        "PYSCOPE_MCP_ROOT": "/abs/path/to/repo"
      }
    }
  }
}

Setup for an agent in your repo (Claude Code)

If you are an agent setting up pyscope-mcp in a new repo, follow these steps:

1. Install the package

   pip install pyscope-mcp

2. Build the call-graph index

   pyscope-mcp build --root /abs/path/to/repo --package your_package_name

   This writes .pyscope-mcp/index.json inside the repo. Run this step first — serve will not build the index automatically.

3. Register the MCP server in .claude/settings.json

   {
     "mcpServers": {
       "pyscope": {
         "command": "pyscope-mcp",
         "args": ["serve"],
         "env": {
           "PYSCOPE_MCP_ROOT": "/abs/path/to/repo"
         }
       }
     }
   }

   If the index lives at a non-default path, add "PYSCOPE_MCP_INDEX": "/abs/path/to/index.json" to the env block.

4. Verify the server loaded

   After restarting Claude Code (or reloading the MCP server), ask Claude:

   Call the stats tool on the pyscope-mcp server.

   You should see node and edge counts in the response. If the output is non-empty the index loaded correctly and the MCP tools are ready to use.

Query logging (opt-in)

Every tools/call dispatch can append a structured JSONL entry to a local rotating log file so you can measure tool-use patterns, truncation rates, hub-suppression hits, and latency without parsing claude's session transcripts.

The logger is off by default. Set PYSCOPE_MCP_LOG=1 to enable.

Log location

Default: .pyscope-mcp/query.jsonl next to the index file (already .gitignored).
Override: PYSCOPE_MCP_LOG_PATH=/abs/path/to/query.jsonl.

Enable / disable

# Enable
PYSCOPE_MCP_LOG=1 pyscope-mcp serve ...

# Disable explicitly (or leave PYSCOPE_MCP_LOG unset — off is the default)
PYSCOPE_MCP_LOG=0 pyscope-mcp serve ...

Log entry schema (v1)

{
  "v": 1,
  "ts": "2026-04-25T21:00:00.000+00:00",
  "server_id": "550e8400-e29b-41d4-a716-446655440000",
  "rpc_id": 3,
  "tool": "neighborhood",
  "args": {"symbol": "pkg.mod.Foo.run", "depth": 2, "token_budget": 500},
  "duration_ms": 12,
  "is_error": false,
  "truncated": true,
  "result_count": null,
  "edge_count": 7,
  "hub_suppressed_count": 2,
  "depth_full": 1,
  "token_budget_used": 487,
  "index_version": 5,
  "index_git_sha": "a1b2c3d4...",
  "index_content_hash": "abcdef12..."
}

server_id partitions entries by session (the MCP server is spawned per-session as a stdio subprocess by Claude Code). To join log entries with claude's own session transcript, match by (ts, tool, args) or rpc_id.

Rotation: files rotate at 10 MB; up to 5 historical files are kept (query.jsonl.1 … query.jsonl.5), giving a ~50 MB ceiling.

Index schema v5 note

The index format was bumped from v4 to v5 to add git_sha and content_hash header fields (used by the logger to tie each log entry to a specific graph version). Existing v4 index files are not migrated — re-run pyscope-mcp build to generate a v5 index.