[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-81612":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":12,"stars30d":13,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":15,"rankGlobal":9,"rankLanguage":9,"license":16,"archived":17,"fork":17,"defaultBranch":18,"hasWiki":19,"hasPages":17,"topics":20,"createdAt":9,"pushedAt":9,"updatedAt":21,"readmeContent":22,"aiSummary":23,"trendingCount":14,"starSnapshotCount":14,"syncStatus":13,"lastSyncTime":24,"discoverSource":25},81612,"budget-aware-mcp","Doorman11991\u002Fbudget-aware-mcp","Doorman11991","Model-agnostic code memory MCP server. Budget-aware graph retrieval for AI agents. Sub-millisecond queries, token budgeting, deterministic results. Built on CodeGraphContext.",null,"TypeScript",24,1,2,0,41.6,"MIT License",false,"master",true,[],"2026-06-12 04:01:34","# budget-aware-mcp\n\n[![npm](https:\u002F\u002Fimg.shields.io\u002Fnpm\u002Fv\u002Fbudget-aware-mcp)](https:\u002F\u002Fwww.npmjs.com\u002Fpackage\u002Fbudget-aware-mcp)\n[![CI](https:\u002F\u002Fgithub.com\u002FDoorman11991\u002Fbudget-aware-mcp\u002Factions\u002Fworkflows\u002Fci.yml\u002Fbadge.svg)](https:\u002F\u002Fgithub.com\u002FDoorman11991\u002Fbudget-aware-mcp\u002Factions)\n\nModel-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.\n\nBuilt on [CodeGraphContext](https:\u002F\u002Fgithub.com\u002FCodeGraphContext\u002FCodeGraphContext) for 155-language tree-sitter indexing. Replaces their retrieval layer with hop-based graph walks that respect token budgets.\n\n## Why this exists\n\nEvery other code MCP tool dumps context at you — \"here's 50k tokens of everything I found.\" Your agent's context overflows, it hallucinates, or it wastes money processing irrelevant code.\n\n**budget-aware-mcp** is different: the agent says \"give me context for `AuthService`, max 8000 tokens\" and gets exactly 8000 tokens of the most structurally-relevant code, walking outward from the anchor symbol hop by hop until the budget is hit. No waste. No overflow.\n\n## Install\n\n```bash\nnpm install -g budget-aware-mcp\nbudget-aware-mcp install\n```\n\nAuto-detects and configures: **Kiro, Claude Code, Cursor, VS Code, Windsurf, Zed, Codex CLI, Gemini CLI, Aider, OpenCode**.\n\nOr from source:\n\n```bash\ngit clone https:\u002F\u002Fgithub.com\u002FDoorman11991\u002Fbudget-aware-mcp.git\ncd budget-aware-mcp\nnpm install && npm run build\nbudget-aware-mcp install\n```\n\n## Performance\n\n```\n┌───────────────────────────────┬─────────┬─────────┐\n│ Operation                     │ Avg(ms) │ P95(ms) │\n├───────────────────────────────┼─────────┼─────────┤\n│ Graph walk depth=2            │    0.07 │    0.11 │\n│ Fuzzy search                  │    0.25 │    0.64 │\n│ Explain symbol                │    8.00 │   12.00 │\n│ Scope check                   │    0.04 │    0.48 │\n│ Discover architecture         │    1.41 │    2.33 │\n│ Index 108 files (41k LOC)     │  529.00 │  600.00 │\n└───────────────────────────────┴─────────┴─────────┘\n```\n\nQueries are sub-millisecond once the server is warm. Semantic cache makes repeated\u002Fsimilar queries instant.\n\n## Tools (22)\n\n### Index\n| Tool | Description |\n|------|-------------|\n| `index_repo` | Parse files, build symbol graph, persist to SQLite. 155 languages via tree-sitter. |\n| `list_repos` | List all indexed repositories with stats |\n| `get_repo_stats` | Detailed stats: symbol kinds, languages, edge types, top connected symbols |\n\n### Retrieval\n| Tool | Description |\n|------|-------------|\n| `graph_walk` | BFS from anchor symbol. Budget-aware, deterministic, hop-limited. |\n| `search_graph` | Natural language → fuzzy match → graph walk. Semantic cache enabled. |\n| `check_scope` | \"Is this task feasible?\" — answers without calling any LLM. |\n| `trace_call_path` | Shortest path between two symbols via call\u002Fimport edges. |\n| `analyze_impact` | Blast radius: what breaks if these files change? |\n\n### Discovery\n| Tool | Description |\n|------|-------------|\n| `fuzzy_find_symbol` | camelCase\u002Fsnake_case splitting search. Semantic cache enabled. |\n| `find_by_path` | Search files by path pattern |\n| `find_by_signature` | \"Something that takes User and returns Token\" |\n| `discover_subsystems` | Architecture overview: clusters, hotspots, entry points, languages |\n| `find_similar` | Structural similarity without embeddings |\n| `expand_neighborhood` | Hop=1 from a symbol — bridge into the full graph |\n\n### Context\n| Tool | Description |\n|------|-------------|\n| `get_file_context` | File + all its dependencies, within token budget |\n| `explain_symbol` | One-shot: signature, callers, callees, location, connectivity |\n| `suggest_files` | \"What files should I look at for this task?\" — ranked by relevance |\n| `find_dead_code` | Symbols with zero inbound edges (nothing calls them) |\n| `get_code_snippet` | Read actual source code with line numbers |\n| `search_code` | Full-text regex search across file contents with context |\n\n### Management\n| Tool | Description |\n|------|-------------|\n| `delete_project` | Remove an indexed repository from the graph |\n| `get_session_stats` | Cumulative token accounting across all queries |\n\n## Key Features (unique to budget-aware-mcp)\n\nThese features don't exist in [CodeGraphContext](https:\u002F\u002Fgithub.com\u002FCodeGraphContext\u002FCodeGraphContext) or any other code MCP server. CodeGraphContext is a **required dependency** for full 155-language tree-sitter indexing — we build our retrieval layer on top of their index.\n\n---\n\n### 1. Token Budget Per Query\n\n**Problem:** Other tools return everything they find. An agent asks \"what's relevant to auth?\" and gets 50,000 tokens of code. Most of it is irrelevant. The agent's context window overflows or it wastes money processing junk.\n\n**Our solution:** Every query has a `max_tokens` parameter. The graph walk starts at your anchor symbol, walks outward along real call\u002Fimport edges, and stops adding context the moment the budget is hit.\n\n```\nAgent: graph_walk(\"AuthService\", hop_depth=2, max_tokens=8000)\n\nResult: 20 symbols across 12 files, exactly 7,998 tokens.\n        Stopped at hop 2 because adding the next symbol would exceed 8000.\n```\n\nThe agent asked for 8000. It got 8000. Not 50,000. Not 3,000. Exactly what it asked for, filled with the most structurally-connected code first.\n\n---\n\n### 2. Token Accounting Per Session\n\n**Problem:** Agents have no idea how much context they've consumed across a conversation. After 10 queries they might have blown through 100k tokens without realizing it.\n\n**Our solution:** Every query is tracked. The agent can ask at any time: \"how much have I spent?\"\n\n```\nAgent: get_session_stats()\n\nResult:\n  total_queries: 8\n  total_tokens_returned: 24,500\n  repos_indexed: 2\n  coverage: 12% of codebase explored\n```\n\nThis lets agents make smart decisions: \"I've already seen 24k tokens — do I need more context or should I start generating?\" Instead of blindly reading more files, the agent knows its budget.\n\n---\n\n### 3. Scope\u002FFeasibility Check\n\n**Problem:** An agent decides to \"refactor the PaymentProcessor class.\" It generates 200 lines of code referencing `PaymentProcessor`, `StripeAdapter`, and `WebhookHandler`. None of those exist in the codebase. The agent hallucinated the entire thing.\n\n**Our solution:** Before generating code, the agent asks \"is this task doable?\"\n\n```\nAgent: check_scope(\"refactor PaymentProcessor to support Stripe webhooks\")\n\nResult:\n  feasibility: \"unknown\"\n  found_symbols: []\n  missing_symbols: [\"PaymentProcessor\", \"Stripe\", \"webhook\"]\n  confidence: 0.1\n\n→ Agent knows: these symbols don't exist. Don't generate code for them.\n```\n\nvs.\n\n```\nAgent: check_scope(\"refactor the Emitter class to support multiple targets\")\n\nResult:\n  feasibility: \"full\"\n  found_symbols: [\"Emitter\"]\n  confidence: 0.95\n\n→ Agent knows: Emitter exists, go ahead.\n```\n\nZero LLM calls. Pure graph lookup. Prevents wasted generation attempts.\n\n---\n\n### 4. Blast-Radius Impact Analysis\n\n**Problem:** Other tools detect \"these files changed\" (git diff). That's not useful for an agent planning a refactor — it needs to know \"if I change THIS, what ELSE breaks?\"\n\n**Our solution:** Given a list of changed files, walks the dependency graph backwards to find everything that depends on the changed code.\n\n```\nAgent: analyze_impact(changed_files=[\"auth.ts\"], hop_depth=2)\n\nResult:\n  changed_symbols: [\"AuthService\", \"validateToken\", \"refreshSession\"]\n  blast_radius: 14 symbols across 8 files depend on these\n  affected_files: [\"routes\u002Fuser.ts\", \"middleware\u002Fauth.ts\", \"services\u002Fpayment.ts\", ...]\n```\n\nThe agent now knows: \"If I change auth.ts, I might break 8 other files. Let me check those too before I submit this PR.\"\n\n---\n\n### 5. Deterministic Ordering\n\n**Problem:** BM25 search scores change based on index state, document frequency, and other factors. The same query returns different results on different days. You can't reproduce a bug, you can't write reliable tests, you can't trust the output.\n\n**Our solution:** Same query, same result. Every time. No exceptions.\n\nHow: within each hop level of the graph walk, symbols are sorted alphabetically by FQN. The walk is BFS (breadth-first), so hop 0 is always the anchor, hop 1 is always its direct connections sorted A-Z, hop 2 is always THEIR connections sorted A-Z.\n\n```\nRun 1: graph_walk(\"Emitter\", 2, 8000) → [Emitter, emitBudget, emitCache, emitCheckpoint, ...]\nRun 2: graph_walk(\"Emitter\", 2, 8000) → [Emitter, emitBudget, emitCache, emitCheckpoint, ...]\nRun 3: graph_walk(\"Emitter\", 2, 8000) → [Emitter, emitBudget, emitCache, emitCheckpoint, ...]\n```\n\nAlways the same. Debuggable. Reproducible. Testable.\n\n---\n\n### 6. Multi-Hop Walk With Budget Cutoff\n\n**Problem:** A flat search returns \"here are 20 results ranked by keyword relevance.\" But code isn't flat — it's a graph. `AuthService` calls `TokenValidator` which calls `CryptoUtils`. You need to understand the CHAIN, not just individual matches.\n\n**Our solution:** Start at a symbol. Walk outward along actual call\u002Fimport\u002Finheritance edges. Each \"hop\" adds the next layer of connected code. Stop when the budget is full.\n\n```\nHop 0: AuthService (the thing you asked about)\nHop 1: validateToken, refreshSession, hashPassword (things AuthService calls)\nHop 2: CryptoUtils, SessionStore, TokenBlacklist (things THOSE call)\n        ↑ stopped here — budget hit at 8000 tokens\n```\n\nThis gives the agent a **connected subgraph** — not a flat list. It understands the call chain, the dependencies, the architecture. In 8000 tokens instead of reading 12 files manually (50,000+ tokens).\n\n---\n\n## Dependency: CodeGraphContext\n\nbudget-aware-mcp uses [CodeGraphContext](https:\u002F\u002Fgithub.com\u002FCodeGraphContext\u002FCodeGraphContext) as its indexing engine. When installed, it provides:\n- 155-language tree-sitter parsing\n- 4000+ edges per project (calls, imports, inheritance, usage)\n- Incremental re-indexing\n- 3D graph visualization (localhost:9749)\n\nInstall it for best results:\n```bash\n# Windows\npowershell -c \"irm https:\u002F\u002Fraw.githubusercontent.com\u002FCodeGraphContext\u002FCodeGraphContext\u002Fmain\u002Finstall.ps1 | iex\"\n\n# macOS\u002FLinux\ncurl -fsSL https:\u002F\u002Fraw.githubusercontent.com\u002FCodeGraphContext\u002FCodeGraphContext\u002Fmain\u002Finstall.sh | bash\n```\n\nWithout CodeGraphContext, budget-aware-mcp falls back to its built-in regex parser (~30 languages, 86% edge coverage). Everything still works — just fewer edges to walk.\n- **Entry points**: functions with high out-degree but low in-degree\n- **Language breakdown**: files and LOC per language\n\n## How it differs from CodeGraphContext\n\n| | CodeGraphContext | budget-aware-mcp |\n|---|---|---|\n| **Retrieval** | BM25 keyword search | Hop-based graph walk with token budget |\n| **Token control** | None — returns everything | Agent specifies max, retrieval stops there |\n| **Determinism** | BM25 scores vary | Same query = same result, always |\n| **Caching** | None | Semantic cache (similar queries → instant) |\n| **Scope check** | Not available | \"Is this task feasible?\" |\n| **Explain symbol** | Not available | One call: signature + callers + callees |\n| **File context** | Not available | File + all dependencies in one shot |\n| **Suggest files** | Not available | Task → ranked file list |\n| **Dead code** | Not available | Zero-inbound-edge detection |\n| **Session tracking** | Not available | Cumulative token spend |\n| **Code reading** | `get_code_snippet` | `get_code_snippet` + `search_code` |\n| **Architecture** | Packages, layers, routes | Clusters, hotspots, entry points |\n| **Startup** | ~15ms (native C) | ~200ms (Node.js) — 0.07ms per query once warm |\n\n## Architecture\n\n```\nAI Agent (any MCP client)\n  ↓ stdio (JSON-RPC 2.0)\nbudget-aware-mcp\n  ├── Semantic Cache (trigram similarity, 5min TTL)\n  ├── Retrieval (graph_walk, fuzzy, scope_check, cluster, similarity)\n  ├── Context (get_file_context, explain_symbol, suggest_files)\n  ├── Code Access (get_code_snippet, search_code)\n  ├── CodeGraphContext .db (when installed — 155 langs, 4000+ edges)\n  ├── Built-in parser (regex + call resolution — 30 langs, 3500+ edges)\n  └── SQLite (.code-graph\u002Fgraph.db)\n```\n\n## CLI\n\n```bash\nbudget-aware-mcp              # Run MCP server on stdio\nbudget-aware-mcp install      # Auto-detect agents, configure MCP\nbudget-aware-mcp uninstall    # Remove MCP config from all agents\nbudget-aware-mcp --version    # Show version\nbudget-aware-mcp --help       # Show help\n```\n\n## Development\n\n```bash\nnpm test              # Run 19-test suite\nnpm run bench         # In-process latency benchmarks\nnpm run bench:compare # Side-by-side with CodeGraphContext\n```\n\n## License\n\nMIT\n","budget-aware-mcp 是一个模型无关的代码内存MCP服务器，专为AI代理提供预算感知的图检索功能。其核心特性包括亚毫秒级查询、令牌预算管理和确定性结果输出，无需使用嵌入、向量数据库或API密钥。该工具基于CodeGraphContext构建，支持155种编程语言的tree-sitter索引，并通过跳数限制的图遍历来替代传统的检索层。适用于需要高效且精准地获取代码上下文的开发场景，如自动化代码理解与分析任务中，能够显著减少不必要的数据处理开销并避免上下文溢出问题。","2026-06-11 04:05:41","CREATED_QUERY"]