context-mcp-server 1.0.6 → 1.0.8

package/codegraph/server.py

@@ -4,8 +4,7 @@ codegraph/server.py — MCP server exposing codebase knowledge graph tools.
 
 Tools:
   codegraph_build   — scan project, extract AST nodes, build graph (local only, no API)
-  codegraph_query   — fetch details about any part of the codebase via natural language
-  codegraph_explain — look up a specific node: type, file, connections
+  codegraph_query   — structural question OR single-node lookup (or both); replaces codegraph_explain
   codegraph_report  — return full CODEGRAPH_REPORT.md
   codegraph_nodes   — list nodes of a given type
   codegraph_path    — shortest path between two concepts
@@ -56,36 +55,21 @@ TOOLS = [
     Tool(
         name="codegraph_query",
         description=(
-            "Fetch details about any part of the codebase using a natural language question. "
-            "Searches the knowledge graph — instant, no API call. "
-            "Use for: finding functions, classes, files, understanding what exists, "
-            "what a module contains, what calls what, what imports what. "
-            "NOT for: bug investigation or tracing unexpected behavior — read the file for that."
+            "Ask a structural question about the codebase OR look up a specific node by name — or both in one call. "
+            "Pass `question` for natural-language traversal: what calls X, what does module Y depend on. "
+            "Pass `node` for fast single-node lookup: returns type, file, depends_on, used_by. "
+            "Pass both to get node detail + surrounding graph context together. "
+            "Returns structured text within token_budget. Use before reading any files."
         ),
         inputSchema={
             "type": "object",
             "properties": {
                 "path":         {"type": "string", "description": "Project root"},
-                "question":     {"type": "string", "description": "Natural language question"},
+                "question":     {"type": "string", "description": "Natural language question about the codebase"},
+                "node":         {"type": "string", "description": "Node name or partial name to look up (type, file, deps, callers)"},
                 "token_budget": {"type": "integer", "description": "Max tokens in response (default 2000)"},
             },
-            "required": ["path", "question"],
-        },
-    ),
-    Tool(
-        name="codegraph_explain",
-        description=(
-            "Look up a specific function, class, or module by name — returns its type, file location, "
-            "and all direct connections (what it depends on, what uses it). "
-            "Use when you already know the name and want its full context in the graph."
-        ),
-        inputSchema={
-            "type": "object",
-            "properties": {
-                "path": {"type": "string", "description": "Project root"},
-                "node": {"type": "string", "description": "Node name or partial name"},
-            },
-            "required": ["path", "node"],
+            "required": ["path"],
         },
     ),
     Tool(
@@ -143,7 +127,7 @@ async def call_tool(name: str, arguments: dict):
 async def _dispatch(name: str, args: dict):
     if name == "codegraph_build":   return await _build(args)
     if name == "codegraph_query":   return await _query(args)
-    if name == "codegraph_explain": return await _explain(args)
+    if name == "codegraph_explain": return await _query(args)
     if name == "codegraph_report":  return await _report(args)
     if name == "codegraph_nodes":   return await _nodes(args)
     if name == "codegraph_path":    return await _path(args)
@@ -223,19 +207,8 @@ async def _build(args: dict) -> dict:
 
 # ── Query / Report / Nodes / Path ─────────────────────────────────────────────
 
-async def _query(args: dict) -> dict:
-    graph_dict = load_graph(args["path"])
-    if not graph_dict:
-        raise ValueError("No graph found. Run codegraph_build first.")
-    return graph_answer(args["question"], graph_dict, token_budget=args.get("token_budget", 2000))
-
-
-async def _explain(args: dict) -> dict:
-    graph_dict = load_graph(args["path"])
-    if not graph_dict:
-        raise ValueError("No graph found. Run codegraph_build first.")
-
-    query = args["node"].lower()
+def _explain_node(node_name: str, graph_dict: dict) -> dict:
+    query = node_name.lower()
     nodes = graph_dict.get("nodes", [])
     edges = graph_dict.get("edges", [])
 
@@ -244,8 +217,8 @@ async def _explain(args: dict) -> dict:
         match = next((n for n in nodes if query in n.get("name", "").lower()), None)
     if not match:
         candidates = [n["name"] for n in nodes if query in n.get("id", "").lower()]
-        return {"found": False, "query": args["node"],
-                "message": f"No node matching '{args['node']}'.",
+        return {"found": False, "query": node_name,
+                "message": f"No node matching '{node_name}'.",
                 "suggestions": candidates[:10]}
 
     nid = match["id"]
@@ -254,13 +227,13 @@ async def _explain(args: dict) -> dict:
         if e.get("from") == nid:
             t = next((n for n in nodes if n.get("id") == e.get("to")), None)
             depends_on.append({"name": t["name"] if t else e["to"],
-                               "file": t.get("file","") if t else "",
-                               "relation": e.get("relation","→")})
+                               "file": t.get("file", "") if t else "",
+                               "relation": e.get("relation", "→")})
         elif e.get("to") == nid:
             s = next((n for n in nodes if n.get("id") == e.get("from")), None)
             used_by.append({"name": s["name"] if s else e["from"],
-                            "file": s.get("file","") if s else "",
-                            "relation": e.get("relation","→")})
+                            "file": s.get("file", "") if s else "",
+                            "relation": e.get("relation", "→")})
 
     return {
         "found":       True,
@@ -270,10 +243,28 @@ async def _explain(args: dict) -> dict:
         "description": match.get("description") or None,
         "depends_on":  depends_on[:20],
         "used_by":     used_by[:20],
-        "hint": None,
     }
 
 
+async def _query(args: dict) -> dict:
+    graph_dict = load_graph(args["path"])
+    if not graph_dict:
+        raise ValueError("No graph found. Run codegraph_build first.")
+
+    question  = args.get("question")
+    node_name = args.get("node")
+
+    if not question and not node_name:
+        raise ValueError("Provide at least one of: question, node")
+
+    result = {}
+    if node_name:
+        result["node"] = _explain_node(node_name, graph_dict)
+    if question:
+        result["query"] = graph_answer(question, graph_dict, token_budget=args.get("token_budget", 2000))
+    return result
+
+
 async def _report(args: dict) -> dict:
     report_path = Path(args["path"]) / "codegraph-cache" / "CODEGRAPH_REPORT.md"
     if report_path.exists():

package/package.json

@@ -1,19 +1,20 @@
 {
   "name": "context-mcp-server",
-  "version": "1.0.6",
+  "version": "1.0.8",
   "description": "Persistent AI memory + codebase knowledge graph MCP server. Works across Claude Code, Cursor, Gemini CLI, Codex, Windsurf, VS Code Copilot, Claude.ai, and ChatGPT.",
   "type": "module",
   "bin": {
     "context-mcp": "./src/index.js",
     "context-mcp-server": "./src/index.js",
     "context-mcp-http": "./src/http.js",
-    "ctx": "./src/cli.js"
+    "ctx": "./src/cli.js",
+    "context": "./src/cli.js"
   },
   "scripts": {
     "mcp": "node src/index.js",
     "mcp-server": "node src/http.js",
     "cli": "node src/cli.js",
-    "check": "node --check src/index.js && node --check src/server.js && node --check src/db.js && node --check src/vector.js && node --check src/summarizer.js && node --check src/search.js && node --check src/config.js && node --check src/cli.js && node --check src/http.js && node --check src/tools/context.js && node --check src/tools/search.js && node --check src/tools/discussion.js && node --check src/tools/errorCheck.js && node --check src/tools/fileTools.js && node --check src/tools/gitTools.js && node --check src/tools/codegraph.js && node --check src/hooks/autoLink.js && node --check src/hooks/autoContext.js",
+    "check": "node --check src/index.js && node --check src/server.js && node --check src/db.js && node --check src/vector.js && node --check src/summarizer.js && node --check src/search.js && node --check src/config.js && node --check src/cli.js && node --check src/http.js && node --check src/tools/context.js && node --check src/tools/search.js && node --check src/tools/plan.js &&node --check src/tools/errorCheck.js && node --check src/tools/fileTools.js && node --check src/tools/gitTools.js && node --check src/tools/codegraph.js && node --check src/hooks/autoLink.js && node --check src/hooks/autoContext.js",
     "check-mcp": "npm run check",
     "test": "node --test",
     "prepublishOnly": "npm run check"

package/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "codegraph-mcp"
-version = "1.0.6"
+version = "1.0.8"
 description = "Codebase knowledge graph MCP server — AST extraction, graph queries, community detection"
 readme = "README.md"
 requires-python = ">=3.11"

package/src/cli.js

@@ -107,8 +107,8 @@ function printSection(title, meta = '') {
 function printUsage() {
   printBanner();
 
-  // Terminal commands (ctx ...)
-  printSection('Terminal commands', 'run from your shell');
+  // Terminal commands (ctx / context ...)
+  printSection('Terminal commands', 'run from your shell  (ctx … or context …)');
   const cmd = (c, desc) => console.log(`  ${accent(c.padEnd(40))} ${faint(desc)}`);
   cmd('ctx',                           'open interactive mode');
   cmd('ctx list [project]',            'list entries + discussions + graphs');
@@ -131,8 +131,8 @@ function printUsage() {
   cmd('ctx help',                      'show this screen');
   console.log('');
 
-  // Interactive mode commands (no ctx prefix)
-  printSection('Interactive mode', 'type these inside  ctx  (no "ctx" prefix)');
+  // Interactive mode commands (no prefix needed)
+  printSection('Interactive mode', 'type these inside the UI — no "ctx" prefix needed');
   const icmd = (c, desc) => console.log(`  ${accent(c.padEnd(40))} ${faint(desc)}`);
   icmd('list [project]',               'list entries');
   icmd('search <query>',               'search context');
@@ -163,17 +163,20 @@ function cmdList(args) {
 
   printSection('Context', filterProject ? `project: ${filterProject}` : 'all projects');
 
-  // Build per-project map
+  // Build per-project map, split entries into their three trees
   const projects = {};
+  const ensureProj = p => {
+    if (!projects[p]) projects[p] = { context: [], summary: [], plans: [] };
+    return projects[p];
+  };
   for (const entry of entries) {
     const p = entry.project || 'global';
-    if (!projects[p]) projects[p] = { contexts: [], discussions: [] };
-    projects[p].contexts.push(entry);
+    const d = ensureProj(p);
+    if (entry.type === 'compaction') d.summary.push(entry);
+    else d.context.push(entry);
   }
   for (const disc of allDiscussions) {
-    const p = disc.project || 'global';
-    if (!projects[p]) projects[p] = { contexts: [], discussions: [] };
-    projects[p].discussions.push(disc);
+    ensureProj(disc.project || 'global').plans.push(disc);
   }
 
   const projectNames = Object.keys(projects).sort();
@@ -185,73 +188,82 @@ function cmdList(args) {
   }
 
   for (const projectName of projectNames) {
-    const pData     = projects[projectName];
-    const graph     = _graphForProject(allGraphs, projectName);
-    const activeD   = pData.discussions.filter(d => d.status === 'active').length;
-    const totalSecs = (pData.contexts.length > 0 ? 1 : 0) + (pData.discussions.length > 0 ? 1 : 0) + (graph ? 1 : 0);
-    let   secIdx    = 0;
-
-    const projReg  = projectRegistry.get(projectName);
+    const pData        = projects[projectName];
+    const graphBuild   = _graphForProject(allGraphs, projectName);
+    const totalEntries = pData.context.length + pData.summary.length;
+    const activePlans  = pData.plans.filter(p => p.status === 'active').length;
+    const sections     = [
+      graphBuild               && 'graph',
+      pData.context.length     && 'context',
+      pData.summary.length     && 'summary',
+      pData.plans.length       && 'plans',
+    ].filter(Boolean);
+    let secIdx = 0;
+
+    const projReg   = projectRegistry.get(projectName);
     const projIdStr = projReg?.id ? faint('  id:' + projReg.id.slice(0, 8)) : '';
-    console.log(`\n  ${color(C.dblue, '◆')} ${bold(lblue(projectName))}${projIdStr}  ${faint(`${pData.contexts.length} entries · ${pData.discussions.length} discussions`)}${activeD ? `  ${warn('● ' + activeD + ' active')}` : ''}`);
+    console.log(`\n  ${color(C.dblue, '◆')} ${bold(lblue(projectName))}${projIdStr}  ${faint(`${totalEntries} entries · ${pData.plans.length} plans`)}${activePlans ? `  ${warn('● ' + activePlans + ' active')}` : ''}`);
     console.log(`  ${color(C.darkgray, '│')}`);
 
-    // ── Graph ────────────────────────────────────────────────────────────────
-    if (graph) {
+    const renderEntries = (items, label, secIsLast) => {
+      console.log(`  ${color(C.darkgray, secIsLast ? '└─' : '├─')} ${muted(label)}  ${faint(items.length + ' entries')}`);
+      items.forEach((item, i) => {
+        const br   = i === items.length - 1 ? '└─' : '├─';
+        const date = (item.createdAt || '').slice(0, 10);
+        const id   = item.id.slice(0, 8);
+        const tags = safeTags(item.tags);
+        const pipe = secIsLast ? ' ' : '│';
+        console.log(`  ${color(C.darkgray, pipe)}  ${color(C.darkgray, br)} ${pill(item.type || 'note')}  ${bold(item.title || '(no title)')}  ${faint('id:' + id)}  ${faint(date)}`);
+        if (tags.length) console.log(`  ${color(C.darkgray, pipe)}     ${faint(tags.map(t => '#' + t).join(' '))}`);
+      });
+      if (!secIsLast) console.log(`  ${color(C.darkgray, '│')}`);
+    };
+
+    // ── Graph (build stats only) ──────────────────────────────────────────────
+    if (graphBuild) {
       secIdx++;
-      const isLast  = secIdx === totalSecs;
-      const builtAt = (graph.builtAt || '').slice(0, 10);
-      console.log(`  ${color(C.darkgray, isLast ? '└─' : '├─')} ${accent('⬡')} ${muted('graph')}  ${faint(`${graph.nodes}n · ${graph.edges}e · ${graph.communities} clusters · ${builtAt}`)}`);
+      const isLast  = secIdx === sections.length;
+      const builtAt = (graphBuild.builtAt || '').slice(0, 10);
+      console.log(`  ${color(C.darkgray, isLast ? '└─' : '├─')} ${accent('⬡')} ${muted('graph')}  ${faint(`${graphBuild.nodes}n · ${graphBuild.edges}e · ${graphBuild.communities} clusters · ${builtAt}`)}`);
       if (!isLast) console.log(`  ${color(C.darkgray, '│')}`);
     }
 
-    // ── Context entries ───────────────────────────────────────────────────────
-    if (pData.contexts.length) {
+    // ── Context ───────────────────────────────────────────────────────────────
+    if (pData.context.length) {
       secIdx++;
-      const isLast = secIdx === totalSecs;
-      console.log(`  ${color(C.darkgray, isLast ? '└─' : '├─')} ${muted('memory')}  ${faint(pData.contexts.length + ' entries')}`);
-      pData.contexts.forEach((item, i) => {
-        const br   = i === pData.contexts.length - 1 ? '└─' : '├─';
+      renderEntries(pData.context, 'context', secIdx === sections.length);
+    }
+
+    // ── Summary (compaction digests only — no type labels) ───────────────────
+    if (pData.summary.length) {
+      secIdx++;
+      const isLast = secIdx === sections.length;
+      console.log(`  ${color(C.darkgray, isLast ? '└─' : '├─')} ${muted('summary')}  ${faint(pData.summary.length + ' compactions')}`);
+      pData.summary.forEach((item, i) => {
+        const br   = i === pData.summary.length - 1 ? '└─' : '├─';
         const date = (item.createdAt || '').slice(0, 10);
-        const type = item.type || 'note';
-        const id   = item.id.slice(0, 8);
-        const tags = safeTags(item.tags);
         const pipe = isLast ? ' ' : '│';
-        console.log(`  ${color(C.darkgray, pipe)}  ${color(C.darkgray, br)} ${pill(type)}  ${bold(item.title || '(no title)')}  ${faint('id:' + id)}  ${faint(date)}`);
-        if (tags.length) console.log(`  ${color(C.darkgray, pipe)}     ${faint(tags.map(t => '#' + t).join(' '))}`);
+        console.log(`  ${color(C.darkgray, pipe)}  ${color(C.darkgray, br)} ${faint('◎')} ${bold(item.title || '(compaction)')}  ${faint(date)}`);
       });
       if (!isLast) console.log(`  ${color(C.darkgray, '│')}`);
     }
 
-    // ── Discussions ───────────────────────────────────────────────────────────
-    if (pData.discussions.length) {
+    // ── Plans ─────────────────────────────────────────────────────────────────
+    if (pData.plans.length) {
       secIdx++;
-      const isLast = secIdx === totalSecs;
-      console.log(`  ${color(C.darkgray, isLast ? '└─' : '├─')} ${muted('discussions')}  ${faint(pData.discussions.length + ' total')}`);
-      pData.discussions.forEach((disc, i) => {
-        const br    = i === pData.discussions.length - 1 ? '└─' : '├─';
-        const sc    = disc.status === 'done' ? 'green' : 'tcyan';
-        const steps = disc.stepsSummary?.total ? faint(` ${disc.stepsSummary.done}/${disc.stepsSummary.total}`) : '';
-        const pipe  = isLast ? ' ' : '│';
-        console.log(`  ${color(C.darkgray, pipe)}  ${color(C.darkgray, br)} ${warn(disc.status === 'active' ? '●' : '○')} ${bold(disc.name)}  ${pill(disc.status, sc)}  ${faint(disc.type || 'plan')}${steps}`);
-        if (disc.description) console.log(`  ${color(C.darkgray, pipe)}     ${faint(disc.description)}`);
+      const isLast = secIdx === sections.length;
+      console.log(`  ${color(C.darkgray, isLast ? '└─' : '├─')} ${muted('plans')}  ${faint(pData.plans.length + ' total')}`);
+      pData.plans.forEach((plan, i) => {
+        const br   = i === pData.plans.length - 1 ? '└─' : '├─';
+        const pipe = isLast ? ' ' : '│';
+        console.log(`  ${color(C.darkgray, pipe)}  ${color(C.darkgray, br)} ${warn(plan.status === 'active' ? '●' : '○')} ${bold(plan.name)}  ${pill(plan.status, plan.status === 'done' ? 'green' : 'tcyan')}  ${faint((plan.description || '').slice(0, 60))}`);
       });
     }
   }
 
-  // Orphan graphs (no matching project)
-  const orphanGraphs = allGraphs.filter(g => !projectNames.some(p => _graphForProject([g], p)));
-  if (orphanGraphs.length) {
-    console.log(`\n  ${color(C.dblue, '◇')} ${muted('other graphs')}`);
-    for (const g of orphanGraphs) {
-      const pathShort = g.path.replace(/\\/g, '/').split('/').slice(-2).join('/');
-      console.log(`    ${accent('⬡')} ${bold(pathShort)}  ${faint(`${g.nodes}n · ${g.edges}e · ${g.communities} clusters`)}`);
-    }
-  }
-
   console.log('');
   console.log(line());
-  console.log(faint(`  ${entries.length} entries  ·  ${allDiscussions.length} discussions  ·  ${allGraphs.length} graphs  ·  ${projectNames.length} projects`));
+  console.log(faint(`  ${entries.length} entries  ·  ${allDiscussions.length} plans  ·  ${allGraphs.length} graphs  ·  ${projectNames.length} projects`));
 }
 
 // ── Search ────────────────────────────────────────────────────────────────────
@@ -429,7 +441,7 @@ function cmdBenchmark() {
   printSection('Benchmark', 'real token savings');
 
   const RESUME_LIMIT = 15;
-  const COMPACT_AT   = 50;
+  const COMPACT_AT   = 20;
 
   // ── Measure entry sizes from actual stored data ──────────────────────────────
   const allEntries   = getContext({ limit: 500, compact: false });