mcp-context-bridge 0.1.0

Unified context layer connecting local data to LLMs via MCP

Context Bridge

A unified context layer that connects your local data — repositories, documents, remote machines, and notes — to LLM interfaces through the Model Context Protocol (MCP).

Installation • Configuration • Connectors • Contributing

The Problem

Modern LLMs are powerful but context-starved. They don't know about:

• Your local codebase structure and recent changes
• Your Obsidian notes and personal knowledge base
• Your remote servers and their configurations
• Your project's documentation and dependencies
• Your PostgreSQL database schemas and query history
• Your Docker container logs and running services

You end up copy-pasting snippets or trying to explain complex contexts in a chat window.

The Solution

Context Bridge runs locally, reads your data sources, and exposes them to any MCP-compatible LLM client (Claude Desktop, Cursor, Continue, Aether, etc.). It handles authentication, caching, chunking, and real-time updates so the LLM always has relevant context.

Installation

From PyPI (recommended)

pip install context-bridge

From Source

git clone https://github.com/Codinglone/context-bridge.git
cd context-bridge
make install

Quick Start

# Generate a starter config
context-bridge init ~/.config/context-bridge/config.yaml

# Set your GitHub token (optional, for GitHub connector)
export GITHUB_TOKEN="ghp_..."

# Start the MCP server (stdio mode for Claude Desktop)
context-bridge serve

# Or start in HTTP mode for browser extension support
context-bridge serve --transport http

Why Context Bridge?

What you do today

Want LLM to see...	Your workflow right now
Local code	Copy-paste files, or hope the editor's index is current
GitHub PR + issues	Open browser, copy links, paste context
Obsidian notes	Export to text, paste into chat
PostgreSQL schema	Run \d in psql, copy output
Docker logs	docker logs ..., copy-paste
Remote server files	SSH, cat, copy-paste

Each source is a separate manual step. Ten minutes later the LLM still might miss that the DB migration in PR #42 changed a column name.

What Context Bridge enables

One MCP server exposes structured tools for every source. The LLM can query across boundaries in a single conversation turn:

You: "Why is my deploy failing?"

LLM calls:
  docker.get_logs("api-container")     → sees the error
  github.get_pr("my-app", 42)          → sees the migration
  pg.get_schema("users")               → confirms the column rename
  obsidian.get_note("deploy runbook")  → finds your troubleshooting notes
  fs.read_file("src/db/migrations/042_*.sql")  → reads the actual migration

The LLM gets the same situational awareness you have when sitting at your terminal — without you copy-pasting anything.

Key advantages

• Unified toolset — One server, all sources. No context switching between browser, terminal, and chat.
• Real-time sync — File watchers push updates within seconds. No stale indexes.
• Structured tools — obsidian.get_backlinks("Next Steps") returns your link graph. pg.get_schema("users") returns column types + constraints. Way better than raw text dumps.
• Privacy-first — SSH keys, DB passwords, vault contents stay local. Only the data you choose goes to the LLM.
• Pluggable — Need a new source? Write one connector. The rest of the system doesn't change.

Key Features

• Filesystem Connector: Watch local directories, respect .gitignore, provide file contents and tree structure
• GitHub Connector: Fetch repository code, issues, PRs, and discussions via API
• SSH Connector: Execute commands and read files on remote VMs/servers
• Obsidian Connector: Index your vault, follow wiki-links, search by tags and backlinks
• PostgreSQL Connector: Introspect schemas, list tables, view recent query history
• Docker Connector: Inspect running containers, stream logs, view service status
• MCP Server: Standard MCP protocol — works with any compatible client
• Smart Chunking: RAG-style retrieval so you don't burn context windows on irrelevant data
• Real-time Sync: File watchers push updates to connected clients automatically

Configuration

Context Bridge reads from ~/.config/context-bridge/config.yaml. Create it with:

context-bridge init ~/.config/context-bridge/config.yaml

Minimal Example

server:
  transport: stdio  # stdio for Claude Desktop; http for remote
  port: 8080

connectors:
  filesystem:
    - path: ~/projects
      name: projects
      exclude: [node_modules, .git, __pycache__]

  github:
    token: ${GITHUB_TOKEN}
    repos: ["owner/repo"]
    cache_ttl: 300

  obsidian:
    vault: ~/Documents/Obsidian Vault
    exclude: [.git, attachments, .trash]

  docker:
    socket: unix:///var/run/docker.sock

Filesystem Connector

Watch local directories with file change detection:

connectors:
  filesystem:
    - path: ~/projects
      name: projects
      exclude: [node_modules, .git, __pycache__, .venv, target, dist, build]
      max_file_size: 1048576  # 1 MB

• path: Directory to watch
• name: Alias used in tool calls
• exclude: Patterns to ignore
• max_file_size: Reject files larger than this (bytes)

GitHub Connector

Access public and private repositories via the GitHub API:

connectors:
  github:
    token: ${GITHUB_TOKEN}
    repos:
      - owner/repo
      - owner/another-repo
    cache_ttl: 300  # seconds

Token setup:

1. Go to https://github.com/settings/tokens
2. Generate a Classic token with repo scope
3. Export it: export GITHUB_TOKEN="ghp_..."

SSH Connector

Execute commands and read files on remote servers:

connectors:
  ssh:
    - host: prod-server
      user: deploy
      port: 22
      key: ~/.ssh/id_rsa

• host: Alias or hostname
• user: SSH username
• port: SSH port (default 22)
• key: Path to private key (uses SSH agent if omitted)

Tools exposed:

• ssh.run_command("prod-server", "df -h")
• ssh.read_file("prod-server", "/var/log/syslog")
• ssh.list_dir("prod-server", "/etc")

PostgreSQL Connector

Introspect schemas and run read-only queries:

connectors:
  postgresql:
    - name: local-dev
      connection_string: postgresql://user:pass@localhost:5432/mydb
      schemas: [public]
      query_timeout: 30
      # ssh_tunnel: bastion  # Optional: tunnel through SSH host

Connection string formats:

• URL: postgresql://user:pass@host:5432/dbname
• Key-value: host=localhost port=5432 dbname=mydb user=postgres password=secret

SSH Tunnel for remote databases:

If your database is behind a bastion host, add the SSH host first, then reference it:

connectors:
  ssh:
    - host: bastion
      user: admin
      port: 22
      key: ~/.ssh/id_rsa

  postgresql:
    - name: remote-db
      connection_string: postgresql://dbuser:[e-mail]:5432/app
      schemas: [public]
      query_timeout: 30
      ssh_tunnel: bastion  # References the SSH host above

Context Bridge will:

1. Open an SSH connection to the bastion
2. Create a local port forward
3. Rewrite the connection string to use 127.0.0.1:<random_port>
4. Connect PostgreSQL through the tunnel

Tools exposed:

• pg.list_tables("local-dev", "public")
• pg.get_schema("local-dev", "public", "users")
• pg.get_indexes("local-dev", "public", "users")
• pg.get_foreign_keys("local-dev", "public", "users")
• pg.run_query("local-dev", "SELECT * FROM users LIMIT 5")

Obsidian Connector

Index and query your Obsidian vault:

connectors:
  obsidian:
    vault: ~/Documents/Obsidian Vault
    exclude: [.git, attachments, .trash]

Features:

• Full-text search across all notes
• Wiki-link graph traversal ([[Note Title]])
• Tag extraction (#tag)
• Backlink discovery
• Frontmatter parsing
• Real-time re-indexing on file changes

Tools exposed:

• obsidian.search("deploy")
• obsidian.get_note("Next Steps")
• obsidian.get_backlinks("Context Bridge")
• obsidian.get_tags()

Docker Connector

Inspect running containers:

connectors:
  docker:
    socket: unix:///var/run/docker.sock
    include_stopped: false
    max_log_lines: 500

Tools exposed:

• docker.list_containers()
• docker.get_logs("api-container", tail=100)
• docker.inspect("api-container")
• docker.list_services() # Docker Compose projects

Connecting to Claude Desktop

Add to Claude Desktop's MCP config (~/.config/claude-desktop/config.json):

{
  "mcpServers": {
    "context-bridge": {
      "command": "/home/codinglone/Documents/projects/context-bridge/.venv/bin/python",
      "args": ["-m", "context_bridge.cli", "serve"]
    }
  }
}

Restart Claude Desktop. The LLM will now see all your configured tools.

Web-Based Chatbots (ChatGPT, Claude Web, etc.)

Web-based chatbots don't support MCP natively — they run in a browser sandbox with no access to your local filesystem. Context Bridge provides three integration paths:

Option 1: Browser Extension (Recommended)

A Chrome extension is included in extensions/chrome/.

Installation:

# 1. Start Context Bridge in HTTP mode
context-bridge serve --transport http

# 2. Load the extension
# Open Chrome → chrome://extensions/ → Enable Developer Mode → Load Unpacked
# Select: extensions/chrome/

Features:

• @context trigger button appears on ChatGPT, Claude, and Poe pages
• Browse all connectors and tools in a searchable modal
• Execute tools with arguments
• Insert results directly into the chat input or copy to clipboard
• Extension popup for quick tool access from the toolbar

Architecture:

Browser Extension → localhost:8080 → Context Bridge → Your Data
     ↓
Injects context into ChatGPT/Claude/Poe web UI

Option 2: HTTP Server + Manual Copy-Paste

For quick testing without installing the extension:

context-bridge serve --transport http
# Open http://localhost:8080 in browser
# Click tools, copy results, paste into chat

Option 3: Aether Native Integration

Since you have an aether repo, integrate Context Bridge directly into your own AI interface:

from context_bridge.server import ContextBridgeServer
from context_bridge.config import ContextBridgeConfig

config = ContextBridgeConfig.from_yaml("config.yaml")
server = ContextBridgeServer(config)
await server.router.initialize_all()

# In your chat handler:
result = await server.router.call_tool("github.get_file", {
    "repo": "Codinglone/aether",
    "path": "src/main.py"
})
# Feed result.context into your LLM prompt

This gives you full control — no browser sandbox, no copy-paste, no extensions.

Option 4: Proxy Bridge (Advanced)

Run Context Bridge as a proxy between the web chatbot's API and your data:

User → Web Chatbot API (OpenAI/Anthropic)
         ↓
    Context Bridge intercepts the prompt
         ↓
    Injects relevant context from fs/github/obsidian/etc.
         ↓
    Forwards enriched prompt to LLM
         ↓
    Returns response to user

This requires building a middleware layer but gives fully automatic context injection.

Status

All 6 connectors implemented with real-world integration tests. See docs/DESIGN.md and docs/ARCHITECTURE.md for design docs.

License

MIT