context-mcp-server 1.0.8 → 1.1.1

package/src/migrator.js

@@ -1,124 +0,0 @@
-/**
- * migrator.js — one-time migration from flat JSON files to per-project directory structure.
- *
- * Old layout:
- *   ~/.context-mcp/contexts.json      all entries flat
- *   ~/.context-mcp/discussions.json   all discussions flat
- *   ~/.context-mcp/graphs.json        all graph build records flat
- *
- * New layout:
- *   ~/.context-mcp/projects/<slug>/context.json
- *   ~/.context-mcp/projects/<slug>/graph.json     { build, entries[] }
- *   ~/.context-mcp/projects/<slug>/summary.json
- *   ~/.context-mcp/projects/<slug>/discussions.json
- */
-
-import { readFileSync, existsSync, mkdirSync, unlinkSync } from 'node:fs';
-import { join } from 'node:path';
-
-function normPath(p) {
-  return p ? p.toLowerCase().replace(/\\/g, '/').replace(/\/$/, '') : '';
-}
-
-function treeFor(entry) {
-  if (entry.type === 'compaction') return 'summary';
-  return 'context';
-}
-
-function readArr(filePath, key) {
-  if (!existsSync(filePath)) return [];
-  try {
-    const d = JSON.parse(readFileSync(filePath, 'utf8'));
-    return Array.isArray(d[key]) ? d[key] : (Array.isArray(d) ? d : []);
-  } catch { return []; }
-}
-
-/**
- * Run migration if legacy flat files are present.
- * @param {object} opts
- * @param {string}   opts.dataDir       - base data dir (~/.context-mcp)
- * @param {string}   opts.projectsDir   - projects sub-dir
- * @param {string}   opts.projectsPath  - path to projects.json
- * @param {Function} opts.slugify       - name → filesystem slug
- * @param {Function} opts.flushFile     - (filePath, content) atomic write
- * @param {Array}    opts.projectsIndex - current projects.json array (mutated in place)
- */
-export function runMigration({ dataDir, projectsDir, projectsPath, slugify, flushFile, projectsIndex }) {
-  const legacyContexts    = join(dataDir, 'contexts.json');
-  const legacyDiscussions = join(dataDir, 'discussions.json');
-  const legacyGraphs      = join(dataDir, 'graphs.json');
-
-  const hasLegacy = existsSync(legacyContexts)
-    || existsSync(legacyDiscussions)
-    || existsSync(legacyGraphs);
-
-  if (!hasLegacy) return false;
-
-  const oldContexts    = readArr(legacyContexts,    'contexts');
-  const oldDiscussions = readArr(legacyDiscussions,  'discussions');
-  const oldGraphs      = readArr(legacyGraphs,       'graphs');
-
-  // Remap legacy type names to current 4-type schema
-  const TYPE_MAP = { architecture: 'note', code: 'note', error: 'bug', summary: 'compaction' };
-  const remapType = entry => {
-    if (TYPE_MAP[entry.type]) entry.type = TYPE_MAP[entry.type];
-    return entry;
-  };
-
-  // Group everything by project name
-  const byProject = {};
-  const ensure = name => {
-    if (!byProject[name]) byProject[name] = {
-      context: [], graph: { build: null }, summary: [], discussions: [],
-    };
-    return byProject[name];
-  };
-
-  for (const entry of oldContexts) {
-    remapType(entry);
-    const p = entry.project || 'global';
-    const d = ensure(p);
-    if (treeFor(entry) === 'summary') d.summary.push(entry);
-    else d.context.push(entry);
-  }
-
-  for (const disc of oldDiscussions) {
-    ensure(disc.project || 'global').discussions.push(disc);
-  }
-
-  // Match graph build records to projects via rootPath
-  for (const graph of oldGraphs) {
-    const proj = projectsIndex.find(p => normPath(p.rootPath) === normPath(graph.path));
-    const name = proj ? proj.name : 'global';
-    const d = ensure(name);
-    d.graph.build = {
-      path: graph.path, nodes: graph.nodes, edges: graph.edges,
-      communities: graph.communities, cached: graph.cached || 0,
-      changed: graph.changed || 0, time_ms: graph.time_ms || 0,
-      summary: graph.summary || '', builtAt: graph.builtAt,
-    };
-  }
-
-  // Write per-project files
-  for (const [name, data] of Object.entries(byProject)) {
-    const dir = join(projectsDir, slugify(name));
-    mkdirSync(dir, { recursive: true });
-    flushFile(join(dir, 'context.json'),     { entries: data.context });
-    flushFile(join(dir, 'graph.json'),       data.graph);
-    flushFile(join(dir, 'summary.json'),     { entries: data.summary });
-    flushFile(join(dir, 'discussions.json'), { discussions: data.discussions });
-  }
-
-  // Stamp dataDir onto each project record
-  for (const proj of projectsIndex) {
-    if (!proj.dataDir) proj.dataDir = `projects/${slugify(proj.name)}`;
-  }
-  flushFile(projectsPath, { projects: projectsIndex });
-
-  // Remove legacy flat files
-  try { unlinkSync(legacyContexts);    } catch {}
-  try { unlinkSync(legacyDiscussions); } catch {}
-  try { unlinkSync(legacyGraphs);      } catch {}
-
-  return true;
-}

package/src/templates/AGENTS.md

@@ -1,80 +0,0 @@
-# Context-MCP — Codex CLI Usage Guide
-
-Persistent memory + codebase knowledge graph.
-Every conversation starts with `context.resume`. Every codebase question uses `codegraph_query`. Files only read for bugs/logic.
-
----
-
-## 1. Start of Every Conversation (MANDATORY)
-
-Call the `context` MCP tool with `action: "resume"`, `project: "<project-name>"` **before anything else**.
-
-Returns:
-- `recentEntries` — decisions, bugs, notes from previous conversations
-- `activePlans` — active AI-created plans for this project
-- `codegraph` — `{ built: true/false, nodes, edges, communities }`
-
-Then:
-- `codegraph.built: true` → use `codegraph_query` before reading any files
-- `codegraph.built: false` → call `codegraph_build(path)` first, then proceed
-
----
-
-## 2. When to Auto-Save Context
-
-**After graph build or rebuild** — every time `codegraph_build` completes:
-```
-context.save  type: "note"  title: "ContextGraph built — <project>"
-content: "nodes: X | edges: Y | communities: Z"
-```
-
-**User explicitly asks** — "save this", "remember this", "note that" → save immediately.
-
-**During plan / implementation / discussion / research** — save only when genuinely valuable:
-
-| What happened | Type |
-|--------------|------|
-| Approach / library / pattern decided | `decision` |
-| Bug found, root cause known, or fixed | `bug` |
-| Gotcha, constraint, discovery, structure understood | `note` |
-| Config / env var / secret / deploy step | `config` |
-
-Do NOT save: routine reads, search results, temporary debugging dead-ends.
-**Making any kind of plan** → call `plan.save` immediately with the plan summary and `planDir` pointing to your platform's plans folder.
-Need past info → `search` before asking. Always pass `project`.
-
----
-
-## 3. ContextGraph Pipeline
-
-> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
-
-### Step 1 — Build (once, fast, local)
-```
-codegraph_build(path)  →  AST graph: functions, classes, imports, edges
-```
-
-### Step 2 — Query (free, instant)
-```
-codegraph_query(path, question)   →  fetch any details about the codebase
-codegraph_path(path, from, to)    →  shortest path
-codegraph_nodes(path, type)       →  list nodes by type
-codegraph_report(path)            →  full graph analysis
-```
-
----
-
-## 4. Graph vs File
-
-**Graph** — use for any question about what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
-**File** — bugs, logic, tracing unexpected behavior.
-
----
-
-## 5. Rules
-
-1. **`context.resume` first** — before any tool or response
-2. **Always pass `project`**
-3. **`search` before asking** — if user references past work
-4. **`codegraph_query` before reading files** — graph is faster and cheaper
-5. **Read files for bugs/logic only**

package/src/templates/CLAUDE.md

@@ -1,103 +0,0 @@
----
-name: context-mcp
-description: >
-  Guides Claude on using the context-mcp memory + knowledge graph system.
-  Trigger at the start of every conversation, when the user mentions a project,
-  asks to remember/save something, or says "pick up where we left off".
----
-
-# Context-MCP — Claude Usage Guide
-
-Persistent memory + codebase knowledge graph for Claude.
-Every conversation starts with `context.resume`. Every codebase question uses `codegraph_query`. Files only read for bugs/logic.
-
----
-
-## 1. Start of Every Conversation (MANDATORY)
-
-Call `context` tool **before anything else** 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
-
-Both fields are required: `project` names the memory bucket, `rootPath` enables exact graph matching and file sandboxing.
-
-Returns:
-- `recentEntries` — decisions, bugs, notes from previous conversations
-- `activePlans` — active AI-created plans for this project
-- `codegraph` — `{ built: true/false, nodes, edges, communities }`
-
-Then:
-- `codegraph.built: true` → use `codegraph_query` before reading any files
-- `codegraph.built: false` → call `codegraph_build(path)` first, then proceed
-
----
-
-## 2. When to Auto-Save Context
-
-### Always save — no user prompt needed
-
-**After graph build or rebuild** — every time `codegraph_build` completes:
-```
-context.save  project: "<project>"  type: "note"  title: "ContextGraph built — <project>"
-content: "nodes: X | edges: Y | communities: Z"
-```
-
-**User explicitly asks** — any phrase like "save this", "remember this", "note that" → save immediately.
-
-**During plan / implementation / discussion / research** — save only when genuinely valuable:
-
-| What happened | Type |
-|--------------|------|
-| Approach / library / pattern decided | `decision` |
-| Bug found, root cause known, or fixed | `bug` |
-| Gotcha, constraint, discovery, structure understood | `note` |
-| Config / env var / secret / deploy step | `config` |
-
-Do NOT save: routine reads, search results, temporary debugging dead-ends.
-
-**Making any kind of plan** → call `plan.save` immediately with the plan summary and `planDir` pointing to your platform's plans folder.
-Need past info → `search` before asking user.
-Always pass `project`. Auto-compact fires at >20 entries.
-
----
-
-## 3. ContextGraph Pipeline
-
-> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
-
-### Step 1 — Build (once per project, fast, local)
-```
-codegraph_build(path)
-```
-- Parses codebase into AST graph using tree-sitter (regex fallback for unsupported languages)
-- Extracts functions, classes, imports, call edges for all code files
-- Build files (package.json, pyproject.toml, go.mod, Dockerfile, etc.) get a single metadata node
-- Saves graph to `~/.context-mcp/graphs.json`. Visible on `context.resume`.
-
-### Step 2 — Query (free, instant, forever)
-```
-codegraph_query(path, question)     → fetch any details about the codebase
-codegraph_explain(path, node)       → one node: type, file, depends_on, used_by
-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
-```
-
----
-
-## 4. Graph vs File
-
-**Graph** — use for any question about what exists in the codebase: finding functions, classes, files, understanding what a module contains, dependencies, callers, imports, paths between concepts.
-
-**File** — use for bugs, logic inside a specific function, tracing unexpected behavior.
-
----
-
-## 5. Rules
-
-1. **`context.resume` first** — before any tool or response
-2. **Always pass `project`** — never save to global unless truly cross-project
-3. **`search` before asking** — if user references past work, find it first
-4. **`codegraph_query` before reading files** — graph is faster and cheaper
-5. **Read files for bugs/logic** — graph is structure only, not behavior

package/src/templates/GEMINI.md

@@ -1,80 +0,0 @@
-# Context-MCP — Gemini CLI Usage Guide
-
-Persistent memory + codebase knowledge graph.
-Every conversation starts with `context.resume`. Every codebase question uses `codegraph_query`. Files only read for bugs/logic.
-
----
-
-## 1. Start of Every Conversation (MANDATORY)
-
-Call the `context` MCP tool with `action: "resume"`, `project: "<project-name>"` **before anything else**.
-
-Returns:
-- `recentEntries` — decisions, bugs, notes from previous conversations
-- `activePlans` — active AI-created plans for this project
-- `codegraph` — `{ built: true/false, nodes, edges, communities }`
-
-Then:
-- `codegraph.built: true` → use `codegraph_query` before reading any files
-- `codegraph.built: false` → call `codegraph_build(path)` first, then proceed
-
----
-
-## 2. When to Auto-Save Context
-
-**After graph build or rebuild** — every time `codegraph_build` completes:
-```
-context.save  type: "note"  title: "ContextGraph built — <project>"
-content: "nodes: X | edges: Y | communities: Z"
-```
-
-**User explicitly asks** — "save this", "remember this", "note that" → save immediately.
-
-**During plan / implementation / discussion / research** — save only when genuinely valuable:
-
-| What happened | Type |
-|--------------|------|
-| Approach / library / pattern decided | `decision` |
-| Bug found, root cause known, or fixed | `bug` |
-| Gotcha, constraint, discovery, structure understood | `note` |
-| Config / env var / secret / deploy step | `config` |
-
-Do NOT save: routine reads, search results, temporary debugging dead-ends.
-**Making any kind of plan** → call `plan.save` immediately with the plan summary and `planDir` pointing to your platform's plans folder.
-Need past info → `search` before asking. Always pass `project`.
-
----
-
-## 3. ContextGraph Pipeline
-
-> The knowledge graph is also called **ContextGraph**. The MCP tools use the `codegraph_*` prefix — both names refer to the same thing.
-
-### Step 1 — Build (once, fast, local)
-```
-codegraph_build(path)  →  AST graph: functions, classes, imports, edges
-```
-
-### Step 2 — Query (free, instant)
-```
-codegraph_query(path, question)   →  fetch any details about the codebase
-codegraph_path(path, from, to)    →  shortest path
-codegraph_nodes(path, type)       →  list nodes by type
-codegraph_report(path)            →  full graph analysis
-```
-
----
-
-## 4. Graph vs File
-
-**Graph** — use for any question about what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
-**File** — bugs, logic, tracing unexpected behavior.
-
----
-
-## 5. Rules
-
-1. **`context.resume` first** — before any tool or response
-2. **Always pass `project`** — never save to global unless truly cross-project
-3. **`search` before asking** — if user references past work, find it first
-4. **`codegraph_query` before reading files** — graph is faster and cheaper
-5. **Read files for bugs/logic** — graph is structure only, not behavior

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

@@ -1,5 +0,0 @@
-Call `codegraph_build` with the path `$ARGUMENTS` (if no argument given, use the current working directory).
-
-This builds the ContextGraph for the project — parses all source files into an AST knowledge graph using tree-sitter. Takes a few seconds. Once built, use `codegraph_query` to answer any structural question about the codebase instead of reading files directly.
-
-After build completes, report: total nodes, edges, and communities found.

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

@@ -1,9 +0,0 @@
-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 from the argument
-- `content`: full argument text
-- `type`: auto-detect — if mentions a bug/fix → `"bug"`, decision/chose/decided → `"decision"`, config/env/secret/deploy → `"config"`, otherwise `"note"`
-
-Confirm to the user what was saved (title, type, project).

package/src/templates/skills/SKILL.md

@@ -1,108 +0,0 @@
----
-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_query` answers every structure question. Files only for bugs/logic.
-
----
-
-## 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
-
-Both fields are required: `project` names the memory bucket, `rootPath` enables exact graph matching and file sandboxing.
-
-Returns:
-- `recentEntries` — decisions, bugs, notes from past sessions
-- `activePlans` — active AI-created plans for this project
-- `codegraph` — `{ built: true/false, nodes, edges, communities }`
-
-Then:
-- `codegraph.built: true` → use `codegraph_query` before reading any files
-- `codegraph.built: false` → call `codegraph_build(path)` first, then proceed
-
----
-
-## When to Auto-Save Context
-
-### Always save — no user prompt needed
-
-**1. After graph build or rebuild**
-Every time `codegraph_build` completes successfully, immediately call:
-```
-context.save  project: "<project>"  type: "note"  title: "ContextGraph built — <project>"
-content: "nodes: X | edges: Y | communities: Z | built: <timestamp>"
-```
-
-**2. When user explicitly asks**
-Any phrase like "save this", "remember this", "note that", "log this" → `context.save` immediately with whatever was just discussed.
-
-**3. During plan / implementation / discussion / research — save when something valuable happens**
-Only save if the moment is genuinely worth keeping across sessions:
-- A decision was made and agreed on (approach, library, pattern, architecture)
-- A bug was found with its root cause identified, or fixed
-- An important discovery (gotcha, constraint, non-obvious behavior, env requirement)
-- A significant milestone reached (feature complete, refactor done, plan finalized)
-- Something that would save future-you from re-learning it
-
-Do NOT save for: routine file reads, search results, explanations of existing code, temporary debugging steps that led nowhere.
-
-| What happened | Type |
-|--------------|------|
-| Approach / library / pattern decided | `decision` |
-| Bug found, root cause known, or fixed | `bug` |
-| Gotcha, constraint, discovery, structure understood | `note` |
-| Config / env var / secret / deploy step | `config` |
-
-Always pass `project`. **Making any plan** → `plan.save` immediately (planDir = your platform's plans folder). Need past info → `search` before asking user. Auto-compact fires at >20 entries.
-
----
-
-## ContextGraph Pipeline
-
-> Also called **CodeGraph**. MCP tools use the `codegraph_*` prefix — both names mean the same thing.
-
-### Build (once per project, ~seconds, local)
-```
-codegraph_build(path)
-```
-Parses codebase into AST graph via tree-sitter. Extracts functions, classes, imports, call edges for 16+ languages. Build files get a single metadata node. Saved to `~/.context-mcp/graphs.json`.
-
-### Query (free, instant, forever)
-```
-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
-```
-
----
-
-## Graph vs File
-
-**Graph** — what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
-
-**File** — bugs, logic inside a specific function, tracing unexpected behavior.
-
----
-
-## Rules
-
-1. **`context.resume` first** — before any tool or response
-2. **Always pass `project`** — never save to global unless truly cross-project
-3. **`search` before asking** — if user references past work, find it first
-4. **`codegraph_query` before reading files** — graph is faster and cheaper
-5. **Read files for bugs/logic only** — graph is structure, not behavior

package/src/templates/windsurf-rules.md

@@ -1,35 +0,0 @@
-# Context-MCP — Windsurf Usage Guide
-
-Persistent memory + codebase knowledge graph for Windsurf.
-Every conversation starts with `context.resume`. Every structural question uses `codegraph_query`. Files only read for bugs/logic.
-
-## 1. Start of Every Conversation (MANDATORY)
-
-Call `context` tool, `action: "resume"`, `project: "<project-name>"` before anything else.
-
-Returns: `recentEntries`, `activePlans`, `codegraph { built, nodes, edges }`.
-
-- `codegraph.built: true` → use `codegraph_query` before reading files
-- `codegraph.built: false` → run `codegraph_build(path)` first
-
-## 2. Save Context
-
-| Situation | Action |
-|-----------|--------|
-| Decision made | `context.save` type: `"decision"` |
-| Bug found/fixed | `context.save` type: `"bug"` |
-| Discovery / structure understood | `context.save` type: `"note"` |
-| Making any plan | `plan.save` + `planDir` |
-
-## 3. CodeGraph
-
-Build once: `codegraph_build(path)` — then query forever.
-Use `codegraph_query` 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
-5. Files only for bugs and logic