Semantic Intelligence for Large-Scale Engineering.

Context+ is an MCP server designed for developers who demand 99% accuracy. By combining Tree-sitter AST, Spectral Clustering, and Obsidian-style linking, Context+ turns a massive codebase into a searchable, hierarchical feature graph.

Local Install

For local development, install the linked contextplus CLI with:

What it does:

• runs npm install
• runs npm run build
• runs npm link
• verifies the linked contextplus command resolves to this checkout

After editing this repo, rebuild the linked CLI with:

Because npm link points contextplus at this checkout’s build/index.js, future builds update the command Codex launches.

To add it to Codex, put this in ~/.codex/config.toml as a separate manual step:

[mcp_servers.contextplus]
command = "contextplus"
args = []

[mcp_servers.contextplus.env]
OLLAMA_EMBED_MODEL = "qwen3-embedding:0.6b-32k"
OLLAMA_CHAT_MODEL = "nemotron-3-nano:4b-128k"
CONTEXTPLUS_EMBED_BATCH_SIZE = "8"
CONTEXTPLUS_EMBED_TRACKER = "lazy"

Tools

Discovery

Analysis

Code Ops

Version Control

Setup

Quick Start (npx / bunx)

No installation needed. Add Context+ to your IDE MCP config.

For Claude Code, Cursor, and Windsurf, use mcpServers:

{
  "mcpServers": {
    "contextplus": {
      "command": "bunx",
      "args": ["contextplus"],
      "env": {
        "OLLAMA_EMBED_MODEL": "qwen3-embedding:0.6b-32k",
        "OLLAMA_CHAT_MODEL": "nemotron-3-nano:4b-128k",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
      }
    }
  }
}

For VS Code (.vscode/mcp.json), use servers and inputs:

{
  "servers": {
    "contextplus": {
      "type": "stdio",
      "command": "bunx",
      "args": ["contextplus"],
      "env": {
        "OLLAMA_EMBED_MODEL": "qwen3-embedding:0.6b-32k",
        "OLLAMA_CHAT_MODEL": "nemotron-3-nano:4b-128k",
        "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
      }
    }
  },
  "inputs": []
}

If you prefer npx, use:

• "command": "npx"
• "args": ["-y", "contextplus"]

Or generate the MCP config file directly in your current directory:

npx -y contextplus init claude
bunx contextplus init cursor
npx -y contextplus init opencode
bunx contextplus init codex

Supported coding agent names: claude, cursor, vscode, windsurf, opencode, codex.

Config file locations:

CLI Subcommands

• init [target] - Generate MCP configuration (targets: claude, cursor, vscode, windsurf, opencode, codex).
• index [path] [--mode=core|full] - Create or refresh .contextplus/ for the target repo. Defaults to full mode. The authoritative durable machine state now lives only in state/index.sqlite. core persists the project config, context-tree export, file manifest, stage state, indexing status, and eager file/identifier search state in SQLite. full also persists first-class AST chunk artifacts, hybrid chunk and identifier retrieval indexes, richer code-structure artifacts, and the full-manifest plus embedding caches in SQLite. The structure layer now includes per-file imports, exports, calls, symbols, dependency paths, normalized symbol records, file-to-symbol maps, ownership edges, module summaries, and module import edges. The hybrid layer stores lexical term maps alongside embedding-cache keys so later search surfaces can combine lexical and dense evidence without rebuilding transient indexes. Refresh uses file content hashes for file and identifier artifacts, file-plus-chunk content hashes for chunk reuse, and dependency hashes for structure artifacts so local import changes invalidate affected downstream files. Legacy JSON artifact files are deleted during bootstrap so the database remains the only source of truth. The persisted contract metadata covers supported modes, stage order, sqlite-only storage, invalidation rules, and crash-only failure semantics.
• validate_index - Verify that a prepared core or full index is still version-compatible and internally consistent before query tools rely on it.
• repair_index - Repair a broken prepared index by rerunning core, full, or a specific stage target like full-artifacts, then revalidate the result.
• skeleton [path] or tree [path] - (New) View the structural tree of a project with file headers and symbol definitions directly in your terminal.
• [path] - Start the MCP server (stdio) for the specified path (defaults to current directory).

Codex

Codex uses project-scoped TOML configuration in .codex/config.toml:

[mcp_servers.contextplus]
command = "bunx"
args = ["contextplus"]

[mcp_servers.contextplus.env]
OLLAMA_EMBED_MODEL = "qwen3-embedding:0.6b-32k"
OLLAMA_CHAT_MODEL = "nemotron-3-nano:4b-128k"
OLLAMA_API_KEY = "YOUR_OLLAMA_API_KEY"
CONTEXTPLUS_EMBED_BATCH_SIZE = "8"
CONTEXTPLUS_EMBED_TRACKER = "lazy"

From Source

npm install
npm run build

Embedding Providers

Context+ supports two embedding backends controlled by CONTEXTPLUS_EMBED_PROVIDER:

Ollama (Default)

No extra configuration needed. Just run Ollama with an embedding model:

ollama pull qwen3-embedding:0.6b-32k
ollama pull nemotron-3-nano:4b-128k
ollama serve

Google Gemini (Free Tier)

Full Claude Code .mcp.json example:

{
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "CONTEXTPLUS_OPENAI_API_KEY": "YOUR_GEMINI_API_KEY",
        "CONTEXTPLUS_OPENAI_BASE_URL": "https://generativelanguage.googleapis.com/v1beta/openai",
        "CONTEXTPLUS_OPENAI_EMBED_MODEL": "text-embedding-004"
      }
    }
  }
}

Get a free API key at Google AI Studio.

OpenAI

{
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "OPENAI_API_KEY": "sk-...",
        "OPENAI_EMBED_MODEL": "text-embedding-3-small"
      }
    }
  }
}

Other OpenAI-compatible APIs (Groq, vLLM, LiteLLM)

Any endpoint implementing the OpenAI Embeddings API works:

{
  "mcpServers": {
    "contextplus": {
      "command": "npx",
      "args": ["-y", "contextplus"],
      "env": {
        "CONTEXTPLUS_EMBED_PROVIDER": "openai",
        "CONTEXTPLUS_OPENAI_API_KEY": "YOUR_KEY",
        "CONTEXTPLUS_OPENAI_BASE_URL": "https://your-proxy.example.com/v1",
        "CONTEXTPLUS_OPENAI_EMBED_MODEL": "your-model-name"
      }
    }
  }
}

Note: The cluster tool also uses a chat model for cluster labeling. When using the openai provider, set CONTEXTPLUS_OPENAI_CHAT_MODEL (default: gpt-4o-mini).

For VS Code, Cursor, or OpenCode, use the same env block inside your IDE's MCP config format (see Config file locations table above).

Architecture

Three layers built with TypeScript over stdio using the Model Context Protocol SDK:

Core (src/core/) - Multi-language AST parsing (tree-sitter, 43 extensions), gitignore-aware traversal, Ollama vector embeddings with disk cache, and wikilink hub graph.

Tools (src/tools/) - MCP tools exposing structural, semantic, and operational codebase capabilities.

Git (src/git/) - Shadow restore point system for undo without touching git history.

Project State (.contextplus/) - created by index; stores repo-local config, context-tree snapshots, indexing status, persisted stage state for rerunnable indexing stages, persisted file and identifier search state, full-mode derived chunk, code-structure, semantic-cluster, and hub-suggestion artifacts, restore-point manifests, embedding caches, and suggested hub markdown under .contextplus/hubs/suggested/. Later searches refresh only changed files before querying the prepared state.

Config

Test

npm test
npm run test:demo
npm run test:all