Add KGraph MCP server orchestration

README.md

@@ -384,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.
@@ -393,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                                                                                                                                                                                                |
 | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -557,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.

docs/wiki/AI-Tool-Integrations.md

@@ -23,6 +23,17 @@ New integrations default to `always` mode, so every chat in the repository start
 
 Generated instructions teach agents to use the atom-native workflow: `context`, `pack`, `knowledge`, `stale`, `blame`, `conclude`, `compact`, `repair`, `impact`, `history`, and `session` where supported.
 
+## MCP
+
+For VS Code/Copilot, add `--mcp` when initializing or adding the Copilot integration:
+
+```bash
+kgraph init --integrations copilot --mcp
+kgraph integrate add copilot --mcp
+```
+
+This registers KGraph as a VS Code MCP server for the current repository. See [MCP Setup](MCP-Setup) for client behavior and setup details.
+
 ## Managed Files
 
 | Tool           | Files KGraph manages                                   |

docs/wiki/Command-Guide.md

@@ -125,3 +125,23 @@ kgraph visualize --no-open
 ```
 
 The graph shows files, imports, relationship edges, and canonical knowledge atoms. Symbols are shown in the file detail panel for performance.
+
+## `kgraph mcp`
+
+Starts the local KGraph MCP server over stdio.
+
+```bash
+kgraph mcp
+kgraph mcp --root /path/to/repo
+```
+
+MCP clients start this command automatically after KGraph is registered in that client's MCP config; you normally do not run it directly in a terminal. MCP clients can call typed `kgraph_*` tools for orchestration, context packs, impact analysis, capture, health checks, session tracking, and command-compatible access to the full CLI surface. If MCP tools are not available in the client, use the normal CLI commands.
+
+For VS Code/Copilot, register KGraph automatically while initializing or adding the Copilot integration:
+
+```bash
+kgraph init --integrations copilot --mcp
+kgraph integrate add copilot --mcp
+```
+
+Plain `kgraph init` stays repo-local and does not edit editor config. Add `--mcp` only when you want KGraph to write the VS Code MCP entry for this repository. Reload VS Code after KGraph prints the MCP config path. See [MCP Setup](MCP-Setup) for the full guide.

docs/wiki/Home.md

@@ -11,6 +11,7 @@ KGraph gives AI coding tools a local repo memory: file maps, symbols, relationsh
 
 - [Command Guide](Command-Guide)
 - [AI Tool Integrations](AI-Tool-Integrations)
+- [MCP Setup](MCP-Setup)
 - [Local-First Design](Local-First-Design)
 - [Roadmap](Roadmap)
 - [Contributing](Contributing)

docs/wiki/MCP-Setup.md

@@ -0,0 +1,84 @@
+# MCP Setup
+
+KGraph can run as a local MCP server so AI clients can call structured `kgraph_*` tools instead of shelling out to CLI commands.
+
+## Mental Model
+
+- `kgraph mcp` starts a stdio MCP server.
+- You normally do not run `kgraph mcp` manually in a terminal.
+- The AI client starts `kgraph mcp` automatically after KGraph is registered in that client's MCP config.
+- MCP changes the transport only. It does not change KGraph's local-first storage, integration modes, or capture policy.
+
+If MCP tools are available in the client, prefer them. If MCP is not available, use the normal CLI commands.
+
+## VS Code and Copilot
+
+For first-time setup in a repository:
+
+```bash
+kgraph init --integrations copilot --mcp
+```
+
+For an existing KGraph repository:
+
+```bash
+kgraph integrate add copilot --mcp
+```
+
+KGraph writes a `KGraph` server entry to VS Code's MCP config for the current repository and prints the config path. Reload VS Code after this command so Copilot can start the server.
+
+On macOS, VS Code's user MCP config is usually:
+
+```text
+~/Library/Application Support/Code/User/mcp.json
+```
+
+The generated server entry is equivalent to:
+
+```json
+{
+  "command": "kgraph",
+  "args": ["mcp", "--root", "/path/to/repo"],
+  "type": "stdio"
+}
+```
+
+## Why `--mcp` Is Explicit
+
+Plain `kgraph init` stays repo-local:
+
+- creates `.kgraph/`
+- writes KGraph config
+- scans the repository
+- optionally writes repo-local integration instruction files
+
+MCP setup edits editor/client configuration outside the repository, so KGraph only does it when you pass `--mcp`.
+
+## Other Clients
+
+Codex, Cursor, Claude Code, VS Code, and other MCP clients each have their own MCP config location. The current `--mcp` setup targets VS Code/Copilot. For other clients, point the client at:
+
+```bash
+kgraph mcp --root /path/to/repo
+```
+
+Future KGraph releases can add first-class MCP setup targets for more clients.
+
+## Available Tools
+
+KGraph exposes typed tools for common workflows, including:
+
+- `kgraph_orchestrate`
+- `kgraph_context_pack`
+- `kgraph_impact`
+- `kgraph_capture`
+- `kgraph_health`
+- `kgraph_command`
+
+It also exposes command-specific tools for scan, update, context, pack, history, stale, blame, doctor, repair, compact, knowledge, session, integrations, init, uninstall, and visualize workflows.
+
+Tools are labeled by mutability:
+
+- `read-only`
+- `repo-write`
+- `destructive`

docs/wiki/Roadmap.md

@@ -13,7 +13,7 @@ KGraph's roadmap stays focused on practical repo intelligence for AI coding work
 
 ## Integrations
 
-- Optional MCP support
+- More MCP client setup targets beyond VS Code/Copilot
 - More editor/tool-call integration surfaces
 - Better session capture for agents that support hooks or tool commands
 

src/cli/commands/init.ts

@@ -7,6 +7,7 @@ import {
 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';
@@ -30,6 +31,7 @@ interface InitOptions {
   integration?: string[];
   integrations?: string;
   mode: string;
+  mcp?: boolean;
 }
 
 export function registerInitCommand(program: Command): void {
@@ -51,6 +53,10 @@ export function registerInitCommand(program: Command): void {
       'Integration mode: always, smart, manual, or off',
       'always',
     )
+    .option(
+      '--mcp',
+      'Configure the VS Code/Copilot MCP server for this repository',
+    )
     .action((options: InitOptions) =>
       runCommand(async () => {
         const workspace = await ensureWorkspace(process.cwd());
@@ -74,6 +80,14 @@ export function registerInitCommand(program: Command): void {
           );
         }
 
+        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

src/cli/commands/integrate.ts

@@ -6,6 +6,7 @@ import {
   removeIntegrations,
   setIntegrationMode,
 } from '../../integrations/integration-store.js';
+import { installVSCodeMcpServer } from '../../integrations/vscode-mcp.js';
 import { assertWorkspace } from '../../storage/kgraph-paths.js';
 import type { IntegrationMode } from '../../types/config.js';
 import { KGraphError, runCommand } from '../errors.js';
@@ -40,7 +41,11 @@ export function registerIntegrateCommand(program: Command): void {
     .description('Add AI tool integrations')
     .argument('<names...>')
     .option('--mode <mode>', 'always, smart, manual, or off', 'always')
-    .action((names: string[], options: { mode: string }) =>
+    .option(
+      '--mcp',
+      'Configure the VS Code/Copilot MCP server for this repository',
+    )
+    .action((names: string[], options: { mode: string; mcp?: boolean }) =>
       runCommand(async () => {
         const workspace = await assertWorkspace(process.cwd());
         const normalized = normalizeIntegrationNames(names);
@@ -52,6 +57,13 @@ export function registerIntegrateCommand(program: Command): void {
         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.');
+        }
       }),
     );
 

src/cli/commands/mcp.ts

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

src/cli/help.ts

@@ -32,6 +32,10 @@ export function renderRootHelp(useColor = supportsColor()): string {
       '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'),
@@ -99,6 +103,7 @@ export function renderRootHelp(useColor = supportsColor()): string {
       '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'),
@@ -110,6 +115,10 @@ export function renderRootHelp(useColor = supportsColor()): string {
       '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',

src/cli/index.ts

@@ -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';
@@ -102,6 +103,7 @@ export function createProgram(): Command {
   registerContextCommand(program);
   registerPackCommand(program);
   registerKnowledgeCommand(program);
+  registerMcpCommand(program);
   registerStaleCommand(program);
   registerBlameCommand(program);
   registerImpactCommand(program);