context-mcp-server 1.0.8 → 1.1.1

package/src/templates/antigravity/workflows/graph-build.md

@@ -0,0 +1,23 @@
+# graph-build
+
+Build or refresh the codebase knowledge graph for the current project.
+
+## Steps
+
+1. Identify the project root — use the workspace path or ask if ambiguous.
+2. Call `codegraph_build` with `path: "<absolute project root>"`.
+   - This scans all source files using AST extraction (16+ languages).
+   - Incremental: only changed files are re-processed.
+3. When complete, call `context` with `action:"save"`:
+   ```
+   type: "note"
+   title: "CodeGraph built — <project>"
+   content: "nodes: N | edges: E | communities: C | time: Xms"
+   project: "<project>"
+   tags: ["codegraph"]
+   ```
+4. Report: node count, edge count, communities, any warnings.
+5. Suggest next steps:
+   - `codegraph_arch` — module map
+   - `codegraph_report` — god nodes, surprising connections
+   - `codegraph_query` — ask structural questions

package/src/templates/antigravity/workflows/save-context.md

@@ -0,0 +1,29 @@
+# save-context
+
+Save the current work state to persistent memory.
+
+## Steps
+
+1. Ask (or infer from context):
+   - **Title** — one-line summary of what was done
+   - **Why** — motivation or trigger
+   - **Outcome** — result, decision, or current state
+   - **Files** — list of files touched (if applicable)
+2. Call `context` MCP tool with `action: "save"`:
+   ```
+   type: "note"
+   title: "<title>"
+   why: "<why>"
+   outcome: "<outcome>"
+   files: ["<file1>", "<file2>"]
+   project: "<project>"
+   ```
+3. Confirm: report the saved entry ID and title.
+
+## When to use
+
+- After completing a task, fix, or feature
+- After making a significant decision
+- When discovering a constraint or gotcha
+- When the user says "save this" or "remember this"
+- After a graph build (use `graph-build` workflow instead)

package/src/templates/claude/CLAUDE.md

@@ -0,0 +1,140 @@
+---
+name: context-mcp
+description: >
+  Persistent memory + ContextGraph for Claude.
+  Use at the START of every conversation to resume project context.
+  Use whenever the user mentions a project, asks to remember/save something,
+  references past work, or says "pick up where we left off".
+  Also use when the user asks about code structure — query ContextGraph before reading any files.
+---
+
+# Context-MCP — Claude Usage Guide
+
+Persistent memory + codebase knowledge graph across every conversation.
+`context.resume` starts every session. `codegraph_arch` shows module structure. `codegraph_query` finds specific symbols. Files only for bugs/logic.
+
+---
+
+## 1. Start of Every Conversation (MANDATORY)
+
+Call `context` tool **before any tool or response**:
+- `action: "resume"`
+- `project: "<basename of git repo root>"` — infer from cwd
+- `rootPath: "<absolute path to git repo root>"` — required
+
+Returns:
+- `recentEntries` — last 15 entries; newest 5 have full content, rest have 200-char preview
+- `activePlans` — in-progress plans; read them before starting any new work
+- `codegraph` — `{ built: true/false, nodes, edges }`
+- `stats.totalEntries` — if ≥ 20, write a compaction summary before proceeding (see Rule 4)
+
+Then:
+- `codegraph.built: true` → use `codegraph_arch` for structure overview, `codegraph_query` for specific lookups
+- `codegraph.built: false` → call `codegraph_build(path)` first
+
+---
+
+## 2. When to Save Context (MANDATORY TRIGGERS)
+
+Call `context.save` with `type: "note"` whenever you finish something or discover something worth keeping:
+
+```
+context.save
+  project: "<project>"
+  title:   "<what was done — up to 120 chars>"
+  why:     "<why it mattered>"
+  outcome: "<what the result was>"
+  files:   ["src/file.js", ...]
+```
+
+**Save immediately after:**
+- Task / fix / feature complete
+- Decision made (architecture, library, approach)
+- Discovery — non-obvious behavior, constraint, gotcha
+- Config / env / deploy info
+- Graph build complete — include nodes/edges count in content
+- User says "save this" / "remember this"
+
+**Manual compaction** — "compact now", "compress memory", "clean up context":
+Save a full session summary as `type: "compaction"`. Server removes old entries using it.
+
+**Do NOT save:** routine reads, search results, explanations of existing code, dead-end debugging.
+
+---
+
+## 3. Plans (MANDATORY for multi-file work)
+
+**Create a plan when:** editing 2+ files, multi-step implementation, refactor, multi-file bug fix.
+
+**Skip plan for:** single-file edits, questions, simple config tweaks.
+
+1. Call `plan.save` with `name`, `content` (full plan in markdown), `project`, `planDir` before starting
+2. Work through the plan
+3. Call `plan.update status:"done"` when complete — this deletes the plan
+
+On `resume`, if `activePlans` is non-empty — read them before starting new work. Do not create a duplicate.
+
+---
+
+## 4. Auto-Summary Rule (MANDATORY)
+
+When `resume` returns `stats.totalEntries ≥ 20`, call `context.save` **before doing anything else**:
+
+```
+context.save
+  type:    "compaction"
+  title:   "Session summary — <YYYY-MM-DD>"
+  content: "<what was built, decided, broke, current state>"
+  project: "<project>"
+```
+
+---
+
+## 5. Search Before Asking
+
+If the user references past work → call `search` first:
+```
+search  query: "<what they're referencing>"  project: "<project>"
+```
+
+---
+
+## 6. ContextGraph Pipeline
+
+### Build (once per project)
+```
+codegraph_build(path)
+```
+
+### Query tools
+```
+codegraph_arch(path, limit?)             → module map: every file, its exports, its imports
+codegraph_query(path, question?, node?)  → find function/class/file or answer structural question
+codegraph_nodes(path, type)              → list all nodes of a type
+codegraph_report(path)                   → god nodes, clusters, structural analysis
+codegraph_affected(path, node, depth?)   → blast radius BFS — what breaks if X changes?
+codegraph_html(path, formats?)           → regenerate visualizations (auto-runs on every build)
+```
+
+| Question | Tool |
+|---|---|
+| What files exist and what do they export? | `codegraph_arch` |
+| Where is function X defined? | `codegraph_query node:"X"` |
+| What does module Y depend on? | `codegraph_query question:"what does Y import?"` |
+| What are all the classes? | `codegraph_nodes type:"class"` |
+| Most connected files? | `codegraph_report` |
+| What breaks if I change X? | `codegraph_affected node:"X"` |
+
+**Never read files for structure questions — use graph tools first.**
+
+---
+
+## 7. Rules
+
+1. `context.resume` first — before any tool or response
+2. Always pass `project`
+3. Save on task complete — `why` + `outcome` + `files`
+4. Compaction at ≥ 20 entries — before starting the task
+5. Plan for multi-file work — save before starting, `status:"done"` deletes it
+6. Search before asking about past work
+7. Graph tools before files

package/src/templates/claude/commands/graph-build.md

@@ -0,0 +1,9 @@
+Call `codegraph_build` with the path `$ARGUMENTS`.
+
+If no argument is given, use the current working directory.
+
+This builds the ContextGraph for the project by parsing source files into an AST
+knowledge graph. Once built, use `codegraph_query` to answer structural questions
+about the codebase before reading files directly.
+
+After the build completes, report total nodes, edges, and communities.

package/src/templates/claude/commands/save-context.md

@@ -0,0 +1,19 @@
+Call the `context` MCP tool with `action: "save"` to store a note for the
+current project.
+
+Parse `$ARGUMENTS` to determine:
+
+- `project`: infer from current working directory name if not specified.
+- `title`: first sentence or phrase, up to 120 chars.
+- `why`: why it mattered, what problem it solved, or what constraint it revealed.
+- `outcome`: what changed, what was verified, what shipped, and which files were affected.
+- `files`: list of files changed, required for task/bug types.
+- `content`: full argument text.
+- `type`: auto-detect:
+  - bug/fix/error -> `"bug"`
+  - task/done/complete/shipped/implemented -> `"task"`
+  - decision/chose/decided/approach -> `"decision"`
+  - config/env/secret/deploy -> `"config"`
+  - otherwise -> `"note"`
+
+Confirm to the user: title, type, why, outcome, and project.

package/src/templates/claude/hooks/context-mcp-post-tool-use.js

@@ -0,0 +1,59 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Code PostToolUse hook for context-mcp.
+ *
+ * Input (stdin JSON): { session_id, cwd, hook_event_name: "PostToolUse",
+ *   tool_name, tool_input: { command }, tool_response | tool_output }
+ *
+ * Saves failed Bash commands to context-mcp so the next session can see
+ * what broke. Exits silently when the command succeeded or the exit code
+ * cannot be determined.
+ */
+
+import { spawnSync } from 'node:child_process';
+
+process.stdin.resume();
+process.stdin.setEncoding('utf8');
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  let event = {};
+  try {
+    event = input.trim() ? JSON.parse(input) : {};
+  } catch {
+    return;
+  }
+
+  const toolInput = event.tool_input || {};
+  const toolResult = typeof event.tool_response === 'object' && event.tool_response !== null
+    ? event.tool_response
+    : {};
+  const command = toolInput.command || '';
+  const exitCode = toolResult.exit_code ?? toolResult.exitCode ?? toolResult.code;
+
+  if (!command || exitCode === undefined || Number(exitCode) === 0) return;
+
+  const output = String(
+    toolResult.stderr || toolResult.stdout || toolResult.output || event.tool_output || '',
+  ).trim();
+
+  const content = [
+    `Command: ${command}`,
+    `Exit code: ${exitCode}`,
+    output ? `Output:\n${output.slice(0, 4000)}` : null,
+  ].filter(Boolean).join('\n\n');
+
+  spawnSync('ctx', [
+    'save',
+    '--project', (event.cwd || process.cwd()).split(/[\\/]/).pop() || 'default',
+    '--type', 'bug',
+    '--title', `Failed shell command: ${command.slice(0, 80)}`,
+    '--content', content,
+  ], {
+    encoding: 'utf8',
+    shell: true,
+    stdio: 'ignore',
+  });
+});

package/src/templates/claude/hooks/context-mcp-pre-tool-use.js

@@ -0,0 +1,26 @@
+#!/usr/bin/env node
+
+/**
+ * Claude Code PreToolUse hook for context-mcp.
+ *
+ * Input (stdin JSON): { session_id, cwd, hook_event_name: "PreToolUse",
+ *   tool_name, tool_input, permission_mode }
+ *
+ * This hook is intentionally conservative. It validates the hook pipeline
+ * runs before Bash commands but never blocks or rewrites them (exit 0 =
+ * allow). Keep policy decisions in CLAUDE.md or a dedicated security hook
+ * if your team needs command blocking (exit 2 + stderr blocks the call).
+ */
+
+process.stdin.resume();
+process.stdin.setEncoding('utf8');
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    if (input.trim()) JSON.parse(input);
+  } catch {
+    // Do not interrupt the user's command because hook input changed.
+  }
+});

package/src/templates/claude/skills/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: context-mcp
+description: >
+  Persistent memory + ContextGraph (codebase knowledge graph) for Claude.
+  Use at the START of every conversation to resume project context. Use
+  whenever the user mentions a project, asks to remember/save something,
+  references past work, or says "pick up where we left off". Also use
+  when the user asks about code structure, dependencies, or what exists
+  in a codebase — query the ContextGraph before reading any files.
+---
+
+# Context-MCP
+
+Persistent memory + codebase knowledge graph across every conversation.
+`context.resume` starts every session. `codegraph_arch` shows module structure. `codegraph_query` finds specific symbols. Files only for bugs/logic.
+
+---
+
+## Subcommands
+
+When invoked with an argument, act immediately:
+
+**`/context-mcp resume`** — call `context` tool with `action:"resume"`, infer `project` from cwd, pass `rootPath`. Report what was returned.
+
+**`/context-mcp save`** — call `context` tool with `action:"save"` to save the most recent thing worth keeping from this conversation. Use `type:"note"`, fill in `title`, `why`, `outcome`, `files` from context. Confirm what was saved.
+
+---
+
+## MANDATORY: Start of Every Conversation
+
+Call `context` tool **before any tool or response** with:
+- `action: "resume"`
+- `project: "<basename of git repo root dir>"` — infer from `cwd` if not stated
+- `rootPath: "<absolute path to git repo root>"` — required for sandbox + graph lookup
+
+Returns:
+- `recentEntries` — last 15 entries; newest 5 have full content, rest have 200-char preview
+- `activePlans` — in-progress plans; read them before starting any new work
+- `codegraph` — `{ built: true/false, nodes, edges, communities }`
+- `stats.totalEntries` — if ≥ 20, write a compaction summary before proceeding (see Rule 4)
+
+Then:
+- `codegraph.built: true` → use `codegraph_arch` for structure overview, `codegraph_query` for specific lookups
+- `codegraph.built: false` → call `codegraph_build(path)` first
+
+---
+
+## When to Save Context (MANDATORY TRIGGERS)
+
+Call `context.save` with `type: "note"` after finishing anything worth keeping:
+
+```
+context.save
+  project: "<project>"
+  title:   "<what was done — up to 120 chars>"
+  why:     "<why it mattered>"
+  outcome: "<what the result was>"
+  files:   ["src/file.js", ...]
+```
+
+**Save immediately after:**
+- Task / fix / feature complete
+- Decision made (architecture, library, approach)
+- Discovery — non-obvious behavior, constraint, gotcha
+- Config / env / deploy info
+- Graph build complete — include nodes/edges count in content
+- User says "save this" / "remember this"
+
+**Manual compaction** — "compact now", "compress memory", "clean up context":
+Save a full session summary as `type: "compaction"`. Server removes old entries using it.
+
+**Do NOT save:** routine reads, search results, explanations of existing code, dead-end debugging.
+
+---
+
+## Plans (MANDATORY for multi-file work)
+
+**Create a plan when:** editing 2+ files, multi-step implementation, refactor, multi-file bug fix.
+
+**Skip plan for:** single-file edits, questions, simple config tweaks.
+
+1. `plan.save` with name, content, project, planDir — before starting work
+2. Work through plan
+3. `plan.update status:"done"` when complete — deletes the plan
+
+On `resume`, check `activePlans` — do not duplicate in-progress work.
+
+---
+
+## Auto-Summary Rule (MANDATORY)
+
+When `resume` returns `stats.totalEntries ≥ 20`, call `context.save` **before the user's task**:
+
+```
+type: "compaction"  title: "Session summary — <date>"
+content: "<what was built, decided, broke, current state>"
+project: "<project>"
+```
+
+---
+
+## Search Before Asking
+
+If user references past work → `search` first. Never ask user to re-explain saved information.
+
+---
+
+## ContextGraph Pipeline
+
+### Build (once per project)
+```
+codegraph_build(path)  →  AST graph: functions, classes, imports, edges
+```
+
+### Query tools
+```
+codegraph_arch(path)                     → module map: every file, exports, imports
+codegraph_query(path, question?, node?)  → find symbol or answer structural question
+codegraph_nodes(path, type)              → list all nodes of a type
+codegraph_report(path)                   → god nodes, clusters, structural analysis
+codegraph_affected(path, node, depth?)   → blast radius BFS — what breaks if X changes?
+codegraph_html(path, formats?)           → regenerate visualizations (auto-runs on every build)
+```
+
+| Question | Tool |
+|---|---|
+| Architecture overview / what files exist | `codegraph_arch` |
+| Where is function/class X defined? | `codegraph_query node:"X"` |
+| What does module Y import? | `codegraph_query question:"..."` |
+| List all classes/functions | `codegraph_nodes type:"class"` |
+| Most connected / central files | `codegraph_report` |
+| What breaks if I change X? | `codegraph_affected node:"X"` |
+
+---
+
+## Rules
+
+1. `context.resume` first — before any tool or response
+2. Always pass `project`
+3. Save on task complete — `why` + `outcome` + `files`
+4. Compaction at ≥ 20 entries — before starting task
+5. Plan for multi-file work — `status:"done"` deletes it
+6. Search before asking about past work
+7. Graph tools before files

package/src/templates/codex/AGENTS.md

@@ -0,0 +1,107 @@
+# Context-MCP - Codex CLI Usage Guide
+
+Persistent memory + codebase knowledge graph.
+`context.resume` starts every session. `codegraph_query` finds specific symbols.
+Read files only for bugs or implementation logic.
+
+---
+
+## 1. Start of Every Conversation (MANDATORY)
+
+Call the `context` MCP tool before any other action:
+
+```json
+{
+  "action": "resume",
+  "project": "<project>",
+  "rootPath": "<absolute path to the project root>"
+}
+```
+
+Returns: `recentEntries`, `activePlans`, `codegraph`, `stats.totalEntries`.
+
+- `codegraph.built: true` -> use graph tools before reading files.
+- `codegraph.built: false` -> call `codegraph_build(path)` first.
+- `stats.totalEntries >= 20` -> write a compaction summary first.
+- `activePlans` non-empty -> read them before starting new work.
+
+---
+
+## 2. Save Triggers (MANDATORY)
+
+Call `context.save` with `type: "note"` after finishing anything worth keeping:
+
+| Trigger | Required fields |
+|---|---|
+| Task / fix / feature complete | title, why, outcome, files[] |
+| Decision made | title, why, outcome |
+| Discovery / constraint / gotcha | title, content |
+| Config / env / deploy info | title, content |
+| Graph build complete | title, content with nodes/edges count |
+| User says "save this" | title, content |
+| "compact now" / "compress memory" | `type: "compaction"`, full session summary |
+
+Do not save routine reads, search results, or explanations of existing code.
+
+---
+
+## 3. Plans (MANDATORY for multi-file work)
+
+Create a plan when editing 2+ files, doing a multi-step implementation, refactor,
+or multi-file bug fix.
+
+1. Call `plan.save` with name, content, and project before starting.
+2. Call `plan.update status: "done"` when complete.
+
+Check `activePlans` on resume. Do not create duplicates.
+
+---
+
+## 4. Auto-Summary at >= 20 Entries (MANDATORY)
+
+When `totalEntries >= 20`, call `context.save` before the user's task:
+
+```json
+{
+  "type": "compaction",
+  "title": "Session summary - <YYYY-MM-DD>",
+  "content": "<what was built, decided, broke, current state>",
+  "project": "<project>"
+}
+```
+
+---
+
+## 5. Search Before Asking
+
+Call `search` before asking the user to re-explain past work.
+
+---
+
+## 6. ContextGraph Tools
+
+```text
+codegraph_build(path)                    -> build AST graph + auto-generate all visualizations
+codegraph_arch(path, limit?)             -> module map: files, exports, imports
+codegraph_query(path, question?, node?)  -> find symbol or answer structural question
+codegraph_nodes(path, type)              -> list all nodes of a type
+codegraph_report(path)                   -> structural analysis
+codegraph_affected(path, node, depth?)   -> blast radius BFS — what breaks if X changes?
+codegraph_html(path, formats?)           -> regenerate visualizations on demand
+```
+
+Use `codegraph_arch` first. Read files only when you need exact bug or
+implementation details.
+
+---
+
+## 7. Rules
+
+1. `context.resume` first, before any tool or response.
+2. Always pass `project`.
+3. Pass `rootPath` whenever the current project root is known.
+4. Save on task complete with why, outcome, and files.
+5. Compact at >= 20 entries before starting the task.
+6. Plan before multi-file work.
+7. Search before asking about past work.
+8. Use graph tools before files.

package/src/templates/codex/hooks/context-mcp-post-tool-use.js

@@ -0,0 +1,46 @@
+#!/usr/bin/env node
+
+import { spawnSync } from 'node:child_process';
+
+process.stdin.resume();
+process.stdin.setEncoding('utf8');
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  let event = {};
+  try {
+    event = input.trim() ? JSON.parse(input) : {};
+  } catch {
+    return;
+  }
+
+  const toolInput = event.tool_input || event.toolInput || {};
+  const toolResult = event.tool_response || event.toolResponse || event.result || {};
+  const command = toolInput.command || toolInput.cmd || event.command || '';
+  const exitCode = toolResult.exit_code ?? toolResult.exitCode ?? event.exit_code ?? event.exitCode;
+
+  if (!command || exitCode === undefined || Number(exitCode) === 0) return;
+
+  const output = String(
+    toolResult.stderr || toolResult.stdout || toolResult.output || event.output || '',
+  ).trim();
+
+  const content = [
+    `Command: ${command}`,
+    `Exit code: ${exitCode}`,
+    output ? `Output:\n${output.slice(0, 4000)}` : null,
+  ].filter(Boolean).join('\n\n');
+
+  spawnSync('ctx', [
+    'save',
+    '--project', process.cwd().split(/[\\/]/).pop() || 'default',
+    '--type', 'bug',
+    '--title', `Failed shell command: ${command.slice(0, 80)}`,
+    '--content', content,
+  ], {
+    encoding: 'utf8',
+    shell: true,
+    stdio: 'ignore',
+  });
+});

package/src/templates/codex/hooks/context-mcp-pre-tool-use.js

@@ -0,0 +1,23 @@
+#!/usr/bin/env node
+
+/**
+ * Codex PreToolUse hook for context-mcp.
+ *
+ * This hook is intentionally conservative. It validates that Codex can run the
+ * project-local hook pipeline before Bash commands, but it does not block or
+ * rewrite commands. Keep policy decisions in AGENTS.md or a dedicated security
+ * hook if your team needs command blocking.
+ */
+
+process.stdin.resume();
+process.stdin.setEncoding('utf8');
+
+let input = '';
+process.stdin.on('data', chunk => { input += chunk; });
+process.stdin.on('end', () => {
+  try {
+    if (input.trim()) JSON.parse(input);
+  } catch {
+    // Do not interrupt the user's command because hook input changed.
+  }
+});

package/src/templates/codex/prompts/context-resume.md

@@ -0,0 +1,15 @@
+---
+description: "Resume project memory + ContextGraph from context-mcp"
+argument-hint: [project]
+---
+
+Call the `context` MCP tool with `action: "resume"`, `project: "$ARGUMENTS"` (if no argument given, infer the project name from the current working directory name), and `rootPath: "<absolute path to the project root / git repo root>"`.
+
+Both `project` and `rootPath` are required: `project` names the memory bucket, `rootPath` enables exact graph lookup and file sandboxing.
+
+This loads:
+- Recent decisions, bugs, and notes from past sessions
+- Active plans
+- ContextGraph status (built or not)
+
+If `codegraph.built` is false in the response, immediately call `codegraph_build` on the project path before proceeding.

package/src/templates/codex/prompts/graph-build.md

@@ -0,0 +1,14 @@
+---
+description: "Build the ContextGraph (AST knowledge graph) for a project"
+argument-hint: [path]
+---
+
+Call `codegraph_build` with the path `$ARGUMENTS`.
+
+If no argument is given, use the current working directory.
+
+This builds the ContextGraph for the project by parsing source files into an AST
+knowledge graph. Once built, use `codegraph_query` to answer structural questions
+about the codebase before reading files directly.
+
+After the build completes, report total nodes, edges, and communities.