# mcp-sqlite-graph-memory

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Python: 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
[![MCP: 2024-11-05](https://img.shields.io/badge/MCP-2024--11--05-green.svg)](https://modelcontextprotocol.io/)

Universal Model Context Protocol (MCP) server delivering **dynamic SQLite-backed code knowledge graph memory** for AI coding assistants and autonomous agents.

Automatically detects active workspaces, parses multi-language ASTs and structural dependencies into an isolated local SQLite knowledge graph, and exposes precision MCP tools to inspect symbols, calculate shortest call/import paths, and navigate code topologies.

---

## 🌟 Key Capabilities

- **Zero Runtime Dependencies**: Written entirely in Python standard library (`ast`, `sqlite3`, `json`, `re`, `hashlib`, `threading`).
- **Dynamic Multi-Workspace Isolation**: Generates deterministic SHA-256 hashes per workspace root; stores isolated SQLite databases in `~/.mcp-graph-memory/storage/graph_<hash>.db`.
- **Incremental Stat Caching**: Verifies file `mtime` and `size` to achieve sub-millisecond skips for unchanged files during re-indexing.
- **Multi-Language AST & Structural Parser**:
  - **Python**: Classes, methods, functions, async functions, decorators, imports (`from x import y`, `import z`), inheritance hierarchies, call sites.
  - **TypeScript / JavaScript**: Classes, interfaces, types, functions, arrow functions, ES6 imports/exports, CommonJS `require()`.
  - **Go**: Packages, imports, structs, interfaces, functions, methods.
  - **Rust**: Modules, structs, enums, traits, `impl` blocks, `fn` signatures.
  - **C / C++ / Java / PHP / Ruby / Kotlin / Swift / Shell**: Structs, classes, definitions.
- **Freeze & CPU Starvation Protection**:
  - Non-blocking asynchronous daemon initialization.
  - Non-busy stdio transport (`for raw_line in sys.stdin:`).
  - Strict ignore list for `node_modules/`, `.git/`, `.venv/`, binary weights, and cache blobs.

---

## 🛠️ MCP Tools Specification

| Tool | Parameters | Description |
| :--- | :--- | :--- |
| `graph_reindex` | `force` (bool), `format` (str) | Scans and updates workspace graph memory incrementally or forced. |
| `graph_query_symbol` | `query` (str), `type` (str), `exact` (bool), `format` (`compact`\|`json`) | Finds symbols with exact file paths, line ranges, signatures, and relations. |
| `graph_find_paths` | `source` (str), `target` (str), `max_depth` (int), `format` (`compact`\|`json`) | Calculates shortest dependency / import / call paths between two files or symbols. |
| `graph_get_neighbors` | `node_id_or_path` (str), `direction` (in/out/both), `relation`, `format` (`compact`\|`json`) | Inspects direct callers, callees, imports, and containment edges. |
| `graph_structure_overview` | `depth` (int), `focus_path` (str), `format` (`compact`\|`json`) | Returns architectural metrics, hub modules, and directory tree. |
| `graph_find_files` | `pattern` (str), `extension` (str), `contains_symbol` (str), `format` (`compact`\|`json`) | Finds workspace files by path pattern, extension, or contained symbols. |

---

## ⚡ Token Minimization & Compact Mode

All query tools support a `format` parameter:
- **`format: "compact"`** (Recommended for AI agents): Formats symbols and graph edges into SCIP-style single-line text (e.g. `[class] OrderService @ service.py#L16-L21 | sig: class OrderService`), achieving **up to 75% reduction in LLM context token consumption**.
- **`format: "json"`**: Serializes responses into compact, unindented single-line JSON, cutting whitespace overhead by ~40%.

---

## 🚀 Installation

```bash
git clone https://github.com/Luiguard/mcp-sqlite-graph-memory.git ~/.mcp-graph-memory
chmod +x ~/.mcp-graph-memory/server.py
```

---

## 🔌 Integration Guides

### 1. Google Antigravity Integration

#### Option A: Global Configuration (Recommended)
Add `graph-memory` to your global Antigravity MCP configuration file at `~/.gemini/config/mcp_config.json`:

```json
{
  "mcpServers": {
    "graph-memory": {
      "command": "python3",
      "args": [
        "/home/YOUR_USER/.mcp-graph-memory/server.py"
      ]
    }
  }
}
```
*(Replace `/home/YOUR_USER` with your actual `$HOME` directory path or use an absolute path).*

#### Option B: Workspace-Level Configuration
For per-project activation, place `mcp_config.json` inside your workspace root under `.agents/mcp_config.json`:

```json
{
  "mcpServers": {
    "graph-memory": {
      "command": "python3",
      "args": [
        "${workspaceFolder}/.mcp-graph-memory/server.py"
      ]
    }
  }
}
```

---

### 2. Claude Desktop Integration

Locate your Claude configuration:
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add the server definition:

```json
{
  "mcpServers": {
    "graph-memory": {
      "command": "python3",
      "args": [
        "/path/to/mcp-sqlite-graph-memory/server.py"
      ]
    }
  }
}
```

---

### 3. Cursor / VSCode / Windsurf Integration

In `.cursor/mcp.json` or `.vscode/mcp.json`:

```json
{
  "mcpServers": {
    "graph-memory": {
      "command": "python3",
      "args": [
        "/path/to/mcp-sqlite-graph-memory/server.py"
      ]
    }
  }
}
```

---

## 🔧 Environment Variables

| Variable | Default | Description |
| :--- | :--- | :--- |
| `MCP_GRAPH_STORAGE_DIR` | `~/.mcp-graph-memory/storage` | Persistent directory for SQLite databases (`graph_<hash>.db`). |
| `MCP_WORKSPACE_ROOT` | `os.getcwd()` | Fallback workspace path if client omits `rootUri` in `initialize`. |

---

## 🧪 Verification & Testing

Execute the automated integration suite:

```bash
python3 test_server.py
```

---

## 📄 License

MIT License - Copyright (c) 2026 **Benjamin Leimer**. See [LICENSE](LICENSE) for details.