Context Bridge

Bridge the context gap between your codebase and AI coding tools.

Context Bridge is a lightweight MCP (Model Context Protocol) server that builds a persistent index of your codebase. It enables AI assistants to query complex codebases with sub-millisecond latency, eliminating the need to re-read files every session.

Why?

AI coding tools are powerful but suffer from a context gap:

• They re-read the same files in every session

• They lack deep understanding of your architecture

• They can't learn from your coding conventions

• 23 minutes of developer focus are lost per context switch

Context Bridge solves this by indexing your codebase into a local store that persists across sessions.

Related MCP server: CodeRAG

Features

• Fast Code Search — Full-text keyword search over every indexed file

• Persistent Index — SQLite-based, survives restarts

• Sub-millisecond Queries — SQLite FTS5

• MCP Protocol — Works with Claude Code, Cursor, and any MCP client

• Auto-indexing — Watches files and updates the index automatically

• Zero Cloud — Everything runs locally

Quick Start

# Clone and install locally
git clone https://github.com/hussain-alsaibai/context-bridge.git
cd context-bridge && npm install

# Initialize in your project
cd your-project
node /path/to/context-bridge/src/server.js init

# Start the MCP server
node /path/to/context-bridge/src/server.js serve

# Or use with Claude Code
claude mcp add context-bridge -- node /path/to/context-bridge/src/server.js serve

Note: the unscoped npm name context-bridge is owned by an unrelated third-party package, so npm install -g context-bridge installs that package instead of this one. Use the clone-and-install steps above until an official npm release under a scoped name is available.

Configuration

Create .context-bridge.json in your project root:

{
  "include": ["src/**/*.{js,ts,jsx,tsx}", "lib/**/*.py"],
  "exclude": ["node_modules/**", "dist/**", "*.test.js"],
  "dbPath": ".context-bridge/db.sqlite",
  "watch": true,
  "maxFileSizeKB": 500
}

MCP Tools

Search syntax: search_code is a keyword engine, not a semantic one. It takes an FTS5 query string, so slugify or index* match, and a natural sentence like how do we index files does not. Combine terms with OR, or use a prefix *.

Architecture

┌─────────────────┐     ┌──────────────┐     ┌────────────────┐
│  Claude Code    │────▶│ Context      │────▶│ SQLite + FTS5  │
│  Cursor         │     │ Bridge MCP   │     │ Knowledge Graph│
│  Other MCP      │◀────│ Server       │◀────│ (persistent)   │
│  Clients        │     │              │     │                │
└─────────────────┘     └──────────────┘     └────────────────┘
                               │
                               ▼
                        ┌──────────────┐
                        │ File Watcher │
                        │ (auto-index) │
                        └──────────────┘

Status

v0.2.2 — the README now matches the server, and every tool it names is reachable.

• v0.1.0 shipped on 2026-06-20 and was broken: it threw on startup, matched no files, and lost the index on every re-index. It was fixed on 2026-10-25 in commit 2cc4ee9.

• The standalone indexer (src/indexer.js) never indexed anything — it started the MCP server instead. Fixed in v0.2.0.

• v0.2.0 shipped a handler that read {tool, params}. No MCP client sends that shape — clients speak JSON-RPC {jsonrpc, id, method, params} — so every real request arrived with tool === undefined and fell through to "Unknown tool: undefined". The four existing tests stayed green because they asserted the same wrong shape. Fixed in v0.2.1 (commit 688f79c), which adds a contract test that drives a real handshake over stdio.

• CI now runs on every push and pull request: install, test, lint.

• v0.2.1 shipped a README that advertised five MCP tools. The server implemented four and advertised one, so get_symbol, get_dependencies and summarize_module were unreachable for any client that discovers tools by listing them. get_callers was advertised in the README but implemented nowhere, and the relationships table it would have queried was created and never populated -- the README described a graph feature that did not exist. The README also claimed "FTS5 + precomputed embeddings" and natural-language search; there are no embeddings, and search_code is a keyword engine. Fixed in v0.2.2, which advertises all four real tools and drops the claims.

• get_dependencies returned imports: [] for ordinary ES modules. The pattern only matched a bare specifier directly after the keyword, so import { a } from "./x" -- the most common form -- was missed, as was export { a } from "./x". Fixed in v0.2.2.

Run the test suite with npm test (10 tests). One of them parses this README and fails if it documents a tool the server does not implement or advertise, so this drift cannot come back.

License

MIT