@kentwynn/kgraph 0.2.38 → 0.2.40

package/README.md

@@ -2,7 +2,7 @@
 
 <img src="media/logo.svg" alt="KGraph Atom Core Logo" width="140" height="140">
 
-# KGraph: Persistent repository intelligence for AI coding tools.
+# KGraph: Local repo memory for AI coding tools.
 
 <strong>atoms · evidence · context packs</strong>
 
@@ -35,10 +35,20 @@
 
 </div>
 
-KGraph gives Codex, GitHub Copilot, Cursor, Claude Code, Gemini CLI, Windsurf, and Cline a local knowledge layer for your repo: file maps, symbols, imports, relationships, and durable knowledge atoms from previous AI sessions. The goal is simple: your assistant should not spend every session re-learning the same codebase.
+KGraph gives AI coding tools a local repo memory: file maps, symbols, imports, relationships, and durable knowledge atoms stored under `.kgraph/`. The goal is simple: stop re-learning the same codebase every session.
 
 The CLI presents this as **Atom Core**: lightweight local atoms plus deterministic repo maps, context packs, and session history that remain inspectable under `.kgraph/`.
 
+## Try It in 30 Seconds
+
+```bash
+npm install -g @kentwynn/kgraph@latest
+kgraph init
+kgraph "auth token refresh"
+```
+
+That gets you a local scan, a focused context response, and durable memory under `.kgraph/` for the next session.
+
 ## The Workflow
 
 Use KGraph with one setup command and one normal daily command:
@@ -148,19 +158,21 @@ From the root of a repository:
 # 1. Create the local KGraph workspace and run the first scan
 kgraph init
 
-# 2. Optional: accept detected AI tool recommendations during init,
-# or add integrations later when you want KGraph-managed instructions
-kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
-
-# 3. Run the normal workflow for a topic
+# 2. Ask for focused context on a real repo topic
 kgraph "auth token refresh"
 
-# 4. Verify the setup and use doctor as the quality gate
+# 3. Optional: verify the workspace and saved intelligence
 kgraph doctor
 ```
 
 `kgraph init` scans once, prints repo language coverage, detects likely local AI tools, and recommends matching integrations. Integrations are still optional: they only write local instruction files so tools know when to run KGraph. They do not start background agents or call AI providers.
 
+If you already know exactly which integrations you want, you can add them later:
+
+```bash
+kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
+```
+
 After useful AI work, assistants save durable runtime-capture notes into `.kgraph/inbox/`. These notes are not project documentation; they are KGraph input files that the next `kgraph` run processes automatically. You can also process them directly with `kgraph update`.
 
 Normal agent flow is intentionally small. For coding context, agents use the
@@ -372,6 +384,13 @@ kgraph history --json
 
 Show processed capture history. Add a query to find historical work by title, summary, file, symbol, or note body.
 
+```bash
+kgraph mcp
+kgraph mcp --root /path/to/repo
+```
+
+Start the local KGraph MCP server over stdio. You normally do not run this command by hand; MCP clients such as VS Code start it automatically after KGraph is registered in that client's MCP config. MCP clients can call typed `kgraph_*` tools for orchestration, context packs, impact analysis, capture, health checks, and command-compatible access to the full CLI surface. Prefer MCP tools when the client exposes them; otherwise use the normal CLI commands.
+
 ## AI Tool Integrations
 
 KGraph integrations are local files. They do not start background agents, call AI providers, or send data anywhere.
@@ -381,14 +400,18 @@ You do not need integrations to use KGraph manually. They are useful when you wa
 `kgraph init` detects likely local tools and recommends integrations when possible. You can also manage them explicitly:
 
 ```bash
+kgraph init --integrations copilot --mcp
 kgraph integrate add codex copilot cursor claude-code gemini windsurf cline
+kgraph integrate add copilot --mcp
 kgraph integrate add copilot --mode smart
 kgraph integrate set copilot --mode manual
 kgraph integrate list
 kgraph integrate remove cursor
 ```
 
-New integrations default to `always` mode, so every chat in the repository starts with the matching KGraph command. Use `--mode smart` to run KGraph only for repo-specific work, or `--mode manual` to run only when explicitly asked.
+New integrations default to `always` mode, so every chat in the repository starts with the matching KGraph command. Use `--mode smart` to run KGraph only for repo-specific work, or `--mode manual` to run only when explicitly asked. Plain `kgraph init` stays repo-local; add `--mcp` only when you want KGraph to write editor/client MCP config.
+
+Add `--mcp` when configuring Copilot from VS Code. KGraph writes a `KGraph` stdio server entry to the VS Code MCP config for this repository and prints the config path; reload VS Code afterward so Copilot can start the server. If an AI client exposes MCP tools named `kgraph_*`, use those tools for KGraph orchestration and context. If MCP is unavailable, use the CLI commands generated in the integration instructions. MCP changes the transport, not the `always`, `smart`, `manual`, or `off` policy. See the [MCP setup wiki page](docs/wiki/MCP-Setup.md) for details.
 
 | Mode     | Behavior                                                                                                                                                                                                |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -545,5 +568,5 @@ The release workflow builds, tests, packs, publishes the npm package on version
 - Smarter cross-file symbol and call relationship inference.
 - Stronger TypeScript path alias and package export resolution.
 - Richer graph filtering for large repositories.
-- Optional MCP and editor integration.
+- More MCP client setup targets beyond VS Code/Copilot.
 - Team-friendly shared knowledge workflows that stay local-first.

package/dist/cli/commands/init.js

@@ -2,6 +2,7 @@ import { loadConfig, saveConfig, writeDefaultConfig, } from '../../config/config
 import { installCopilotMemory } from '../../integrations/copilot-memory.js';
 import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
 import { addIntegrations } from '../../integrations/integration-store.js';
+import { installVSCodeMcpServer } from '../../integrations/vscode-mcp.js';
 import { ensureKnowledgeStore } from '../../knowledge/atom-store.js';
 import { scanRepository } from '../../scanner/repo-scanner.js';
 import { ensureWorkspace } from '../../storage/kgraph-paths.js';
@@ -18,6 +19,7 @@ export function registerInitCommand(program) {
         .option('--integration <name>', 'Configure an AI tool integration', collectOption, [])
         .option('--integrations <names>', 'Configure comma-separated AI tool integrations')
         .option('--mode <mode>', 'Integration mode: always, smart, manual, or off', 'always')
+        .option('--mcp', 'Configure the VS Code/Copilot MCP server for this repository')
         .action((options) => runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
         await ensureKnowledgeStore(workspace);
@@ -34,6 +36,11 @@ export function registerInitCommand(program) {
             const changed = await addIntegrations(workspace, names, mode);
             console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
         }
+        if (options.mcp) {
+            const result = await installVSCodeMcpServer(workspace);
+            console.log(`${result.changed ? 'Configured' : 'Verified'} VS Code MCP server: ${result.serverName} (${result.configPath})`);
+            console.log('Reload VS Code so it starts the KGraph MCP server.');
+        }
         let config = await loadConfig(workspace);
         // Workspace detection — only for fresh init, non-destructive
         const workspaceInfo = await detectWorkspaces(workspace.rootPath);

package/dist/cli/commands/integrate.js

@@ -1,5 +1,6 @@
 import { normalizeIntegrationNames } from '../../integrations/integration-registry.js';
 import { addIntegrations, listIntegrations, removeIntegrations, setIntegrationMode, } from '../../integrations/integration-store.js';
+import { installVSCodeMcpServer } from '../../integrations/vscode-mcp.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import { KGraphError, runCommand } from '../errors.js';
 export function registerIntegrateCommand(program) {
@@ -26,6 +27,7 @@ export function registerIntegrateCommand(program) {
         .description('Add AI tool integrations')
         .argument('<names...>')
         .option('--mode <mode>', 'always, smart, manual, or off', 'always')
+        .option('--mcp', 'Configure the VS Code/Copilot MCP server for this repository')
         .action((names, options) => runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
@@ -35,6 +37,11 @@ export function registerIntegrateCommand(program) {
         const mode = normalizeIntegrationMode(options.mode);
         const changed = await addIntegrations(workspace, normalized, mode);
         console.log(`Configured integrations: ${changed.map((item) => `${item.name}:${item.mode}`).join(', ')}`);
+        if (options.mcp) {
+            const result = await installVSCodeMcpServer(workspace);
+            console.log(`${result.changed ? 'Configured' : 'Verified'} VS Code MCP server: ${result.serverName} (${result.configPath})`);
+            console.log('Reload VS Code so it starts the KGraph MCP server.');
+        }
     }));
     integrate
         .command('set')

package/dist/cli/commands/mcp.d.ts

@@ -0,0 +1,2 @@
+import type { Command } from 'commander';
+export declare function registerMcpCommand(program: Command): void;

package/dist/cli/commands/mcp.js

@@ -0,0 +1,10 @@
+import { runMcpServer } from '../../mcp/server.js';
+export function registerMcpCommand(program) {
+    program
+        .command('mcp')
+        .description('Start the local KGraph MCP server over stdio')
+        .option('--root <path>', 'Repository root path', process.cwd())
+        .action(async (options) => {
+        await runMcpServer({ rootPath: options.root ?? process.cwd() });
+    });
+}

package/dist/cli/help.js

@@ -24,6 +24,7 @@ export function renderRootHelp(useColor = supportsColor()) {
         sectionTitle(theme, `${accent} Start`),
         command('init', 'Required once: create .kgraph/ workspace'),
         command('init --integrations codex,gemini', 'Optional: initialize and connect named AI tools'),
+        command('init --integrations copilot --mcp', 'Optional: also register KGraph as a VS Code MCP server'),
         '',
         sectionTitle(theme, `${accent} Daily workflow`),
         command('kgraph', 'Refresh scan maps and process pending capture notes'),
@@ -55,11 +56,13 @@ export function renderRootHelp(useColor = supportsColor()) {
         command('uninstall --yes --memory', 'Also remove Copilot memory rule'),
         command('visualize', 'Interactive dependency graph at http://localhost:4242'),
         command('history "blog button"', 'Search processed cognition sessions'),
+        command('mcp', 'Start the local MCP server over stdio'),
         '',
         sectionTitle(theme, `${accent} Integrations`),
         command('integrate list', 'Show configured AI tool integrations'),
         command('integrate add gemini windsurf cline', 'Write KGraph instructions using always mode by default'),
         command('integrate add copilot --mode smart', 'Run KGraph for repo-specific Copilot work only'),
+        command('integrate add copilot --mcp', 'Also register the KGraph MCP server in VS Code'),
         command('integrate set copilot --mode manual', 'Only run KGraph when explicitly requested'),
         command('integrate remove cursor', 'Remove KGraph-managed instruction blocks'),
         command('--mode smart|always|manual|off', 'Control automatic KGraph involvement per integration'),

package/dist/cli/index.js

@@ -13,6 +13,7 @@ import { registerImpactCommand } from './commands/impact.js';
 import { registerInitCommand } from './commands/init.js';
 import { registerIntegrateCommand } from './commands/integrate.js';
 import { registerKnowledgeCommand } from './commands/knowledge.js';
+import { registerMcpCommand } from './commands/mcp.js';
 import { registerPackCommand } from './commands/pack.js';
 import { registerRepairCommand } from './commands/repair.js';
 import { registerScanCommand } from './commands/scan.js';
@@ -71,6 +72,7 @@ export function createProgram() {
     registerContextCommand(program);
     registerPackCommand(program);
     registerKnowledgeCommand(program);
+    registerMcpCommand(program);
     registerStaleCommand(program);
     registerBlameCommand(program);
     registerImpactCommand(program);

package/dist/integrations/vscode-mcp.d.ts

@@ -0,0 +1,10 @@
+import type { KGraphWorkspace } from '../types/config.js';
+export interface VSCodeMcpInstallResult {
+    configPath: string;
+    serverName: string;
+    command: string;
+    args: string[];
+    changed: boolean;
+}
+export declare function installVSCodeMcpServer(workspace: KGraphWorkspace): Promise<VSCodeMcpInstallResult>;
+export declare function resolveVSCodeMcpConfigPath(): string;

package/dist/integrations/vscode-mcp.js

@@ -0,0 +1,76 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+import { KGraphError } from '../cli/errors.js';
+const SERVER_NAME = 'KGraph';
+export async function installVSCodeMcpServer(workspace) {
+    const configPath = resolveVSCodeMcpConfigPath();
+    const command = resolveKGraphMcpCommand();
+    const args = ['mcp', '--root', workspace.rootPath];
+    const existing = await readVSCodeMcpConfig(configPath);
+    const servers = normalizeServers(existing.servers);
+    const nextServer = {
+        command,
+        args,
+        type: 'stdio',
+    };
+    const previous = servers[SERVER_NAME];
+    servers[SERVER_NAME] = nextServer;
+    const next = {
+        ...existing,
+        servers,
+        inputs: Array.isArray(existing.inputs) ? existing.inputs : [],
+    };
+    const changed = JSON.stringify(previous ?? null) !== JSON.stringify(nextServer);
+    await mkdir(path.dirname(configPath), { recursive: true });
+    await writeFile(configPath, `${JSON.stringify(next, null, 2)}\n`, 'utf8');
+    return { configPath, serverName: SERVER_NAME, command, args, changed };
+}
+export function resolveVSCodeMcpConfigPath() {
+    if (process.env.KGRAPH_VSCODE_MCP_CONFIG) {
+        return process.env.KGRAPH_VSCODE_MCP_CONFIG;
+    }
+    if (process.platform === 'darwin') {
+        return path.join(os.homedir(), 'Library', 'Application Support', 'Code', 'User', 'mcp.json');
+    }
+    if (process.platform === 'win32') {
+        const appData = process.env.APPDATA;
+        if (!appData) {
+            throw new KGraphError('APPDATA is not set; cannot locate VS Code MCP config.');
+        }
+        return path.join(appData, 'Code', 'User', 'mcp.json');
+    }
+    return path.join(os.homedir(), '.config', 'Code', 'User', 'mcp.json');
+}
+function resolveKGraphMcpCommand() {
+    if (process.env.KGRAPH_MCP_COMMAND) {
+        return process.env.KGRAPH_MCP_COMMAND;
+    }
+    const entrypoint = process.argv[1];
+    if (entrypoint && path.basename(entrypoint).startsWith('kgraph')) {
+        return entrypoint;
+    }
+    return 'kgraph';
+}
+async function readVSCodeMcpConfig(configPath) {
+    try {
+        return JSON.parse(await readFile(configPath, 'utf8'));
+    }
+    catch (error) {
+        if (isMissingFile(error)) {
+            return { servers: {}, inputs: [] };
+        }
+        const message = error instanceof Error ? error.message : String(error);
+        throw new KGraphError(`Invalid VS Code MCP config at ${configPath}: ${message}`);
+    }
+}
+function normalizeServers(value) {
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? { ...value }
+        : {};
+}
+function isMissingFile(error) {
+    return (error instanceof Error &&
+        'code' in error &&
+        error.code === 'ENOENT');
+}

package/dist/integrations/workflow-steps.js

@@ -32,6 +32,7 @@ const COMPACT_STEP = `Run \`kgraph compact --dry-run\` when cognition looks dupl
 const HISTORY_STEP = `Run \`kgraph history "<topic>"\` when the user asks what was done, decided, or changed — it covers the full timeline including notes captured via \`conclude\`, \`--capture\`, and inbox. Prefer history over \`knowledge list\` when the question is about sequence, timing, or authorship rather than atom details.`;
 const KNOWLEDGE_STEP = `Run \`kgraph knowledge list --topic "<topic>"\` or \`kgraph knowledge get <atom-id>\` when the user asks what KGraph remembers or atom provenance/lifecycle matters.`;
 const STALE_STEP = `Run \`kgraph stale\` when changed or deleted code may have invalidated durable knowledge. Run \`kgraph blame <atom-id>\` when provenance or evidence for a memory matters.`;
+const MCP_ROUTING_STEP = `If MCP tools named \`kgraph_*\` are available in this client, prefer those tools for KGraph orchestration and context. If MCP is not available, use the normal CLI commands shown here. MCP changes the transport, not the memory policy.`;
 const EXPLORATION_BOUNDARY_STEP = `Keep exploration bounded by the task. For simple edits, use KGraph to identify the likely file, then read only that file or a narrow range and make the edit. Do not keep searching after the target file is found, do not retry malformed shell commands with broader variants, and do not run broad \`find\`, recursive \`grep\`, or repeated full-file dumps after KGraph already returned candidate files.`;
 const VERIFY_EDIT_STEP = `After editing, verify the change actually landed before claiming completion. Prefer a narrow read of the changed range or \`git diff -- <path>\`; if there is no diff or the expected text is missing, say the edit did not apply and fix it before summarizing.`;
 const SCAN_STEP = `After bulk file creation, deletion, or rename (3+ files), run \`kgraph scan\` before the next \`kgraph pack\` so maps stay accurate.`;
@@ -48,24 +49,25 @@ function sessionStep(agentName, qualifier) {
  */
 export function numberedWorkflow(agentName, options = {}) {
     return `1. Infer the topic from the user's request.
-2. {{KGRAPH_CONTEXT_POLICY}}
-3. When a pack item includes an \`excerpt\` field (symbol) or a \`content\` field (file), you already have the source code inline — do not read that file separately. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
-4. ${EXPLORATION_BOUNDARY_STEP}
-5. ${VERIFY_EDIT_STEP}
-6. ${smartRootStep(agentName)}
-7. ${KNOWLEDGE_STEP}
-8. ${DOCTOR_STEP}
-9. ${STALE_STEP}
-10. ${SCAN_STEP}
-11. ${sessionStep(agentName, options.sessionQualifier)}
-12. ${IMPACT_STEP}
+2. ${MCP_ROUTING_STEP}
+3. {{KGRAPH_CONTEXT_POLICY}}
+4. When a pack item includes an \`excerpt\` field (symbol) or a \`content\` field (file), you already have the source code inline — do not read that file separately. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
+5. ${EXPLORATION_BOUNDARY_STEP}
+6. ${VERIFY_EDIT_STEP}
+7. ${smartRootStep(agentName)}
+8. ${KNOWLEDGE_STEP}
+9. ${DOCTOR_STEP}
+10. ${STALE_STEP}
+11. ${SCAN_STEP}
+12. ${sessionStep(agentName, options.sessionQualifier)}
+13. ${IMPACT_STEP}
 
 {{KGRAPH_CAPTURE_POLICY}}
 
-13. ${REPAIR_STEP}
-14. ${COMPACT_STEP}
-15. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph locally with PNG export.
-16. ${HISTORY_STEP}
+14. ${REPAIR_STEP}
+15. ${COMPACT_STEP}
+16. Run \`kgraph visualize\` when the user wants to inspect the dependency graph — opens an interactive graph locally with PNG export.
+17. ${HISTORY_STEP}
 
 ${DECISION_CONTEXT}`;
 }
@@ -74,7 +76,8 @@ ${DECISION_CONTEXT}`;
  * Used by: cursor, cline, windsurf, gemini.
  */
 export function bulletWorkflow(agentName, options = {}) {
-    return `- {{KGRAPH_CONTEXT_POLICY}}
+    return `- ${MCP_ROUTING_STEP}
+- {{KGRAPH_CONTEXT_POLICY}}
 - When a pack item includes an \`excerpt\` field (symbol) or a \`content\` field (file), you already have the source code inline — do not read that file separately. Items in the \`omitted\` array were evaluated and excluded — do not manually search for them unless the user explicitly asks.
 - ${EXPLORATION_BOUNDARY_STEP}
 - ${VERIFY_EDIT_STEP}

package/dist/mcp/server.d.ts

@@ -0,0 +1,7 @@
+interface McpServerOptions {
+    rootPath?: string;
+    stdin?: NodeJS.ReadableStream;
+    stdout?: NodeJS.WritableStream;
+}
+export declare function runMcpServer(options?: McpServerOptions): Promise<void>;
+export {};

package/dist/mcp/server.js

@@ -0,0 +1,665 @@
+import { createProgram } from '../cli/index.js';
+import { KGraphError } from '../cli/errors.js';
+import { concludeTopic } from '../cognition/conclusion.js';
+import { normalizeConfidence, normalizeKind } from '../cli/commands/conclude.js';
+import { loadConfig } from '../config/config.js';
+import { buildContextPack } from '../context/context-pack.js';
+import { queryContext } from '../context/context-query.js';
+import { analyzeImpact } from '../context/impact.js';
+import { atomToCognitionNote, refreshKnowledgeAtomStatuses, } from '../knowledge/atom-store.js';
+import { assertSessionAgent, recordSessionEvent, } from '../session/session-store.js';
+import { listInboxNotes } from '../storage/cognition-store.js';
+import { assertWorkspace } from '../storage/kgraph-paths.js';
+import { mapsExist, readMaps } from '../storage/map-store.js';
+export async function runMcpServer(options = {}) {
+    const server = new KGraphMcpServer(options.rootPath ?? process.cwd());
+    await server.run(options.stdin ?? process.stdin, options.stdout ?? process.stdout);
+}
+class KGraphMcpServer {
+    defaultRootPath;
+    tools;
+    constructor(defaultRootPath) {
+        this.defaultRootPath = defaultRootPath;
+        this.tools = createTools(defaultRootPath);
+    }
+    async run(stdin, stdout) {
+        let buffer = Buffer.alloc(0);
+        const pending = [];
+        let queue = Promise.resolve();
+        stdin.on('data', (chunk) => {
+            buffer = Buffer.concat([buffer, Buffer.from(chunk)]);
+            const parsed = parseMessages(buffer);
+            buffer = parsed.remaining;
+            for (const raw of parsed.messages) {
+                queue = queue.then(() => this.handleRawMessage(raw, stdout));
+                pending.push(queue);
+            }
+        });
+        await new Promise((resolve) => stdin.on('end', () => resolve()));
+        await Promise.all(pending);
+    }
+    async handleRawMessage(raw, stdout) {
+        let request;
+        try {
+            request = JSON.parse(raw);
+        }
+        catch {
+            writeMessage(stdout, {
+                jsonrpc: '2.0',
+                id: null,
+                error: { code: -32700, message: 'Parse error' },
+            });
+            return;
+        }
+        if (request.id === undefined) {
+            return;
+        }
+        try {
+            const result = await this.dispatch(request);
+            writeMessage(stdout, { jsonrpc: '2.0', id: request.id, result });
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            writeMessage(stdout, {
+                jsonrpc: '2.0',
+                id: request.id,
+                error: { code: -32000, message },
+            });
+        }
+    }
+    async dispatch(request) {
+        if (request.method === 'initialize') {
+            return {
+                protocolVersion: '2025-06-18',
+                capabilities: { tools: {} },
+                serverInfo: { name: 'kgraph', version: '0.1.0' },
+            };
+        }
+        if (request.method === 'ping') {
+            return {};
+        }
+        if (request.method === 'tools/list') {
+            return {
+                tools: this.tools.map((tool) => ({
+                    name: tool.name,
+                    description: `${tool.description} Mutability: ${tool.mutability}.`,
+                    inputSchema: tool.inputSchema,
+                })),
+            };
+        }
+        if (request.method === 'tools/call') {
+            const name = stringParam(request.params, 'name');
+            const args = objectParam(request.params, 'arguments', {});
+            const tool = this.tools.find((candidate) => candidate.name === name);
+            if (!tool) {
+                throw new KGraphError(`Unknown MCP tool "${name}".`);
+            }
+            const result = await tool.handler(args);
+            return {
+                content: [{ type: 'text', text: result.text }],
+                structuredContent: result.structuredContent ?? {},
+                isError: result.isError ?? false,
+            };
+        }
+        throw new KGraphError(`Unsupported MCP method "${request.method}".`);
+    }
+}
+function createTools(defaultRootPath) {
+    const command = commandTool(defaultRootPath);
+    const commandBacked = (name, description, mutability, buildArgs, inputSchema = schema({})) => ({
+        name,
+        description,
+        mutability,
+        inputSchema,
+        handler: async (args) => command.handler({ ...args, args: buildArgs(args) }),
+    });
+    return [
+        orchestrateTool(defaultRootPath),
+        contextPackTool(defaultRootPath),
+        impactTool(defaultRootPath),
+        captureTool(defaultRootPath),
+        healthTool(defaultRootPath),
+        command,
+        commandBacked('kgraph_scan', 'Refresh deterministic file, symbol, import, and relationship maps.', 'repo-write', (args) => [
+            'scan',
+            ...(booleanParam(args, 'verbose') ? ['--verbose'] : []),
+        ]),
+        commandBacked('kgraph_update', 'Process Markdown cognition notes from .kgraph/inbox.', 'repo-write', (args) => [
+            'update',
+            ...(booleanParam(args, 'dryRun') ? ['--dry-run'] : []),
+        ]),
+        commandBacked('kgraph_context', 'Return compact repo context for a query.', 'read-only', (args) => [
+            'context',
+            requiredString(args, 'query'),
+            '--json',
+        ], schema({ query: { type: 'string' } }, ['query'])),
+        commandBacked('kgraph_pack', 'Build a budget-aware context pack.', 'read-only', (args) => [
+            'pack',
+            requiredString(args, 'task'),
+            '--budget',
+            String(numberParam(args, 'budget', 8000)),
+            '--json',
+            ...agentArgs(args),
+        ], schema({ task: { type: 'string' }, budget: { type: 'number' }, agent: { type: 'string' } }, ['task'])),
+        commandBacked('kgraph_history', 'Show processed cognition session history.', 'read-only', (args) => [
+            'history',
+            ...optionalWords(args, 'query'),
+            ...numberOption(args, 'last', '--last'),
+            '--json',
+        ]),
+        commandBacked('kgraph_stale', 'Show stale or needs-review knowledge atoms.', 'read-only', () => [
+            'stale',
+            '--json',
+        ]),
+        commandBacked('kgraph_blame', 'Show provenance and evidence for a knowledge atom.', 'read-only', (args) => [
+            'blame',
+            requiredString(args, 'atomId'),
+            '--json',
+        ], schema({ atomId: { type: 'string' } }, ['atomId'])),
+        commandBacked('kgraph_doctor', 'Check KGraph workspace health.', 'read-only', (args) => [
+            'doctor',
+            ...(booleanParam(args, 'quality') ? ['--quality'] : []),
+        ]),
+        commandBacked('kgraph_repair', 'Clean noisy stale references from knowledge atoms.', 'repo-write', (args) => [
+            'repair',
+            ...(booleanParam(args, 'dryRun', true) ? ['--dry-run'] : []),
+        ]),
+        commandBacked('kgraph_compact', 'Merge duplicate cognition and archive low-value stale entries.', 'repo-write', (args) => [
+            'compact',
+            ...(booleanParam(args, 'dryRun', true) ? ['--dry-run'] : []),
+            '--json',
+        ]),
+        commandBacked('kgraph_knowledge_list', 'List canonical knowledge atoms.', 'read-only', (args) => [
+            'knowledge',
+            'list',
+            ...stringOption(args, 'type', '--type'),
+            ...stringOption(args, 'topic', '--topic'),
+            ...(booleanParam(args, 'includeArchived') ? ['--include-archived'] : []),
+            '--json',
+        ]),
+        commandBacked('kgraph_knowledge_get', 'Get one canonical knowledge atom.', 'read-only', (args) => [
+            'knowledge',
+            'get',
+            requiredString(args, 'atomId'),
+            '--json',
+        ], schema({ atomId: { type: 'string' } }, ['atomId'])),
+        commandBacked('kgraph_knowledge_archive', 'Archive one knowledge atom.', 'repo-write', (args) => [
+            'knowledge',
+            'archive',
+            requiredString(args, 'atomId'),
+            '--json',
+        ], schema({ atomId: { type: 'string' } }, ['atomId'])),
+        commandBacked('kgraph_knowledge_supersede', 'Mark one atom as superseded by another.', 'repo-write', (args) => [
+            'knowledge',
+            'supersede',
+            requiredString(args, 'oldId'),
+            requiredString(args, 'newId'),
+            '--json',
+        ], schema({ oldId: { type: 'string' }, newId: { type: 'string' } }, ['oldId', 'newId'])),
+        commandBacked('kgraph_session_report', 'Report agent read/write activity and token estimates.', 'read-only', () => [
+            'session',
+            '--json',
+        ]),
+        commandBacked('kgraph_session_start', 'Start lightweight session tracking for an agent.', 'repo-write', (args) => [
+            'session',
+            'start',
+            ...requiredAgentArgs(args),
+            ...sourceArgs(args),
+        ]),
+        commandBacked('kgraph_session_read', 'Record an agent file read.', 'repo-write', (args) => [
+            'session',
+            'read',
+            requiredString(args, 'path'),
+            ...requiredAgentArgs(args),
+            ...sourceArgs(args),
+        ]),
+        commandBacked('kgraph_session_write', 'Record an agent file write.', 'repo-write', (args) => [
+            'session',
+            'write',
+            requiredString(args, 'path'),
+            ...requiredAgentArgs(args),
+            ...sourceArgs(args),
+        ]),
+        commandBacked('kgraph_session_end', 'End session tracking for an agent.', 'repo-write', (args) => [
+            'session',
+            'end',
+            ...requiredAgentArgs(args),
+            ...(booleanParam(args, 'conclude') ? ['--conclude'] : []),
+            ...stringOption(args, 'topic', '--topic'),
+            ...stringOption(args, 'note', '--note'),
+            ...stringOption(args, 'confidence', '--confidence'),
+            ...sourceArgs(args),
+        ]),
+        commandBacked('kgraph_session_reset', 'Clear current session tracking.', 'destructive', () => [
+            'session',
+            'reset',
+        ]),
+        commandBacked('kgraph_integrate_list', 'List configured AI tool integrations.', 'read-only', () => [
+            'integrate',
+            'list',
+        ]),
+        commandBacked('kgraph_integrate_add', 'Add AI tool integrations.', 'repo-write', (args) => [
+            'integrate',
+            'add',
+            ...stringArray(args, 'names'),
+            ...stringOption(args, 'mode', '--mode'),
+        ]),
+        commandBacked('kgraph_integrate_set', 'Set AI tool integration modes.', 'repo-write', (args) => [
+            'integrate',
+            'set',
+            ...stringArray(args, 'names'),
+            ...stringOption(args, 'mode', '--mode'),
+        ]),
+        commandBacked('kgraph_integrate_remove', 'Remove AI tool integrations.', 'destructive', (args) => [
+            'integrate',
+            'remove',
+            ...stringArray(args, 'names'),
+        ]),
+        commandBacked('kgraph_init', 'Initialize a .kgraph workspace.', 'repo-write', (args) => [
+            'init',
+            ...stringOption(args, 'integration', '--integration'),
+            ...stringOption(args, 'integrations', '--integrations'),
+            ...(booleanParam(args, 'yes') ? ['--yes'] : []),
+        ]),
+        commandBacked('kgraph_uninstall', 'Preview or remove KGraph from this repository.', 'destructive', (args) => [
+            'uninstall',
+            ...(booleanParam(args, 'yes') ? ['--yes'] : []),
+            ...(booleanParam(args, 'keepIntegrations') ? ['--keep-integrations'] : []),
+            ...(booleanParam(args, 'memory') ? ['--memory'] : []),
+        ]),
+        commandBacked('kgraph_visualize', 'Return visualization command output or local URL guidance.', 'read-only', (args) => [
+            'visualize',
+            '--no-open',
+            ...numberOption(args, 'port', '--port'),
+        ]),
+    ];
+}
+function commandTool(defaultRootPath) {
+    return {
+        name: 'kgraph_command',
+        description: 'Compatibility wrapper for the exact KGraph CLI surface. Prefer typed kgraph_* MCP tools when possible.',
+        mutability: 'repo-write',
+        inputSchema: schema({
+            args: { type: 'array', items: { type: 'string' } },
+            rootPath: { type: 'string' },
+        }, ['args']),
+        handler: async (args) => {
+            const commandArgs = stringArray(args, 'args');
+            const result = await runCliInProcess(stringParam(args, 'rootPath', defaultRootPath), commandArgs);
+            const parsed = parseJsonOrUndefined(result.stdout);
+            const structuredContent = {
+                args: commandArgs,
+                exitCode: result.code,
+                stdout: result.stdout,
+                stderr: result.stderr,
+            };
+            if (parsed !== undefined) {
+                structuredContent.parsed = parsed;
+            }
+            return {
+                text: summarizeCommand(commandArgs, result),
+                structuredContent,
+                isError: result.code !== 0,
+            };
+        },
+    };
+}
+function orchestrateTool(defaultRootPath) {
+    return {
+        name: 'kgraph_orchestrate',
+        description: 'Smart root workflow: refresh maps, process inbox notes, optionally return topic context, run final checks, or capture durable knowledge.',
+        mutability: 'repo-write',
+        inputSchema: schema({
+            topic: { type: 'string' },
+            final: { type: 'boolean' },
+            capture: { type: 'string' },
+            captureType: { type: 'string' },
+            confidence: { type: 'string' },
+            domain: { type: 'string' },
+            tags: { type: 'array', items: { type: 'string' } },
+            files: { type: 'array', items: { type: 'string' } },
+            symbols: { type: 'array', items: { type: 'string' } },
+            agent: { type: 'string' },
+            rootPath: { type: 'string' },
+        }),
+        handler: async (args) => {
+            const cliArgs = [
+                ...optionalWords(args, 'topic'),
+                ...(booleanParam(args, 'final') ? ['--final'] : []),
+                ...stringOption(args, 'capture', '--capture'),
+                ...stringOption(args, 'captureType', '--capture-type'),
+                ...stringOption(args, 'confidence', '--capture-confidence'),
+                ...stringOption(args, 'domain', '--capture-domain'),
+                ...repeatOption(args, 'tags', '--capture-tag'),
+                ...repeatOption(args, 'files', '--capture-file'),
+                ...repeatOption(args, 'symbols', '--capture-symbol'),
+                ...agentArgs(args),
+            ];
+            const result = await runCliInProcess(stringParam(args, 'rootPath', defaultRootPath), cliArgs);
+            return {
+                text: summarizeCommand(cliArgs, result),
+                structuredContent: {
+                    args: cliArgs,
+                    exitCode: result.code,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                },
+                isError: result.code !== 0,
+            };
+        },
+    };
+}
+function contextPackTool(defaultRootPath) {
+    return {
+        name: 'kgraph_context_pack',
+        description: 'Build a structured budget-aware ContextPack directly from KGraph internals.',
+        mutability: 'read-only',
+        inputSchema: schema({
+            task: { type: 'string' },
+            budget: { type: 'number' },
+            agent: { type: 'string' },
+            rootPath: { type: 'string' },
+        }, ['task']),
+        handler: async (args) => {
+            const task = requiredString(args, 'task');
+            const budget = numberParam(args, 'budget', 8000);
+            const workspace = await assertWorkspace(stringParam(args, 'rootPath', defaultRootPath));
+            if (!(await mapsExist(workspace))) {
+                throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
+            }
+            const [config, maps] = await Promise.all([
+                loadConfig(workspace),
+                readMaps(workspace),
+            ]);
+            const response = await queryContext(workspace, config, maps, task);
+            const pack = buildContextPack(response, budget, workspace.rootPath);
+            const pendingInboxFiles = await listInboxNotes(workspace);
+            if (pendingInboxFiles.length > 0) {
+                pack.pendingInbox = {
+                    count: pendingInboxFiles.length,
+                    files: pendingInboxFiles,
+                };
+            }
+            const agent = stringParam(args, 'agent', '');
+            if (agent) {
+                await recordSessionEvent(workspace, {
+                    agent: assertSessionAgent(agent),
+                    type: 'context',
+                    captureSource: 'automatic',
+                    packUsedTokens: pack.usedTokens,
+                    packOmittedTokens: pack.omitted.reduce((sum, item) => sum + item.tokenEstimate, 0),
+                });
+            }
+            return {
+                text: `KGraph context pack for "${task}": ${pack.items.length} item(s), ${pack.usedTokens}/${pack.budget} tokens.`,
+                structuredContent: pack,
+            };
+        },
+    };
+}
+function impactTool(defaultRootPath) {
+    return {
+        name: 'kgraph_impact',
+        description: 'Analyze practical impact for a file, symbol, or topic.',
+        mutability: 'read-only',
+        inputSchema: schema({ query: { type: 'string' }, rootPath: { type: 'string' } }, ['query']),
+        handler: async (args) => {
+            const query = requiredString(args, 'query');
+            const workspace = await assertWorkspace(stringParam(args, 'rootPath', defaultRootPath));
+            if (!(await mapsExist(workspace))) {
+                throw new KGraphError('KGraph maps are missing. Run `kgraph scan` first.');
+            }
+            const [config, maps] = await Promise.all([
+                loadConfig(workspace),
+                readMaps(workspace),
+            ]);
+            const { atoms } = await refreshKnowledgeAtomStatuses(workspace, {
+                fileMap: maps.fileMap,
+                symbolMap: maps.symbolMap,
+            });
+            const response = analyzeImpact(query, maps, atoms.filter((atom) => atom.status !== 'archived').map(atomToCognitionNote), config.maxContextItems);
+            return {
+                text: `KGraph impact for "${query}": ${response.files.length} file(s), ${response.symbols.length} symbol(s), ${response.risk.length} risk signal(s).`,
+                structuredContent: response,
+            };
+        },
+    };
+}
+function captureTool(defaultRootPath) {
+    return {
+        name: 'kgraph_capture',
+        description: 'Store a durable typed engineering conclusion.',
+        mutability: 'repo-write',
+        inputSchema: schema({
+            topic: { type: 'string' },
+            note: { type: 'string' },
+            type: { type: 'string' },
+            confidence: { type: 'string' },
+            domain: { type: 'string' },
+            tags: { type: 'array', items: { type: 'string' } },
+            files: { type: 'array', items: { type: 'string' } },
+            symbols: { type: 'array', items: { type: 'string' } },
+            rootPath: { type: 'string' },
+        }, ['topic']),
+        handler: async (args) => {
+            const workspace = await assertWorkspace(stringParam(args, 'rootPath', defaultRootPath));
+            const note = await concludeTopic(workspace, {
+                topic: requiredString(args, 'topic'),
+                body: stringParam(args, 'note', undefined),
+                kind: normalizeKind(stringParam(args, 'type', 'summary')),
+                confidence: normalizeConfidence(stringParam(args, 'confidence', 'medium')),
+                domain: stringParam(args, 'domain', undefined),
+                tags: stringArray(args, 'tags', []),
+                relatedFiles: stringArray(args, 'files', []),
+                relatedSymbols: stringArray(args, 'symbols', []),
+                source: 'conclude',
+            });
+            return {
+                text: `Stored ${note.kind} cognition: ${note.title}`,
+                structuredContent: note,
+            };
+        },
+    };
+}
+function healthTool(defaultRootPath) {
+    return {
+        name: 'kgraph_health',
+        description: 'Check KGraph workspace health and optional cognition quality.',
+        mutability: 'read-only',
+        inputSchema: schema({ quality: { type: 'boolean' }, rootPath: { type: 'string' } }),
+        handler: async (args) => {
+            const result = await runCliInProcess(stringParam(args, 'rootPath', defaultRootPath), ['doctor', ...(booleanParam(args, 'quality') ? ['--quality'] : [])]);
+            return {
+                text: summarizeCommand(['doctor'], result),
+                structuredContent: {
+                    exitCode: result.code,
+                    stdout: result.stdout,
+                    stderr: result.stderr,
+                    checks: parseDoctorChecks(result.stdout),
+                },
+                isError: result.code !== 0,
+            };
+        },
+    };
+}
+async function runCliInProcess(rootPath, args) {
+    const originalCwd = process.cwd();
+    const originalStdout = process.stdout.write;
+    const originalStderr = process.stderr.write;
+    const originalConsoleLog = console.log;
+    const originalConsoleError = console.error;
+    const originalExitCode = process.exitCode;
+    let stdout = '';
+    let stderr = '';
+    process.chdir(rootPath);
+    process.exitCode = undefined;
+    process.stdout.write = ((chunk) => {
+        stdout += chunk.toString();
+        return true;
+    });
+    process.stderr.write = ((chunk) => {
+        stderr += chunk.toString();
+        return true;
+    });
+    console.log = (...items) => {
+        stdout += `${items.map(String).join(' ')}\n`;
+    };
+    console.error = (...items) => {
+        stderr += `${items.map(String).join(' ')}\n`;
+    };
+    try {
+        await createProgram().parseAsync(['node', 'kgraph', ...args], {
+            from: 'node',
+        });
+        return {
+            stdout,
+            stderr,
+            code: typeof process.exitCode === 'number' ? process.exitCode : 0,
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { stdout, stderr: `${stderr}${message}\n`, code: 1 };
+    }
+    finally {
+        process.stdout.write = originalStdout;
+        process.stderr.write = originalStderr;
+        console.log = originalConsoleLog;
+        console.error = originalConsoleError;
+        process.exitCode = originalExitCode;
+        process.chdir(originalCwd);
+    }
+}
+function parseMessages(buffer) {
+    const messages = [];
+    let remaining = buffer;
+    while (remaining.length > 0) {
+        const headerEnd = remaining.indexOf('\r\n\r\n');
+        if (headerEnd === -1) {
+            const newline = remaining.indexOf('\n');
+            if (newline === -1)
+                break;
+            const line = remaining.subarray(0, newline).toString('utf8').trim();
+            if (!line) {
+                remaining = remaining.subarray(newline + 1);
+                continue;
+            }
+            messages.push(line);
+            remaining = remaining.subarray(newline + 1);
+            continue;
+        }
+        const header = remaining.subarray(0, headerEnd).toString('utf8');
+        const match = /content-length:\s*(\d+)/i.exec(header);
+        if (!match) {
+            remaining = remaining.subarray(headerEnd + 4);
+            continue;
+        }
+        const length = Number.parseInt(match[1], 10);
+        const bodyStart = headerEnd + 4;
+        const bodyEnd = bodyStart + length;
+        if (remaining.length < bodyEnd)
+            break;
+        messages.push(remaining.subarray(bodyStart, bodyEnd).toString('utf8'));
+        remaining = remaining.subarray(bodyEnd);
+    }
+    return { messages, remaining };
+}
+function writeMessage(stdout, message) {
+    stdout.write(`${JSON.stringify(message)}\n`);
+}
+function schema(properties, required = []) {
+    return {
+        type: 'object',
+        properties: {
+            rootPath: {
+                type: 'string',
+                description: 'Repository root path. Defaults to the MCP server cwd.',
+            },
+            ...properties,
+        },
+        required,
+        additionalProperties: false,
+    };
+}
+function objectParam(params, key, fallback) {
+    const value = params?.[key];
+    return value && typeof value === 'object' && !Array.isArray(value)
+        ? value
+        : fallback;
+}
+function stringParam(args, key, fallback = '') {
+    const value = args?.[key];
+    return typeof value === 'string' ? value : fallback;
+}
+function requiredString(args, key) {
+    const value = stringParam(args, key).trim();
+    if (!value)
+        throw new KGraphError(`${key} is required.`);
+    return value;
+}
+function booleanParam(args, key, fallback = false) {
+    const value = args[key];
+    return typeof value === 'boolean' ? value : fallback;
+}
+function numberParam(args, key, fallback) {
+    const value = args[key];
+    return typeof value === 'number' && Number.isFinite(value) ? value : fallback;
+}
+function stringArray(args, key, fallback = []) {
+    const value = args[key];
+    if (!Array.isArray(value))
+        return fallback;
+    return value.filter((item) => typeof item === 'string');
+}
+function stringOption(args, key, flag) {
+    const value = stringParam(args, key);
+    return value ? [flag, value] : [];
+}
+function numberOption(args, key, flag) {
+    const value = args[key];
+    return typeof value === 'number' && Number.isFinite(value)
+        ? [flag, String(value)]
+        : [];
+}
+function repeatOption(args, key, flag) {
+    return stringArray(args, key).flatMap((value) => [flag, value]);
+}
+function optionalWords(args, key) {
+    const value = stringParam(args, key);
+    return value ? [value] : [];
+}
+function agentArgs(args) {
+    return stringOption(args, 'agent', '--agent');
+}
+function requiredAgentArgs(args) {
+    return ['--agent', requiredString(args, 'agent')];
+}
+function sourceArgs(args) {
+    return stringOption(args, 'source', '--source');
+}
+function parseJsonOrUndefined(value) {
+    try {
+        return JSON.parse(value);
+    }
+    catch {
+        return undefined;
+    }
+}
+function summarizeCommand(args, result) {
+    const command = args.length > 0 ? `kgraph ${args.join(' ')}` : 'kgraph';
+    const firstLine = result.stdout.split('\n').find((line) => line.trim()) ??
+        result.stderr.split('\n').find((line) => line.trim()) ??
+        'no output';
+    return `${command} exited ${result.code}: ${firstLine}`;
+}
+function parseDoctorChecks(stdout) {
+    return stdout
+        .split('\n')
+        .map((line) => /^(OK|FAIL)\s+([^:]+):\s*(.*)$/.exec(line))
+        .filter((match) => Boolean(match))
+        .map((match) => ({
+        ok: match[1] === 'OK',
+        label: match[2].trim(),
+        detail: match[3].trim(),
+    }));
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kentwynn/kgraph",
-  "version": "0.2.38",
+  "version": "0.2.40",
   "description": "Persistent repo intelligence for AI coding assistants.",
   "type": "module",
   "bin": {
@@ -75,7 +75,7 @@
     "tree-sitter-rust": "^0.24.0",
     "tree-sitter-scala": "^0.24.0",
     "tree-sitter-wasms": "^0.1.13",
-    "tsx": "^4.19.2",
+    "tsx": "^4.22.4",
     "vitest": "^3.2.4"
   },
   "engines": {