MCP Server Integration¶

NervaPack ships two MCP servers. Use both together for the full picture: the knowledge-graph server answers structural questions about your code; the memory server recalls decisions and facts from previous sessions.

MCP Registry: io.github.ramdhavepreetam/nervapack — listed on the official MCP Registry.

Supported editors: Claude Code, Cursor, Windsurf, GitHub Copilot — all use MCP config files (format varies by editor, see setup below).

Editor Setup¶

Claude Code¶

Claude Code auto-discovers .mcp.json in the project root. No additional configuration needed.

pip install "nervapack[mcp]"
nervapack ingest .

Add .mcp.json to your project root (config shown below), then reload Claude Code.

Cursor¶

Cursor reads .mcp.json from the project root identically to Claude Code.

pip install "nervapack[mcp]"
nervapack ingest .

Add .mcp.json (see the config below), then open the Cursor MCP panel (Settings → MCP) and click Reload.

GitHub Copilot (VS Code)¶

GitHub Copilot in VS Code reads MCP servers from .vscode/mcp.json in the project root. Note that this uses a different format from .mcp.json — the top-level key is servers (not mcpServers) and each server requires type: "stdio".

VS Code version requirement

Copilot MCP support requires VS Code 1.99 or later. Earlier versions load the file but silently ignore MCP servers.

Create .vscode/mcp.json in your project root:

{
  "servers": {
    "nervapack": {
      "type": "stdio",
      "command": "/path/to/nervapack-mcp",
      "description": "NervaPack code graph — query, explore, impact, graph_status, show_savings"
    },
    "nervapack-memory": {
      "type": "stdio",
      "command": "/path/to/nervapack-memory-mcp",
      "description": "NervaPack agent memory — memory_store, memory_recall, memory_why, memory_timeline"
    }
  }
}

Replace /path/to/nervapack-mcp with the absolute path to the binary. Find it with:

which nervapack-mcp
# e.g. /Library/Frameworks/Python.framework/Versions/3.11/bin/nervapack-mcp

VS Code does not inherit your shell $PATH, so the absolute path is required.

After saving the file, open the VS Code Command Palette and run "MCP: List Servers" to verify both servers appear.

Windsurf¶

Windsurf (Codeium) supports MCP via a global config file at ~/.codeium/windsurf/mcp_config.json. You can also use a project-local .mcp.json — check your Windsurf version's docs for project-level support.

Global config (works in all Windsurf projects):

mkdir -p ~/.codeium/windsurf

{
  "mcpServers": {
    "nervapack": {
      "command": "nervapack-mcp",
      "description": "NervaPack knowledge graph (v0.6.8) — query, graph_status, explore, impact"
    },
    "nervapack-memory": {
      "command": "nervapack-memory-mcp",
      "description": "NervaPack agent memory (v0.6.8) — store, recall, and reason over facts across sessions"
    }
  }
}

Save to ~/.codeium/windsurf/mcp_config.json, then restart Windsurf. The NervaPack tools appear in the Cascade panel automatically.

Tip: You still need to run nervapack ingest . per-project. The MCP server reads from the project's .nervapack/ directory.

Full mcp.json¶

Drop this in your project root for all editors:

{
  "mcpServers": {
    "nervapack": {
      "command": "nervapack-mcp",
      "description": "NervaPack knowledge graph (v0.6.8) — query, graph_status, explore, impact"
    },
    "nervapack-memory": {
      "command": "nervapack-memory-mcp",
      "description": "NervaPack agent memory (v0.6.8) — store, recall, and reason over facts across sessions"
    }
  }
}

Breaking change in v0.6.8

Two MCP tools were renamed. Update any hardcoded tool names in prompts or CLAUDE.md files:

Old name (≤ v0.5.8)	New name (v0.6.8+)
`query_codebase`	`query`
`list_entities`	`explore`

Knowledge Graph Server (`nervapack-mcp`)¶

Exposes the code knowledge graph to Claude Code and Cursor.

Quick Setup¶

# 1. Install MCP support
pip install "nervapack[mcp]"

# 2. Build the graph
nervapack ingest .

# 3. Add to .mcp.json

{
  "mcpServers": {
    "nervapack": {
      "command": "nervapack-mcp",
      "description": "NervaPack knowledge graph (v0.6.8) — query, graph_status, explore, impact"
    }
  }
}

# 4. Reload your editor

Tools¶

Tool	Parameters	Description
`query`	`prompt: str`, `max_hops?: int`	Vector search → K-Hop BFS → focused Markdown context with bold token savings footer
`graph_status`	—	Node/edge counts by type, language breakdown, unsynced file warnings, cumulative savings summary
`explore`	`entity_type?: str`, `file_path?: str`	Browse all indexed classes, functions, imports, and markdown docs
`impact`	`target: str`, `max_hops?: int`	Reverse dependency analysis — find what depends on a given entity
`show_savings`	—	Markdown table of cumulative token savings across all queries — total queries, avg reduction %, cost saved

Example Interactions¶

You:     "How does the sync command decide which files to re-ingest?"
Claude:  → calls query("sync command file re-ingest logic")
         → gets 1,180 tokens of focused context (vs 12,840 tokens naive — 90.8% saved)
         → answers precisely, citing exact line numbers

You:     "What would break if I refactor VectorStore?"
Claude:  → calls impact("VectorStore")
         → returns list of callers and dependents with their file paths

You:     "How many tokens has NervaPack saved across all my queries?"
Claude:  → calls show_savings()
         → returns a Markdown table: 47 queries, 83.2% avg reduction, $0.11 GPT-4o cost saved

Every query call appends a bold efficiency line to the response, visible in your AI tool's chat:

**NervaPack:** 1,180 tokens  (naive RAG: 12,840 — **90.8% saved**, ~$0.0292 GPT-4o cost per query)

To see the running total, call show_savings or ask your AI to show it:

"Show me my NervaPack token savings."

Memory Server (`nervapack-memory-mcp`)¶

Persists and recalls structured facts, decisions, and outcomes across agent sessions.

Quick Setup¶

# 1. Install memory support
pip install "nervapack[memory]"

# 2. Initialise
python -m nervapack.memory init

# 3. Add to .mcp.json alongside the knowledge-graph server

{
  "mcpServers": {
    "nervapack": {
      "command": "nervapack-mcp",
      "description": "NervaPack knowledge graph — query_codebase, graph_status, list_entities"
    },
    "nervapack-memory": {
      "command": "nervapack-memory-mcp",
      "description": "NervaPack agent memory — store, recall, and reason over facts across sessions"
    }
  }
}

Tools¶

Tool	Description
`memory_start_session`	Open a named session — call this first every session
`memory_store`	Persist a fact, decision, outcome, procedure, preference, or action
`memory_recall`	FTS5 search → graph expansion → scored, budget-capped recall
`memory_about`	Dossier on one entity: all linked facts/decisions newest first
`memory_why`	Explain a decision: rationale, rejected alternatives, outcomes
`memory_timeline`	Chronological trace including superseded versions
`memory_end_session`	Close the session with an outcome summary
`memory_forget`	Tombstone or hard-purge nodes
`memory_verify`	Confirm (confidence +0.1) or refute (close + confidence ×0.5)
`memory_stats`	Node counts, DB size, top entities, all namespaces
`memory_list_sessions`	List all sessions with node counts, newest first
`memory_clear_session`	Tombstone or hard-purge all nodes in a session
`memory_for_code`	Memories that TOUCH a source file or specific line
`memory_to_code`	Code locations a memory node TOUCHES (file, line range)
`memory_import`	Bulk-seed memory from a JSON array of node specs
`memory_switch_namespace`	Switch the active namespace, resetting the active session
`memory_verify_staleness`	Scan TOUCHES edges; flag memories whose source file changed

Full tool reference: Memory MCP Server.

Using Both Servers Together¶

With both servers registered, Claude Code has:

Structural knowledge (via nervapack) — current code, live function signatures, import graph, coverage.
Historical knowledge (via nervapack-memory) — past decisions, architectural rationale, outcomes from prior sessions.

You:     "Why did we choose JWT over session cookies, and is the auth module still structured that way?"

Claude:  → calls memory_recall("JWT auth decision")  ← history
         → calls query("auth module structure")        ← current code
         → synthesises both into a coherent answer

Storage¶

Server	Data	Location
`nervapack-mcp`	NetworkX graph (graphml) + ChromaDB	`.nervapack/graph.graphml`, `.nervapack/chroma_db/`
`nervapack-memory-mcp`	SQLite (FTS5 + bi-temporal)	`.nervapack/memory.db` or `~/.nervapack/memory.db`

Add .nervapack/ to .gitignore to keep both out of version control.

MCP Server Integration¶

Editor Setup¶

Claude Code¶

Cursor¶

GitHub Copilot (VS Code)¶

Windsurf¶

Full mcp.json¶

Knowledge Graph Server (`nervapack-mcp`)¶

Quick Setup¶

Tools¶

Example Interactions¶

Token savings footer¶

Memory Server (`nervapack-memory-mcp`)¶

Quick Setup¶

Tools¶

Using Both Servers Together¶

Storage¶

See Also¶

MCP Server Integration¶

Editor Setup¶

Claude Code¶

Cursor¶

GitHub Copilot (VS Code)¶

Windsurf¶

Full mcp.json¶

Knowledge Graph Server (nervapack-mcp)¶

Quick Setup¶

Tools¶

Example Interactions¶

Token savings footer¶

Memory Server (nervapack-memory-mcp)¶

Quick Setup¶

Tools¶

Using Both Servers Together¶

Storage¶

See Also¶

Knowledge Graph Server (`nervapack-mcp`)¶

Memory Server (`nervapack-memory-mcp`)¶