context-mcp-server 1.0.1 → 1.0.3

package/src/templates/CLAUDE.md

@@ -9,7 +9,7 @@ description: >
 # 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.
+Every conversation starts with `context.resume`. Every codebase question uses `codegraph_query`. Files only read for bugs/logic.
 
 ---
 
@@ -45,42 +45,31 @@ Always pass `project`. Auto-compact fires at >50 entries — oldest summarized a
 
 ## 3. CodeGraph Pipeline
 
-### Step 1 — Build (once per project, free)
+### Step 1 — Build (once per project, fast, local)
 ```
 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`.
+- Parses codebase into AST graph using tree-sitter (regex fallback for unsupported languages)
+- Extracts functions, classes, imports, call edges for all code files
+- Build files (package.json, pyproject.toml, go.mod, Dockerfile, etc.) get a single metadata node
+- Saves graph to `~/.context-mcp/graphs.json`. Visible on `context.resume`.
 
-### Step 2 — Enrich (one-time cost per file)
+### Step 2 — Query (free, instant, forever)
 ```
-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
+codegraph_query(path, question)     → fetch any details about the codebase
+codegraph_explain(path, node)       → one node: type, file, depends_on, used_by
+codegraph_path(path, from, to)      → shortest path between two concepts
+codegraph_nodes(path, type)         → list all nodes of a type
+codegraph_report(path)              → god nodes, clusters, surprises
 ```
 
 ---
 
 ## 4. Graph vs File
 
-**Graph** — structural questions: dependencies, callers, imports, paths between concepts.
-**File** — bugs, logic inside a function, tracing unexpected behavior.
+**Graph** — use for any question about what exists in the codebase: finding functions, classes, files, understanding what a module contains, dependencies, callers, imports, paths between concepts.
+
+**File** — use for bugs, logic inside a specific function, tracing unexpected behavior.
 
 ---
 
@@ -91,4 +80,3 @@ codegraph_report(path)            → god nodes, clusters, surprises
 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

@@ -1,7 +1,7 @@
 # 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.
+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.
 
 ---
 
@@ -73,4 +67,3 @@ codegraph_report(path)            →  full graph analysis
 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/tools/context.js

@@ -1,9 +1,19 @@
+import { execFileSync } from 'node:child_process';
+import { guardPath } from '../guard.js';
 import {
   saveContext, updateContext, getContext, deleteContext,
   listProjects, findDuplicate, archiveExpired, linkContextToDiscussion,
   listDiscussions, listGraphs, countContext, shouldCompact, compactProject,
   ensureProject, getProjectRoot,
 } from '../db.js';
+
+function detectGitRoot() {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: process.cwd(), encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch { return null; }
+}
 import { summarizeEntries } from '../summarizer.js';
 import { fireAutoLink } from '../hooks/autoLink.js';
 
@@ -71,10 +81,12 @@ export async function handle(args, state) {
       // 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);
+      // Store rootPath with project (first time only) and load it onto session state.
+      // Auto-detect from git if neither provided nor previously stored.
       const storedRoot = proj ? getProjectRoot(proj) : null;
-      state.projectRootPath = args.rootPath || storedRoot || null;
+      const resolvedRoot = args.rootPath || storedRoot || detectGitRoot() || null;
+      if (proj) ensureProject(proj, resolvedRoot || undefined);
+      state.projectRootPath = resolvedRoot;
 
       const entries       = getContext({ project: proj, limit: 15, compact: true })
         .filter(e => e.status !== 'archived');
@@ -105,6 +117,9 @@ export async function handle(args, state) {
         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,
+        sandbox: state.projectRootPath
+          ? `All file and git operations are sandboxed to: ${state.projectRootPath} — do not use paths outside this root.`
+          : 'No project root configured — pass rootPath to restrict file/git access to a directory.',
         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.',
@@ -114,6 +129,27 @@ export async function handle(args, state) {
     case 'save': {
       if (!args.content) throw new Error('content is required for save');
       if (!args.project && state.sessionProject) args = { ...args, project: state.sessionProject };
+      // Auto-detect and store project root if not yet configured
+      if (args.project) {
+        const existing = getProjectRoot(args.project);
+        if (!existing) {
+          const detected = state.projectRootPath || detectGitRoot();
+          if (detected) {
+            ensureProject(args.project, detected);
+            if (!state.projectRootPath) state.projectRootPath = detected;
+          }
+        }
+      }
+      // Validate file paths in files[] and codeRefs[] stay within project root
+      if (state.projectRootPath) {
+        if (Array.isArray(args.files)) {
+          args.files.forEach(f => { if (f.path) guardPath(f.path, state.projectRootPath); });
+        }
+        if (Array.isArray(args.codeRefs)) {
+          args.codeRefs.forEach(r => { if (r.file) guardPath(r.file, state.projectRootPath); });
+        }
+      }
+
       const dupe = findDuplicate(args.content, args.project);
       if (dupe) {
         const updated = updateContext({

package/src/tools/fileTools.js

@@ -20,28 +20,30 @@ function atomicWrite(filePath, data) {
   }
 }
 
+const ROOT_NOTE = ' Sandboxed to project root — paths outside root are denied.';
+
 export const definitions = [
   {
     name: 'create_dir',
-    description: 'Create a directory (and any missing parent directories). Safe to call if already exists.',
+    description: 'Create a directory (and any missing parent directories). Safe to call if already exists.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
     outputSchema: { type: 'object', properties: { path: { type: 'string' }, existed: { type: 'boolean' }, message: { type: 'string' } } },
   },
   {
     name: 'list_dir',
-    description: 'List the contents of a local directory.',
+    description: 'List the contents of a local directory.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
     outputSchema: { type: 'object', properties: { directory: { type: 'string' }, items: { type: 'array' } } },
   },
   {
     name: 'read_file',
-    description: 'Read the text contents of a local file.',
+    description: 'Read the text contents of a local file.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { path: { type: 'string' } }, required: ['path'] },
     outputSchema: { type: 'object', properties: { file: { type: 'string' }, content: { type: 'string' } } },
   },
   {
     name: 'write_file',
-    description: 'Create a new file or overwrite an existing file.',
+    description: 'Create a new file or overwrite an existing file.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { path: { type: 'string' }, content: { type: 'string' } }, required: ['path', 'content'] },
     outputSchema: { type: 'object', properties: { file: { type: 'string' }, message: { type: 'string' } } },
   },
@@ -51,7 +53,7 @@ export const definitions = [
       `Apply targeted string replacement(s) to a file.\n` +
       `Single edit: pass old_str + new_str.\n` +
       `Multi edit:  pass edits:[{old_str, new_str, description?}] — atomic.\n` +
-      `Use dry_run:true to validate without writing.`,
+      `Use dry_run:true to validate without writing.` + ROOT_NOTE,
     inputSchema: {
       type: 'object',
       properties: {
@@ -68,7 +70,7 @@ export const definitions = [
   },
   {
     name: 'delete_file',
-    description: 'Delete a local file. Pass recursive:true to delete a directory and its contents.',
+    description: 'Delete a local file. Pass recursive:true to delete a directory and its contents.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { path: { type: 'string' }, recursive: { type: 'boolean', description: 'Required to delete a directory. Defaults to false.' } }, required: ['path'] },
     outputSchema: { type: 'object', properties: { path: { type: 'string' }, message: { type: 'string' } } },
   },

package/src/tools/gitTools.js

@@ -15,69 +15,85 @@ function runGit(argArr, cwd) {
   }
 }
 
+function autoDetectRoot(fromDir) {
+  try {
+    return execFileSync('git', ['rev-parse', '--show-toplevel'], {
+      cwd: fromDir, encoding: 'utf8', stdio: ['pipe', 'pipe', 'pipe'],
+    }).trim();
+  } catch {
+    return null;
+  }
+}
+
 function resolveCwd(args, state) {
-  const raw = args.cwd ? pathResolve(args.cwd) : process.cwd();
-  // If a project root is configured, validate cwd is within it
+  // Auto-detect project root on first use if not already configured.
+  if (!state.projectRootPath) {
+    const detected = autoDetectRoot(args.cwd ? pathResolve(args.cwd) : process.cwd());
+    if (detected) state.projectRootPath = detected;
+  }
+  const raw = args.cwd ? pathResolve(args.cwd) : (state.projectRootPath || process.cwd());
   if (state.projectRootPath) return guardPath(raw, state.projectRootPath);
   return raw;
 }
 
+const ROOT_NOTE = ' All paths must be within the project root (sandboxed — access outside root is denied).';
+
 export const definitions = [
   {
     name: 'git_status',
-    description: 'Show working tree status — current branch, staged, unstaged, and untracked files.',
+    description: 'Show working tree status — current branch, staged, unstaged, and untracked files.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { cwd: { type: 'string' } } },
     outputSchema: { type: 'object', properties: { branch: { type: 'string' }, clean: { type: 'boolean' }, staged: { type: 'array' }, unstaged: { type: 'array' }, untracked: { type: 'array' } } },
   },
   {
     name: 'git_diff',
-    description: 'Show file changes. Use staged:true for cached diff. Optionally scope to a path.',
+    description: 'Show file changes. Use staged:true for cached diff. Optionally scope to a path.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { staged: { type: 'boolean' }, path: { type: 'string' }, cwd: { type: 'string' } } },
     outputSchema: { type: 'object', properties: { diff: { type: 'string' }, staged: { type: 'boolean' } } },
   },
   {
     name: 'git_log',
-    description: 'Show recent commit history — hash, author, date, message.',
+    description: 'Show recent commit history — hash, author, date, message.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { limit: { type: 'number' }, path: { type: 'string' }, cwd: { type: 'string' } } },
     outputSchema: { type: 'object', properties: { commits: { type: 'array' }, count: { type: 'number' } } },
   },
   {
     name: 'git_add',
-    description: 'Stage files for commit. Pass paths:["."] to stage everything.',
+    description: 'Stage files for commit. Pass paths:["."] to stage everything.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { paths: { type: 'array', items: { type: 'string' } }, cwd: { type: 'string' } }, required: ['paths'] },
     outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, staged: { type: 'array' }, message: { type: 'string' } } },
   },
   {
     name: 'git_commit',
-    description: 'Commit staged changes. Set all:true to auto-stage tracked modified files first. Auto-saves context entry.',
+    description: 'Commit staged changes. Set all:true to auto-stage tracked modified files first. Auto-saves context entry.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { message: { type: 'string' }, all: { type: 'boolean' }, cwd: { type: 'string' } }, required: ['message'] },
     outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, hash: { type: 'string' }, branch: { type: 'string' }, message: { type: 'string' }, files: { type: 'array' } } },
   },
   {
     name: 'git_push',
-    description: 'Push current branch to remote.',
+    description: 'Push current branch to remote.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { remote: { type: 'string' }, branch: { type: 'string' }, cwd: { type: 'string' } } },
     outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, remote: { type: 'string' }, branch: { type: 'string' }, output: { type: 'string' } } },
   },
   {
     name: 'git_pull',
-    description: 'Pull from remote and merge into current branch.',
+    description: 'Pull from remote and merge into current branch.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { remote: { type: 'string' }, branch: { type: 'string' }, cwd: { type: 'string' } } },
     outputSchema: { type: 'object', properties: { success: { type: 'boolean' }, remote: { type: 'string' }, output: { type: 'string' } } },
   },
   {
     name: 'git_branch',
-    description: 'List, create, or checkout branches.',
+    description: 'List, create, or checkout branches.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['list', 'create', 'checkout'] }, name: { type: 'string' }, cwd: { type: 'string' } } },
   },
   {
     name: 'git_stash',
-    description: 'Stash or restore work-in-progress changes.',
+    description: 'Stash or restore work-in-progress changes.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { action: { type: 'string', enum: ['save', 'pop', 'list', 'drop'] }, message: { type: 'string' }, ref: { type: 'string' }, cwd: { type: 'string' } } },
   },
   {
     name: 'git_reset',
-    description: 'Unstage files or reset HEAD. Use mode:file + path to restore a single file.',
+    description: 'Unstage files or reset HEAD. Use mode:file + path to restore a single file.' + ROOT_NOTE,
     inputSchema: { type: 'object', properties: { mode: { type: 'string', enum: ['soft', 'mixed', 'hard', 'file'] }, path: { type: 'string' }, ref: { type: 'string' }, cwd: { type: 'string' } } },
   },
   {