context-mcp-server 1.0.6 → 1.0.8

package/README.md

@@ -1,31 +1,35 @@
-# context-mcp
+<p align="center">
+  <img src="src/assests/main.png" alt="context-mcp" />
+</p>
 
-Persistent memory and codebase knowledge graph for AI coding assistants — delivered as a single MCP server.
+<p align="center">
+  <a href="https://www.npmjs.com/package/context-mcp-server"><img src="https://img.shields.io/npm/v/context-mcp-server?style=flat-square" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/context-mcp-server"><img src="https://img.shields.io/npm/dm/context-mcp-server?style=flat-square" alt="npm downloads" /></a>
+  <a href="LICENSE"><img src="https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square" alt="License: MIT" /></a>
+  <a href="package.json"><img src="https://img.shields.io/node/v/context-mcp-server?style=flat-square" alt="Node.js" /></a>
+</p>
 
-One shared context store. Works across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Claude.ai, and ChatGPT. Save context from one AI, pick it up in another. Your memory follows the project, not the tool.
+Persistent memory and codebase knowledge graph for AI coding assistants — delivered as a single MCP server.
 
-**6 AI platforms** · **6 IDEs** · **16 programming languages** (Python, JS, TS, Go, Rust, Java, Kotlin, C, C++, C#, Ruby, PHP, Swift, Lua, and more) · tree-sitter AST parsing with regex fallback
+One shared context store across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Claude.ai, and ChatGPT. Save context from one AI, pick it up in another.
 
 ---
 
 ## The Problem
 
-Every conversation with an AI assistant starts from zero. The AI re-reads files it already read yesterday, re-discovers architecture it already understood, re-derives decisions that were already made. You repeat context. You paste the same background. You explain the same things.
+Every conversation with an AI assistant starts from zero. The AI re-reads files it already read yesterday, re-discovers architecture it already understood, re-derives decisions that were already made. You repeat context. You paste the same background.
 
-This gets worse as projects grow. A codebase with 50 files means the AI either reads all of them every time (burning thousands of tokens) or misses context and gives wrong answers.
+This gets worse as projects grow — reading 20 files to answer "what calls this function?" burns thousands of tokens every time.
 
 ---
 
-## What context-mcp Solves
+## What It Solves
 
-**1. You lose context between conversations.**
-AI assistants have no memory. Every new chat is a blank slate. context-mcp gives the AI a persistent store of decisions, bugs, notes, and architecture — loaded automatically at conversation start.
+- **Persistent memory** — decisions, bugs, notes, and config saved across sessions, loaded automatically at conversation start
+- **Shared store** — `~/.context-mcp/projects/<name>/` per-project on your machine; all AI tools read and write it
+- **ContextGraph** — build a knowledge graph of your codebase once, answer structural questions in ~500 tokens instead of ~50,000
 
-**2. Context is siloed to one tool.**
-You fix a bug with Claude Code, then open Cursor and it knows nothing about it. context-mcp stores everything in `~/.context-mcp/` — a single shared store on your machine. Any AI that connects reads and writes the same store.
-
-**3. Structural understanding costs too many tokens.**
-Reading 20 files to answer "what calls this function?" is wasteful. context-mcp builds a knowledge graph of your codebase once, then answers structural questions in ~500 tokens instead of ~50,000.
+Real measured reduction on this project: **162× fewer tokens**, **99.38% reduction** per conversation.
 
 ---
 
@@ -35,36 +39,37 @@ Reading 20 files to answer "what calls this function?" is wasteful. context-mcp
 npm install -g context-mcp-server
 ```
 
-That's it. One command installs everything — the MCP server, HTTP server, and `ctx` CLI.
+Requires Node.js ≥ 18. Installs `context-mcp`, `context-mcp-http`, and the `ctx` CLI.
 
-Then run from your project root:
+**ContextGraph requires [uv](https://docs.astral.sh/uv/)** (Python runner). Memory tools work without it.
 
 ```bash
-ctx install --all
+# macOS / Linux
+curl -Ls https://astral.sh/uv/install.sh | sh
+
+# Windows
+winget install astral-sh.uv
 ```
 
-This writes MCP config + AI instruction files for every platform **and** automatically sets up the Python codegraph environment if [uv](https://docs.astral.sh/uv/) is installed.
+---
 
-> **CodeGraph requires uv.** Install it first if you want graph features:
-> ```bash
-> curl -Ls https://astral.sh/uv/install.sh | sh   # macOS / Linux
-> winget install astral-sh.uv                      # Windows
-> ```
-> Memory tools work with npm alone — uv is only needed for `codegraph_build` and graph queries.
+## Quick Start
 
-Requires Node.js ≥ 18.
+Run from your project root:
 
-Installs three commands:
+```bash
+ctx install --initial
+```
 
-| Command | What it runs |
-|---------|-------------|
-| `context-mcp` | Stdio MCP server (for local AI clients) |
-| `context-mcp-http` | HTTP MCP server with OAuth 2.0 (for web clients) |
-| `ctx` | Interactive CLI — browse, search, manage context |
+This installs Node.js + Python (ContextGraph) dependencies. Run once after installing the npm package.
 
----
+Then write MCP config + AI instruction files:
 
-## Platform Setup
+```bash
+ctx install --all
+```
+
+To install for a specific platform only:
 
 ```bash
 ctx install --claude      # Claude Code
@@ -73,398 +78,132 @@ ctx install --vscode      # VS Code Copilot
 ctx install --gemini      # Gemini CLI
 ctx install --codex       # Codex CLI
 ctx install --windsurf    # Windsurf
-ctx install --all         # all platforms + Python setup at once
 ```
 
-Run from your project root. Each command writes the MCP config file and AI instruction file for that platform, then checks for uv and sets up the Python codegraph environment.
+For web clients (Claude.ai, ChatGPT), start the HTTP server:
 
----
-
-### Claude Code
-
-`ctx install --claude` writes:
-- `.claude/mcp.json` — MCP server config
-- `CLAUDE.md` — instructions Claude reads automatically at conversation start
-
-Manual config — add to `.claude/mcp.json`:
-
-```json
-{
-  "mcpServers": {
-    "context-mcp": {
-      "command": "npx",
-      "args": ["-y", "context-mcp-server@latest"]
-    }
-  }
-}
+```bash
+ctx online               # start in background, prints OAuth credentials + URL
+ctx online --restart     # force restart
+ctx online --port 3200   # different port
 ```
 
 ---
 
-### Cursor
-
-`ctx install --cursor` writes:
-- `.cursor/mcp.json` — MCP server config
-- `.cursor/rules/context-mcp.mdc` — Cursor rules file
-
-Manual config — add to `.cursor/mcp.json`:
+## CLI Reference
 
-```json
-{
-  "mcpServers": {
-    "context-mcp": {
-      "command": "npx",
-      "args": ["-y", "context-mcp-server@latest"]
-    }
-  }
-}
-```
+Both `ctx` and `context` are aliases for the same CLI.
 
----
+```bash
+ctx                            # interactive mode (UI)
 
-### VS Code Copilot
+# Context
+ctx list [project]             # list entries by tree: graph / context / summary / plans
+ctx projects                   # all projects with graph status + recent entries
+ctx search "query"             # keyword → semantic fallback search
+ctx add                        # add entry interactively
+ctx summary [project]          # summarize recent entries
 
-`ctx install --vscode` writes:
-- `.vscode/mcp.json` — MCP server config
-- `CLAUDE.md` — instruction file
+# Delete
+ctx delete <id-prefix>         # delete one entry
+ctx delete project <name>      # delete all entries for a project
 
-Manual config — add to `.vscode/mcp.json`:
+# Server
+ctx online                     # start HTTP server (idempotent)
+ctx online --restart           # force stop + restart
+ctx settings                   # view and edit config interactively
 
-```json
-{
-  "servers": {
-    "context-mcp": {
-      "type": "stdio",
-      "command": "npx",
-      "args": ["-y", "context-mcp-server@latest"]
-    }
-  }
-}
+# Tools
+ctx benchmark                  # token savings report (memory + graph)
 ```
 
 ---
 
-### Gemini CLI
+## Security
 
-`ctx install --gemini` writes:
-- `.gemini/settings.json` — MCP server config
-- `GEMINI.md` — instructions Gemini reads automatically
-
-Manual config — add to `.gemini/settings.json`:
+File and git tools are sandboxed to your project root. Pass `rootPath` when calling `context.resume`:
 
 ```json
-{
-  "mcpServers": {
-    "context-mcp": {
-      "command": "npx",
-      "args": ["-y", "context-mcp-server@latest"]
-    }
-  }
-}
+{ "action": "resume", "project": "my-app", "rootPath": "/home/user/my-app" }
 ```
 
----
-
-### Codex CLI
-
-`ctx install --codex` writes:
-- `.codex/config.toml` — MCP server config
-- `AGENTS.md` — instructions Codex reads automatically
-
-Manual config — add to `.codex/config.toml`:
-
-```toml
-[[mcp_servers]]
-name    = "context-mcp"
-command = "npx"
-args    = ["-y", "context-mcp-server@latest"]
-```
+Any file or git operation outside that directory is rejected. Applies to all HTTP-connected clients.
 
 ---
 
-### Windsurf
-
-`ctx install --windsurf` writes:
-- `.windsurf/rules/context-mcp.md` — local rules file (project scope)
-- `~/.codeium/windsurf/mcp_config.json` — global MCP config (merged, not overwritten)
-
-Manual config — add to `~/.codeium/windsurf/mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "context-mcp": {
-      "command": "npx",
-      "args": ["-y", "context-mcp-server@latest"]
-    }
-  }
-}
-```
-
----
+## Features
 
-### Claude.ai / ChatGPT (HTTP mode)
+### Memory
 
-Web-based clients connect over HTTP with OAuth 2.0. Use `ctx online` to start the HTTP server.
+- `context.resume` — loads recent entries, active plans, and graph status; registers `rootPath` for sandboxing
+- `context.save` — store context with 4 types: `decision`, `bug`, `note`, `config`
+- `context.get` / `context.update` / `context.delete` — full CRUD, single or batch
+- `search` — keyword-first, semantic fallback
+- `plan` — auto-triggered when AI makes any plan; saves a markdown summary to a `planDir` you specify
+- Auto-deduplication on save; auto-compact at 20 entries → stored in `summary.json`
 
-**Step 1 — Start the server:**
+### ContextGraph
 
-```bash
-ctx online
-```
+> Also called **CodeGraph**. MCP tools use the `codegraph_*` prefix — both names mean the same thing.
 
-Starts the server in the background, shows your OAuth credentials, and prints the endpoint URL. Safe to re-run — won't start a second copy.
+**Step 1 — Build** (once per project, runs locally, no API cost):
 
-```bash
-ctx online --restart   # force restart
-ctx online --port 3200 # use a different port
 ```
-
-Or start directly:
-
-```bash
-context-mcp-http --port 3100 --host localhost --access-git
+codegraph_build(path)
 ```
 
-**Step 2 — Add as a remote MCP connector:**
-
-1. Go to Claude.ai → Settings → Integrations → Add MCP Connector
-2. Enter your server URL (e.g. `http://localhost:3100`)
-3. Use the **Client ID** and **Client Secret** from `~/.context-mcp/contextconfig.json`
+Parses codebase via tree-sitter AST (16 languages, regex fallback). Extracts functions, classes, imports, call edges. Build metadata saved to `~/.context-mcp/projects/<name>/graph.json`.
 
-**View or edit config:**
+**Step 2 — Query** (instant, forever):
 
-```bash
-ctx settings
 ```
-
----
-
-## Path Sandboxing (Security)
-
-File and git tools are sandboxed to your project root. Pass `rootPath` when calling `context.resume` to register it:
-
-```json
-{ "action": "resume", "project": "my-app", "rootPath": "/home/user/my-app" }
+codegraph_query(path, question?, node?)   → structural question OR single-node lookup (or both)
+codegraph_path(path, from, to)            → shortest path between two concepts
+codegraph_nodes(path, type)               → list all nodes of a type
+codegraph_report(path)                    → god nodes, clusters, surprising connections
 ```
 
-The root is stored permanently with the project. Any file or git operation outside that directory is rejected. This applies to all HTTP-connected clients (Claude.ai, ChatGPT) — they can only access files within the registered project root.
+`codegraph_query` accepts `question` (natural language), `node` (exact/partial name for type + file + deps + callers), or both in one call. Use before reading any files.
 
----
+### File & Git Tools
 
-## CLI Reference
-
-```bash
-ctx                                  # open interactive mode
-
-# Context
-ctx list [project]                   # list entries, discussions, graphs
-ctx projects                         # all projects with IDs, graph status, recent entries
-ctx search "query"                   # keyword → semantic fallback search
-ctx add                              # add entry interactively
-ctx summary [project]                # summarize recent entries
-
-# Delete
-ctx delete <id-prefix>               # delete one entry by ID prefix
-ctx delete project <name|id>         # delete all entries for a project
+Available to HTTP-connected clients (Claude.ai, ChatGPT). Local AI clients use their native IDE tools.
 
-# Server
-ctx online                           # start HTTP server (idempotent)
-ctx online --restart                 # force stop + restart
-ctx online --port 3200               # use a different port
-ctx settings                         # view and edit config interactively
-
-# Setup
-ctx install --claude                 # write MCP config for Claude Code
-ctx install --cursor                 # write MCP config for Cursor
-ctx install --vscode                 # write MCP config for VS Code
-ctx install --gemini                 # write MCP config for Gemini CLI
-ctx install --codex                  # write MCP config for Codex CLI
-ctx install --windsurf               # write MCP config for Windsurf
-ctx install --all                    # all platforms + Python setup
+- `read_file`, `write_file`, `patch_file`, `create_dir`, `list_dir`, `delete_file`
+- `git_status`, `git_diff`, `git_log`, `git_add`, `git_commit`, `git_push`, `git_pull`, `git_branch`, `git_stash`, `git_reset`, `git_show`
 
-# Tools
-ctx benchmark                        # real token savings report (memory + graph)
-ctx discuss [project]                # view discussions
-```
+Enable git tools with `--access-git` flag or `access_git: true` in config.
 
 ---
 
 ## Server Flags
 
-### `context-mcp` (stdio)
-
 ```
-context-mcp [options]
+context-mcp [--data-dir <path>]
 
-Options:
-  --data-dir <path>   Override storage directory (default: ~/.context-mcp)
-                      Also via env: CONTEXT_MCP_DIR=<path>
-  --help, -h          Show help
+context-mcp-http [--port <number>] [--host <string>] [--access-git] [--data-dir <path>]
 ```
 
-### `context-mcp-http` (HTTP + OAuth)
-
-```
-context-mcp-http [options]
-
-Options:
-  --port <number>     HTTP listen port (default: 3100)
-  --host <string>     Bind address (default: localhost)
-  --access-git        Enable git tools for connected clients
-  --data-dir <path>   Override storage directory (default: ~/.context-mcp)
-                      Also via env: CONTEXT_MCP_DIR=<path>
-  --help, -h          Show help
-```
+Default port: `3100`. Default data dir: `~/.context-mcp`.
 
 ---
 
 ## Config Reference
 
-Config lives at `~/.context-mcp/contextconfig.json` — auto-created on first run:
-
-```json
-{
-  "client_id": "context-mcp",
-  "client_secret": "<auto-generated>",
-  "port": 3100,
-  "host": "localhost",
-  "access_git": false,
-  "public_url": null,
-  "allowed_redirect_uris": ["https://claude.ai"],
-  "allowed_origins": []
-}
-```
+`~/.context-mcp/contextconfig.json` — auto-created on first run:
 
 | Field | Default | Description |
 |-------|---------|-------------|
 | `client_id` | `"context-mcp"` | OAuth client ID |
-| `client_secret` | auto-generated | OAuth signing secret — keep private |
+| `client_secret` | auto-generated | OAuth signing secret |
 | `port` | `3100` | HTTP server port |
 | `host` | `"localhost"` | HTTP bind host |
 | `access_git` | `false` | Enable git tools for HTTP clients |
-| `public_url` | `null` | Public URL shown in `ctx online` output |
+| `public_url` | `null` | Public URL for `ctx online` output |
 | `allowed_redirect_uris` | `["https://claude.ai"]` | OAuth redirect URI whitelist |
-| `allowed_origins` | `[]` | Extra CORS origins beyond `claude.ai` and `localhost` |
-
-Edit any field interactively with `ctx settings`.
-
----
-
-## Features
-
-### Memory
-- `context.resume` — loads recent entries, active discussions, and graph status. Pass `rootPath` to sandbox file/git tools to your project directory.
-- `context.save` — store decisions, bugs, notes, code snippets, architecture with type tags
-- `context.get` / `context.update` / `context.delete` — full CRUD
-- `search` — keyword-first, semantic fallback, searches all past context
-- `discussion` — threaded plans with steps, status tracking, cross-session continuity
-- Auto-deduplication on save
-- Auto-compact at 50 entries (oldest entries summarized into a digest)
-- Per-project isolation with stable UUIDs
-
-### File & Git Tools (HTTP mode)
-Available to web clients (Claude.ai, ChatGPT) only — local AI clients use their native IDE tools directly.
-
-- `read_file`, `write_file`, `patch_file`, `create_dir`, `list_dir`, `delete_file`
-- `git_status`, `git_diff`, `git_log`, `git_add`, `git_commit`, `git_push`, `git_pull`, `git_branch`, `git_stash`, `git_reset`, `git_show`
-
-All file and git operations are sandboxed to the registered project root. Enable git tools with `--access-git` or `access_git: true` in config.
-
-### ContextGraph (CodeGraph)
-
-> Also referred to as **ContextGraph** — the MCP tools use the `codegraph_*` prefix but both names mean the same thing.
-
-- `codegraph_build` — AST scan using tree-sitter: functions, classes, imports, edges. Runs locally, no API cost.
-- `codegraph_query` — fetch any details about the codebase using natural language: find functions, classes, files, dependencies, callers
-- `codegraph_explain` — single node: type, file location, all direct connections (depends_on, used_by)
-- `codegraph_path` — shortest path between two concepts
-- `codegraph_nodes` — list all nodes of a given type
-- `codegraph_report` — full graph analysis: god nodes, clusters, surprising connections
-
-### Multi-AI Support
-
-| AI | Config File | Instructions | Slash Commands |
-|----|------------|--------------|----------------|
-| Claude Code | `.claude/mcp.json` | Skill → `~/.claude/skills/context-mcp/` (global) | ✓ (3 commands) |
-| Cursor | `.cursor/mcp.json` | Rule → `.cursor/rules/context-mcp.mdc` | — |
-| Windsurf | `~/.codeium/windsurf/mcp_config.json` | Rule → `.windsurf/rules/context-mcp.md` | — |
-| Gemini CLI | `.gemini/settings.json` | `GEMINI.md` | — |
-| Codex CLI | `.codex/config.toml` | `AGENTS.md` | — |
-| VS Code Copilot | `.vscode/mcp.json` | — | — |
-| Claude.ai / ChatGPT | HTTP (`ctx online`) | — | — |
-
-> Claude Code installs context-mcp as a **skill** (`~/.claude/skills/context-mcp/SKILL.md`) — available globally across all projects, not just the current one. Cursor and Windsurf use their native rules system. Gemini and Codex use plain instruction files since they have no skill/rules system.
+| `allowed_origins` | `[]` | Extra CORS origins |
 
-`ctx install --claude` also writes slash commands into `.claude/commands/`:
-
-| Command | What it does |
-|---------|-------------|
-| `/context-resume` | Resume context for the current project |
-| `/graph-build` | Build or rebuild the ContextGraph |
-| `/save-context` | Save a note, decision, or bug to context |
-
-> The context store lives at `~/.context-mcp/` — not inside any tool, IDE, or session. A decision saved in Claude Code is visible in Cursor. A bug logged from Gemini CLI shows up when you resume in Codex.
-
----
-
-## Token Reduction
-
-| Scenario | Without context-mcp | With context-mcp |
-|----------|-------------------|--------------------|
-| Start of conversation | Paste background, re-explain project | `context.resume` → 15 entries, ~750 tokens |
-| "What calls function X?" | Read 10 files to trace callers | `codegraph_query` → subgraph, ~400 tokens |
-| "What does module Y depend on?" | Read module + all imports | `codegraph_explain` → node + edges, ~200 tokens |
-| Understand architecture | Read 20+ files | Graph built once, queried forever |
-| Remember last session's decision | Ask user or re-derive | `context.resume` loads it automatically |
-
-Real measured reduction on this project: **162× fewer tokens**, **99.38% reduction** per conversation.
-
----
-
-## Architecture
-
-```
-context-mcp/
-├── src/
-│   ├── index.js           Stdio MCP server entrypoint
-│   ├── server.js          MCP server — registers all tools
-│   ├── db.js              JSON store — in-memory cache, debounced writes, project registry
-│   ├── guard.js           Path sandboxing — enforces project root on all file/git ops
-│   ├── search.js          Keyword + semantic search
-│   ├── summarizer.js      Auto-compact summarization
-│   ├── cli.js             Interactive CLI (ctx)
-│   ├── http.js            HTTP server — OAuth 2.0 + Streamable HTTP transport
-│   ├── config.js          Config loader — contextconfig.json + keytar
-│   ├── vector.js          Embedding helpers
-│   └── tools/
-│       ├── context.js     Memory tool (resume/save/get/update/delete)
-│       ├── discussion.js  Discussion tool (threaded plans + steps)
-│       ├── codegraph.js   CodeGraph tool — bridge to Python subprocess
-│       ├── search.js      Search tool
-│       ├── fileTools.js   File read/write (HTTP mode, sandboxed to project root)
-│       ├── gitTools.js    Git integration (HTTP mode, sandboxed to project root)
-│       └── errorCheck.js  Error checking tool
-├── codegraph/             Python package — AST extraction + graph queries
-│   ├── server.py          MCP server — tool definitions + dispatch
-│   ├── scanner.py         File walker + classifier (SKIP/BUILD/CODE/CONFIG/DOC/MEDIA)
-│   ├── config.py          File type taxonomy
-│   ├── cache.py           AST cache (hash-based, incremental)
-│   ├── report.py          Graph report generator
-│   ├── extractors/
-│   │   ├── ast_extractor.py    Tree-sitter AST (16 languages) + regex fallback
-│   │   └── build_extractor.py  Single-node extraction for build files
-│   └── graph/
-│       ├── builder.py     NetworkX graph construction
-│       ├── query.py       Natural language → subgraph traversal
-│       └── clustering.py  Community detection
-└── ~/.context-mcp/        Data directory (outside repo, never committed)
-    ├── contexts.json
-    ├── discussions.json
-    ├── projects.json      Project registry — includes rootPath per project
-    ├── graphs.json        Knowledge graph (nodes, edges, communities)
-    └── contextconfig.json OAuth config + server settings
-```
+Edit with `ctx settings`.
 
 ---