context-mcp-server 1.0.1 → 1.0.3

package/codegraph/extractors/build_extractor.py

@@ -0,0 +1,68 @@
+"""
+build_extractor.py — extract key metadata from build/config files.
+Returns a SINGLE node per file (not decomposed into functions/classes).
+"""
+
+import json
+import re
+from pathlib import Path
+
+
+def extract(abs_path: str, rel_path: str) -> list[dict]:
+    """Return a single node for the build file with key fields in description."""
+    p    = Path(abs_path)
+    name = p.name
+    meta = _read_meta(p)
+
+    node = {
+        "id":          f"{rel_path}::file::{name}",
+        "name":        name,
+        "type":        "file",
+        "file":        rel_path,
+        "description": _format_meta(meta) if meta else None,
+    }
+    return [node]
+
+
+def _read_meta(p: Path) -> dict:
+    try:
+        if p.name == "package.json":
+            data = json.loads(p.read_text(encoding="utf-8", errors="ignore"))
+            return {
+                "name":    data.get("name"),
+                "version": data.get("version"),
+                "deps":    list((data.get("dependencies") or {}).keys())[:10],
+            }
+        if p.suffix == ".toml":
+            text    = p.read_text(encoding="utf-8", errors="ignore")
+            name    = re.search(r'^name\s*=\s*"([^"]+)"', text, re.M)
+            version = re.search(r'^version\s*=\s*"([^"]+)"', text, re.M)
+            return {
+                "name":    name.group(1) if name else None,
+                "version": version.group(1) if version else None,
+            }
+        if p.name in {"requirements.txt", "Pipfile"}:
+            lines = p.read_text(encoding="utf-8", errors="ignore").splitlines()
+            deps  = [l.strip() for l in lines if l.strip() and not l.startswith("#")]
+            return {"deps": deps[:10]}
+        if p.name == "go.mod":
+            text   = p.read_text(encoding="utf-8", errors="ignore")
+            module = re.search(r'^module\s+(\S+)', text, re.M)
+            go_ver = re.search(r'^go\s+(\S+)', text, re.M)
+            return {
+                "module": module.group(1) if module else None,
+                "go":     go_ver.group(1) if go_ver else None,
+            }
+    except Exception:
+        pass
+    return {}
+
+
+def _format_meta(meta: dict) -> str | None:
+    parts = []
+    if meta.get("name"):    parts.append(f"name={meta['name']}")
+    if meta.get("version"): parts.append(f"version={meta['version']}")
+    if meta.get("module"):  parts.append(f"module={meta['module']}")
+    if meta.get("go"):      parts.append(f"go={meta['go']}")
+    if meta.get("deps"):    parts.append(f"deps=[{', '.join(meta['deps'])}]")
+    return ", ".join(parts) if parts else None

package/codegraph/scanner.py

@@ -7,12 +7,7 @@ from pathlib import Path
 from typing import Iterator
 
 from .cache import file_hash, get_cached_nodes, set_cached_nodes, remove_deleted, load_cache, save_cache
-from .config import (
-    DEFAULT_IGNORE, MAX_FILE_BYTES,
-    CODE_EXTENSIONS, SQL_EXTENSIONS, CONFIG_EXTENSIONS,
-    DOC_EXTENSIONS, PDF_EXTENSIONS, IMAGE_EXTENSIONS,
-    AUDIO_EXTENSIONS, VIDEO_EXTENSIONS,
-)
+from .config import DEFAULT_IGNORE, MAX_FILE_BYTES, SKIP_FILENAMES, SKIP_EXTENSIONS, classify_file
 
 
 def _should_ignore(name: str, ignore: set) -> bool:
@@ -26,6 +21,9 @@ def walk_files(root: str, extra_ignore: set | None = None) -> Iterator[str]:
         # Prune ignored dirs in-place so os.walk doesn't descend
         dirnames[:] = [d for d in dirnames if d not in ignore and not d.startswith(".")]
         for fname in filenames:
+            ext = Path(fname).suffix.lower()
+            if fname in SKIP_FILENAMES or ext in SKIP_EXTENSIONS:
+                continue
             abs_path = os.path.join(dirpath, fname)
             try:
                 if os.path.getsize(abs_path) > MAX_FILE_BYTES:
@@ -35,20 +33,6 @@ def walk_files(root: str, extra_ignore: set | None = None) -> Iterator[str]:
             yield abs_path
 
 
-def classify_file(path: str) -> str:
-    """Return extraction category for a file."""
-    ext = Path(path).suffix.lower()
-    if ext in CODE_EXTENSIONS:    return "code"
-    if ext in SQL_EXTENSIONS:     return "sql"
-    if ext in CONFIG_EXTENSIONS:  return "config"
-    if ext in DOC_EXTENSIONS:     return "doc"
-    if ext in PDF_EXTENSIONS:     return "pdf"
-    if ext in IMAGE_EXTENSIONS:   return "image"
-    if ext in AUDIO_EXTENSIONS:   return "audio"
-    if ext in VIDEO_EXTENSIONS:   return "video"
-    return "unknown"
-
-
 def scan(project_root: str, extra_ignore: set | None = None) -> dict:
     """
     Walk project, diff against cache.
@@ -72,7 +56,7 @@ def scan(project_root: str, extra_ignore: set | None = None) -> dict:
         rel_path = os.path.relpath(abs_path, root).replace("\\", "/")
         existing_rel.add(rel_path)
         category = classify_file(abs_path)
-        if category == "unknown":
+        if category in ("unknown", "skip"):
             continue
         h = file_hash(abs_path)
         nodes = get_cached_nodes(cache, rel_path, h)

package/codegraph/server.py

@@ -3,13 +3,12 @@
 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_extract    — return raw doc content for the AI to read and extract concepts from
-  codegraph_add_nodes  — AI pushes extracted concept nodes back into the graph
-  codegraph_query      — natural language question → graph traversal answer
-  codegraph_report     — return full CODEGRAPH_REPORT.md
-  codegraph_nodes      — list nodes of a given type
-  codegraph_path       — shortest path between two concepts
+  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_report  — return full CODEGRAPH_REPORT.md
+  codegraph_nodes   — list nodes of a given type
+  codegraph_path    — shortest path between two concepts
 """
 
 import asyncio
@@ -22,10 +21,10 @@ from mcp.server import Server
 from mcp.server.stdio import stdio_server
 from mcp.types import Tool, TextContent
 
-from .scanner import scan, classify_file
-from .cache import file_hash, set_cached_nodes, save_cache, save_semantic_cache
+from .scanner import scan
+from .config import classify_file
+from .cache import file_hash, set_cached_nodes, save_cache
 from .extractors.ast_extractor import extract as ast_extract
-from .extractors.doc_extractor import extract_text
 from .graph.builder import build, to_json_dict, save_graph, load_graph
 from .graph.query import answer as graph_answer, find_path
 from .graph.clustering import detect_communities
@@ -41,10 +40,9 @@ TOOLS = [
         name="codegraph_build",
         description=(
             "Scan a project directory and build the knowledge graph from code files. "
-            "Uses AST extraction (with regex fallback) for all code files. "
+            "Uses tree-sitter AST (with regex fallback) for all code files. "
             "Fast, local, no API key needed. "
-            "For docs and images, call codegraph_extract afterward — the AI reads and extracts concepts, "
-            "then calls codegraph_add_nodes to push them into the graph."
+            "Run once per project; rebuild whenever code changes."
         ),
         inputSchema={
             "type": "object",
@@ -55,69 +53,14 @@ TOOLS = [
             "required": ["path"],
         },
     ),
-    Tool(
-        name="codegraph_extract",
-        description=(
-            "Return raw content of changed doc files so the AI can read them and extract concepts. "
-            "Call this after codegraph_build. Read the returned files, extract key concepts and "
-            "relationships, then call codegraph_add_nodes with your findings. "
-            "Works with any AI — no API key required."
-        ),
-        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)"},
-            },
-            "required": ["path"],
-        },
-    ),
-    Tool(
-        name="codegraph_add_nodes",
-        description=(
-            "Add concept nodes extracted by the AI into the graph. "
-            "Call this after reading the output of codegraph_extract. "
-            "Each node should have: 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"],
-        },
-    ),
     Tool(
         name="codegraph_query",
         description=(
-            "Ask a structural question about the codebase. Pure graph traversal — instant, no API call. "
-            "Returns structured NODE/EDGE text truncated to token_budget. "
-            "Good for: dependencies, callers, module relationships. "
-            "NOT for: bug investigation or understanding code logic — read the file for that."
+            "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."
         ),
         inputSchema={
             "type": "object",
@@ -132,9 +75,9 @@ TOOLS = [
     Tool(
         name="codegraph_explain",
         description=(
-            "Look up a node by name — returns description, type, file, and direct neighbors. "
-            "Use to understand what a specific function/class/module does and how it connects. "
-            "Descriptions are AI-written via codegraph_add_nodes."
+            "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",
@@ -198,14 +141,12 @@ 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_extract":    return await _extract(args)
-    if name == "codegraph_add_nodes":  return await _add_nodes(args)
-    if name == "codegraph_query":      return await _query(args)
-    if name == "codegraph_explain":    return await _explain(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)
+    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_report":  return await _report(args)
+    if name == "codegraph_nodes":   return await _nodes(args)
+    if name == "codegraph_path":    return await _path(args)
     raise ValueError(f"Unknown tool: {name}")
 
 
@@ -222,9 +163,7 @@ async def _build(args: dict) -> dict:
     changed = scan_result["changed"]
     deleted = scan_result["deleted"]
 
-    # Local AST extraction — code/sql/config files only
     all_nodes: list[dict] = []
-    pending_docs: list[str] = []   # rel_paths of changed docs/images for codegraph_extract
 
     for nodes in cached.values():
         all_nodes.extend(nodes)
@@ -241,9 +180,12 @@ async def _build(args: dict) -> dict:
                     "name": Path(rel_path).name, "type": "file", "file": rel_path}
             set_cached_nodes(cache, rel_path, file_hash(abs_path), [node])
             all_nodes.append(node)
-        elif cat in ("doc", "pdf"):
-            pending_docs.append(rel_path)
-        elif cat in ("image", "audio", "video"):
+        elif cat == "build":
+            from codegraph.extractors.build_extractor import extract as build_extract
+            nodes = build_extract(abs_path, rel_path)
+            set_cached_nodes(cache, rel_path, file_hash(abs_path), nodes)
+            all_nodes.extend(nodes)
+        elif cat in ("image", "audio", "video", "doc", "pdf"):
             # Label-only — node in graph so AI can reference the file, no content extraction
             node = {"id": f"{rel_path}::file::{Path(rel_path).name}",
                     "name": Path(rel_path).name, "type": "file", "file": rel_path}
@@ -276,147 +218,9 @@ async def _build(args: dict) -> dict:
         "summary":     f"Built graph: {len(graph_dict.get('nodes', []))} nodes from code files.",
     }
 
-    if pending_docs:
-        result["pending_docs"] = len(pending_docs)
-        result["hint"] = (
-            f"{len(pending_docs)} doc/image file(s) need concept extraction. "
-            "Call codegraph_extract to get their content, then codegraph_add_nodes with your findings."
-        )
-
     return result
 
 
-# ── Extract (return raw content for AI to read) ───────────────────────────────
-
-async def _extract(args: dict) -> dict:
-    root  = args["path"]
-    limit = args.get("limit", 10)
-    force = args.get("force", False)
-
-    scan_result = scan(root)
-    cache   = scan_result["cache"]
-    scan_root = scan_result["root"]
-    # force=True: return all files; otherwise only changed
-    if force:
-        from codegraph.scanner import walk_files, classify_file
-        candidates = {
-            os.path.relpath(p, scan_root).replace("\\", "/"): p
-            for p in walk_files(scan_root)
-            if classify_file(p) in ("doc", "code")
-        }
-    else:
-        candidates = scan_result["changed"]
-
-    files = []
-    for rel_path, abs_path in list(candidates.items()):
-        if len(files) >= limit:
-            break
-        cat = classify_file(abs_path)
-        if cat in ("doc", "code"):
-            text = extract_text(abs_path)
-            if not text:
-                continue
-            entry: dict = {"rel_path": rel_path, "type": cat, "content": text}
-            # For code files, include existing AST nodes so AI knows what to describe
-            if cat == "code":
-                cached_entry = cache.get(rel_path, {})
-                existing_nodes = cached_entry.get("nodes", [])
-                entry["existing_nodes"] = [
-                    {"name": n.get("name"), "type": n.get("type")}
-                    for n in existing_nodes
-                ]
-            files.append(entry)
-
-    remaining = max(0, len(candidates) - limit)
-    return {
-        "files": files,
-        "returned": len(files),
-        "remaining": remaining,
-        "instruction": (
-            "For each file: read the content. "
-            "For code files, write a description for each existing_node (name + type listed). "
-            "For doc files, extract key concepts, decisions, and relationships as new nodes. "
-            "Then call codegraph_add_nodes with all nodes (include description field)."
-        ),
-    }
-
-
-# ── Add nodes (AI pushes extracted concepts in) ───────────────────────────────
-
-async def _add_nodes(args: dict) -> dict:
-    root  = args["path"]
-    nodes = args.get("nodes", [])
-
-    if not nodes:
-        return {"success": False, "message": "No nodes provided."}
-
-    graph_dict = load_graph(root) or {"nodes": [], "edges": [], "communities": [], "god_nodes": []}
-
-    # Assign IDs and merge; update description on existing nodes
-    existing_map = {n["id"]: n for n in graph_dict["nodes"]}
-    added = 0
-    updated = 0
-    for node in nodes:
-        nid = f"{node['file']}::concept::{node['name']}"
-        desc = node.get("description", "")
-        if nid in existing_map:
-            if desc and desc != existing_map[nid].get("description", ""):
-                existing_map[nid]["description"] = desc
-                updated += 1
-            # Still add edges below
-        else:
-            new_node = {
-                "id":          nid,
-                "name":        node["name"],
-                "type":        node.get("type", "concept"),
-                "file":        node["file"],
-                "description": desc,
-            }
-            graph_dict["nodes"].append(new_node)
-            existing_map[nid] = new_node
-            added += 1
-
-        # Also try to enrich AST nodes (different ID pattern: file::type::name)
-        for id_pattern in [
-            f"{node['file']}::{node.get('type','function')}::{node['name']}",
-            f"{node['file']}::function::{node['name']}",
-            f"{node['file']}::class::{node['name']}",
-            f"{node['file']}::module::{node['name']}",
-        ]:
-            if id_pattern in existing_map and desc:
-                if not existing_map[id_pattern].get("description"):
-                    existing_map[id_pattern]["description"] = desc
-                    updated += 1
-
-        # Add relation edges
-        for rel in node.get("relations", []):
-            graph_dict["edges"].append({
-                "from":     nid,
-                "to":       rel["name"],
-                "relation": rel.get("relation", "relates-to"),
-                "confidence": "EXTRACTED",
-            })
-
-    # Persist descriptions to semantic cache (never overwritten by rebuild)
-    by_file: dict = {}
-    for node in nodes:
-        if node.get("description"):
-            by_file.setdefault(node["file"], []).append(node)
-    if by_file:
-        save_semantic_cache(root, by_file)
-
-    save_graph(root, graph_dict)
-    generate_report(graph_dict, root)
-
-    return {
-        "success":      True,
-        "nodes_added":  added,
-        "nodes_updated": updated,
-        "total_nodes":  len(graph_dict["nodes"]),
-        "message":      f"Added {added}, updated {updated} node description(s).",
-    }
-
-
 # ── Query / Report / Nodes / Path ─────────────────────────────────────────────
 
 async def _query(args: dict) -> dict:
@@ -466,8 +270,7 @@ async def _explain(args: dict) -> dict:
         "description": match.get("description") or None,
         "depends_on":  depends_on[:20],
         "used_by":     used_by[:20],
-        "hint": None if match.get("description") else
-                "No description yet. Call codegraph_extract → codegraph_add_nodes to enrich.",
+        "hint": None,
     }
 
 

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "context-mcp-server",
-  "version": "1.0.1",
+  "version": "1.0.3",
   "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"
   },

package/src/cli.js

@@ -119,9 +119,11 @@ function printUsage() {
   cmd('ctx discuss [project]',      'show discussions');
   cmd('ctx benchmark',              'token savings report (memory + graph)');
   console.log('');
+  cmd('ctx install --initial',          'install / update Node.js + Python (codegraph) deps');
   cmd('ctx install --<platform>',      'write MCP config + instruction file for an AI platform');
   cmd('ctx install --all',             'install for all platforms at once');
   cmd('ctx online [--port N]',         'start HTTP server + show credentials for Claude.ai / ChatGPT');
+  cmd('ctx online --close',            'stop the running HTTP server');
   cmd('ctx settings',                  'view and edit config (port, host, client id/secret)');
   console.log('');
   cmd('ctx help',                      'show this screen');
@@ -586,10 +588,8 @@ const PLATFORMS = {
   windsurf: {
     label: 'Windsurf',
     install(cwd) {
-      // Local rule file
       const rules = _tpl('windsurf-rules.md');
       if (rules) _writeFile(join(cwd, '.windsurf', 'rules', 'context-mcp.md'), rules, '.windsurf/rules/context-mcp.md');
-      // Global Windsurf config
       const globalCfgPath = join(homedir(), '.codeium', 'windsurf', 'mcp_config.json');
       let existing = {};
       try { existing = JSON.parse(readFileSync(globalCfgPath, 'utf8')); } catch {}
@@ -602,12 +602,57 @@ const PLATFORMS = {
 
 function cmdInstall(args) {
   const flags = new Set(args.map(a => a.replace(/^--/, '')));
-  const all   = flags.has('all');
+  const all     = flags.has('all');
+  const initial = flags.has('initial');
   const keys  = all ? Object.keys(PLATFORMS) : Object.keys(PLATFORMS).filter(k => flags.has(k));
 
+  if (initial) {
+    printSection('Install', 'install / update');
+    console.log('');
+
+    const __dirname_init = dirname(fileURLToPath(import.meta.url));
+    const pkgRootInit = join(__dirname_init, '..');
+
+    // Node.js packages
+    console.log(`  ${bold(lblue('Node.js packages'))}`);
+    const npmInstall = spawnSync('npm', ['install', '--omit=dev'], {
+      cwd: pkgRootInit, encoding: 'utf8', shell: true,
+    });
+    if (npmInstall.status !== 0) {
+      console.log(`  ${bad('✗')} npm install failed:\n${faint((npmInstall.stderr || npmInstall.stdout || '').trim())}`);
+    } else {
+      console.log(`  ${ok('✓')} Node.js dependencies installed`);
+    }
+    console.log('');
+
+    // Python / uv (codegraph)
+    console.log(`  ${bold(lblue('Python Codegraph'))}`);
+    const uvCheck2 = spawnSync('uv', ['--version'], { encoding: 'utf8', shell: true });
+    if (uvCheck2.error || uvCheck2.status !== 0) {
+      console.log(`  ${bad('✗')} uv not found — install from ${accent('https://docs.astral.sh/uv/')} to enable codegraph`);
+    } else {
+      console.log(`  ${ok('✓')} uv found: ${faint(uvCheck2.stdout.trim())}`);
+      // On Windows, an existing .venv contains a lib64 junction that uv can't remove — wipe it first
+      if (process.platform === 'win32') {
+        const venvPath = join(pkgRootInit, '.venv');
+        spawnSync('cmd', ['/c', 'rmdir', '/s', '/q', venvPath], { encoding: 'utf8' });
+      }
+      const sync2 = spawnSync('uv', ['sync', '--no-dev'], { cwd: pkgRootInit, encoding: 'utf8', shell: true });
+      if (sync2.status !== 0) {
+        console.log(`  ${bad('✗')} uv sync failed:\n${faint((sync2.stderr || sync2.stdout || '').trim())}`);
+      } else {
+        console.log(`  ${ok('✓')} Python environment ready — codegraph enabled`);
+      }
+    }
+    console.log('');
+    return;
+  }
+
   if (!keys.length) {
     printSection('Install');
-    console.log(`  ${muted('Usage:')}  ctx install ${faint('[--claude] [--cursor] [--vscode] [--gemini] [--codex] [--windsurf] [--all]')}`);
+    console.log(`  ${muted('Usage:')}  ctx install ${faint('[--initial] [--claude] [--cursor] [--vscode] [--gemini] [--codex] [--windsurf] [--all]')}`);
+    console.log('');
+    console.log(`  ${accent('--initial      ')}  ${faint('Install / update Node.js + Python (codegraph) deps')}`);
     console.log('');
     console.log(`  Writes MCP config file + AI instruction file for each selected platform.`);
     console.log(`  Files are written into the ${accent('current directory')} (your project root).`);
@@ -700,6 +745,7 @@ function cmdOnline(args) {
   const host    = hostIdx !== -1 && args[hostIdx + 1] ? args[hostIdx + 1] : null;
   const git     = args.includes('--access-git');
   const restart = args.includes('--restart');
+  const close   = args.includes('--close');
 
   let cfg;
   try { cfg = getConfig(); } catch { cfg = { client_id: 'context-mcp', client_secret: '(unavailable)', port: 3100, host: 'localhost' }; }
@@ -710,6 +756,21 @@ function cmdOnline(args) {
   printSection('Online', `HTTP MCP server → Claude.ai / ChatGPT`);
   console.log('');
 
+  if (close) {
+    const existing2 = _checkExistingHttpServer(resolvedPort);
+    if (existing2.status === 'running') {
+      if (existing2.pid) {
+        try { process.kill(existing2.pid); } catch {}
+      }
+      try { unlinkSync(_httpPidFile(resolvedPort)); } catch {}
+      const pidStr = existing2.pid ? `pid ${existing2.pid}  ·  ` : '';
+      console.log(`  ${ok('✓')} ${bold('server stopped')}  ${faint(pidStr + 'port ' + resolvedPort)}\n`);
+    } else {
+      console.log(`  ${warn('–')} no server running on port ${resolvedPort}\n`);
+    }
+    return;
+  }
+
   // Check if a server is already running on this port
   const existing = _checkExistingHttpServer(resolvedPort);
   if (existing.status === 'running') {

package/src/templates/AGENTS.md

@@ -1,7 +1,7 @@
 # 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.
+Every conversation starts with `context.resume`. Every codebase question uses `codegraph_query`. Files only read for bugs/logic.
 
 ---
 
@@ -37,21 +37,15 @@ Always pass `project`. Auto-compact fires at >50 entries.
 
 ## 3. CodeGraph Pipeline
 
-### Step 1 — Build (once, free)
+### Step 1 — Build (once, fast, local)
 ```
 codegraph_build(path)  →  AST graph: functions, classes, imports, edges
 ```
 
-### Step 2 — Enrich (one-time per file)
+### Step 2 — Query (free, instant)
 ```
-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_query(path, question)   →  fetch any details about the codebase
+codegraph_explain(path, node)     →  single node: type, file, connections
 codegraph_path(path, from, to)    →  shortest path
 codegraph_nodes(path, type)       →  list nodes by type
 codegraph_report(path)            →  full graph analysis
@@ -61,8 +55,8 @@ codegraph_report(path)            →  full graph analysis
 
 ## 4. Graph vs File
 
-**Graph** — structural questions: dependencies, callers, imports.
-**File** — bugs, logic, tracing behavior.
+**Graph** — use for any question about what exists: finding functions, classes, files, dependencies, callers, imports, paths between concepts.
+**File** — bugs, logic, tracing unexpected behavior.
 
 ---
 
@@ -71,6 +65,5 @@ codegraph_report(path)            →  full graph analysis
 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**
+4. **`codegraph_query` before reading files** — graph is faster and cheaper
 5. **Read files for bugs/logic only**
-6. **Enrich once** — descriptions persist forever