Context Bridge

An MCP server that captures, stores, and shares the engineering intent behind AI-generated code — the why layer Git is missing.

The Problem

AI coding agents produce the richest engineering documentation ever created — the actual conversation where decisions are made, alternatives rejected, and trade-offs debated. And we throw it all away when the terminal closes.

Context Bridge fixes that.

How It Works

Context Bridge runs as a local MCP server that any AI coding agent can connect to. It provides 8 tools:

Tool	Purpose
context_init	Set up context-bridge in a git repo (dirs, config, pre-commit hook)
context_commit	Capture a decision/constraint/insight linked to the current git commit
context_finalize	Rename pending context to actual commit SHA after git commit
context_query	Search captured context semantically using fuzzy matching
context_list	List all context entries with optional filters (tags, types, commit)
context_share	Share filtered context with a specific recipient
context_export	Export context as a portable .context.json file
context_import	Import shared context from another developer/agent

All context is stored locally in SQLite (.context-bridge/store.db in your project directory). Per-commit context is also written to .context-bridge/commits/{short-sha}.json for git-trackable history. No cloud, no server, no accounts.

Getting Started

# 1. Install
npm install -g context-bridge

# 2. In your project (via MCP), call context_init
# This creates .context-bridge/ dir, installs pre-commit hook, updates .gitignore

# 3. Start committing with context!

Agent Workflow

Agent writes code → stages changes → context_commit(commit_sha="pending")
                  → git commit -m "message"
                  → context_finalize (renames _pending.json → {sha}.json)

The pre-commit hook automatically stages .context-bridge/ files, so the context JSON is included in the same commit as the code changes.

Installation

# Clone and build
git clone https://github.com/yugonline/context-bridge.git
cd context-bridge
npm install
npm run build

# Or install globally
npm install -g .

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "context-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/context-bridge/dist/index.js"],
      "cwd": "/path/to/your/project"
    }
  }
}

Cursor

Add to your .cursor/mcp.json in your project root:

{
  "mcpServers": {
    "context-bridge": {
      "command": "node",
      "args": ["/absolute/path/to/context-bridge/dist/index.js"]
    }
  }
}

Any MCP Client (Generic)

Context Bridge uses stdio transport — the standard for local MCP servers. Point your MCP client at:

command: node /path/to/context-bridge/dist/index.js
transport: stdio

Set the working directory to your project root so the SQLite database is created in the right place.

Usage

Once connected, your AI agent has access to the tools automatically. Examples:

Committing Decisions (linked to git)

Ask your agent: "Capture that we chose JWT over session cookies for auth"

The agent calls context_commit with:

{
  "type": "decision",
  "summary": "Chose JWT over session cookies for auth",
  "reasoning": "Need stateless auth for horizontal scaling. Sessions require sticky sessions or shared store.",
  "tags": ["auth", "architecture"],
  "related_files": ["src/auth/jwt.ts"],
  "confidence": "high"
}

The entry is stored in SQLite and written to .context-bridge/commits/{sha}.json, linking it to the current git HEAD. You can also pass an explicit commit_sha.

Querying Context

Ask your agent: "Why did we choose JWT for auth?"

{
  "query": "Why did we choose JWT for auth?",
  "tags": ["auth"]
}

You can filter by commit too:

{
  "query": "auth decisions",
  "commit_sha": "abc1234",
  "commit_range": "v1.0..v2.0"
}

Sharing Context

Share decisions with a teammate directly:

{
  "recipient": "alice",
  "tags": ["auth"],
  "message": "Here's the auth context for the new service"
}

This creates .context-bridge/shared/alice-2026-04-11T17-00-00.context.json with all matching entries packaged for import.

Listing by Commit

{
  "commit_sha": "abc1234"
}

Or a range:

{
  "commit_range": "main~5..main"
}

Export / Import

Export your decisions for bulk sharing:

// context_export
{ "tags": ["auth"], "path": "./shared/auth-context.json" }

They import it:

// context_import
{ "source": "./shared/auth-context.json" }

The .context.json Format

Context Bridge uses a portable JSON format for sharing:

{
  "version": "1.0",
  "created_by": "yug",
  "created_at": "2026-04-11T17:00:00Z",
  "project": "my-app",
  "entries": [
    {
      "id": "ctx_abc123",
      "type": "decision",
      "summary": "Chose JWT over session cookies",
      "reasoning": "Need stateless auth for horizontal scaling...",
      "tags": ["auth", "architecture"],
      "related_files": ["src/auth/jwt.ts"],
      "confidence": "high",
      "timestamp": "2026-04-11T16:30:00Z",
      "parent_id": null,
      "references": [],
      "commit_sha": "a1b2c3d4e5f6..."
    }
  ]
}

Entry Types

Type	Use For
decision	Architectural or implementation choices
constraint	Requirements, limitations, or boundaries
rejected_alternative	Options considered and why they were rejected
insight	Observations, learnings, or discoveries
todo	Future work or known gaps

Storage

• SQLite database at {project}/.context-bridge/store.db
• Per-commit JSON files at {project}/.context-bridge/commits/{sha}.json
• Shared context at {project}/.context-bridge/shared/
• Add .context-bridge/store.db to your .gitignore
• Optionally track .context-bridge/commits/ in git for commit-linked context history

License

MIT