ctxman 3.1.1 → 3.2.8

package/lib/api/mcp/server.js

@@ -19,10 +19,18 @@ import { PromptProvider } from './prompts.js';
 import { buildPrContext } from '../../pr/pr-context.js';
 import { resolveRootDir, resolveSandboxPath } from './sandbox.js';
 import { searchProject, DEFAULT_LIMIT, DEFAULT_MAX_TOKENS } from '../../search/bm25.js';
+import { hybridSearch } from '../../search/hybrid.js';
 import { getSymbol } from '../../search/symbols.js';
 import { countForModel } from '../../count/index.js';
 import { explainHistory } from '../../why/index.js';
 import { packContext, describePack, TOOL_DEFAULT_BUDGET } from '../../pack/index.js';
+import { focusContext, describeFocus, DEFAULT_FOCUS_DEPTH } from '../../focus/index.js';
+import {
+  resolveWorkspaceRepos,
+  mapWorkspace,
+  searchWorkspace,
+  packWorkspace,
+} from '../../workspace/index.js';
 import {
   loadPolicy,
   guardExport,
@@ -31,8 +39,14 @@ import {
   readAuditLog,
   filterAuditEvents,
   parseSince,
+  checkWorkspacePolicies,
+  readWorkspaceAuditLogs,
 } from '../../policy/index.js';
 import { askCodebase, DEFAULT_ASK_LIMIT } from '../../rag/ask.js';
+import { buildTaskContext, DEFAULT_TASK_BUDGET } from '../../task/index.js';
+import { diagnoseFailure, DEFAULT_DIAGNOSE_BUDGET } from '../../diagnose/index.js';
+import { findExperts, DEFAULT_WHO_LIMIT } from '../../who/index.js';
+import { IncrementalAnalyzer } from '../../watch/IncrementalAnalyzer.js';
 import fs from 'fs';
 import path from 'path';
 import { createRequire } from 'module';
@@ -45,6 +59,7 @@ const FILE_PATH_TOOLS = new Set(['list_methods']);
 const DEFAULT_AUDIT_LIMIT = 50;
 // Characters of each ask_codebase snippet (the index stores whole files)
 const ASK_SNIPPET_CHARS = 2000;
+const DEFAULT_GRAPH_LIMIT = 50;
 
 class MCPServer {
   /**
@@ -69,21 +84,47 @@ class MCPServer {
       }
     );
 
-    this.analyzer = new Analyzer();
+    this.analyzer = new Analyzer({ cache: true });
     this.contextBuilder = new ContextBuilder();
+    this.incrementalAnalyzers = new Map();
     this.resourceProvider = new ResourceProvider(this.root ?? undefined);
     this.promptProvider = new PromptProvider(this.analyzer, this.contextBuilder);
     this.setupHandlers();
     this.setupErrorHandling();
   }
 
+  /**
+   * Get or create a cached IncrementalAnalyzer instance bound to the project's SQLite knowledge graph.
+   * @param {string} projectPath
+   * @returns {IncrementalAnalyzer}
+   */
+  getIncrementalAnalyzer(projectPath, repos = []) {
+    const resolved = path.resolve(projectPath);
+    const extraRepos = Array.isArray(repos)
+      ? repos.filter(Boolean).map((r) => path.resolve(r))
+      : [];
+    const cacheKey = [resolved, ...extraRepos].join('::');
+    let inc = this.incrementalAnalyzers.get(cacheKey);
+    if (!inc) {
+      inc = new IncrementalAnalyzer({
+        projectRoot: resolved,
+        repos: extraRepos,
+        sync: true,
+        hydrateGraphOnStart: false,
+      });
+      this.incrementalAnalyzers.set(cacheKey, inc);
+    }
+    return inc;
+  }
+
   setupHandlers() {
     this.server.setRequestHandler(ListToolsRequestSchema, async () => {
       return {
         tools: [
           {
             name: 'analyze_codebase',
-            description: 'Analyze the codebase and return statistics and token counts',
+            description:
+              'Analyze the codebase (single-repo or multi-repo workspace) and return statistics and token counts',
             inputSchema: {
               type: 'object',
               properties: {
@@ -91,13 +132,20 @@ class MCPServer {
                   type: 'string',
                   description: 'Absolute path to the project root',
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to analyze together in a multi-repository workspace',
+                },
               },
               required: ['path'],
             },
           },
           {
             name: 'generate_context',
-            description: 'Generate optimized context for LLMs from the codebase',
+            description:
+              'Generate optimized context for LLMs from the codebase (single-repo or multi-repo workspace)',
             inputSchema: {
               type: 'object',
               properties: {
@@ -114,13 +162,20 @@ class MCPServer {
                   type: 'number',
                   description: 'Maximum tokens for the context',
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to include in multi-repository context generation',
+                },
               },
               required: ['path'],
             },
           },
           {
             name: 'git_diff',
-            description: 'Analyze git changes and return diff context',
+            description:
+              'Analyze git changes (single-repo or multi-repo workspace) and return diff context',
             inputSchema: {
               type: 'object',
               properties: {
@@ -129,6 +184,12 @@ class MCPServer {
                   type: 'string',
                   description: 'Branch to compare against (default: main)',
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to include in multi-repository git diff',
+                },
               },
               required: ['path'],
             },
@@ -136,13 +197,17 @@ class MCPServer {
           {
             name: 'search_code',
             description:
-              'Search source lines by regular expression (default) or plain substring ("semantic" is currently a substring match). "ranked" returns the methods/functions (or 40-line windows) that best match the query words by BM25, with their source.',
+              'Search source lines by regular expression (default) or plain substring (single-repo or multi-repo workspace). "ranked" returns BM25-ranked methods/chunks; "semantic" runs vector embedding search projected onto chunks (with BM25 fallback); "hybrid" fuses BM25 and semantic embeddings via Reciprocal Rank Fusion (RRF).',
             inputSchema: {
               type: 'object',
               properties: {
                 path: { type: 'string', description: 'Project root' },
                 query: { type: 'string', description: 'Search query' },
-                type: { type: 'string', enum: ['regex', 'semantic', 'ranked'], default: 'regex' },
+                type: {
+                  type: 'string',
+                  enum: ['regex', 'substring', 'semantic', 'ranked', 'hybrid'],
+                  default: 'regex',
+                },
                 limit: {
                   type: 'number',
                   description: `ranked: maximum number of chunks (default ${DEFAULT_LIMIT})`,
@@ -155,13 +220,19 @@ class MCPServer {
                   type: 'boolean',
                   description: 'ranked: redact secrets in the returned source (default true)',
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description: 'Additional repository roots to search across in the workspace',
+                },
               },
               required: ['path', 'query'],
             },
           },
           {
             name: 'list_methods',
-            description: 'List all methods/functions in a given file or project',
+            description:
+              'List all methods/functions in a given file, project, or multi-repository workspace',
             inputSchema: {
               type: 'object',
               properties: {
@@ -171,7 +242,14 @@ class MCPServer {
                 },
                 file: {
                   type: 'string',
-                  description: 'Optional: Relative path to a specific file within the project',
+                  description:
+                    'Optional: Relative path (or <alias>/<path>) to a specific file within the project',
+                },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to list methods across in a multi-repository workspace',
                 },
               },
               required: ['path'],
@@ -195,6 +273,12 @@ class MCPServer {
                   description:
                     'Project-relative files or folders to rank higher, with the files next to them in the import graph',
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to include in a multi-repository workspace map under one shared token budget',
+                },
               },
               required: ['path'],
             },
@@ -202,7 +286,7 @@ class MCPServer {
           {
             name: 'pr_context',
             description:
-              'Review context for a branch: summary, commit log, changed files, full source of changed methods, unified diff and related tests (secrets redacted)',
+              'Review context for a branch (single-repo or multi-repo workspace): summary, commit log, changed files, full source of changed methods, unified diff and related tests (secrets redacted)',
             inputSchema: {
               type: 'object',
               properties: {
@@ -215,6 +299,12 @@ class MCPServer {
                 head: { type: 'string', description: 'Head branch or commit (default: HEAD)' },
                 budget: { type: 'number', description: 'Maximum tokens of the result' },
                 style: { type: 'string', enum: ['markdown', 'xml', 'json'], default: 'markdown' },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to include in multi-repository PR review context under one shared token budget',
+                },
               },
               required: ['path'],
             },
@@ -222,7 +312,7 @@ class MCPServer {
           {
             name: 'get_symbol',
             description:
-              'Full source of a method, function or class by name, with file and line range. Exact matches first, then case-insensitive; similar names are suggested when nothing matches. "Class.method" narrows to methods of a class.',
+              'Full source of a method, function or class by name, with file and line range (single-repo or multi-repo workspace). Exact matches first, then case-insensitive; similar names are suggested when nothing matches. "Class.method" narrows to methods of a class.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -230,12 +320,19 @@ class MCPServer {
                 name: { type: 'string', description: 'Symbol name, or Class.method' },
                 file: {
                   type: 'string',
-                  description: 'Optional: only look in this project-relative file',
+                  description:
+                    'Optional: only look in this project-relative (or <alias>/<path>) file',
                 },
                 redact: {
                   type: 'boolean',
                   description: 'Redact secrets in the source (default true)',
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to search for symbols across under one shared token budget',
+                },
               },
               required: ['path', 'name'],
             },
@@ -243,7 +340,7 @@ class MCPServer {
           {
             name: 'count_tokens',
             description:
-              "Token count of a project (or of a text) for a model, with the model's context window and whether it fits. Exact for OpenAI models; approximate for models with their own tokenizer (Claude, Gemini, ...). Nothing leaves the machine; for Claude's exact count run `ctxman count --model <id> --api`",
+              "Token count of a project or multi-repository workspace (or of a text) for a model, with the model's context window and whether it fits. Exact for OpenAI models; approximate for models with their own tokenizer (Claude, Gemini, ...). Nothing leaves the machine; for Claude's exact count run `ctxman count --model <id> --api`",
             inputSchema: {
               type: 'object',
               properties: {
@@ -260,13 +357,19 @@ class MCPServer {
                   type: 'number',
                   description: 'How many of the largest files to list (default 10)',
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to count across in a multi-repository workspace (ignored when text is given)',
+                },
               },
             },
           },
           {
             name: 'explain_history',
             description:
-              'Explain why code looks the way it does, from the local git history (offline): commits that changed a file, symbol or line range with their messages, referenced issues/PRs/tickets, blame ownership, files that change together with it, related docs/ADRs/comments, TODO notes and tests. Returns Markdown.',
+              'Explain why code looks the way it does, from the local git history (offline, single-repo or multi-repo workspace): commits that changed a file, symbol or line range with their messages, referenced issues/PRs/tickets, institutional memory citations (.plansmith/analyzer.sqlite), blame ownership, files that change together with it, related docs/ADRs/comments, TODO notes and tests. Returns Markdown.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -277,7 +380,7 @@ class MCPServer {
                 target: {
                   type: 'string',
                   description:
-                    'File relative to path, optionally with a symbol or line range: "src/cart.js", "src/cart.js:total", "src/cart.js:Cart.total", "src/cart.js#L10-L40"',
+                    'File relative to path (or <alias>/<path> in multi-repo mode), optionally with a symbol or line range: "src/cart.js", "src/cart.js:total", "src/cart.js:Cart.total", "src/cart.js#L10-L40"',
                 },
                 limit: {
                   type: 'number',
@@ -296,6 +399,32 @@ class MCPServer {
                   type: 'boolean',
                   description: "Include each commit's diff of the target (default false)",
                 },
+                discussions: {
+                  type: 'boolean',
+                  description:
+                    'Fetch referenced GitHub/GitLab issue, PR and MR discussions over HTTPS (default false; uses GITHUB_TOKEN/GH_TOKEN or GITLAB_TOKEN when set)',
+                },
+                maxDiscussions: {
+                  type: 'number',
+                  description:
+                    'Maximum remote discussions to fetch when discussions is true (default 10)',
+                },
+                analyzer: {
+                  type: 'boolean',
+                  description:
+                    'Query local @plansmithai/analyzer SQLite database (.plansmith/analyzer.sqlite) for institutional memory citations',
+                },
+                analyzerDb: {
+                  type: 'string',
+                  description:
+                    'Explicit path to @plansmithai/analyzer SQLite database file or directory',
+                },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to include in multi-repository history explanation and cross-repo ADR/doc/test discovery',
+                },
               },
               required: ['path', 'target'],
             },
@@ -349,18 +478,102 @@ class MCPServer {
                   type: 'string',
                   description: "Count with this model's tokenizer encoding and report the fit",
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to pack into one workspace document under one shared token budget',
+                },
               },
               required: ['path'],
             },
           },
+          {
+            name: 'focus_context',
+            description:
+              'Focused neighborhood context around a target file (or file:symbol): packs the target file together with its outgoing imports/callees and incoming importers/callers up to `depth` hops in the repository import and AST symbol call graph (directional traversal avoids shared-hub explosion), honouring .gitignore/.contextignore and export policy, with secrets redacted and trimmed to a token budget (target file kept first).',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                path: { type: 'string', description: 'Project root' },
+                file: {
+                  type: 'string',
+                  description:
+                    'Project-relative (or <alias>/<path>) file or file:symbol to focus on (e.g. "src/auth/login.ts" or "src/auth/login.ts:authenticate")',
+                },
+                symbol: {
+                  type: 'string',
+                  description:
+                    'Optional function or method name inside `file` to traverse the cross-file AST symbol call graph around',
+                },
+                depth: {
+                  type: 'number',
+                  description: `Import/call graph hops (default ${DEFAULT_FOCUS_DEPTH}; 0 = target file only)`,
+                },
+                direction: {
+                  type: 'string',
+                  enum: ['both', 'imports', 'importers', 'calls', 'callers'],
+                  default: 'both',
+                },
+                callGraph: {
+                  type: 'boolean',
+                  description:
+                    'Include cross-file AST symbol call graph edges alongside module imports (default true)',
+                },
+                includeTests: {
+                  type: 'boolean',
+                  description: 'Include test files in the neighborhood (default true)',
+                },
+                style: {
+                  type: 'string',
+                  enum: ['xml', 'markdown', 'plain', 'json'],
+                  default: 'xml',
+                },
+                compress: {
+                  type: 'boolean',
+                  description: 'Keep signatures, replace function bodies with a placeholder',
+                },
+                lineNumbers: { type: 'boolean', description: 'Number every line' },
+                tree: {
+                  type: 'boolean',
+                  description: 'Directory tree at the top (default true)',
+                },
+                instructions: {
+                  type: 'string',
+                  description: 'Text placed at the end, after the files',
+                },
+                budget: {
+                  type: 'number',
+                  description: `Maximum tokens of the document (default ${TOOL_DEFAULT_BUDGET})`,
+                },
+                targetModel: {
+                  type: 'string',
+                  description: "Count with this model's tokenizer encoding and report the fit",
+                },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to include in the workspace import/call graph neighborhood under one shared token budget',
+                },
+              },
+              required: ['path', 'file'],
+            },
+          },
           {
             name: 'check_policy',
             description:
-              'The effective export policy of a project (.ctxman/policy.json plus the organisation policy named by CTXMAN_POLICY): denied paths, redaction and token limits, allowed target models, AI-tool ignore files and audit logging. Reports whether the policy files are valid and, if not, every error.',
+              'The effective export policy of a project or multi-repository workspace (.ctxman/policy.json plus the organisation policy named by CTXMAN_POLICY): denied paths, redaction and token limits, allowed target models, AI-tool ignore files and audit logging. Reports whether the policy files are valid and, if not, every error.',
             inputSchema: {
               type: 'object',
               properties: {
                 path: { type: 'string', description: 'Project root' },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to validate and summarize together in a multi-repository workspace',
+                },
               },
               required: ['path'],
             },
@@ -368,7 +581,7 @@ class MCPServer {
           {
             name: 'audit_log',
             description:
-              "Exports recorded in the project's audit log while the export policy enables audit: when, by whom, which command, where to, which files, token count and a SHA-256 of the exported text. Newest last.",
+              "Exports recorded in the project's (or multi-repository workspace's) audit log while the export policy enables audit: when, by whom, which command, where to, which files, token count and a SHA-256 of the exported text. Newest last.",
             inputSchema: {
               type: 'object',
               properties: {
@@ -382,6 +595,12 @@ class MCPServer {
                   type: 'number',
                   description: `The last N events (default ${DEFAULT_AUDIT_LIMIT}; 0 = all)`,
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots whose export audit logs should be merged chronologically with repo attribution',
+                },
               },
               required: ['path'],
             },
@@ -389,7 +608,7 @@ class MCPServer {
           {
             name: 'ask_codebase',
             description:
-              'Semantic search: the files whose content is closest in meaning to a question, from a local embedding index (.ctxman/self-knowledge, built on first use; the first call downloads the embedding model and can take minutes). Needs the optional @xenova/transformers and @lancedb/lancedb packages. For exact names or keywords, search_code is faster.',
+              'Semantic search: the files whose content is closest in meaning to a question, from a local SQLite embedding index (.ctxman/self-knowledge/index.sqlite via built-in node:sqlite, single-repo or multi-repo workspace). Uses @xenova/transformers when installed and automatically falls back to deterministic offline LocalHashEmbeddingProvider otherwise. For exact names or keywords, search_code is faster.',
             inputSchema: {
               type: 'object',
               properties: {
@@ -399,10 +618,152 @@ class MCPServer {
                   type: 'number',
                   description: `How many files (default ${DEFAULT_ASK_LIMIT})`,
                 },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to include in multi-repository semantic search',
+                },
               },
               required: ['path', 'query'],
             },
           },
+          {
+            name: 'task_context',
+            description:
+              'Task-driven automatic context builder: fuses hybrid search, PageRank import/call neighborhood, and architectural map for a task description within a token budget (single-repo or multi-repo workspace).',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                path: { type: 'string', description: 'Project root' },
+                task: { type: 'string', description: 'Natural-language task or issue description' },
+                budget: {
+                  type: 'number',
+                  description: `Maximum tokens (default ${DEFAULT_TASK_BUDGET})`,
+                },
+                format: { type: 'string', enum: ['xml', 'markdown', 'json'], default: 'xml' },
+                model: { type: 'string', description: 'Optional target LLM model ID' },
+                callGraph: {
+                  type: 'boolean',
+                  description:
+                    'Include cross-file AST symbol call graph edges alongside module imports (default true)',
+                },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to include in a multi-repository task context bundle under one shared token budget',
+                },
+              },
+              required: ['path', 'task'],
+            },
+          },
+          {
+            name: 'diagnose_failure',
+            description:
+              'Diagnose a stack trace, test failure, or error log: parses implicated repo files/lines (single-repo or multi-repo workspace), packs enclosing symbols and 1-hop graph neighbors, and surfaces recent commits that touched them.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                path: { type: 'string', description: 'Project root' },
+                trace: { type: 'string', description: 'Error stack trace or failure log text' },
+                budget: {
+                  type: 'number',
+                  description: `Maximum tokens (default ${DEFAULT_DIAGNOSE_BUDGET})`,
+                },
+                format: { type: 'string', enum: ['xml', 'markdown', 'json'], default: 'xml' },
+                callGraph: {
+                  type: 'boolean',
+                  description:
+                    'Include cross-file AST symbol call graph edges alongside module imports (default true)',
+                },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots to resolve stack frames and 1-hop neighbors across under one shared token budget',
+                },
+              },
+              required: ['path', 'trace'],
+            },
+          },
+          {
+            name: 'find_experts',
+            description:
+              'Expert Finder ("Who knows about this?"): ranks code and domain experts for a file, symbol, directory, or natural-language topic (single-repo or multi-repo workspace) by fusing surviving git blame ownership, recency-decayed commit/churn history, and CODEOWNERS stewardship.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                path: { type: 'string', description: 'Project root inside a git repository' },
+                target: {
+                  type: 'string',
+                  description:
+                    'File path (<alias>/<path>), file:symbol, file#L10-L40, directory, or natural-language topic query',
+                },
+                limit: {
+                  type: 'number',
+                  description: `Maximum ranked experts to return (default ${DEFAULT_WHO_LIMIT})`,
+                },
+                halfLifeDays: {
+                  type: 'number',
+                  description: 'Recency exponential decay half-life in days (default 90)',
+                },
+                style: {
+                  type: 'string',
+                  enum: ['markdown', 'xml', 'json'],
+                  default: 'markdown',
+                },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Additional repository roots inside git repositories to include in multi-repository expert ranking',
+                },
+              },
+              required: ['path', 'target'],
+            },
+          },
+          {
+            name: 'query_knowledge_graph',
+            description:
+              'Query the persistent SQLite knowledge graph (.ctxman/self-knowledge/index.sqlite) or IncrementalAnalyzer cache for file nodes, method declarations, and import/dependency edges.',
+            inputSchema: {
+              type: 'object',
+              properties: {
+                path: { type: 'string', description: 'Project root' },
+                query: {
+                  type: 'string',
+                  description:
+                    'Optional substring or symbol query to filter graph nodes and method declarations',
+                },
+                file: {
+                  type: 'string',
+                  description:
+                    'Optional project-relative file path to inspect along with its dependency neighborhood',
+                },
+                depth: {
+                  type: 'number',
+                  description: 'Neighborhood hop depth when file is provided (default: 1, max: 4)',
+                },
+                limit: {
+                  type: 'number',
+                  description: `Maximum number of graph nodes to return (default ${DEFAULT_GRAPH_LIMIT})`,
+                },
+                refresh: {
+                  type: 'boolean',
+                  description:
+                    'Re-synchronize the IncrementalAnalyzer cache and SQLite knowledge graph before querying',
+                },
+                repos: {
+                  type: 'array',
+                  items: { type: 'string' },
+                  description:
+                    'Optional additional repository roots to include in a multi-repository knowledge graph under <alias>/<path>',
+                },
+              },
+              required: ['path'],
+            },
+          },
         ],
       };
     });
@@ -468,6 +829,21 @@ class MCPServer {
             }),
           };
         }
+        if (args.repos !== undefined) {
+          if (!Array.isArray(args.repos)) {
+            throw new Error('repos must be an array of directory paths');
+          }
+          args = {
+            ...args,
+            repos: args.repos.map((repoPath) =>
+              resolveSandboxPath(repoPath, {
+                root: this.root,
+                expect: 'directory',
+                name: 'repos',
+              })
+            ),
+          };
+        }
 
         switch (name) {
           case 'analyze_codebase': {
@@ -476,6 +852,28 @@ class MCPServer {
             // Update resource provider project path
             this.resourceProvider.projectPath = projectPath;
 
+            if (args.repos?.length > 0) {
+              const resolvedRepos = resolveWorkspaceRepos([projectPath, ...args.repos]);
+              const allFiles = [];
+              for (const repo of resolvedRepos) {
+                const scanner = new Scanner(repo.root, { policy: repo.policy });
+                for (const file of scanner.scan()) {
+                  const relPosix = `${repo.alias}/${file.relativePath.split(path.sep).join('/')}`;
+                  allFiles.push({
+                    ...file,
+                    relativePath: relPosix,
+                  });
+                }
+              }
+              const analysis = await this.analyzer.analyze(allFiles);
+              analysis.repos = resolvedRepos.map((r) => ({ alias: r.alias, root: r.root }));
+              const analysisId = Date.now().toString();
+              this.resourceProvider.cacheAnalysis(analysisId, analysis);
+              return {
+                content: [{ type: 'text', text: JSON.stringify(analysis, null, 2) }],
+              };
+            }
+
             const scanner = new Scanner(projectPath);
             const files = scanner.scan();
             const analysis = await this.analyzer.analyze(files);
@@ -499,20 +897,57 @@ class MCPServer {
             // Update resource provider project path
             this.resourceProvider.projectPath = projectPath;
 
-            const scanner = new Scanner(projectPath);
-            const files = scanner.scan();
-            const analysis = await this.analyzer.analyze(files);
-
-            // Configure ContextBuilder based on args
             const builderOptions = {
               targetTokens: args.maxTokens,
               useCase: args.template || 'custom',
             };
             const contextBuilder = new ContextBuilder(builderOptions);
+            const templateName = args.template || 'custom';
+
+            if (args.repos?.length > 0) {
+              const resolvedRepos = resolveWorkspaceRepos([projectPath, ...args.repos]);
+              const allFiles = [];
+              for (const repo of resolvedRepos) {
+                const scanner = new Scanner(repo.root, { policy: repo.policy });
+                for (const file of scanner.scan()) {
+                  const relPosix = `${repo.alias}/${file.relativePath.split(path.sep).join('/')}`;
+                  allFiles.push({
+                    ...file,
+                    relativePath: relPosix,
+                  });
+                }
+              }
+              const analysis = await this.analyzer.analyze(allFiles);
+              const context = contextBuilder.build(analysis);
+              context.repos = resolvedRepos.map((r) => ({ alias: r.alias, root: r.root }));
+              const contextText = JSON.stringify(context, null, 2);
+              const exportedFiles = Object.values(context.files || {}).flat();
+              for (const repo of resolvedRepos) {
+                const prefix = `${repo.alias}/`;
+                const repoFiles = exportedFiles
+                  .filter((f) => typeof f.path === 'string' && f.path.startsWith(prefix))
+                  .map((f) => ({ ...f, path: f.path.slice(prefix.length) }));
+                guardExport(repo.policy, {
+                  command: 'mcp generate_context',
+                  root: repo.root,
+                  destination: 'mcp',
+                  format: 'json',
+                  files: repoFiles,
+                  text: contextText,
+                });
+              }
+              this.resourceProvider.cacheContext(templateName, contextText);
+              return {
+                content: [{ type: 'text', text: contextText }],
+              };
+            }
+
+            const scanner = new Scanner(projectPath);
+            const files = scanner.scan();
+            const analysis = await this.analyzer.analyze(files);
             const context = contextBuilder.build(analysis);
 
             // Cache context as a resource
-            const templateName = args.template || 'custom';
             const contextText = JSON.stringify(context, null, 2);
             // Export policy: throws PolicyViolationError (an isError result) and logs the export
             guardExport(loadPolicy(projectPath), {
@@ -536,7 +971,6 @@ class MCPServer {
           }
           case 'git_diff': {
             const projectPath = args.path;
-            const gitClient = new GitClient(projectPath);
             const branch = args.branch || 'main';
 
             if (!isValidGitRef(branch)) {
@@ -548,6 +982,47 @@ class MCPServer {
               };
             }
 
+            if (args.repos?.length > 0) {
+              const resolvedRepos = resolveWorkspaceRepos([projectPath, ...args.repos]);
+              const diffs = [];
+              const errors = [];
+              for (const repo of resolvedRepos) {
+                try {
+                  const gitClient = new GitClient(repo.root);
+                  const rawDiff = gitClient.exec([
+                    'diff',
+                    branch,
+                    '--',
+                    ...(this.root ? ['.'] : []),
+                  ]);
+                  if (rawDiff && rawDiff.trim()) {
+                    const prefixed = rawDiff
+                      .replace(
+                        /^diff --git a\/(.+) b\/(.+)$/gm,
+                        `diff --git a/${repo.alias}/$1 b/${repo.alias}/$2`
+                      )
+                      .replace(/^--- a\/(.+)$/gm, `--- a/${repo.alias}/$1`)
+                      .replace(/^\+\+\+ b\/(.+)$/gm, `+++ b/${repo.alias}/$1`);
+                    diffs.push(prefixed.trimEnd());
+                  }
+                } catch (e) {
+                  errors.push(`${repo.alias}: ${e.message}`);
+                }
+              }
+              if (errors.length === resolvedRepos.length) {
+                return {
+                  content: [{ type: 'text', text: `Error executing git diff: ${errors[0]}` }],
+                  isError: true,
+                };
+              }
+              const notes = errors.map((err) => `# Note: ${err}`).join('\n');
+              const combined = [diffs.join('\n'), notes].filter(Boolean).join('\n\n');
+              return {
+                content: [{ type: 'text', text: combined || 'No changes detected.' }],
+              };
+            }
+
+            const gitClient = new GitClient(projectPath);
             let diff;
             try {
               // With a root, keep the diff to that directory even if the repository is larger
@@ -565,6 +1040,17 @@ class MCPServer {
           }
           case 'search_code': {
             const { path: projectPath, query, type = 'regex' } = args;
+            if (
+              args.repos?.length > 0 &&
+              (type === 'ranked' || type === 'hybrid' || type === 'semantic')
+            ) {
+              const result = searchWorkspace([projectPath, ...args.repos], query, {
+                limit: args.limit ?? DEFAULT_LIMIT,
+                maxTokens: args.maxTokens ?? DEFAULT_MAX_TOKENS,
+                redact: args.redact !== false,
+              });
+              return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
             if (type === 'ranked') {
               const result = searchProject(projectPath, query, {
                 limit: args.limit ?? DEFAULT_LIMIT,
@@ -573,6 +1059,16 @@ class MCPServer {
               });
               return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
             }
+            if (type === 'hybrid' || type === 'semantic') {
+              const result = await hybridSearch(projectPath, query, {
+                mode: type,
+                fallbackToBm25: true,
+                limit: args.limit ?? DEFAULT_LIMIT,
+                maxTokens: args.maxTokens ?? DEFAULT_MAX_TOKENS,
+                redact: args.redact !== false,
+              });
+              return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
             let pattern = null;
             if (type === 'regex') {
               try {
@@ -584,6 +1080,37 @@ class MCPServer {
                 };
               }
             }
+
+            if (args.repos?.length > 0) {
+              const resolvedRepos = resolveWorkspaceRepos([projectPath, ...args.repos]);
+              const results = [];
+              for (const repo of resolvedRepos) {
+                const scanner = new Scanner(repo.root, { policy: repo.policy });
+                for (const file of scanner.scan()) {
+                  try {
+                    const content = fs.readFileSync(file.path, 'utf-8');
+                    const lines = content.split('\n');
+                    const relPosix = `${repo.alias}/${file.relativePath.split(path.sep).join('/')}`;
+                    lines.forEach((line, index) => {
+                      const match = pattern ? pattern.test(line) : line.includes(query);
+                      if (match) {
+                        results.push({
+                          file: relPosix,
+                          line: index + 1,
+                          content: line.trim(),
+                        });
+                      }
+                    });
+                  } catch (_e) {
+                    // Skip read errors
+                  }
+                }
+              }
+              return {
+                content: [{ type: 'text', text: JSON.stringify(results, null, 2) }],
+              };
+            }
+
             const scanner = new Scanner(projectPath);
             const files = scanner.scan();
             const results = [];
@@ -621,6 +1148,48 @@ class MCPServer {
               file = path.basename(projectPath);
               projectPath = path.dirname(projectPath);
             }
+
+            if (args.repos?.length > 0) {
+              const resolvedRepos = resolveWorkspaceRepos([projectPath, ...args.repos]);
+              const targetPosix = file ? file.split(path.sep).join('/').replace(/^\.\//, '') : null;
+              const allFiles = [];
+              for (const repo of resolvedRepos) {
+                const scanner = new Scanner(repo.root, { policy: repo.policy });
+                for (const f of scanner.scan()) {
+                  const barePosix = f.relativePath.split(path.sep).join('/');
+                  const relPosix = `${repo.alias}/${barePosix}`;
+                  if (!targetPosix || relPosix === targetPosix || barePosix === targetPosix) {
+                    allFiles.push({
+                      ...f,
+                      relativePath: relPosix,
+                    });
+                  }
+                }
+              }
+              if (targetPosix && allFiles.length === 0) {
+                return {
+                  content: [{ type: 'text', text: `File not found in project: ${file}` }],
+                  isError: true,
+                };
+              }
+              const methodAnalyzer = new Analyzer({ methodLevel: true, cache: true });
+              const analysis = await methodAnalyzer.analyze(allFiles);
+              const methods = [];
+              if (analysis.files) {
+                for (const analyzedFile of analysis.files) {
+                  if (analyzedFile.methods && analyzedFile.methods.length > 0) {
+                    methods.push({
+                      file: analyzedFile.relativePath,
+                      methods: analyzedFile.methods,
+                    });
+                  }
+                }
+              }
+              return {
+                content: [{ type: 'text', text: JSON.stringify(methods, null, 2) }],
+              };
+            }
+
             const scanner = new Scanner(projectPath);
             // Optional `file`: one project-relative file instead of the whole project
             const target = file ? path.normalize(file) : null;
@@ -635,7 +1204,7 @@ class MCPServer {
             }
 
             // Use Analyzer with methodLevel: true
-            const methodAnalyzer = new Analyzer({ methodLevel: true });
+            const methodAnalyzer = new Analyzer({ methodLevel: true, cache: true });
             const analysis = await methodAnalyzer.analyze(files);
 
             const methods = [];
@@ -655,10 +1224,18 @@ class MCPServer {
             };
           }
           case 'repo_map': {
-            const map = renderRepoMap(args.path, {
-              tokens: args.tokens,
-              focus: args.focus,
-            });
+            const map =
+              args.repos?.length > 0
+                ? mapWorkspace([args.path, ...args.repos], {
+                    tokens: args.tokens,
+                    focus: args.focus,
+                    callGraph: args.callGraph,
+                  })
+                : renderRepoMap(args.path, {
+                    tokens: args.tokens,
+                    focus: args.focus,
+                    callGraph: args.callGraph,
+                  });
             const notes = map.warnings.map((warning) => `Note: ${warning}`).join('\n');
             return {
               content: [
@@ -671,6 +1248,7 @@ class MCPServer {
           }
           case 'pr_context': {
             const result = await buildPrContext(args.path, {
+              repos: args.repos,
               base: args.base,
               head: args.head,
               budget: args.budget == null ? undefined : Math.floor(args.budget),
@@ -682,6 +1260,7 @@ class MCPServer {
             const result = getSymbol(args.path, args.name, {
               file: args.file,
               redact: args.redact !== false,
+              repos: args.repos,
             });
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
           }
@@ -692,6 +1271,7 @@ class MCPServer {
             const { largestFiles, ...summary } = await countForModel(args.path, {
               model: args.model,
               text: args.text,
+              repos: args.repos,
             });
             const top = Number.isInteger(args.top) && args.top >= 0 ? args.top : 10;
             const result = { ...summary, largestFiles: largestFiles.slice(0, top) };
@@ -699,15 +1279,47 @@ class MCPServer {
           }
           case 'explain_history': {
             const whole = (value) => (typeof value === 'number' ? Math.floor(value) : value);
+            const analyzerDb =
+              args.analyzerDb !== undefined
+                ? resolveSandboxPath(args.analyzerDb, {
+                    root: this.root,
+                    expect: 'any',
+                    name: 'analyzerDb',
+                  })
+                : undefined;
             const result = await explainHistory(args.path, args.target, {
+              repos: args.repos,
               limit: whole(args.limit),
               budget: whole(args.budget ?? 20000),
               since: args.since,
               patches: args.patches === true,
+              discussions: args.discussions === true,
+              maxDiscussions: whole(args.maxDiscussions),
+              analyzer: args.analyzer === true,
+              analyzerDb,
             });
             return { content: [{ type: 'text', text: result.text }] };
           }
           case 'pack_context': {
+            if (args.repos?.length > 0) {
+              const result = await packWorkspace([args.path, ...args.repos], {
+                include: args.include,
+                exclude: args.exclude,
+                style: args.style,
+                compress: args.compress,
+                lineNumbers: args.lineNumbers,
+                tree: args.tree,
+                instructions: args.instructions,
+                budget: args.budget == null ? TOOL_DEFAULT_BUDGET : Math.floor(args.budget),
+                targetModel: args.targetModel,
+              });
+              return {
+                content: [
+                  { type: 'text', text: result.text },
+                  { type: 'text', text: describePack(result) },
+                ],
+              };
+            }
             const result = await packContext(args.path, {
               include: args.include,
               exclude: args.exclude,
@@ -729,7 +1341,35 @@ class MCPServer {
               ],
             };
           }
+          case 'focus_context': {
+            const result = await focusContext(args.path, args.file ?? args.target, {
+              repos: args.repos,
+              symbol: args.symbol,
+              depth: args.depth == null ? undefined : Math.floor(args.depth),
+              direction: args.direction,
+              callGraph: args.callGraph,
+              includeTests: args.includeTests,
+              cwd: args.path,
+              style: args.style,
+              compress: args.compress,
+              lineNumbers: args.lineNumbers,
+              tree: args.tree,
+              instructions: args.instructions,
+              budget: args.budget == null ? TOOL_DEFAULT_BUDGET : Math.floor(args.budget),
+              targetModel: args.targetModel,
+            });
+            return {
+              content: [
+                { type: 'text', text: result.text },
+                { type: 'text', text: describeFocus(result) },
+              ],
+            };
+          }
           case 'check_policy': {
+            if (args.repos?.length > 0) {
+              const result = checkWorkspacePolicies(args.path, args.repos);
+              return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
             let result;
             try {
               result = { valid: true, ...loadPolicy(args.path).toJSON() };
@@ -743,6 +1383,18 @@ class MCPServer {
             const since = args.since === undefined ? null : parseSince(String(args.since));
             const limit =
               Number.isInteger(args.limit) && args.limit >= 0 ? args.limit : DEFAULT_AUDIT_LIMIT;
+            if (args.repos?.length > 0) {
+              const ws = readWorkspaceAuditLogs(args.path, args.repos, { since, limit });
+              const result = {
+                repos: ws.repos,
+                files: ws.files,
+                total: ws.total,
+                events: ws.events,
+                skippedLines: ws.skippedLines,
+              };
+              if (ws.policyErrors.length > 0) result.policyErrors = ws.policyErrors;
+              return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
+            }
             // Only the policy's own logs: a tool argument never names a file to read
             const { files, error } = auditLogFiles(args.path);
             const { events, skipped, missing } = readAuditLog(files);
@@ -758,11 +1410,173 @@ class MCPServer {
           }
           case 'ask_codebase': {
             const result = await askCodebase(args.path, args.query, {
+              repos: args.repos,
               limit: Number.isInteger(args.limit) ? args.limit : undefined,
               maxChars: ASK_SNIPPET_CHARS,
             });
             return { content: [{ type: 'text', text: JSON.stringify(result, null, 2) }] };
           }
+          case 'task_context': {
+            const result = await buildTaskContext(
+              args.path ?? args.dir ?? process.cwd(),
+              args.task ?? args.query ?? '',
+              {
+                repos: args.repos,
+                budget: args.budget == null ? DEFAULT_TASK_BUDGET : Math.floor(args.budget),
+                format: args.format,
+                model: args.model,
+                callGraph: args.callGraph,
+              }
+            );
+            return {
+              content: [
+                { type: 'text', text: result.text },
+                {
+                  type: 'text',
+                  text: `Task Context: ${result.files.length} file(s), ${result.totalTokens}/${result.budget} tokens (${result.format}).`,
+                },
+              ],
+            };
+          }
+          case 'diagnose_failure': {
+            const result = await diagnoseFailure(
+              args.path ?? args.dir ?? process.cwd(),
+              args.trace ?? args.log ?? '',
+              {
+                repos: args.repos,
+                budget: args.budget == null ? DEFAULT_DIAGNOSE_BUDGET : Math.floor(args.budget),
+                format: args.format,
+                callGraph: args.callGraph,
+              }
+            );
+            return {
+              content: [
+                { type: 'text', text: result.text },
+                {
+                  type: 'text',
+                  text: `Diagnosed: ${result.implicatedFiles.length} implicated file(s), ${result.totalTokens}/${result.budget} tokens.`,
+                },
+              ],
+            };
+          }
+          case 'find_experts': {
+            const result = await findExperts(
+              args.path ?? process.cwd(),
+              args.target ?? args.query ?? '',
+              {
+                repos: args.repos,
+                limit: Number.isInteger(args.limit) ? args.limit : undefined,
+                halfLifeDays: typeof args.halfLifeDays === 'number' ? args.halfLifeDays : undefined,
+                style: args.style || 'markdown',
+              }
+            );
+            return {
+              content: [{ type: 'text', text: result.text }],
+            };
+          }
+          case 'query_knowledge_graph': {
+            const projectPath = args.path ?? process.cwd();
+            const extraRepos = Array.isArray(args.repos) ? args.repos : [];
+            const scanner = new Scanner(projectPath);
+            scanner.getPolicy();
+            for (const repoPath of extraRepos) {
+              new Scanner(repoPath).getPolicy();
+            }
+
+            const inc = this.getIncrementalAnalyzer(projectPath, extraRepos);
+            await inc.ensureSyncReady(projectPath);
+            const store = inc.vectorStore;
+            const initialCounts = store.graphCounts();
+
+            let bootstrapped = false;
+            if (args.refresh === true || initialCounts.nodes === 0) {
+              await inc.bootstrapSync(projectPath, { repos: extraRepos });
+              bootstrapped = true;
+            }
+
+            const rawGraph = await inc.getGraph();
+            let nodes = rawGraph.nodes.filter((n) => !inc.isPathDenied(n.path));
+            let edges = rawGraph.edges.filter(
+              (e) => !inc.isPathDenied(e.from) && !inc.isPathDenied(e.to)
+            );
+
+            if (typeof args.file === 'string' && args.file.trim()) {
+              const targetFile = args.file.trim().replace(/\\/g, '/').replace(/^\.\//, '');
+              const maxDepth = Math.max(
+                1,
+                Math.min(4, Number.isFinite(args.depth) ? Math.floor(args.depth) : 1)
+              );
+              const visited = new Set([targetFile]);
+              let frontier = new Set([targetFile]);
+
+              for (let hop = 0; hop < maxDepth && frontier.size > 0; hop++) {
+                const nextFrontier = new Set();
+                for (const edge of edges) {
+                  if (frontier.has(edge.from) && !visited.has(edge.to)) {
+                    visited.add(edge.to);
+                    nextFrontier.add(edge.to);
+                  }
+                  if (frontier.has(edge.to) && !visited.has(edge.from)) {
+                    visited.add(edge.from);
+                    nextFrontier.add(edge.from);
+                  }
+                }
+                frontier = nextFrontier;
+              }
+
+              nodes = nodes.filter((n) => visited.has(n.path));
+              edges = edges.filter((e) => visited.has(e.from) && visited.has(e.to));
+            }
+
+            if (typeof args.query === 'string' && args.query.trim()) {
+              const needle = args.query.trim().toLowerCase();
+              nodes = nodes.filter((n) => {
+                if (n.path.toLowerCase().includes(needle)) return true;
+                if (Array.isArray(n.methods)) {
+                  return n.methods.some((m) => {
+                    const name = typeof m === 'string' ? m : m?.name || '';
+                    const sig = typeof m === 'object' ? m?.signature || '' : '';
+                    return (
+                      name.toLowerCase().includes(needle) || sig.toLowerCase().includes(needle)
+                    );
+                  });
+                }
+                return false;
+              });
+              const matchedPaths = new Set(nodes.map((n) => n.path));
+              edges = edges.filter((e) => matchedPaths.has(e.from) || matchedPaths.has(e.to));
+            }
+
+            const limit = Math.max(
+              1,
+              Math.min(
+                500,
+                Number.isFinite(args.limit) ? Math.floor(args.limit) : DEFAULT_GRAPH_LIMIT
+              )
+            );
+            const limitedNodes = nodes.slice(0, limit);
+            const keptPaths = new Set(limitedNodes.map((n) => n.path));
+            const matchingEdges = edges.filter((e) => keptPaths.has(e.from) || keptPaths.has(e.to));
+
+            const counts = store.graphCounts();
+            const payload = {
+              path: projectPath,
+              bootstrapped,
+              cached: inc.fileCache.size > 0 || inc.graphNodes.size > 0,
+              stats: {
+                totalNodes: counts.nodes,
+                totalEdges: counts.edges,
+                vectorDocuments: store.count(),
+                cachedFiles: inc.fileCache.size,
+              },
+              nodes: limitedNodes,
+              edges: matchingEdges,
+            };
+
+            return {
+              content: [{ type: 'text', text: JSON.stringify(payload, null, 2) }],
+            };
+          }
           default:
             throw new Error(`Unknown tool: ${name}`);
         }