context-mcp-server 1.0.1

package/src/tools/codegraph.js

@@ -0,0 +1,215 @@
+/**
+ * src/tools/codegraph.js — CodeGraph tools bridged to Python subprocess.
+ * Spawns `uv run python -m codegraph` with JSON on stdin, reads JSON from stdout.
+ */
+
+import { spawnSync } from 'node:child_process';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const REPO_ROOT  = join(__dirname, '..', '..');
+
+function callPython(tool, args) {
+  const result = spawnSync('uv', ['run', 'python', '-m', 'codegraph'], {
+    input:    JSON.stringify({ tool, args }),
+    encoding: 'utf8',
+    cwd:      REPO_ROOT,
+    timeout:  120_000,
+  });
+  if (result.error) throw new Error(`codegraph subprocess failed: ${result.error.message}`);
+  if (result.status !== 0) throw new Error(result.stderr?.trim() || 'codegraph error');
+  const out = result.stdout.trim();
+  if (!out) throw new Error('codegraph returned no output');
+  return JSON.parse(out);
+}
+
+export const definitions = [
+  {
+    name: 'codegraph_build',
+    description:
+      'Scan a project directory and build the knowledge graph from code files. ' +
+      'Uses AST extraction for code files. For docs and PDFs, call codegraph_extract ' +
+      'afterward — the AI reads and extracts concepts, then calls codegraph_add_nodes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path:    { type: 'string', description: 'Absolute path to project root' },
+        cluster: { type: 'boolean', description: 'Run community detection after build (default true)' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'codegraph_extract',
+    description:
+      'Return raw content of changed code and doc/PDF files so the AI can write descriptions. ' +
+      'Code files: lists existing AST nodes — AI writes a description for each. ' +
+      'Doc files: AI extracts new concept nodes. ' +
+      'Call after codegraph_build, then call codegraph_add_nodes with results. ' +
+      'Pass force:true to re-enrich all files (not just changed ones).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path:  { type: 'string', description: 'Project root (same as codegraph_build)' },
+        limit: { type: 'integer', description: 'Max files to return per call (default 10)' },
+        force: { type: 'boolean', description: 'Return all files, not just changed (for re-enrichment)' },
+      },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'codegraph_add_nodes',
+    description:
+      'Add concept nodes extracted by the AI into the graph. ' +
+      'Call after reading codegraph_extract output. ' +
+      'Each node: name, type, file, and optionally description and relations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path:  { type: 'string', description: 'Project root' },
+        nodes: {
+          type: 'array',
+          description: 'Concept nodes to add',
+          items: {
+            type: 'object',
+            properties: {
+              name:        { type: 'string' },
+              type:        { type: 'string', description: 'class|function|concept|service|decision|requirement' },
+              file:        { type: 'string', description: 'Relative file path this concept came from' },
+              description: { type: 'string' },
+              relations: {
+                type: 'array',
+                items: {
+                  type: 'object',
+                  properties: {
+                    name:     { type: 'string' },
+                    relation: { type: 'string', description: 'depends-on|uses|implements|defines|documents' },
+                  },
+                },
+              },
+            },
+            required: ['name', 'type', 'file'],
+          },
+        },
+      },
+      required: ['path', 'nodes'],
+    },
+  },
+  {
+    name: 'codegraph_query',
+    description:
+      'Ask a structural/dependency question about the codebase. ' +
+      'Pure graph traversal — returns NODE/EDGE structured text truncated to token_budget. ' +
+      'Good for: "what does module X depend on?", "what calls function Y?", "what is the path from A to B?". ' +
+      'NOT for: bug investigation, logic errors, or understanding what code actually does — read the file directly for those.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path:         { type: 'string', description: 'Project root' },
+        question:     { type: 'string', description: 'Natural language question' },
+        token_budget: { type: 'integer', description: 'Max tokens in response (default 2000)' },
+      },
+      required: ['path', 'question'],
+    },
+  },
+  {
+    name: 'codegraph_explain',
+    description:
+      'Look up a node by name — returns description, type, file, and direct neighbors (depends_on + used_by). ' +
+      'Use to understand what a specific function/class/module does and how it connects. ' +
+      'Descriptions are AI-written via codegraph_add_nodes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string', description: 'Project root' },
+        node: { type: 'string', description: 'Node name or partial name' },
+      },
+      required: ['path', 'node'],
+    },
+  },
+  {
+    name: 'codegraph_report',
+    description: 'Return CODEGRAPH_REPORT.md — god nodes, clusters, surprising connections, suggested questions.',
+    inputSchema: {
+      type: 'object',
+      properties: { path: { type: 'string' } },
+      required: ['path'],
+    },
+  },
+  {
+    name: 'codegraph_nodes',
+    description: 'List all nodes of a given type in the graph.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path:  { type: 'string' },
+        type:  { type: 'string', enum: ['class', 'function', 'module', 'concept', 'service', 'file', 'struct', 'table'] },
+        limit: { type: 'integer', description: 'Max results (default 50)' },
+      },
+      required: ['path', 'type'],
+    },
+  },
+  {
+    name: 'codegraph_path',
+    description: 'Find the shortest relationship path between two concepts in the graph.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        from: { type: 'string' },
+        to:   { type: 'string' },
+      },
+      required: ['path', 'from', 'to'],
+    },
+  },
+];
+
+export const TOOL_NAMES = new Set(definitions.map(d => d.name));
+
+export function handle(name, args, state) {
+  const result = callPython(name, args);
+
+  // Persist graph metadata + save/update a context entry as a visible build record
+  if (name === 'codegraph_build' && result.success) {
+    import('../db.js').then(({ saveGraph, saveContext, updateContext, getContext }) => {
+      saveGraph({
+        path:        args.path,
+        nodes:       result.nodes,
+        edges:       result.edges,
+        communities: result.communities,
+        cached:      result.cached,
+        changed:     result.changed,
+        time_ms:     result.time_ms,
+        summary:     result.summary || '',
+      });
+
+      const project = state?.sessionProject || 'global';
+      const title   = `CodeGraph — ${args.path}`;
+      const content = [
+        `nodes: ${result.nodes} | edges: ${result.edges} | communities: ${result.communities}`,
+        `cached: ${result.cached} | changed: ${result.changed} | time: ${result.time_ms}ms`,
+        result.summary || '',
+      ].filter(Boolean).join('\n');
+
+      const existing = getContext({ project, tags: ['codegraph'], limit: 100 })
+        .find(e => e.title === title);
+
+      if (existing) {
+        updateContext({ id: existing.id, content, status: 'active' });
+      } else {
+        saveContext({
+          project,
+          sessionId: state?.sessionId || null,
+          title,
+          content,
+          type:   'architecture',
+          source: 'auto',
+          tags:   ['codegraph', 'graph-build'],
+        });
+      }
+    }).catch(() => {});
+  }
+
+  return result;
+}

package/src/tools/context.js

@@ -0,0 +1,188 @@
+import {
+  saveContext, updateContext, getContext, deleteContext,
+  listProjects, findDuplicate, archiveExpired, linkContextToDiscussion,
+  listDiscussions, listGraphs, countContext, shouldCompact, compactProject,
+  ensureProject, getProjectRoot,
+} from '../db.js';
+import { summarizeEntries } from '../summarizer.js';
+import { fireAutoLink } from '../hooks/autoLink.js';
+
+function autoDigest(entries, project) {
+  if (entries.length <= 10) return null;
+  return summarizeEntries(entries, { project: project || 'global', topN: 5 });
+}
+
+export const definition = {
+  name: 'context',
+  description:
+    `Factual memory — record what happened, what was decided, what broke, what was built.\n` +
+    `• "resume"       — START HERE every conversation. Loads recent context, active discussions, and graph status for a project.\n` +
+    `• "save"         — Store a note, decision, bug, or code snippet. Auto-deduplicates.\n` +
+    `• "get"          — Load recent entries (compact previews). Auto-digests when large.\n` +
+    `• "update"       — Edit an existing entry by id (any field).\n` +
+    `• "delete"       — Remove an entry by id.\n` +
+    `• "list_projects"— Show all projects and entry counts.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action:        { type: 'string', enum: ['resume', 'save', 'get', 'update', 'delete', 'list_projects'] },
+      content:       { type: 'string' },
+      title:         { type: 'string' },
+      project:       { type: 'string' },
+      rootPath:      { type: 'string', description: 'Absolute path to the project root directory. Stored on first call and used to sandbox file/git tool access.' },
+      type:          { type: 'string', enum: ['decision', 'note', 'code', 'bug', 'architecture', 'config', 'summary', 'error'] },
+      status:        { type: 'string', enum: ['active', 'archived'] },
+      tags:          { type: 'array', items: { type: 'string' } },
+      source:        { type: 'string', enum: ['user', 'ai-summary', 'file', 'web', 'cli', 'auto'] },
+      files:         { type: 'array', items: { type: 'object' } },
+      codeRefs:      { type: 'array', items: { type: 'object' } },
+      relations:     { type: 'array', items: { type: 'object' } },
+      expiresAt:     { type: 'string' },
+      limit:         { type: 'number' },
+      includeArchived: { type: 'boolean' },
+      id:            { type: 'string' },
+    },
+    required: ['action'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      success:  { type: 'boolean' },
+      id:       { type: 'string' },
+      message:  { type: 'string' },
+      entries:  { type: 'array' },
+      count:    { type: 'number' },
+      digest:   { type: 'string' },
+      projects: { type: 'array' },
+      storePath:{ type: 'string' },
+    },
+  },
+};
+
+export async function handle(args, state) {
+  const { getStorePath } = await import('../db.js');
+
+  switch (args.action) {
+
+    case 'resume': {
+      const proj = args.project || null;
+      archiveExpired(proj);
+
+      // Set project on state so autoLink works for subsequent saves
+      if (proj) state.sessionProject = proj;
+
+      // Store rootPath with project (first time only) and load it onto session state
+      if (proj) ensureProject(proj, args.rootPath || undefined);
+      const storedRoot = proj ? getProjectRoot(proj) : null;
+      state.projectRootPath = args.rootPath || storedRoot || null;
+
+      const entries       = getContext({ project: proj, limit: 15, compact: true })
+        .filter(e => e.status !== 'archived');
+      const discussions   = listDiscussions({ project: proj, status: 'active' });
+      const allGraphs     = listGraphs();
+      const graph         = proj
+        ? allGraphs.find(g => g.path?.toLowerCase().includes(proj.toLowerCase())) || allGraphs[0] || null
+        : allGraphs[0] || null;
+      const totalEntries  = countContext(proj);
+
+      // Auto-restore single active discussion
+      if (discussions.length === 1) state.discussionId = discussions[0].id;
+
+      const digest = totalEntries > 10
+        ? autoDigest(getContext({ project: proj, limit: 30 }), proj)
+        : null;
+
+      const graphStatus = graph
+        ? { built: true, path: graph.path, nodes: graph.nodes, edges: graph.edges, communities: graph.communities, builtAt: graph.builtAt }
+        : { built: false };
+
+      return {
+        recentEntries:      entries,
+        activeDiscussions:  discussions,
+        restoredDiscussion: discussions.length === 1 ? { id: discussions[0].id, name: discussions[0].name } : null,
+        codegraph:          graphStatus,
+        digest:             digest || undefined,
+        stats:              { totalEntries, projects: listProjects().length },
+        message: `Loaded ${totalEntries} entries for project "${proj || 'global'}".${discussions.length === 1 ? ` Auto-linked to discussion "${discussions[0].name}".` : ''}`,
+        rootPath: state.projectRootPath || undefined,
+        hint: graphStatus.built
+          ? `Graph ready (${graphStatus.nodes} nodes). Use codegraph_query for structural questions.`
+          : 'No graph built yet. Call codegraph_build on the project root to enable graph queries.',
+      };
+    }
+
+    case 'save': {
+      if (!args.content) throw new Error('content is required for save');
+      if (!args.project && state.sessionProject) args = { ...args, project: state.sessionProject };
+      const dupe = findDuplicate(args.content, args.project);
+      if (dupe) {
+        const updated = updateContext({
+          id: dupe.id, content: args.content,
+          title: args.title || dupe.title, tags: args.tags || dupe.tags,
+          type: args.type || dupe.type, status: args.status || dupe.status,
+          expiresAt: args.expiresAt !== undefined ? args.expiresAt : dupe.expiresAt,
+          files: args.files || dupe.files, codeRefs: args.codeRefs || dupe.codeRefs,
+          relations: args.relations || dupe.relations,
+        });
+        fireAutoLink(updated.id, state);
+        return { success: true, id: updated.id, deduplicated: true,
+          message: `Updated existing entry "${updated.title || updated.id}" (auto-dedup).` };
+      }
+      const entry = saveContext({ ...args });
+      fireAutoLink(entry.id, state);
+
+      // Auto-compact when too many entries accumulate
+      let compaction = null;
+      if (shouldCompact(entry.project)) {
+        const old = getContext({ project: entry.project, limit: 500 });
+        const { summarizeEntries: summarize } = await import('../summarizer.js');
+        const cs = summarize(old.slice(old.length - 30), { project: entry.project || 'global', sessionLabel: 'auto-compaction', topN: 5 });
+        compaction = compactProject(entry.project, cs);
+      }
+
+      return { success: true, id: entry.id, deduplicated: false,
+        compaction: compaction ? { removedCount: compaction.removedCount, message: `Auto-compacted ${compaction.removedCount} old entries into summary.` } : null,
+        message: `Saved context "${entry.title || entry.id}" under project "${entry.project}".` };
+    }
+
+    case 'get': {
+      if (!args.project && state.sessionProject) args = { ...args, project: state.sessionProject };
+      archiveExpired(args.project);
+      const includeArchived = args.includeArchived === true;
+      let entries = getContext({ project: args.project, tags: args.tags, limit: args.limit, compact: true });
+      if (!includeArchived) entries = entries.filter(e => e.status !== 'archived');
+      const fullEntries = entries.length > 10
+        ? getContext({ project: args.project, tags: args.tags, limit: args.limit })
+            .filter(e => includeArchived || e.status !== 'archived')
+        : null;
+      const digest = fullEntries ? autoDigest(fullEntries, args.project) : null;
+      return {
+        entries, count: entries.length, digest: digest || undefined,
+        message: entries.length
+          ? `Found ${entries.length} entries.${digest ? ' Auto-digest included.' : ''} Use search for full content.`
+          : 'No context found.',
+      };
+    }
+
+    case 'update': {
+      if (!args.id) throw new Error('id is required for update');
+      const updated = updateContext({ ...args });
+      if (!updated) throw new Error(`No entry found with id "${args.id}"`);
+      fireAutoLink(updated.id, state);
+      return { success: true, id: updated.id, version: updated.version,
+        message: `Updated entry "${updated.title || updated.id}" (v${updated.version}).` };
+    }
+
+    case 'delete': {
+      if (!args.id) throw new Error('id is required for delete');
+      return deleteContext(args);
+    }
+
+    case 'list_projects': {
+      return { projects: listProjects(), storePath: getStorePath() };
+    }
+
+    default:
+      throw new Error(`Unknown context action: ${args.action}`);
+  }
+}

package/src/tools/discussion.js

@@ -0,0 +1,123 @@
+import {
+  saveDiscussion, getDiscussion, listDiscussions, deleteDiscussion,
+  updateDiscussion, updateDiscussionStep, clearDiscussionLink,
+} from '../db.js';
+
+export const definition = {
+  name: 'discussion',
+  description:
+    `Forward-looking thinking space — plans, research, ideas, design.\n` +
+    `• "save"        — Create or update a discussion.\n` +
+    `• "update"      — Patch specific fields without touching the rest.\n` +
+    `• "get"         — Retrieve by name or id (full content + steps).\n` +
+    `• "list"        — List discussions (filterable). Header + stepsSummary only.\n` +
+    `• "delete"      — Remove by name or id.\n` +
+    `• "update_step" — Mark a step done/in-progress. Auto-closes when all done.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action:           { type: 'string', enum: ['save', 'get', 'list', 'delete', 'update', 'update_step'] },
+      name:             { type: 'string' },
+      id:               { type: 'string' },
+      project:          { type: 'string' },
+      title:            { type: 'string' },
+      description:      { type: 'string' },
+      content:          { type: 'string' },
+      type:             { type: 'string', enum: ['plan', 'research', 'idea', 'design', 'implementation', 'review', 'thread'] },
+      status:           { type: 'string', enum: ['active', 'done'] },
+      tags:             { type: 'array', items: { type: 'string' } },
+      parentId:         { type: 'string' },
+      linkedContextIds: { type: 'array', items: { type: 'string' } },
+      steps:            { type: 'array', items: { type: 'object' } },
+      stepId:           { type: 'string' },
+      stepStatus:       { type: 'string', enum: ['pending', 'in-progress', 'done', 'skipped'] },
+      linkedContextId:  { type: 'string' },
+      filterStatus:     { type: 'string' },
+      filterType:       { type: 'string' },
+    },
+    required: ['action'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      success:     { type: 'boolean' },
+      id:          { type: 'string' },
+      name:        { type: 'string' },
+      discussion:  { type: 'object' },
+      discussions: { type: 'array' },
+      step:        { type: 'object' },
+      message:     { type: 'string' },
+    },
+  },
+};
+
+export async function handle(args, state) {
+  switch (args.action) {
+    case 'save': {
+      if (!args.name) throw new Error('name is required for save');
+      const disc = saveDiscussion({ ...args, sessionId: args.sessionId || state.sessionId });
+      if (disc.status === 'active')                                  state.discussionId = disc.id;
+      else if (state.discussionId === disc.id)                       state.discussionId = null;
+      return { success: true, id: disc.id, name: disc.name,
+        message: `Discussion "${disc.name}" saved (${disc.type}, ${disc.status}).` };
+    }
+
+    case 'get': {
+      if (!args.name && !args.id) throw new Error('name or id is required for get');
+      const disc = getDiscussion({ name: args.name, id: args.id, project: args.project });
+      return disc
+        ? { discussion: disc }
+        : { discussion: null, message: `No discussion found for "${args.name || args.id}".` };
+    }
+
+    case 'update': {
+      if (!args.name && !args.id) throw new Error('name or id is required for update');
+      const updated = updateDiscussion({ ...args });
+      if (!updated) throw new Error(`No discussion found for "${args.name || args.id}".`);
+      if (updated.status !== 'active' && state.discussionId === updated.id) state.discussionId = null;
+      if (updated.status === 'active')                                        state.discussionId = updated.id;
+      return { success: true, id: updated.id, name: updated.name, status: updated.status,
+        message: `Discussion "${updated.name}" updated (${updated.status}).` };
+    }
+
+    case 'list': {
+      return { discussions: listDiscussions({ project: args.project, status: args.filterStatus, type: args.filterType }) };
+    }
+
+    case 'delete': {
+      if (!args.name && !args.id) throw new Error('name or id is required for delete');
+      const toDelete = getDiscussion({ name: args.name, id: args.id });
+      if (toDelete) {
+        for (const ctxId of (toDelete.linkedContextIds || [])) clearDiscussionLink(ctxId);
+      }
+      const del = deleteDiscussion({ name: args.name, id: args.id });
+      if (state.discussionId) {
+        const matchById   = args.id   && args.id   === state.discussionId;
+        const matchByName = args.name && del.deleted > 0;
+        if (matchById || matchByName) state.discussionId = null;
+      }
+      return { ...del, message: `Deleted ${del.deleted} discussion(s).` };
+    }
+
+    case 'update_step': {
+      if (!args.name && !args.id) throw new Error('name or id is required for update_step');
+      if (!args.stepId) throw new Error('stepId is required for update_step');
+      const updated = updateDiscussionStep({
+        discussionName:  args.name,
+        discussionId:    args.id,
+        stepId:          args.stepId,
+        status:          args.stepStatus,
+        linkedContextId: args.linkedContextId,
+      });
+      if (!updated) throw new Error('Discussion or step not found.');
+      if (updated.discussion.status === 'done' && state.discussionId === updated.discussion.id) {
+        state.discussionId = null;
+      }
+      return { success: true, step: updated.step, discussionStatus: updated.discussion.status,
+        message: `Step updated. Discussion "${updated.discussion.name}" is now "${updated.discussion.status}".` };
+    }
+
+    default:
+      throw new Error(`Unknown discussion action: ${args.action}`);
+  }
+}

package/src/tools/errorCheck.js

@@ -0,0 +1,65 @@
+import { saveContext, getContext } from '../db.js';
+import { search as unifiedSearch } from '../search.js';
+import { fireAutoLink } from '../hooks/autoLink.js';
+
+export const definition = {
+  name: 'error_check',
+  description:
+    `Diagnose and track terminal errors.\n` +
+    `• action "check" — Search memory for past occurrences of this error.\n` +
+    `• action "save"  — Record a new error, the command that caused it, and the solution.`,
+  inputSchema: {
+    type: 'object',
+    properties: {
+      action:       { type: 'string', enum: ['check', 'save'] },
+      errorMessage: { type: 'string' },
+      command:      { type: 'string' },
+      solution:     { type: 'string' },
+      project:      { type: 'string' },
+    },
+    required: ['action', 'errorMessage'],
+  },
+  outputSchema: {
+    type: 'object',
+    properties: {
+      success: { type: 'boolean' },
+      found:   { type: 'boolean' },
+      matches: { type: 'array' },
+      message: { type: 'string' },
+    },
+  },
+};
+
+export async function handle(args, state) {
+  const { action, errorMessage, command, solution, project } = args;
+
+  if (action === 'check') {
+    const results = unifiedSearch({ mode: 'semantic', query: errorMessage, project, limit: 5 })
+      .filter(r => r.type === 'bug');
+    if (results.length > 0 && results[0].similarity > 0.4) {
+      return {
+        success: true, found: true,
+        matches: results.map(r => ({ title: r.title, solution: r.content, similarity: Math.round(r.similarity * 100) + '%', id: r.id })),
+        message: `Found ${results.length} similar past error(s).`,
+      };
+    }
+    return { success: true, found: false, message: 'No similar past errors found in memory.' };
+  }
+
+  if (action === 'save') {
+    if (!solution) throw new Error('solution is required for save action');
+    const entry = saveContext({
+      project,
+      sessionId: state.sessionId || null,
+      title:   `Error: ${errorMessage.split('\n')[0].slice(0, 60)}`,
+      content: `Command: ${command || 'unknown'}\n\nError:\n${errorMessage}\n\nSolution:\n${solution}`,
+      type:    'bug',
+      status:  'done',
+      tags:    ['error-log', command].filter(Boolean),
+    });
+    fireAutoLink(entry.id, state);
+    return { success: true, message: `Error logged to context (id: ${entry.id.slice(0, 8)}).` };
+  }
+
+  throw new Error(`Unknown error_check action: ${action}`);
+}