| Name | code-graph-rag-mcp JSON |
| Version |
0.1.2
JSON |
| download |
| home_page | None |
| Summary | Local-first code knowledge graph MCP server |
| upload_time | 2025-10-14 22:45:17 |
| maintainer | None |
| docs_url | None |
| author | Andrew |
| requires_python | >=3.10 |
| license | None |
| keywords |
|
| VCS |
|
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# Code GraphRAG MCP Server
A Model Context Protocol server for source-code introspection. It keeps a local-first knowledge graph for your repositories: Tree-sitter derived symbols and relations, AST-aligned chunks, EmbeddingGemma vectors stored in sqlite-vec, and graph traversal through bfsvtab. Wheels ship the native extensions, so the server starts instantly with `uvx`.
## Features
- Hybrid retrieval combining vector search and breadth-first graph expansion over code relations
- Live repository sync via filesystem watcher and job queue
- Deterministic provenance for every symbol, relation, and chunk
- Bundled sqlite-vec and bfsvtab binaries—no manual compilation required
## Installation
```bash
uvx code-graph-rag-mcp serve --config /workspace/config.yaml
```
### MCP manifest example
```json
{
"mcpServers": {
"code-graph": {
"command": "uvx",
"args": ["code-graph-rag-mcp", "serve", "--config", "/workspace/config.yaml"],
"env": {
"CODE_GRAPH_RAG_WATCH_DIR": "/workspace/repo",
"CODE_GRAPH_RAG_DB_PATH": "/workspace/data/code.sqlite"
}
}
}
}
```
This manifest block works for Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), or any other MCP host.
## Configuration
### Minimal `config.yaml`
```yaml
watch:
dir: "/workspace/repo"
database:
sqlite_path: "/workspace/data/code.sqlite"
```
### Environment overrides
| Variable | Description |
| --- | --- |
| `CODE_GRAPH_RAG_CONFIG` | Alternate path to the YAML config. |
| `CODE_GRAPH_RAG_WATCH_DIR` | Override repository directory to watch. |
| `CODE_GRAPH_RAG_WATCH_DEBOUNCE_MS` | Debounce delay (ms) for watcher events. |
| `CODE_GRAPH_RAG_DB_PATH` | Override SQLite database location. |
| `CODE_GRAPH_RAG_EXTENSIONS_DIR` | Directory containing custom sqlite-vec/bfsvtab binaries. |
| `CODE_GRAPH_RAG_SQLITE_VEC` / `CODE_GRAPH_RAG_BFSVTAB` | Explicit extension paths. |
| `CODE_GRAPH_RAG_RETRIEVAL_K` | Default semantic top-k. |
| `CODE_GRAPH_RAG_RETRIEVAL_HOPS` | Graph expansion hop count. |
| `CODE_GRAPH_RAG_EMBED_MODEL` / `CODE_GRAPH_RAG_EMBED_ENDPOINT` | Embedding model overrides. |
## Available tools
| Tool | Purpose |
| --- | --- |
| `ingest_repo` | Full ingest or reingest of the repository. |
| `refresh_path` | Reindex a single file. |
| `purge_path` | Remove a file and its graph artifacts. |
| `hybrid_search` | Semantic + graph search returning chunks with BFS neighbors. |
| `symbol_lookup` | Fuzzy lookup of symbols by name. |
| `explain_symbol` | Show metadata, owning chunk, and outgoing edges for a node ID. |
| `status` | Report ingest counts and extension readiness. |
## Architecture overview
1. **Watcher → queue** – `watchfiles` monitors the repo and enqueues jobs on create/modify/delete.
2. **Indexer** – Tree-sitter adapters extract symbols/relations; the chunker builds AST-aligned snippets; EmbeddingGemma generates embeddings.
3. **SQLite** – files, nodes, edges, chunks, and vectors live in sqlite-vec tables; bfsvtab enables efficient BFS traversal.
4. **MCP surface** – tools expose ingest, search, and introspection over stdio to any MCP client.
## Example workflow
1. Start the server with `uvx` and point it at your repository.
2. Call `ingest_repo` to seed the database.
3. Use `hybrid_search` to find relevant code; responses include semantic scores plus graph neighbors.
4. Inspect specific nodes with `explain_symbol` or `symbol_lookup`.
5. Work normally—the watcher reindexes files as they change.
## Development
```bash
python -m venv .venv
source .venv/bin/activate
pip install -e .[dev]
pytest
```
Rebuild the bundled sqlite-vec/bfsvtab binaries (only if needed) with:
```bash
python scripts/build_sqlite_extensions.py
```
## Support
- File issues or feature requests in this repository.
- Learn more about MCP at [modelcontextprotocol.io](https://modelcontextprotocol.io).
- License: MIT.
Raw data
{
"_id": null,
"home_page": null,
"name": "code-graph-rag-mcp",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": null,
"author": "Andrew",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/ae/20/376db8320c4a28b1043cf458df15c220ad11f24fe25f4df0a14b27f96e95/code_graph_rag_mcp-0.1.2.tar.gz",
"platform": null,
"description": "# Code GraphRAG MCP Server\n\nA Model Context Protocol server for source-code introspection. It keeps a local-first knowledge graph for your repositories: Tree-sitter derived symbols and relations, AST-aligned chunks, EmbeddingGemma vectors stored in sqlite-vec, and graph traversal through bfsvtab. Wheels ship the native extensions, so the server starts instantly with `uvx`.\n\n## Features\n\n- Hybrid retrieval combining vector search and breadth-first graph expansion over code relations\n- Live repository sync via filesystem watcher and job queue\n- Deterministic provenance for every symbol, relation, and chunk\n- Bundled sqlite-vec and bfsvtab binaries\u2014no manual compilation required\n\n## Installation\n\n```bash\nuvx code-graph-rag-mcp serve --config /workspace/config.yaml\n```\n\n### MCP manifest example\n\n```json\n{\n \"mcpServers\": {\n \"code-graph\": {\n \"command\": \"uvx\",\n \"args\": [\"code-graph-rag-mcp\", \"serve\", \"--config\", \"/workspace/config.yaml\"],\n \"env\": {\n \"CODE_GRAPH_RAG_WATCH_DIR\": \"/workspace/repo\",\n \"CODE_GRAPH_RAG_DB_PATH\": \"/workspace/data/code.sqlite\"\n }\n }\n }\n}\n```\n\nThis manifest block works for Claude Desktop (`claude_desktop_config.json`), Cursor (`~/.cursor/mcp.json`), or any other MCP host.\n\n## Configuration\n\n### Minimal `config.yaml`\n\n```yaml\nwatch:\n dir: \"/workspace/repo\"\ndatabase:\n sqlite_path: \"/workspace/data/code.sqlite\"\n```\n\n### Environment overrides\n\n| Variable | Description |\n| --- | --- |\n| `CODE_GRAPH_RAG_CONFIG` | Alternate path to the YAML config. |\n| `CODE_GRAPH_RAG_WATCH_DIR` | Override repository directory to watch. |\n| `CODE_GRAPH_RAG_WATCH_DEBOUNCE_MS` | Debounce delay (ms) for watcher events. |\n| `CODE_GRAPH_RAG_DB_PATH` | Override SQLite database location. |\n| `CODE_GRAPH_RAG_EXTENSIONS_DIR` | Directory containing custom sqlite-vec/bfsvtab binaries. |\n| `CODE_GRAPH_RAG_SQLITE_VEC` / `CODE_GRAPH_RAG_BFSVTAB` | Explicit extension paths. |\n| `CODE_GRAPH_RAG_RETRIEVAL_K` | Default semantic top-k. |\n| `CODE_GRAPH_RAG_RETRIEVAL_HOPS` | Graph expansion hop count. |\n| `CODE_GRAPH_RAG_EMBED_MODEL` / `CODE_GRAPH_RAG_EMBED_ENDPOINT` | Embedding model overrides. |\n\n## Available tools\n\n| Tool | Purpose |\n| --- | --- |\n| `ingest_repo` | Full ingest or reingest of the repository. |\n| `refresh_path` | Reindex a single file. |\n| `purge_path` | Remove a file and its graph artifacts. |\n| `hybrid_search` | Semantic + graph search returning chunks with BFS neighbors. |\n| `symbol_lookup` | Fuzzy lookup of symbols by name. |\n| `explain_symbol` | Show metadata, owning chunk, and outgoing edges for a node ID. |\n| `status` | Report ingest counts and extension readiness. |\n\n## Architecture overview\n\n1. **Watcher \u2192 queue** \u2013 `watchfiles` monitors the repo and enqueues jobs on create/modify/delete.\n2. **Indexer** \u2013 Tree-sitter adapters extract symbols/relations; the chunker builds AST-aligned snippets; EmbeddingGemma generates embeddings.\n3. **SQLite** \u2013 files, nodes, edges, chunks, and vectors live in sqlite-vec tables; bfsvtab enables efficient BFS traversal.\n4. **MCP surface** \u2013 tools expose ingest, search, and introspection over stdio to any MCP client.\n\n## Example workflow\n\n1. Start the server with `uvx` and point it at your repository.\n2. Call `ingest_repo` to seed the database.\n3. Use `hybrid_search` to find relevant code; responses include semantic scores plus graph neighbors.\n4. Inspect specific nodes with `explain_symbol` or `symbol_lookup`.\n5. Work normally\u2014the watcher reindexes files as they change.\n\n## Development\n\n```bash\npython -m venv .venv\nsource .venv/bin/activate\npip install -e .[dev]\npytest\n```\n\nRebuild the bundled sqlite-vec/bfsvtab binaries (only if needed) with:\n\n```bash\npython scripts/build_sqlite_extensions.py\n```\n\n## Support\n\n- File issues or feature requests in this repository.\n- Learn more about MCP at [modelcontextprotocol.io](https://modelcontextprotocol.io).\n- License: MIT.\n",
"bugtrack_url": null,
"license": null,
"summary": "Local-first code knowledge graph MCP server",
"version": "0.1.2",
"project_urls": null,
"split_keywords": [],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "e8b2f414633cb3b0ad2b278f679bd3a134ef00170601507fe42a50bc1dd0059d",
"md5": "f4ac6d5a0741634680b9668d9924db9f",
"sha256": "783fcad1549ab469c9cba01e7efc0c72247d542b0a3d0fa1b5aa7be054159405"
},
"downloads": -1,
"filename": "code_graph_rag_mcp-0.1.2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "f4ac6d5a0741634680b9668d9924db9f",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 105476,
"upload_time": "2025-10-14T22:45:16",
"upload_time_iso_8601": "2025-10-14T22:45:16.146816Z",
"url": "https://files.pythonhosted.org/packages/e8/b2/f414633cb3b0ad2b278f679bd3a134ef00170601507fe42a50bc1dd0059d/code_graph_rag_mcp-0.1.2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "ae20376db8320c4a28b1043cf458df15c220ad11f24fe25f4df0a14b27f96e95",
"md5": "e84fb473796d5719b62111fe1f1a94ca",
"sha256": "2dc3fffd81f9a18b89a59c3a846e5676b017048235a74bb90aed0b79254d433e"
},
"downloads": -1,
"filename": "code_graph_rag_mcp-0.1.2.tar.gz",
"has_sig": false,
"md5_digest": "e84fb473796d5719b62111fe1f1a94ca",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 95320,
"upload_time": "2025-10-14T22:45:17",
"upload_time_iso_8601": "2025-10-14T22:45:17.480409Z",
"url": "https://files.pythonhosted.org/packages/ae/20/376db8320c4a28b1043cf458df15c220ad11f24fe25f4df0a14b27f96e95/code_graph_rag_mcp-0.1.2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-10-14 22:45:17",
"github": false,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"lcname": "code-graph-rag-mcp"
}
