How do I use budget-aware-mcp?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@budget-aware-mcp graph walk from main function, max 500 tokens" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

budget-aware-mcp

npm

Model-agnostic code memory MCP server. Budget-aware graph retrieval for AI agents — sub-millisecond queries, token budgeting, deterministic results. No embeddings, no vector DB, no API keys.

Built on CodeGraphContext for 155-language tree-sitter indexing. Replaces their retrieval layer with hop-based graph walks that respect token budgets.

What it does

Any AI agent (Claude, Cursor, Kiro, Aider, Codex, Gemini CLI, etc.) gets structured codebase memory through MCP — instead of reading files manually or wasting tokens on irrelevant context, the agent says "give me context for Emitter, max 8000 tokens" and gets exactly that.

Performance

┌───────────────────────────────┬─────────┬─────────┐
│ Operation                     │ Avg(ms) │ P95(ms) │
├───────────────────────────────┼─────────┼─────────┤
│ Fuzzy search                  │    0.25 │    0.64 │
│ Graph walk depth=2            │    0.07 │    0.11 │
│ Scope check                   │    0.04 │    0.48 │
│ Discover subsystems           │    1.41 │    2.33 │
│ Find similar                  │    0.09 │    0.38 │
│ Index 108 files (41k LOC)     │   84.50 │  101.34 │
└───────────────────────────────┴─────────┴─────────┘

Install

npm install -g budget-aware-mcp
budget-aware-mcp install

Or from source:

git clone https://github.com/Doorman11991/budget-aware-mcp.git
cd budget-aware-mcp
npm install
npm run build

For 155-language tree-sitter support, also install CodeGraphContext:

# Windows
powershell -c "irm https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/install.ps1 | iex"

# macOS/Linux  
curl -fsSL https://raw.githubusercontent.com/CodeGraphContext/CodeGraphContext/main/install.sh | bash

Configure for your AI agent

Add to your MCP config:

{
  "mcpServers": {
    "code-graph": {
      "command": "node",
      "args": ["/path/to/code-graph-mcp/dist/index.js"]
    }
  }
}

Config locations:

Kiro: .kiro/settings/mcp.json
Claude Code: .claude/mcp.json
Cursor: .cursor/mcp.json

Tools (15)

Index Layer

Tool	Description
`index_repo`	Parse files, build symbol graph, persist to SQLite
`list_repos`	List all indexed repositories with stats
`get_repo_stats`	Detailed stats for a specific repo

Retrieval Layer

Tool	Description
`graph_walk`	BFS from anchor symbol, budget-aware, deterministic
`search_graph`	Natural language → fuzzy match → graph walk
`check_scope`	"Is this task feasible?" — no LLM, pure graph heuristic
`trace_call_path`	Shortest path between two symbols
`analyze_impact`	Blast radius from changed files

Fuzzy Discovery

Tool	Description
`fuzzy_find_symbol`	camelCase-splitting symbol search
`find_by_path`	Search by file path pattern
`find_by_signature`	"Something that takes X and returns Y"
`discover_subsystems`	Top-N architectural clusters
`find_similar`	Structural similarity without embeddings
`expand_neighborhood`	Hop=1 from a symbol

Session Tracking

Tool	Description
`get_session_stats`	Cumulative token accounting

How it differs from CodeGraphContext

	CodeGraphContext	code-graph-mcp
Retrieval	BM25 keyword search	Hop-based graph walk with token budget
Token control	None — returns everything	Agent specifies max tokens, retrieval stops there
Determinism	BM25 scores vary	Same query = same result, always
Scope check	Not available	"Is this task feasible given the codebase?"
Impact analysis	Git diff detection	Blast radius mapping (what DEPENDS on changed code)
Session tracking	Not available	Cumulative token spend across queries
Startup	~15ms (native C)	~200ms (Node.js) — but 0.07ms per query once warm

Architecture

AI Agent (any MCP client)
  ↓ stdio (JSON-RPC 2.0)
budget-aware-mcp (this project)
  ├── Retrieval: graph_walk, fuzzy, scope_check, cluster, similarity
  ├── Reads: CodeGraphContext .db files (1500+ nodes, 4000+ edges)
  ├── Fallback: built-in regex parser (~30 languages)
  └── Storage: SQLite (.code-graph/graph.db)

Benchmarks

npm run bench           # In-process latency (sub-millisecond)
npm run bench:compare   # Side-by-side with CodeGraphContext

License

MIT

budget-aware-mcp

budget-aware-mcp

What it does

Performance

Install

Configure for your AI agent

Tools (15)

Index Layer

Retrieval Layer

Fuzzy Discovery

Session Tracking

How it differs from CodeGraphContext

Architecture

Benchmarks

License

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API