context-mcp-server 1.0.1

package/src/index.js

@@ -0,0 +1,47 @@
+#!/usr/bin/env node
+import { createServer } from './server.js';
+
+// ── CLI flags ─────────────────────────────────────────────────────────────────
+// --data-dir <path>   Override ~/.context-mcp storage directory
+// --help              Show usage
+
+const args = process.argv.slice(2);
+
+if (args.includes('--help') || args.includes('-h')) {
+  console.log(`
+context-mcp — Persistent AI memory MCP server (stdio transport)
+
+Usage:
+  context-mcp [options]
+  npx context-mcp-server@latest [options]
+
+Options:
+  --data-dir <path>   Override storage directory (default: ~/.context-mcp)
+                      Also settable via env: CONTEXT_MCP_DIR=<path>
+  --help, -h          Show this help
+
+Platform setup (stdio):
+  Claude Code:   claude mcp add context-mcp npx context-mcp-server@latest
+  Cursor:        add to .cursor/mcp.json
+  VS Code:       add to .vscode/mcp.json
+  Gemini CLI:    add to .gemini/settings.json
+  Codex CLI:     add to .codex/config.toml
+  Windsurf:      add to global mcp_config.json
+
+Examples:
+  context-mcp
+  context-mcp --data-dir /my/project/.ctx
+  CONTEXT_MCP_DIR=/tmp/ctx context-mcp
+`);
+  process.exit(0);
+}
+
+const dataDirIdx = args.indexOf('--data-dir');
+if (dataDirIdx !== -1 && args[dataDirIdx + 1]) {
+  process.env.CONTEXT_MCP_DIR = args[dataDirIdx + 1];
+}
+
+const { StdioServerTransport } = await import('@modelcontextprotocol/sdk/server/stdio.js');
+const server = createServer();
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/src/search.js

@@ -0,0 +1,50 @@
+/**
+ * search.js — unified search entry point
+ *
+ * Single function replaces direct calls to searchContext / vectorSearch / findRelated
+ * across index.js, cli.js, and error_check. db.js + vector.js stay as low-level impls.
+ */
+
+import { getContext, searchContext } from './db.js';
+import { vectorSearch, findRelated } from './vector.js';
+
+/**
+ * @param {Object} opts
+ * @param {string} opts.query      - search query (keyword/semantic)
+ * @param {string} [opts.mode]     - 'keyword' | 'semantic' | 'related' (default: semantic)
+ * @param {string} [opts.project]  - scope to project
+ * @param {number} [opts.limit]    - max results (default 10)
+ * @param {string} [opts.id]       - [related] entry ID
+ * @param {boolean} [opts.compact] - return compact previews
+ */
+export function search({ query, mode = 'semantic', project, limit = 10, id, compact = false }) {
+  switch (mode) {
+    case 'keyword': {
+      if (!query) throw new Error('query required for keyword search');
+      return searchContext({ query, project, limit, compact });
+    }
+    case 'semantic': {
+      if (!query) throw new Error('query required for semantic search');
+      const corpus = getContext({ project, limit: 500 });
+      return vectorSearch(query, corpus, limit);
+    }
+    case 'related': {
+      if (!id) throw new Error('id required for related search');
+      const all = getContext({ limit: 1000 });
+      const target = all.find(e => e.id === id || e.id.startsWith(id));
+      if (!target) throw new Error(`No entry found with id starting "${id}"`);
+      // explicit relations first, semantic enrichment for remainder
+      const explicitIds = new Set([
+        ...(target.relations  || []).map(r => r.id),
+        ...(target.relatedBy  || []).map(r => r.id),
+      ]);
+      const explicit = all.filter(e => explicitIds.has(e.id));
+      const semantic = explicitIds.size < limit
+        ? findRelated(target, all.filter(e => !explicitIds.has(e.id) && e.id !== target.id), limit - explicitIds.size)
+        : [];
+      return { target, results: [...explicit, ...semantic].slice(0, limit) };
+    }
+    default:
+      throw new Error(`Unknown search mode: ${mode}. Use: keyword, semantic, related`);
+  }
+}

package/src/server.js

@@ -0,0 +1,80 @@
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+
+import { getConfig } from './config.js';
+
+import * as contextTool    from './tools/context.js';
+import * as searchTool     from './tools/search.js';
+import * as discussionTool from './tools/discussion.js';
+import * as errorCheckTool from './tools/errorCheck.js';
+import * as fileTool       from './tools/fileTools.js';
+import * as gitTool        from './tools/gitTools.js';
+import * as codegraphTool  from './tools/codegraph.js';
+
+const FILE_TOOL_NAMES      = new Set(fileTool.definitions.map(d => d.name));
+const GIT_TOOL_NAMES       = new Set(gitTool.definitions.map(d => d.name));
+const CODEGRAPH_TOOL_NAMES = codegraphTool.TOOL_NAMES;
+
+export function createServer({ enableFileTools = false, enableGitTools = getConfig().access_git === true } = {}) {
+  const state = {
+    sessionProject: null,
+    discussionId:   null,
+  };
+
+  const server = new Server(
+    { name: 'context-mcp', version: '1.0.0' },
+    { capabilities: { tools: {} } }
+  );
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const tools = [
+      contextTool.definition,
+      searchTool.definition,
+      discussionTool.definition,
+      errorCheckTool.definition,
+    ];
+    if (enableFileTools) tools.push(...fileTool.definitions);
+    if (enableGitTools)  tools.push(...gitTool.definitions);
+    tools.push(...codegraphTool.definitions);
+    return { tools };
+  });
+
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args = {} } = request.params;
+
+    if (FILE_TOOL_NAMES.has(name) && !enableFileTools) {
+      throw new Error(`Tool "${name}" is only available in online (HTTP) mode.`);
+    }
+    if (GIT_TOOL_NAMES.has(name) && !enableGitTools) {
+      throw new Error(`Tool "${name}" requires ACCESS_GIT=true.`);
+    }
+
+    try {
+      let result;
+
+      if (name === contextTool.definition.name) {
+        result = await contextTool.handle(args, state);
+      } else if (name === searchTool.definition.name) {
+        result = await searchTool.handle(args, state);
+      } else if (name === discussionTool.definition.name) {
+        result = await discussionTool.handle(args, state);
+      } else if (name === errorCheckTool.definition.name) {
+        result = await errorCheckTool.handle(args, state);
+      } else if (FILE_TOOL_NAMES.has(name)) {
+        result = await fileTool.handle(name, args, state);
+      } else if (GIT_TOOL_NAMES.has(name)) {
+        result = await gitTool.handle(name, args, state);
+      } else if (CODEGRAPH_TOOL_NAMES.has(name)) {
+        result = codegraphTool.handle(name, args, state);
+      } else {
+        throw new Error(`Unknown tool: ${name}`);
+      }
+
+      return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+    } catch (err) {
+      return { content: [{ type: 'text', text: `Error: ${err.message}` }], isError: true };
+    }
+  });
+
+  return server;
+}

package/src/summarizer.js

@@ -0,0 +1,124 @@
+/**
+ * summarizer.js — session auto-summarizer
+ *
+ * Groups recent context entries by project and tag, then produces
+ * a structured Markdown summary you can save back as a single entry.
+ *
+ * Uses extractive summarization (no LLM needed):
+ *   1. Score sentences by TF-IDF weight against the session's corpus
+ *   2. Pick top N sentences in original order
+ *   3. Format as structured Markdown
+ */
+
+import { vectorSearch } from './vector.js';
+
+// ── Sentence scoring ──────────────────────────────────────────────────────────
+
+function sentences(text) {
+  return String(text || '')
+    .replace(/\n+/g, ' ')
+    .split(/(?<=[.!?])\s+/)
+    .map(s => s.trim())
+    .filter(s => s.length > 20);
+}
+
+const STOP = new Set([
+  'a','an','the','and','or','but','in','on','at','to','for','of','with',
+  'by','from','is','it','its','as','be','was','are','this','that','i','we',
+]);
+
+function tokens(text) {
+  return text.toLowerCase().replace(/[^a-z0-9\s]/g, ' ').split(/\s+/)
+    .filter(w => w.length > 2 && !STOP.has(w));
+}
+
+function scoreEntry(entry, corpusTokenFreq) {
+  const toks = tokens(`${entry.title || ''} ${entry.content || ''}`);
+  if (!toks.length) return 0;
+  return toks.reduce((s, t) => s + (corpusTokenFreq[t] || 0), 0) / toks.length;
+}
+
+function buildFreq(entries) {
+  const freq = {};
+  for (const e of entries) {
+    for (const t of tokens(`${e.title || ''} ${e.content || ''}`)) {
+      freq[t] = (freq[t] || 0) + 1;
+    }
+  }
+  return freq;
+}
+
+// ── Group by tag ──────────────────────────────────────────────────────────────
+
+function groupByTag(entries) {
+  const groups = {};
+  for (const e of entries) {
+    const tags = Array.isArray(e.tags) ? e.tags : [];
+    const primaryTag = tags[0] || 'general';
+    if (!groups[primaryTag]) groups[primaryTag] = [];
+    groups[primaryTag].push(e);
+  }
+  return groups;
+}
+
+// ── Build Markdown summary ────────────────────────────────────────────────────
+
+/**
+ * Summarize a set of context entries into structured Markdown.
+ *
+ * @param {Array} entries - context entries to summarize
+ * @param {Object} opts
+ * @param {string} opts.project
+ * @param {string} opts.sessionLabel  - e.g. "2025-01-15 morning session"
+ * @param {number} opts.topN          - top entries per group (default 3)
+ * @returns {string} Markdown summary
+ */
+export function summarizeEntries(entries, { project = 'global', sessionLabel = '', topN = 3 } = {}) {
+  if (!entries.length) return '_No entries to summarize._';
+
+  const freq = buildFreq(entries);
+  const label = sessionLabel || new Date().toISOString().slice(0, 10);
+  const groups = groupByTag(entries);
+
+  const lines = [
+    `## Session summary — ${project} · ${label}`,
+    '',
+    `**${entries.length} context entries** across ${Object.keys(groups).length} topic(s).`,
+    '',
+  ];
+
+  for (const [tag, group] of Object.entries(groups)) {
+    lines.push(`### ${tag}`);
+    // Score and pick top N
+    const ranked = group
+      .map(e => ({ ...e, _score: scoreEntry(e, freq) }))
+      .sort((a, b) => b._score - a._score)
+      .slice(0, topN);
+
+    for (const e of ranked) {
+      lines.push(`- **${e.title || e.id.slice(0, 8)}** _(${e.source || 'user'}, ${(e.createdAt || '').slice(0, 10)})_`);
+      // Extract most informative sentence
+      const sents = sentences(e.content);
+      const best = sents.sort((a, b) =>
+        tokens(b).reduce((s, t) => s + (freq[t] || 0), 0) -
+        tokens(a).reduce((s, t) => s + (freq[t] || 0), 0)
+      )[0];
+      if (best) lines.push(`  ${best.length > 140 ? best.slice(0, 137) + '...' : best}`);
+    }
+
+    if (group.length > topN) {
+      lines.push(`  _…and ${group.length - topN} more ${tag} entries_`);
+    }
+    lines.push('');
+  }
+
+  // Key terms
+  const topTerms = Object.entries(freq)
+    .sort((a, b) => b[1] - a[1])
+    .slice(0, 10)
+    .map(([t]) => `\`${t}\``);
+  lines.push(`**Key terms:** ${topTerms.join(', ')}`);
+
+  return lines.join('\n');
+}
+

package/src/templates/AGENTS.md

@@ -0,0 +1,76 @@
+# Context-MCP — Codex CLI Usage Guide
+
+Persistent memory + codebase knowledge graph.
+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 the `context` MCP tool with `action: "resume"`, `project: "<project-name>"` **before anything else**.
+
+Returns:
+- `recentEntries` — decisions, bugs, notes from previous conversations
+- `activeDiscussions` — ongoing topics
+- `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. During the Conversation
+
+| Situation | Action |
+|-----------|--------|
+| Decision made | `context.save` type: `"decision"` |
+| Bug found/fixed | `context.save` type: `"bug"` |
+| Architecture understood | `context.save` type: `"architecture"` |
+| User says "save/remember this" | `context.save` immediately |
+| Feature spans sessions | `discussion.save` status: `"active"` |
+| Need past info | `search` before asking user |
+
+Always pass `project`. Auto-compact fires at >50 entries.
+
+---
+
+## 3. CodeGraph Pipeline
+
+### Step 1 — Build (once, free)
+```
+codegraph_build(path)  →  AST graph: functions, classes, imports, edges
+```
+
+### Step 2 — Enrich (one-time per file)
+```
+codegraph_extract(path)           →  file content + node list
+codegraph_add_nodes(path, nodes)  →  semantic descriptions (permanent cache)
+```
+
+### Step 3 — Query (free, instant)
+```
+codegraph_query(path, question)   →  NODE/EDGE subgraph (token_budget default 2000)
+codegraph_explain(path, node)     →  single node + neighbors
+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** — structural questions: dependencies, callers, imports.
+**File** — bugs, logic, tracing 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**
+5. **Read files for bugs/logic only**
+6. **Enrich once** — descriptions persist forever

package/src/templates/CLAUDE.md

@@ -0,0 +1,94 @@
+---
+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 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` — decisions, bugs, notes from previous conversations
+- `activeDiscussions` — ongoing topics (auto-linked if exactly one active)
+- `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. During the Conversation
+
+| Situation | Action |
+|-----------|--------|
+| Decision made | `context.save` type: `"decision"` |
+| Bug found/fixed | `context.save` type: `"bug"` |
+| Architecture understood | `context.save` type: `"architecture"` |
+| User says "save/remember this" | `context.save` immediately |
+| Feature spans multiple conversations | `discussion.create` or `discussion.update` |
+| Need past info | `search` before asking user |
+
+Always pass `project`. Auto-compact fires at >50 entries — oldest summarized automatically.
+
+---
+
+## 3. CodeGraph Pipeline
+
+### Step 1 — Build (once per project, free)
+```
+codegraph_build(path)
+  → AST: code files → functions, classes, imports, edges
+  → Config: .yaml .toml .sql → schema nodes
+  → Docs: .md .txt .pdf → pending (no content yet)
+```
+Saves graph to `~/.context-mcp/graphs.json`. Visible on `context.resume`.
+
+### Step 2 — Enrich (one-time cost per file)
+```
+codegraph_extract(path)
+  → returns changed code files (with existing node list) + doc files (raw text)
+
+For each code file: write description for each node listed in existing_nodes
+For each doc file:  extract concept nodes + relationships
+
+codegraph_add_nodes(path, nodes)
+  → stores descriptions in semantic cache (never overwritten by rebuild)
+```
+
+### Step 3 — Query (free, instant forever)
+```
+codegraph_query(path, question)   → NODE/EDGE subgraph, token_budget param (default 2000)
+codegraph_explain(path, node)     → one node: description + 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** — structural questions: dependencies, callers, imports, paths between concepts.
+**File** — bugs, logic inside a 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
+6. **Enrich once** — run extract → add_nodes once per project; descriptions persist forever

package/src/templates/GEMINI.md

@@ -0,0 +1,76 @@
+# Context-MCP — Gemini CLI Usage Guide
+
+Persistent memory + codebase knowledge graph.
+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 the `context` MCP tool with `action: "resume"`, `project: "<project-name>"` **before anything else**.
+
+Returns:
+- `recentEntries` — decisions, bugs, notes from previous conversations
+- `activeDiscussions` — ongoing topics (auto-linked if exactly one active)
+- `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. During the Conversation
+
+| Situation | Action |
+|-----------|--------|
+| Decision made | `context.save` type: `"decision"` |
+| Bug found/fixed | `context.save` type: `"bug"` |
+| Architecture understood | `context.save` type: `"architecture"` |
+| User says "save/remember this" | `context.save` immediately |
+| Feature spans sessions | `discussion.save` then `discussion.update` |
+| Need past info | `search` before asking user |
+
+Always pass `project`. Auto-compact fires at >50 entries.
+
+---
+
+## 3. CodeGraph Pipeline
+
+### Step 1 — Build (once, free)
+```
+codegraph_build(path)  →  AST graph: functions, classes, imports, edges
+```
+
+### Step 2 — Enrich (one-time per file)
+```
+codegraph_extract(path)           →  file content + node list
+codegraph_add_nodes(path, nodes)  →  semantic descriptions (permanent cache)
+```
+
+### Step 3 — Query (free, instant)
+```
+codegraph_query(path, question)   →  NODE/EDGE subgraph (token_budget default 2000)
+codegraph_explain(path, node)     →  single node + neighbors
+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** — structural questions: dependencies, callers, imports.
+**File** — bugs, logic, tracing 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
+6. **Enrich once** — descriptions persist forever

package/src/templates/cursor-rules.mdc

@@ -0,0 +1,41 @@
+---
+description: Use context-mcp for persistent memory and codebase knowledge graph across all AI sessions.
+globs: ["**/*"]
+alwaysApply: true
+---
+
+# Context-MCP — Cursor Usage Guide
+
+Persistent memory + codebase knowledge graph for Cursor.
+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`, `activeDiscussions`, `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"` |
+| Architecture understood | `context.save` type: `"architecture"` |
+| Multi-session feature | `discussion.create` |
+
+## 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

package/src/templates/windsurf-rules.md

@@ -0,0 +1,35 @@
+# 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`, `activeDiscussions`, `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"` |
+| Architecture understood | `context.save` type: `"architecture"` |
+| Multi-session feature | `discussion.create` |
+
+## 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