context-mcp-server 1.1.0 → 1.1.2

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

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * Antigravity IDE PostToolUse hook for context-mcp.
+ *
+ * Input (stdin JSON): {
+ *   toolCall: { name, args },
+ *   stepIdx, conversationId, workspacePaths,
+ *   error        ← present when the tool invocation failed
+ * }
+ *
+ * Saves failed tool invocations to context-mcp so the next session can see
+ * what broke. Exits silently when the tool succeeded or no error is present.
+ */
+
+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 toolCall = event.toolCall || {};
+  const toolName = toolCall.name || '';
+  const error = event.error;
+
+  if (!error || !toolName) return;
+
+  const args = toolCall.args || {};
+  const argsSnippet = Object.keys(args).length
+    ? JSON.stringify(args).slice(0, 200)
+    : '';
+
+  const cwd = (event.workspacePaths || [])[0] || process.cwd();
+  const project = cwd.replace(/\\/g, '/').replace(/\/$/, '').split('/').pop() || 'default';
+
+  const content = [
+    `Tool: ${toolName}`,
+    argsSnippet ? `Args: ${argsSnippet}` : null,
+    `Error: ${String(error).slice(0, 4000)}`,
+  ].filter(Boolean).join('\n\n');
+
+  spawnSync('ctx', [
+    'save',
+    '--project', project,
+    '--type', 'bug',
+    '--title', `Failed tool: ${toolName.slice(0, 80)}`,
+    '--content', content,
+  ], {
+    encoding: 'utf8',
+    shell: true,
+    stdio: 'ignore',
+  });
+});

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

@@ -0,0 +1,20 @@
+# context-resume
+
+Resume context for the current project from persistent memory.
+
+## Steps
+
+1. Call the `context` MCP tool with `action: "resume"` and `project: "<current project name>"`.
+2. Read `recentEntries` — the last saved notes, decisions, and bug records.
+3. Read `activePlans` — any in-progress multi-step plans.
+4. Check `codegraph.built`:
+   - `true` → graph tools are available; use `codegraph_arch` before reading files
+   - `false` → run `codegraph_build` when structural questions arise
+5. If `stats.totalEntries ≥ 20`, save a compaction summary before starting work:
+   ```
+   context(action:"save", type:"compaction",
+     title:"Session summary — YYYY-MM-DD",
+     content:"<full summary of session>",
+     project:"<project>")
+   ```
+6. Summarize what was found: recent work, open plans, graph status.

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.md → claude/CLAUDE.md}

@@ -112,6 +112,8 @@ codegraph_arch(path, limit?)             → module map: every file, its exports
 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 |
@@ -121,6 +123,7 @@ codegraph_report(path)                   → god nodes, clusters, structural ana
 | 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.**
 

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/{skills → claude/skills}/SKILL.md

@@ -118,6 +118,8 @@ codegraph_arch(path)                     → module map: every file, exports, im
 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 |
@@ -127,6 +129,7 @@ codegraph_report(path)                   → god nodes, clusters, structural ana
 | 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"` |
 
 ---
 

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.

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

@@ -0,0 +1,24 @@
+---
+description: "Save a note/decision/bug to context-mcp project memory"
+argument-hint: [what to remember]
+---
+
+Call the `context` MCP tool with `action: "save"` to store a note for the
+current project.
+
+Parse the following to determine the fields: $ARGUMENTS
+
+- `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/cursor/commands/context-resume.md

@@ -0,0 +1,7 @@
+# context-resume
+
+Resume project memory and ContextGraph from context-mcp before starting any work.
+
+Call the `context` MCP tool with `action: "resume"`, infer `project` from the current working directory name, and pass `rootPath` as the absolute path to the git repo root.
+
+This loads recent decisions, bugs, notes, active plans, and ContextGraph status. If `codegraph.built` is false, immediately call `codegraph_build` on the project path.

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

@@ -0,0 +1,7 @@
+# graph-build
+
+Build the ContextGraph (AST knowledge graph) for the current project.
+
+Call `codegraph_build` with the current working directory as the path (or a path provided by the user).
+
+After the build completes, report total nodes, edges, and communities. Once built, use `codegraph_query` to answer structural questions about the codebase instead of reading files directly.

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

@@ -0,0 +1,12 @@
+# save-context
+
+Save a note, decision, bug, or task to context-mcp project memory.
+
+Call the `context` MCP tool with `action: "save"`. Infer `project` from the current working directory name. Auto-detect `type` from the user's description:
+- bug/fix/error → `"bug"`
+- task/done/complete/shipped → `"task"`
+- decision/chose/decided → `"decision"`
+- config/env/deploy → `"config"`
+- otherwise → `"note"`
+
+Fill in `title` (up to 120 chars), `why`, `outcome`, and `files`. Confirm back to the user what was saved.

package/src/templates/{cursor-rules.mdc → cursor/cursor-rules.mdc}

@@ -29,13 +29,23 @@ Returns: `recentEntries`, `activePlans`, `codegraph { built, nodes, edges }`.
 
 ## 3. CodeGraph
 
-Build once: `codegraph_build(path)` — then query forever.
-Use `codegraph_query` for structural questions. Read files for bugs/logic.
+Build once: `codegraph_build(path)` — auto-generates visualizations, then query forever.
+
+```
+codegraph_arch(path)                   → 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)                 → god nodes, clusters, structural analysis
+codegraph_affected(path, node, depth?) → blast radius — what breaks if X changes?
+codegraph_html(path, formats?)         → regenerate visualizations on demand
+```
+
+Use `codegraph_arch` for structural questions. Read files for bugs/logic.
 
 ## Rules
 
 1. `context.resume` first — every conversation
 2. Always pass `project`
 3. `search` before asking the user about past work
-4. `codegraph_query` before reading files
+4. `codegraph_arch` before reading files
 5. Files only for bugs and logic

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

@@ -0,0 +1,55 @@
+#!/usr/bin/env node
+
+/**
+ * Cursor postToolUse hook for context-mcp.
+ *
+ * Input (stdin JSON): { hook_event_name: "postToolUse", tool_name,
+ *   tool_input: { command }, tool_response: { exit_code, stdout, stderr }, cwd }
+ *
+ * Saves failed shell commands to context-mcp so the next session can see
+ * what broke. Exits silently when the command succeeded or exit code is unknown.
+ */
+
+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 || toolInput.cmd || '';
+  const exitCode = toolResult.exit_code ?? toolResult.exitCode ?? toolResult.code
+    ?? event.exit_code ?? event.exitCode;
+
+  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/{GEMINI.md → gemini/GEMINI.md}

@@ -68,11 +68,13 @@ Call `search` before asking user to re-explain past work.
 ## 6. ContextGraph Tools
 
 ```
-codegraph_build(path)                    → build AST graph (run once)
+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. Never read files for structure questions.