Skip to content
Back to search

contextplus

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

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/forloopcodes--contextplus/badge.svg)](/listings/forloopcodes--contextplus)

HTML

<a href="/listings/forloopcodes--contextplus"><img src="/api/listings/forloopcodes--contextplus/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

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": "nomic-embed-text",
        "OLLAMA_CHAT_MODEL": "gemma2:27b",
        "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": "nomic-embed-text",
        "OLLAMA_CHAT_MODEL": "gemma2:27b",
        "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

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

Config file locations:

| IDE | Config File | | ----------- | -------------------- | | Claude Code | `.mcp.json` | | Cursor | `.cursor/mcp.json` | | VS Code | `.vscode/mcp.json` | | Windsurf | `.windsurf/mcp.json` | | OpenCode | `opencode.json` |

CLI Subcommands

- `init [target]` - Generate MCP configuration (targets: `claude`, `cursor`, `vscode`, `windsurf`, `opencode`). - `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).

Including paths excluded by the workspace `.gitignore`

If your workspace `.gitignore` excludes a sub-directory that you still want indexed (common in monorepos where sub-projects under `repos/`, `packages/`, or `vendor/` are gitignored at the top level), use `--include` or `CONTEXTPLUS_EXTRA_ROOTS` to add the paths back.

**CLI form** (repeatable):

bunx contextplus /path/to/workspace \
  --include repos/lacuna \
  --include repos/graphrag-core

**Environment variable** (fallback when no `--include` flag is set; uses the system path separator — `:` on Unix, `;` on Windows):

CONTEXTPLUS_EXTRA_ROOTS=repos/lacuna:repos/graphrag-core \
  bunx contextplus /path/to/workspace

**In `.mcp.json`** the env form is usually more ergonomic:

{
  "mcpServers": {
    "contextplus": {
      "command": "bunx",
      "args": ["contextplus", "/path/to/workspace"],
      "env": {
        "CONTEXTPLUS_EXTRA_ROOTS": "repos/lacuna:repos/graphrag-core"
      }
    }
  }
}

Each path listed is walked **independently** of the workspace root, with a fresh ignore scope. Each path's own `.gitignore` is respected. Paths are validated at startup; invalid entries (non-existent, not a directory, outside the workspace) emit a stderr warning and are skipped.

Nested `.gitignore` files inside the workspace and inside each extra root are loaded and merged with inherited rules, matching `git` and `ripgrep` behavior.

From Source

npm install
npm run build

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 312 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Context+
  2. Semantic Intelligence for Large-Scale Engineering.
  3. Context+ is an MCP server designed for developers who demand 99% accuracy. By combining RAG, Tree-sitter AST, Spectral Clustering, and Obsidian-style linking, Context+ turns a massive codebase into a searchable, hierarchical feature graph.
  4. https://github.com/user-attachments/assets/a97a451f-c9b4-468d-b036-15b65fc13e79
  5. ## Tools
  6. ### Discovery
  7. | Tool | Description |
  8. | ---------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
  9. | `get_context_tree` | Structural AST tree of a project with file headers and symbol ranges (line numbers for functions/classes/methods). Dynamic pruning shrinks output automatically. |
  10. | `get_file_skeleton` | Function signatures, class methods, and type definitions with line ranges, without reading full bodies. Shows the API surface. |
  11. | `semantic_code_search` | Search by meaning, not exact text. Uses embeddings over file headers/symbols and returns matched symbol definition lines. |
  12. | `semantic_identifier_search` | Identifier-level semantic retrieval for functions/classes/variables with ranked call sites and line numbers. |
  13. | `semantic_navigate` | Browse codebase by meaning using spectral clustering. Groups semantically related files into labeled clusters. |
  14. ### Analysis
  15. | Tool | Description |
  16. | --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
  17. | `get_blast_radius` | Trace every file and line where a symbol is imported or used. Prevents orphaned references. |
  18. | `run_static_analysis` | Run native linters and compilers to find unused variables, dead code, and type errors. Supports TypeScript, Python, Rust, Go. |
  19. ### Code Ops
  20. | Tool | Description |
  21. | ----------------- | ------------------------------------------------------------------------------------------------------------------------ |
  22. | `propose_commit` | The only way to write code. Validates against strict rules before saving. Creates a shadow restore point before writing. |
  23. | `get_feature_hub` | Obsidian-style feature hub navigator. Hubs are `.md` files with `[[wikilinks]]` that map features to code files. |
  24. ### Version Control
  25. | Tool | Description |
  26. | --------------------- | ---------------------------------------------------------------------------------------------------------- |
  27. | `list_restore_points` | List all shadow restore points created by `propose_commit`. Each captures file state before AI changes. |
  28. | `undo_change` | Restore files to their state before a specific AI change. Uses shadow restore points. Does not affect git. |
  29. ### Memory & RAG
  30. | Tool | Description |
  31. | ------------------------- | -------------------------------------------------------------------------------------------------------- |
  32. | `upsert_memory_node` | Create or update a memory node (concept, file, symbol, note) with auto-generated embeddings. |
  33. | `create_relation` | Create typed edges between nodes (relates_to, depends_on, implements, references, similar_to, contains). |
  34. | `search_memory_graph` | Semantic search with graph traversal — finds direct matches then walks 1st/2nd-degree neighbors. |
  35. | `prune_stale_links` | Remove decayed edges (e^(-λt) below threshold) and orphan nodes with low access counts. |
  36. | `add_interlinked_context` | Bulk-add nodes with auto-similarity linking (cosine ≥ 0.72 creates edges automatically). |
  37. | `retrieve_with_traversal` | Start from a node and walk outward — returns all reachable neighbors scored by decay and depth. |
  38. > **Complementary server:** [pmll-memory-mcp](https://www.npmjs.com/package/pmll-memory-mcp) (`npx pmll-memory-mcp`) is a separate MCP server by [@drQedwards](https://github.com/drQedwards) that adapts Context+'s long-term memory graph and adds short-term KV context memory, Q-promise deduplication, and a solution engine on top. See [drQedwards/PPM](https://github.com/drQedwards/PPM) for details.
  39. ## Setup
  40. ### Quick Start (npx / bunx)
  41. No installation needed. Add Context+ to your IDE MCP config.
  42. For Claude Code, Cursor, and Windsurf, use `mcpServers`:
  43. ```json
  44. {
  45. "mcpServers": {
  46. "contextplus": {
  47. "command": "bunx",
  48. "args": ["contextplus"],
  49. "env": {
  50. "OLLAMA_EMBED_MODEL": "nomic-embed-text",
  51. "OLLAMA_CHAT_MODEL": "gemma2:27b",
  52. "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
  53. }
  54. }
  55. }
  56. }
  57. ```
  58. For VS Code (`.vscode/mcp.json`), use `servers` and `inputs`:
  59. ```json
  60. {
  61. "servers": {
  62. "contextplus": {
  63. "type": "stdio",
  64. "command": "bunx",
  65. "args": ["contextplus"],
  66. "env": {
  67. "OLLAMA_EMBED_MODEL": "nomic-embed-text",
  68. "OLLAMA_CHAT_MODEL": "gemma2:27b",
  69. "OLLAMA_API_KEY": "YOUR_OLLAMA_API_KEY"
  70. }
  71. }
  72. },
  73. "inputs": []
  74. }
  75. ```
  76. If you prefer `npx`, use:
  77. - `"command": "npx"`
  78. - `"args": ["-y", "contextplus"]`
  79. Or generate the MCP config file directly in your current directory:
  80. ```bash
  81. npx -y contextplus init claude
  82. bunx contextplus init cursor
  83. npx -y contextplus init opencode
  84. ```
  85. Supported coding agent names: `claude`, `cursor`, `vscode`, `windsurf`, `opencode`.
  86. Config file locations:
  87. | IDE | Config File |
  88. | ----------- | -------------------- |
  89. | Claude Code | `.mcp.json` |
  90. | Cursor | `.cursor/mcp.json` |
  91. | VS Code | `.vscode/mcp.json` |
  92. | Windsurf | `.windsurf/mcp.json` |
  93. | OpenCode | `opencode.json` |
  94. ### CLI Subcommands
  95. - `init [target]` - Generate MCP configuration (targets: `claude`, `cursor`, `vscode`, `windsurf`, `opencode`).
  96. - `skeleton [path]` or `tree [path]` - **(New)** View the structural tree of a project with file headers and symbol definitions directly in your terminal.
  97. - `[path]` - Start the MCP server (stdio) for the specified path (defaults to current directory).
  98. ### Including paths excluded by the workspace `.gitignore`
  99. If your workspace `.gitignore` excludes a sub-directory that you still want
  100. indexed (common in monorepos where sub-projects under `repos/`, `packages/`,
  101. or `vendor/` are gitignored at the top level), use `--include` or
  102. `CONTEXTPLUS_EXTRA_ROOTS` to add the paths back.
  103. **CLI form** (repeatable):
  104. ```bash
  105. bunx contextplus /path/to/workspace \
  106. --include repos/lacuna \
  107. --include repos/graphrag-core
  108. ```
  109. **Environment variable** (fallback when no `--include` flag is set; uses the
  110. system path separator — `:` on Unix, `;` on Windows):
  111. ```bash
  112. CONTEXTPLUS_EXTRA_ROOTS=repos/lacuna:repos/graphrag-core \
  113. bunx contextplus /path/to/workspace
  114. ```
  115. **In `.mcp.json`** the env form is usually more ergonomic:
  116. ```json
  117. {
  118. "mcpServers": {
  119. "contextplus": {
  120. "command": "bunx",
  121. "args": ["contextplus", "/path/to/workspace"],
  122. "env": {
  123. "CONTEXTPLUS_EXTRA_ROOTS": "repos/lacuna:repos/graphrag-core"
  124. }
  125. }
  126. }
  127. }
  128. ```
  129. Each path listed is walked **independently** of the workspace root, with a
  130. fresh ignore scope. Each path's own `.gitignore` is respected. Paths are
  131. validated at startup; invalid entries (non-existent, not a directory,
  132. outside the workspace) emit a stderr warning and are skipped.
  133. Nested `.gitignore` files inside the workspace and inside each extra root
  134. are loaded and merged with inherited rules, matching `git` and `ripgrep`
  135. behavior.
  136. ### From Source
  137. ```bash
  138. npm install
  139. npm run build
  140. ```
  141. ## Embedding Providers
  142. Context+ supports two embedding backends controlled by `CONTEXTPLUS_EMBED_PROVIDER`:
  143. | Provider | Value | Requires | Best For |
  144. |----------|-------|----------|----------|
  145. | **Ollama** (default) | `ollama` | Local Ollama server | Free, offline, private |
  146. | **OpenAI-compatible** | `openai` | API key | Gemini (free tier), OpenAI, Groq, vLLM |
  147. ### Ollama (Default)
  148. No extra configuration needed. Just run Ollama with an embedding model:
  149. ```bash
  150. ollama pull nomic-embed-text
  151. ollama serve
  152. ```
  153. ### Google Gemini (Free Tier)
  154. Full Claude Code `.mcp.json` example:
  155. ```json
  156. {
  157. "mcpServers": {
  158. "contextplus": {
  159. "command": "npx",
  160. "args": ["-y", "contextplus"],
  161. "env": {
  162. "CONTEXTPLUS_EMBED_PROVIDER": "openai",
  163. "CONTEXTPLUS_OPENAI_API_KEY": "YOUR_GEMINI_API_KEY",
  164. "CONTEXTPLUS_OPENAI_BASE_URL": "https://generativelanguage.googleapis.com/v1beta/openai",
  165. "CONTEXTPLUS_OPENAI_EMBED_MODEL": "text-embedding-004"
  166. }
  167. }
  168. }
  169. }
  170. ```
  171. Get a free API key at [Google AI Studio](https://aistudio.google.com/apikey).
  172. ### OpenAI
  173. ```json
  174. {
  175. "mcpServers": {
  176. "contextplus": {
  177. "command": "npx",
  178. "args": ["-y", "contextplus"],
  179. "env": {
  180. "CONTEXTPLUS_EMBED_PROVIDER": "openai",
  181. "OPENAI_API_KEY": "sk-...",
  182. "OPENAI_EMBED_MODEL": "text-embedding-3-small"
  183. }
  184. }
  185. }
  186. }
  187. ```
  188. ### Other OpenAI-compatible APIs (Groq, vLLM, LiteLLM)
  189. Any endpoint implementing the [OpenAI Embeddings API](https://platform.openai.com/docs/api-reference/embeddings) works:
  190. ```json
  191. {
  192. "mcpServers": {
  193. "contextplus": {
  194. "command": "npx",
  195. "args": ["-y", "contextplus"],
  196. "env": {
  197. "CONTEXTPLUS_EMBED_PROVIDER": "openai",
  198. "CONTEXTPLUS_OPENAI_API_KEY": "YOUR_KEY",
  199. "CONTEXTPLUS_OPENAI_BASE_URL": "https://your-proxy.example.com/v1",
  200. "CONTEXTPLUS_OPENAI_EMBED_MODEL": "your-model-name"
  201. }
  202. }
  203. }
  204. }
  205. ```
  206. > **Note:** The `semantic_navigate` tool also uses a chat model for cluster labeling. When using the `openai` provider, set `CONTEXTPLUS_OPENAI_CHAT_MODEL` (default: `gpt-4o-mini`).
  207. >
  208. > For VS Code, Cursor, or OpenCode, use the same `env` block inside your IDE's MCP config format (see [Config file locations](#setup) table above).
  209. ## Architecture
  210. Three layers built with TypeScript over stdio using the Model Context Protocol SDK:
  211. **Core** (`src/core/`) - Multi-language AST parsing (tree-sitter, 43 extensions), gitignore-aware traversal, Ollama vector embeddings with disk cache, wikilink hub graph, in-memory property graph with decay scoring.
  212. **Tools** (`src/tools/`) - 17 MCP tools exposing structural, semantic, operational, and memory graph capabilities.
  213. **Git** (`src/git/`) - Shadow restore point system for undo without touching git history.
  214. **Runtime Cache** (`.mcp_data/`) - created on server startup; stores reusable file, identifier, and call-site embeddings to avoid repeated GPU/CPU embedding work. A realtime tracker refreshes changed files/functions incrementally.
  215. ## Config
  216. | Variable | Type | Default | Description |
  217. | --------------------------------------- | ------------------------- | -------------------------------------- | ------------------------------------------------------------- |
  218. | `CONTEXTPLUS_EMBED_PROVIDER` | string | `ollama` | Embedding backend: `ollama` or `openai` |
  219. | `OLLAMA_EMBED_MODEL` | string | `nomic-embed-text` | Ollama embedding model |
  220. | `OLLAMA_API_KEY` | string | - | Ollama Cloud API key |
  221. | `OLLAMA_CHAT_MODEL` | string | `llama3.2` | Ollama chat model for cluster labeling |
  222. | `CONTEXTPLUS_OPENAI_API_KEY` | string | - | API key for OpenAI-compatible provider (alias: `OPENAI_API_KEY`) |
  223. | `CONTEXTPLUS_OPENAI_BASE_URL` | string | `https://api.openai.com/v1` | OpenAI-compatible endpoint URL (alias: `OPENAI_BASE_URL`) |
  224. | `CONTEXTPLUS_OPENAI_EMBED_MODEL` | string | `text-embedding-3-small` | OpenAI-compatible embedding model (alias: `OPENAI_EMBED_MODEL`) |
  225. | `CONTEXTPLUS_OPENAI_CHAT_MODEL` | string | `gpt-4o-mini` | OpenAI-compatible chat model for labeling (alias: `OPENAI_CHAT_MODEL`) |
  226. | `CONTEXTPLUS_EMBED_BATCH_SIZE` | string (parsed as number) | `8` | Embedding batch size per GPU call, clamped to 5-10 |
  227. | `CONTEXTPLUS_EMBED_CHUNK_CHARS` | string (parsed as number) | `2000` | Per-chunk chars before merge, clamped to 256-8000 |
  228. | `CONTEXTPLUS_MAX_EMBED_FILE_SIZE` | string (parsed as number) | `51200` | Skip non-code text files larger than this many bytes |
  229. | `CONTEXTPLUS_EMBED_NUM_GPU` | string (parsed as number) | - | Optional Ollama embed runtime `num_gpu` override |
  230. | `CONTEXTPLUS_EMBED_MAIN_GPU` | string (parsed as number) | - | Optional Ollama embed runtime `main_gpu` override |
  231. | `CONTEXTPLUS_EMBED_NUM_THREAD` | string (parsed as number) | - | Optional Ollama embed runtime `num_thread` override |
  232. | `CONTEXTPLUS_EMBED_NUM_BATCH` | string (parsed as number) | - | Optional Ollama embed runtime `num_batch` override |
  233. | `CONTEXTPLUS_EMBED_NUM_CTX` | string (parsed as number) | - | Optional Ollama embed runtime `num_ctx` override |
  234. | `CONTEXTPLUS_EMBED_LOW_VRAM` | string (parsed as boolean)| - | Optional Ollama embed runtime `low_vram` override |
  235. | `CONTEXTPLUS_EMBED_TRACKER` | string (parsed as boolean)| `true` | Enable realtime embedding refresh on file changes |
  236. | `CONTEXTPLUS_EMBED_TRACKER_MAX_FILES` | string (parsed as number) | `8` | Max changed files processed per tracker tick, clamped to 5-10 |
  237. | `CONTEXTPLUS_EMBED_TRACKER_DEBOUNCE_MS` | string (parsed as number) | `700` | Debounce window before tracker refresh |
  238. ## Test
  239. ```bash
  240. npm test
  241. npm run test:demo
  242. npm run test:all
  243. ```

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.