context-mcp-server 1.0.6 → 1.0.7

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 architecture saved across sessions, loaded automatically at conversation start
+- **Shared store** — `~/.context-mcp/` is one place 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,133 @@ 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.
-
----
-
-### 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`:
+For web clients (Claude.ai, ChatGPT), start the HTTP server:
 
-```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 — no "ctx" prefix inside)
 
-### VS Code Copilot
+# Context
+ctx list [project]             # list entries, discussions, graphs
+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)
+ctx discuss [project]          # view discussions
 ```
 
 ---
 
-### Gemini CLI
-
-`ctx install --gemini` writes:
-- `.gemini/settings.json` — MCP server config
-- `GEMINI.md` — instructions Gemini reads automatically
+## Security
 
-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, discussions, and graph status; registers `rootPath` for sandboxing
+- `context.save` — store decisions, bugs, notes, architecture with type tags
+- `context.get` / `context.update` / `context.delete` — full CRUD
+- `search` — keyword-first, semantic fallback
+- `discussion` — threaded plans with steps and cross-session continuity
+- Auto-deduplication on save; auto-compact at 20 entries
 
-**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:**
+Parses codebase via tree-sitter AST (16 languages, regex fallback). Extracts functions, classes, imports, call edges. Saved to `~/.context-mcp/`.
 
-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`
+**Step 2 — Query** (instant, forever):
 
-**View or edit config:**
-
-```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
+Available to HTTP-connected clients (Claude.ai, ChatGPT). Local AI clients use their native IDE tools.
 
-```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
-
-# 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`.
+| `allowed_origins` | `[]` | Extra CORS origins |
 
----
-
-## 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.
-
-`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`.
 
 ---
 

package/codegraph/server.py

@@ -4,8 +4,7 @@ codegraph/server.py — MCP server exposing codebase knowledge graph tools.
 
 Tools:
   codegraph_build   — scan project, extract AST nodes, build graph (local only, no API)
-  codegraph_query   — fetch details about any part of the codebase via natural language
-  codegraph_explain — look up a specific node: type, file, connections
+  codegraph_query   — structural question OR single-node lookup (or both); replaces codegraph_explain
   codegraph_report  — return full CODEGRAPH_REPORT.md
   codegraph_nodes   — list nodes of a given type
   codegraph_path    — shortest path between two concepts
@@ -56,36 +55,21 @@ TOOLS = [
     Tool(
         name="codegraph_query",
         description=(
-            "Fetch details about any part of the codebase using a natural language question. "
-            "Searches the knowledge graph — instant, no API call. "
-            "Use for: finding functions, classes, files, understanding what exists, "
-            "what a module contains, what calls what, what imports what. "
-            "NOT for: bug investigation or tracing unexpected behavior — read the file for that."
+            "Ask a structural question about the codebase OR look up a specific node by name — or both in one call. "
+            "Pass `question` for natural-language traversal: what calls X, what does module Y depend on. "
+            "Pass `node` for fast single-node lookup: returns type, file, depends_on, used_by. "
+            "Pass both to get node detail + surrounding graph context together. "
+            "Returns structured text within token_budget. Use before reading any files."
         ),
         inputSchema={
             "type": "object",
             "properties": {
                 "path":         {"type": "string", "description": "Project root"},
-                "question":     {"type": "string", "description": "Natural language question"},
+                "question":     {"type": "string", "description": "Natural language question about the codebase"},
+                "node":         {"type": "string", "description": "Node name or partial name to look up (type, file, deps, callers)"},
                 "token_budget": {"type": "integer", "description": "Max tokens in response (default 2000)"},
             },
-            "required": ["path", "question"],
-        },
-    ),
-    Tool(
-        name="codegraph_explain",
-        description=(
-            "Look up a specific function, class, or module by name — returns its type, file location, "
-            "and all direct connections (what it depends on, what uses it). "
-            "Use when you already know the name and want its full context in the graph."
-        ),
-        inputSchema={
-            "type": "object",
-            "properties": {
-                "path": {"type": "string", "description": "Project root"},
-                "node": {"type": "string", "description": "Node name or partial name"},
-            },
-            "required": ["path", "node"],
+            "required": ["path"],
         },
     ),
     Tool(
@@ -143,7 +127,7 @@ async def call_tool(name: str, arguments: dict):
 async def _dispatch(name: str, args: dict):
     if name == "codegraph_build":   return await _build(args)
     if name == "codegraph_query":   return await _query(args)
-    if name == "codegraph_explain": return await _explain(args)
+    if name == "codegraph_explain": return await _query(args)
     if name == "codegraph_report":  return await _report(args)
     if name == "codegraph_nodes":   return await _nodes(args)
     if name == "codegraph_path":    return await _path(args)
@@ -223,19 +207,8 @@ async def _build(args: dict) -> dict:
 
 # ── Query / Report / Nodes / Path ─────────────────────────────────────────────
 
-async def _query(args: dict) -> dict:
-    graph_dict = load_graph(args["path"])
-    if not graph_dict:
-        raise ValueError("No graph found. Run codegraph_build first.")
-    return graph_answer(args["question"], graph_dict, token_budget=args.get("token_budget", 2000))
-
-
-async def _explain(args: dict) -> dict:
-    graph_dict = load_graph(args["path"])
-    if not graph_dict:
-        raise ValueError("No graph found. Run codegraph_build first.")
-
-    query = args["node"].lower()
+def _explain_node(node_name: str, graph_dict: dict) -> dict:
+    query = node_name.lower()
     nodes = graph_dict.get("nodes", [])
     edges = graph_dict.get("edges", [])
 
@@ -244,8 +217,8 @@ async def _explain(args: dict) -> dict:
         match = next((n for n in nodes if query in n.get("name", "").lower()), None)
     if not match:
         candidates = [n["name"] for n in nodes if query in n.get("id", "").lower()]
-        return {"found": False, "query": args["node"],
-                "message": f"No node matching '{args['node']}'.",
+        return {"found": False, "query": node_name,
+                "message": f"No node matching '{node_name}'.",
                 "suggestions": candidates[:10]}
 
     nid = match["id"]
@@ -254,13 +227,13 @@ async def _explain(args: dict) -> dict:
         if e.get("from") == nid:
             t = next((n for n in nodes if n.get("id") == e.get("to")), None)
             depends_on.append({"name": t["name"] if t else e["to"],
-                               "file": t.get("file","") if t else "",
-                               "relation": e.get("relation","→")})
+                               "file": t.get("file", "") if t else "",
+                               "relation": e.get("relation", "→")})
         elif e.get("to") == nid:
             s = next((n for n in nodes if n.get("id") == e.get("from")), None)
             used_by.append({"name": s["name"] if s else e["from"],
-                            "file": s.get("file","") if s else "",
-                            "relation": e.get("relation","→")})
+                            "file": s.get("file", "") if s else "",
+                            "relation": e.get("relation", "→")})
 
     return {
         "found":       True,
@@ -270,10 +243,28 @@ async def _explain(args: dict) -> dict:
         "description": match.get("description") or None,
         "depends_on":  depends_on[:20],
         "used_by":     used_by[:20],
-        "hint": None,
     }
 
 
+async def _query(args: dict) -> dict:
+    graph_dict = load_graph(args["path"])
+    if not graph_dict:
+        raise ValueError("No graph found. Run codegraph_build first.")
+
+    question  = args.get("question")
+    node_name = args.get("node")
+
+    if not question and not node_name:
+        raise ValueError("Provide at least one of: question, node")
+
+    result = {}
+    if node_name:
+        result["node"] = _explain_node(node_name, graph_dict)
+    if question:
+        result["query"] = graph_answer(question, graph_dict, token_budget=args.get("token_budget", 2000))
+    return result
+
+
 async def _report(args: dict) -> dict:
     report_path = Path(args["path"]) / "codegraph-cache" / "CODEGRAPH_REPORT.md"
     if report_path.exists():

package/package.json

@@ -1,13 +1,14 @@
 {
   "name": "context-mcp-server",
-  "version": "1.0.6",
+  "version": "1.0.7",
   "description": "Persistent AI memory + codebase knowledge graph MCP server. Works across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Claude.ai, and ChatGPT.",
   "type": "module",
   "bin": {
     "context-mcp": "./src/index.js",
     "context-mcp-server": "./src/index.js",
     "context-mcp-http": "./src/http.js",
-    "ctx": "./src/cli.js"
+    "ctx": "./src/cli.js",
+    "context": "./src/cli.js"
   },
   "scripts": {
     "mcp": "node src/index.js",

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codegraph-mcp"
-version = "1.0.6"
+version = "1.0.7"
 description = "Codebase knowledge graph MCP server — AST extraction, graph queries, community detection"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/cli.js

@@ -107,8 +107,8 @@ function printSection(title, meta = '') {
 function printUsage() {
   printBanner();
 
-  // Terminal commands (ctx ...)
-  printSection('Terminal commands', 'run from your shell');
+  // Terminal commands (ctx / context ...)
+  printSection('Terminal commands', 'run from your shell  (ctx … or context …)');
   const cmd = (c, desc) => console.log(`  ${accent(c.padEnd(40))} ${faint(desc)}`);
   cmd('ctx',                           'open interactive mode');
   cmd('ctx list [project]',            'list entries + discussions + graphs');
@@ -131,8 +131,8 @@ function printUsage() {
   cmd('ctx help',                      'show this screen');
   console.log('');
 
-  // Interactive mode commands (no ctx prefix)
-  printSection('Interactive mode', 'type these inside  ctx  (no "ctx" prefix)');
+  // Interactive mode commands (no prefix needed)
+  printSection('Interactive mode', 'type these inside the UI — no "ctx" prefix needed');
   const icmd = (c, desc) => console.log(`  ${accent(c.padEnd(40))} ${faint(desc)}`);
   icmd('list [project]',               'list entries');
   icmd('search <query>',               'search context');
@@ -429,7 +429,7 @@ function cmdBenchmark() {
   printSection('Benchmark', 'real token savings');
 
   const RESUME_LIMIT = 15;
-  const COMPACT_AT   = 50;
+  const COMPACT_AT   = 20;
 
   // ── Measure entry sizes from actual stored data ──────────────────────────────
   const allEntries   = getContext({ limit: 500, compact: false });

package/src/db.js

@@ -312,10 +312,15 @@ export function updateContext({ id, content, title, tags, type, status, files, c
  * @param {Object} opts
  * @param {boolean} opts.compact - If true, returns previews instead of full content (saves tokens)
  */
-export function getContext({ project, tags, limit = 20, compact = false } = {}) {
+export function getContext({ project, tags, limit = 20, compact = false, ids } = {}) {
   refreshFromDisk();
   const store = load();
   let results = store.contexts;
+  if (ids && ids.length) {
+    const idSet = new Set(ids);
+    results = results.filter(c => idSet.has(c.id));
+    return compact ? results.map(compactEntry) : results;
+  }
   if (project) results = results.filter(c => c.project === project || c.project === 'global');
   if (tags && tags.length) {
     const tagList = Array.isArray(tags) ? tags : tags.split(',').map(t => t.trim());
@@ -348,12 +353,14 @@ export function searchContext({ query, project, limit = 10, compact = false }) {
   return compact ? sliced.map(compactEntry) : sliced;
 }
 
-export function deleteContext({ id }) {
+export function deleteContext({ id, ids }) {
   refreshFromDisk();
   const store = load();
   const before = store.contexts.length;
-  const removed = store.contexts.filter(c => c.id === id);
-  store.contexts = store.contexts.filter(c => c.id !== id);
+  const idSet = new Set(ids && ids.length ? ids : (id ? [id] : []));
+  if (!idSet.size) return { deleted: 0 };
+  const removed = store.contexts.filter(c => idSet.has(c.id));
+  store.contexts = store.contexts.filter(c => !idSet.has(c.id));
   if (store.contexts.length < before) {
     for (const entry of removed) {
       _deletedContextIds.add(entry.id);

package/src/templates/skills/SKILL.md

@@ -89,9 +89,8 @@ Parses codebase into AST graph via tree-sitter. Extracts functions, classes, imp
 
 ### Query (free, instant, forever)
 ```
-codegraph_query(path, question)   → find functions, classes, files, dependencies, callers
-codegraph_explain(path, node)     → one node: type, file, depends_on, used_by
-codegraph_path(path, from, to)    → shortest path between two concepts
+codegraph_query(path, question?, node?)  → structural question OR single-node lookup (or both in one call)
+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, surprises
 ```

package/src/tools/codegraph.js

@@ -40,92 +40,23 @@ export const definitions = [
       required: ['path'],
     },
   },
-  {
-    name: 'codegraph_extract',
-    description:
-      'Return raw content of changed code and doc/PDF files so the AI can write descriptions. ' +
-      'Code files: lists existing AST nodes — AI writes a description for each. ' +
-      'Doc files: AI extracts new concept nodes. ' +
-      'Call after codegraph_build, then call codegraph_add_nodes with results. ' +
-      'Pass force:true to re-enrich all files (not just changed ones).',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path:  { type: 'string', description: 'Project root (same as codegraph_build)' },
-        limit: { type: 'integer', description: 'Max files to return per call (default 10)' },
-        force: { type: 'boolean', description: 'Return all files, not just changed (for re-enrichment)' },
-      },
-      required: ['path'],
-    },
-  },
-  {
-    name: 'codegraph_add_nodes',
-    description:
-      'Add concept nodes extracted by the AI into the graph. ' +
-      'Call after reading codegraph_extract output. ' +
-      'Each node: name, type, file, and optionally description and relations.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path:  { type: 'string', description: 'Project root' },
-        nodes: {
-          type: 'array',
-          description: 'Concept nodes to add',
-          items: {
-            type: 'object',
-            properties: {
-              name:        { type: 'string' },
-              type:        { type: 'string', description: 'class|function|concept|service|decision|requirement' },
-              file:        { type: 'string', description: 'Relative file path this concept came from' },
-              description: { type: 'string' },
-              relations: {
-                type: 'array',
-                items: {
-                  type: 'object',
-                  properties: {
-                    name:     { type: 'string' },
-                    relation: { type: 'string', description: 'depends-on|uses|implements|defines|documents' },
-                  },
-                },
-              },
-            },
-            required: ['name', 'type', 'file'],
-          },
-        },
-      },
-      required: ['path', 'nodes'],
-    },
-  },
   {
     name: 'codegraph_query',
     description:
-      'Ask a structural/dependency question about the codebase. ' +
-      'Pure graph traversal — returns NODE/EDGE structured text truncated to token_budget. ' +
-      'Good for: "what does module X depend on?", "what calls function Y?", "what is the path from A to B?". ' +
-      'NOT for: bug investigation, logic errors, or understanding what code actually does — read the file directly for those.',
+      'Ask a structural question about the codebase OR look up a specific node by name — or both in one call. ' +
+      'Pass `question` for natural-language traversal: "what does module X depend on?", "what calls function Y?". ' +
+      'Pass `node` for fast single-node lookup: returns type, file, depends_on, used_by. ' +
+      'Pass both to get node detail + surrounding graph context together. ' +
+      'Returns structured text within token_budget. Use before reading any files.',
     inputSchema: {
       type: 'object',
       properties: {
         path:         { type: 'string', description: 'Project root' },
-        question:     { type: 'string', description: 'Natural language question' },
+        question:     { type: 'string', description: 'Natural language question about the codebase' },
+        node:         { type: 'string', description: 'Node name or partial name to look up (type, file, deps, callers)' },
         token_budget: { type: 'integer', description: 'Max tokens in response (default 2000)' },
       },
-      required: ['path', 'question'],
-    },
-  },
-  {
-    name: 'codegraph_explain',
-    description:
-      'Look up a node by name — returns description, type, file, and direct neighbors (depends_on + used_by). ' +
-      'Use to understand what a specific function/class/module does and how it connects. ' +
-      'Descriptions are AI-written via codegraph_add_nodes.',
-    inputSchema: {
-      type: 'object',
-      properties: {
-        path: { type: 'string', description: 'Project root' },
-        node: { type: 'string', description: 'Node name or partial name' },
-      },
-      required: ['path', 'node'],
+      required: ['path'],
     },
   },
   {

package/src/tools/context.js

@@ -28,9 +28,9 @@ export const definition = {
     `Factual memory — record what happened, what was decided, what broke, what was built.\n` +
     `• "resume"       — START HERE every conversation. Loads recent context, active discussions, and graph status for a project.\n` +
     `• "save"         — Store a note, decision, bug, or code snippet. Auto-deduplicates.\n` +
-    `• "get"          — Load recent entries (compact previews). Auto-digests when large.\n` +
+    `• "get"          — Load entries. Pass id/ids to fetch specific ones, or project/tags/limit for recent.\n` +
     `• "update"       — Edit an existing entry by id (any field).\n` +
-    `• "delete"       — Remove an entry by id.\n` +
+    `• "delete"       — Remove one entry (id) or multiple at once (ids: [...]).\n` +
     `• "list_projects"— Show all projects and entry counts.`,
   inputSchema: {
     type: 'object',
@@ -50,7 +50,8 @@ export const definition = {
       expiresAt:     { type: 'string' },
       limit:         { type: 'number' },
       includeArchived: { type: 'boolean' },
-      id:            { type: 'string' },
+      id:            { type: 'string', description: 'Single entry ID (get/update/delete)' },
+      ids:           { type: 'array', items: { type: 'string' }, description: 'Multiple entry IDs — fetch or delete several at once' },
     },
     required: ['action'],
   },
@@ -189,8 +190,20 @@ export async function handle(args, state) {
 
     case 'get': {
       if (!args.project && state.sessionProject) args = { ...args, project: state.sessionProject };
-      archiveExpired(args.project);
       const includeArchived = args.includeArchived === true;
+
+      // Fetch by specific ID(s) — bypass project/tag/limit filters
+      const ids = args.ids || (args.id ? [args.id] : null);
+      if (ids) {
+        const entries = getContext({ ids, compact: false })
+          .filter(e => includeArchived || e.status !== 'archived');
+        return {
+          entries, count: entries.length,
+          message: entries.length ? `Found ${entries.length} entries.` : 'No entries found for given IDs.',
+        };
+      }
+
+      archiveExpired(args.project);
       let entries = getContext({ project: args.project, tags: args.tags, limit: args.limit, compact: true });
       if (!includeArchived) entries = entries.filter(e => e.status !== 'archived');
       const fullEntries = entries.length > 10
@@ -216,8 +229,9 @@ export async function handle(args, state) {
     }
 
     case 'delete': {
-      if (!args.id) throw new Error('id is required for delete');
-      return deleteContext(args);
+      if (!args.id && !args.ids) throw new Error('id or ids is required for delete');
+      const result = deleteContext(args);
+      return { ...result, message: `Deleted ${result.deleted} entr${result.deleted === 1 ? 'y' : 'ies'}.` };
     }
 
     case 'list_projects': {

package/uv.lock

@@ -168,7 +168,7 @@ wheels = [
 
 [[package]]
 name = "codegraph-mcp"
-version = "1.0.5"
+version = "1.0.6"
 source = { editable = "." }
 dependencies = [
     { name = "mcp" },

package/codegraph/extractors/audio_extractor.py

@@ -1,8 +0,0 @@
-"""
-audio_extractor.py — audio files are not supported without faster-whisper.
-Stub kept so imports don't break.
-"""
-
-
-def transcribe(_path: str) -> str:
-    return ""

package/codegraph/extractors/doc_extractor.py

@@ -1,34 +0,0 @@
-"""
-doc_extractor.py — extract plain text from doc and PDF files.
-PDF extraction uses pymupdf if installed; falls back to label-only otherwise.
-"""
-
-from pathlib import Path
-
-
-def extract_text(path: str) -> str:
-    """Return text content of a doc/PDF file. Truncated at DOC_MAX_CHARS."""
-    from ..config import DOC_MAX_CHARS
-    if path.lower().endswith(".pdf"):
-        return _extract_pdf(path, DOC_MAX_CHARS)
-    try:
-        return Path(path).read_text(encoding="utf-8", errors="replace")[:DOC_MAX_CHARS]
-    except OSError:
-        return ""
-
-
-def _extract_pdf(path: str, max_chars: int) -> str:
-    try:
-        import pymupdf  # optional dep
-        doc = pymupdf.open(path)
-        parts = []
-        for page in doc:
-            parts.append(page.get_text())
-            if sum(len(p) for p in parts) >= max_chars:
-                break
-        doc.close()
-        return "".join(parts)[:max_chars]
-    except ImportError:
-        return f"[PDF: {Path(path).name} — install pymupdf to extract text]"
-    except Exception:
-        return ""

package/codegraph/extractors/image_extractor.py

@@ -1,26 +0,0 @@
-"""
-image_extractor.py — encode images as base64 for AI vision.
-No external deps — stdlib only.
-"""
-
-import base64
-import mimetypes
-from pathlib import Path
-
-
-def extract_image_b64(path: str) -> dict | None:
-    """Return {"data": base64_str, "media_type": "image/png"} or None on failure."""
-    try:
-        data = Path(path).read_bytes()
-        media_type = mimetypes.guess_type(path)[0] or "image/png"
-        return {"data": base64.b64encode(data).decode(), "media_type": media_type}
-    except OSError:
-        return None
-
-
-def extract_svg_text(path: str) -> str:
-    """Return SVG file as plain text (SVGs are XML — readable as-is)."""
-    try:
-        return Path(path).read_text(encoding="utf-8", errors="replace")[:4000]
-    except OSError:
-        return ""