docorbit 0.1.0 → 0.1.2

package/dist/packages/mcp/src/tools/implementation-context.js

@@ -0,0 +1,102 @@
+import { IngestionPipeline } from "../../../core/src/index.js";
+export class ImplementationContextTool {
+    definition = {
+        name: 'get_implementation_context',
+        description: 'High-level documentation intelligence orchestrator. Automatically resolves workspace dependencies and versions, detects task intent, retrieves relevant chunks, APIs, verified examples, and pitfalls, and compiles an evidence-grounded recipe within a strict token budget.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                task: {
+                    type: 'string',
+                    description: 'The specific coding task or feature to implement (e.g. "Implement Stripe webhook signature verification in Express").',
+                },
+                url: {
+                    type: 'string',
+                    description: 'Optional documentation target URL. If provided and not yet indexed in DocOrbit, DocOrbit will automatically ingest and index it before compiling context.',
+                },
+                project: {
+                    type: 'string',
+                    description: 'Path to repository workspace root for project-aware dependency detection (default: current directory).',
+                },
+                library: {
+                    type: 'string',
+                    description: 'Optional primary library or package to focus documentation on (e.g. "stripe", "next").',
+                },
+                version: {
+                    type: 'string',
+                    description: 'Optional explicit target documentation version (e.g. "v14", "15.0").',
+                },
+                tokenBudget: {
+                    type: 'number',
+                    description: 'Maximum token budget for packed context (default: 4000).',
+                },
+            },
+            required: ['task'],
+        },
+    };
+    async execute(args, ctx) {
+        const task = typeof args.task === 'string' ? args.task.trim() : '';
+        if (!task) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: task' }) }],
+            };
+        }
+        const projectPath = typeof args.project === 'string'
+            ? args.project
+            : (ctx.workspaceRoot || '.');
+        const library = typeof args.library === 'string' ? args.library : undefined;
+        const version = typeof args.version === 'string' ? args.version : undefined;
+        const tokenBudget = typeof args.tokenBudget === 'number' && args.tokenBudget > 0
+            ? args.tokenBudget
+            : 4000;
+        const url = typeof args.url === 'string' ? args.url.trim() : undefined;
+        try {
+            if (url) {
+                const existing = ctx.repo.getSourceByUrl(url);
+                if (!existing) {
+                    try {
+                        const pipeline = new IngestionPipeline(ctx.repo, {
+                            crawlerConfig: { maxPages: 20 },
+                        });
+                        await pipeline.ingest(url);
+                    }
+                    catch {
+                        // Proceed gracefully with available context if crawling fails
+                    }
+                }
+            }
+            const result = await ctx.implService.getContext({
+                task,
+                projectPath,
+                library,
+                version,
+                tokenBudget,
+            });
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: result.markdown,
+                            data: result,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `Failed to compile implementation context: ${err instanceof Error ? err.message : String(err)}`,
+                        }),
+                    },
+                ],
+            };
+        }
+    }
+}

package/dist/packages/mcp/src/tools/index.d.ts

@@ -0,0 +1,19 @@
+import type { McpToolHandler } from './types.ts';
+import { SearchDocsTool } from './search-docs.ts';
+import { GetDocTool } from './get-doc.ts';
+import { FindApiTool } from './find-api.ts';
+import { FindExampleTool } from './find-example.ts';
+import { FindPitfallTool } from './find-pitfall.ts';
+import { FindRecipeTool } from './find-recipe.ts';
+import { GetVersionTool } from './get-version.ts';
+import { ListSourcesTool } from './list-sources.ts';
+import { ImplementationContextTool } from './implementation-context.ts';
+import { CheckApiTool } from './check-api.ts';
+import { DiffDocsTool } from './diff-docs.ts';
+import { AnalyzeImpactTool } from './analyze-impact.ts';
+import { GetDocumentationMapTool } from './get-docs-map.ts';
+import { ExportAgentContextTool } from './export-context.ts';
+import { IngestDocTool } from './ingest-doc.ts';
+export * from './types.ts';
+export { SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, ImplementationContextTool, ImplementationContextTool as GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, IngestDocTool, };
+export declare function createDefaultTools(): Map<string, McpToolHandler>;

package/dist/packages/mcp/src/tools/index.js

@@ -0,0 +1,41 @@
+import { SearchDocsTool } from "./search-docs.js";
+import { GetDocTool } from "./get-doc.js";
+import { FindApiTool } from "./find-api.js";
+import { FindExampleTool } from "./find-example.js";
+import { FindPitfallTool } from "./find-pitfall.js";
+import { FindRecipeTool } from "./find-recipe.js";
+import { GetVersionTool } from "./get-version.js";
+import { ListSourcesTool } from "./list-sources.js";
+import { ImplementationContextTool } from "./implementation-context.js";
+import { CheckApiTool } from "./check-api.js";
+import { DiffDocsTool } from "./diff-docs.js";
+import { AnalyzeImpactTool } from "./analyze-impact.js";
+import { GetDocumentationMapTool } from "./get-docs-map.js";
+import { ExportAgentContextTool } from "./export-context.js";
+import { IngestDocTool } from "./ingest-doc.js";
+export * from "./types.js";
+export { SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, ImplementationContextTool, ImplementationContextTool as GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, IngestDocTool, };
+export function createDefaultTools() {
+    const tools = new Map();
+    const list = [
+        new SearchDocsTool(),
+        new GetDocTool(),
+        new FindApiTool(),
+        new FindExampleTool(),
+        new FindPitfallTool(),
+        new FindRecipeTool(),
+        new GetVersionTool(),
+        new ListSourcesTool(),
+        new ImplementationContextTool(),
+        new CheckApiTool(),
+        new DiffDocsTool(),
+        new AnalyzeImpactTool(),
+        new GetDocumentationMapTool(),
+        new ExportAgentContextTool(),
+        new IngestDocTool(),
+    ];
+    for (const tool of list) {
+        tools.set(tool.definition.name, tool);
+    }
+    return tools;
+}

package/dist/packages/mcp/src/tools/ingest-doc.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class IngestDocTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/ingest-doc.js

@@ -0,0 +1,264 @@
+import { IngestionPipeline } from "../../../core/src/index.js";
+import { buildNormalizedPage, slicePageIntoChunks } from "../../../normalizer/src/index.js";
+export class IngestDocTool {
+    definition = {
+        name: 'ingest_doc',
+        description: 'Ingest, crawl, parse, and index authoritative documentation from any URL or raw content directly into DocOrbit. Extracts semantic chunks, OpenAPI endpoints, code examples, and pitfalls. If taskContext is provided, immediately synthesizes and returns an evidence-grounded implementation recipe with exact code and API details.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                url: {
+                    type: 'string',
+                    description: 'Documentation target URL to crawl and ingest (e.g. "https://nextjs.org/docs" or "https://support.atlassian.com/...").',
+                },
+                taskContext: {
+                    type: 'string',
+                    description: 'Optional coding task or intent (e.g. "Connect Atlassian Remote MCP" or "Implement Stripe payment element"). If provided, DocOrbit compiles and returns an immediate implementation recipe using the newly ingested docs.',
+                },
+                maxPages: {
+                    type: 'number',
+                    description: 'Maximum number of pages to crawl (default: 20, max: 50).',
+                },
+                content: {
+                    type: 'string',
+                    description: 'Optional raw markdown/HTML documentation content to index directly without fetching from the web.',
+                },
+                title: {
+                    type: 'string',
+                    description: 'Optional title when ingesting raw content or overriding page title.',
+                },
+                allowLocalhost: {
+                    type: 'boolean',
+                    description: 'Allow crawling localhost endpoints for testing (default: false).',
+                },
+            },
+        },
+    };
+    async execute(args, ctx) {
+        const rawUrl = typeof args.url === 'string' ? args.url.trim() : '';
+        const rawContent = typeof args.content === 'string' ? args.content.trim() : '';
+        const title = typeof args.title === 'string' ? args.title.trim() : undefined;
+        const taskContext = typeof args.taskContext === 'string' ? args.taskContext.trim() : undefined;
+        const allowLocalhost = Boolean(args.allowLocalhost);
+        const maxPages = typeof args.maxPages === 'number' && args.maxPages > 0
+            ? Math.min(args.maxPages, 50)
+            : 20;
+        if (!rawUrl && !rawContent) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: 'Missing required parameter: provide either "url" to crawl documentation from the web or "content" to index raw documentation.',
+                        }),
+                    },
+                ],
+            };
+        }
+        try {
+            let targetUrl = rawUrl;
+            let snapshotId = '';
+            let pagesCount = 0;
+            let chunksCount = 0;
+            let codeExamplesCount = 0;
+            let estimatedTokens = 0;
+            let durationMs = 0;
+            const pagesSummary = [];
+            if (rawContent) {
+                const startTime = Date.now();
+                targetUrl = rawUrl || 'local://direct-content';
+                const sourceId = ctx.repo.saveSource({
+                    url: targetUrl,
+                    type: 'web',
+                    discoveredBy: 'direct',
+                    status: 'valid',
+                    confidence: 1.0,
+                    authority: 'official',
+                    machineReadable: false,
+                });
+                snapshotId = ctx.repo.createSnapshot(sourceId, {
+                    targetUrl,
+                    pageCount: 1,
+                    ingestedAt: new Date().toISOString(),
+                });
+                const page = buildNormalizedPage({
+                    sourceId,
+                    url: targetUrl,
+                    rawContent,
+                    contentType: 'text/markdown',
+                    sourceUrl: targetUrl,
+                    targetUrl,
+                    title: title || 'Direct Content Ingestion',
+                    discoveredBy: 'direct',
+                    fetchedAt: new Date().toISOString(),
+                });
+                ctx.repo.savePage(page);
+                const slicing = slicePageIntoChunks(page, snapshotId);
+                ctx.repo.saveChunks(slicing.chunks, slicing.relationships, slicing.codeSnippets, slicing.symbols);
+                pagesCount = 1;
+                chunksCount = slicing.chunks.length;
+                codeExamplesCount = page.codeExamples.length;
+                estimatedTokens = page.estimatedTokens;
+                durationMs = Date.now() - startTime;
+                pagesSummary.push({
+                    title: page.title,
+                    url: page.url,
+                    tokens: page.estimatedTokens,
+                    codeBlocks: page.codeExamples.length,
+                });
+            }
+            else {
+                const pipeline = new IngestionPipeline(ctx.repo, {
+                    allowLocalhostForTesting: allowLocalhost,
+                    crawlerConfig: {
+                        maxPages,
+                    },
+                });
+                const result = await pipeline.ingest(rawUrl);
+                targetUrl = result.targetUrl;
+                snapshotId = result.snapshotId;
+                pagesCount = result.stats.totalPages;
+                chunksCount = result.stats.totalChunks;
+                codeExamplesCount = result.stats.totalCodeExamples;
+                estimatedTokens = result.stats.totalEstimatedTokens;
+                durationMs = result.durationMs;
+                for (const p of result.pages) {
+                    pagesSummary.push({
+                        title: p.title,
+                        url: p.url,
+                        tokens: p.estimatedTokens,
+                        codeBlocks: p.codeExamples.length,
+                    });
+                }
+            }
+            // If user provided a specific task context, compile an immediate implementation context recipe!
+            if (taskContext) {
+                const implResult = await ctx.implService.getContext({
+                    task: taskContext,
+                    projectPath: ctx.projectDir || ctx.workspaceRoot,
+                    tokenBudget: 4000,
+                });
+                const lines = [
+                    `# 🛰️ DocOrbit: Ingested & Context Compiled`,
+                    `> [!NOTE]`,
+                    `> Successfully ingested **${targetUrl}** and compiled implementation context for: *"${taskContext}"*`,
+                    ``,
+                    `### Ingestion Metrics`,
+                    `- **Pages Ingested**: ${pagesCount}`,
+                    `- **Chunks Indexed**: ${chunksCount}`,
+                    `- **Code Examples Extracted**: ${codeExamplesCount}`,
+                    `- **Estimated Tokens**: ~${estimatedTokens}`,
+                    `- **Snapshot ID**: \`${snapshotId}\` (${durationMs}ms)`,
+                    ``,
+                    `---`,
+                    ``,
+                    implResult.markdown,
+                ];
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                markdown: lines.join('\n'),
+                                data: {
+                                    targetUrl,
+                                    snapshotId,
+                                    taskContext,
+                                    stats: {
+                                        pagesCount,
+                                        chunksCount,
+                                        codeExamplesCount,
+                                        estimatedTokens,
+                                        durationMs,
+                                    },
+                                    implementationContext: implResult,
+                                },
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            // Query any extracted APIs, examples, and pitfalls from the new documentation
+            const apiEndpoints = ctx.repo.searchApiEndpoints(targetUrl, { limit: 5 });
+            const codeExamples = ctx.repo.searchIndexedExamples(targetUrl, { limit: 3 });
+            const pitfalls = ctx.repo.searchPitfalls(targetUrl, { limit: 4 });
+            const lines = [
+                `# 🛰️ DocOrbit: Documentation Ingested Successfully`,
+                `> **Target**: \`${targetUrl}\` | **Snapshot**: \`${snapshotId}\` | **Duration**: ${durationMs}ms`,
+                ``,
+                `### Ingestion Statistics`,
+                `- **Pages Ingested**: ${pagesCount}`,
+                `- **Chunks Indexed**: ${chunksCount}`,
+                `- **Code Examples Indexed**: ${codeExamplesCount}`,
+                `- **Total Estimated Tokens**: ~${estimatedTokens}`,
+                ``,
+                `### Ingested Pages Directory`,
+            ];
+            for (let i = 0; i < pagesSummary.length; i++) {
+                const p = pagesSummary[i];
+                lines.push(`${i + 1}. **${p.title}** - \`${p.url}\` (~${p.tokens} tokens, ${p.codeBlocks} code snippets)`);
+            }
+            if (apiEndpoints.length > 0) {
+                lines.push(``, `### Discovered API Endpoints`);
+                for (const ep of apiEndpoints) {
+                    lines.push(`- **\`${ep.method.toUpperCase()} ${ep.path}\`**: ${ep.summary || ep.description || 'No description'}`);
+                }
+            }
+            if (codeExamples.length > 0) {
+                lines.push(``, `### Extracted Code Patterns`);
+                for (const ex of codeExamples) {
+                    lines.push(`#### ${ex.task} (${ex.language}${ex.framework ? `, ${ex.framework}` : ''})`);
+                    lines.push('```' + ex.language);
+                    lines.push(ex.code);
+                    lines.push('```\n');
+                }
+            }
+            if (pitfalls.length > 0) {
+                lines.push(``, `### Pitfalls & Deprecation Notices`);
+                for (const pf of pitfalls) {
+                    lines.push(`- ⚠️ **[${pf.kind.toUpperCase()}] ${pf.title}**: ${pf.content}`);
+                }
+            }
+            lines.push(``, `### Recommended Agent Loop Actions`, `- **Compile Recipe**: Call \`get_implementation_context(task: "...")\` to assemble a grounded blueprint with ordered steps and validation criteria.`, `- **Inspect Endpoints**: Call \`find_api(query: "...")\` for parameters, auth, schemas, and error responses.`, `- **Code Examples**: Call \`find_example(task: "...")\` for targeted snippets matching your framework.`, `- **Check Constraints**: Call \`find_pitfall(query: "...")\` to avoid deprecations or runtime traps.`);
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: lines.join('\n'),
+                            data: {
+                                targetUrl,
+                                snapshotId,
+                                stats: {
+                                    pagesCount,
+                                    chunksCount,
+                                    codeExamplesCount,
+                                    estimatedTokens,
+                                    durationMs,
+                                },
+                                pages: pagesSummary,
+                                apiEndpoints,
+                                codeExamples,
+                                pitfalls,
+                            },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            return {
+                isError: true,
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            error: `DocOrbit Ingestion Failed: ${err instanceof Error ? err.message : String(err)}`,
+                        }),
+                    },
+                ],
+            };
+        }
+    }
+}

package/dist/packages/mcp/src/tools/list-sources.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class ListSourcesTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/list-sources.js

@@ -0,0 +1,76 @@
+export class ListSourcesTool {
+    definition = {
+        name: 'list_sources',
+        description: 'List all indexed documentation sources, snapshot records, doc versions, and machine-readability status.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of sources to list (default: 50).',
+                },
+            },
+        },
+    };
+    async execute(args, ctx) {
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 50;
+        const sources = ctx.repo.listSources().slice(0, limit);
+        const snapshots = ctx.repo.listSnapshots();
+        if (sources.length === 0) {
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: '### Indexed Documentation Sources\n\nNo documentation sources have been added yet. Use `docorbit add <url>` to ingest documentation.',
+                            data: { count: 0, sources: [] },
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const formatted = sources.map(s => {
+            const sourceSnaps = snapshots.filter(sn => sn.sourceId === s.id);
+            return {
+                id: s.id,
+                url: s.url,
+                type: s.type,
+                status: s.status,
+                authority: s.authority,
+                confidence: s.confidence,
+                machineReadable: s.machineReadable,
+                snapshots: sourceSnaps.map(sn => ({
+                    id: sn.id,
+                    pageCount: sn.pageCount,
+                    docVersion: sn.docVersion,
+                    capturedAt: sn.capturedAt,
+                })),
+            };
+        });
+        const lines = [`### Indexed Documentation Sources (${sources.length} sources)\n`];
+        for (const s of formatted) {
+            const icon = s.status === 'valid' ? '✓' : '✗';
+            lines.push(`- **${icon} [${s.type}]** ${s.url}`);
+            lines.push(`  *Authority*: ${s.authority} | *Confidence*: ${Math.round(s.confidence * 100)}% | *Machine-Readable*: ${s.machineReadable}`);
+            if (s.snapshots.length > 0) {
+                const snapInfo = s.snapshots.map(sn => `${sn.id}${sn.docVersion ? ` (${sn.docVersion})` : ''} [${sn.pageCount} pages]`).join(', ');
+                lines.push(`  *Snapshots*: ${snapInfo}`);
+            }
+            lines.push('');
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        markdown: lines.join('\n'),
+                        data: {
+                            count: formatted.length,
+                            sources: formatted,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/dist/packages/mcp/src/tools/search-docs.d.ts

@@ -0,0 +1,6 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+export declare class SearchDocsTool implements McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/search-docs.js

@@ -0,0 +1,113 @@
+import { RetrievalEngine } from "../../../retrieval/src/index.js";
+export class SearchDocsTool {
+    definition = {
+        name: 'search_docs',
+        description: 'Search documentation chunks using hybrid FTS5 ranking, symbol awareness, and optional version filtering.',
+        inputSchema: {
+            type: 'object',
+            properties: {
+                query: {
+                    type: 'string',
+                    description: 'The search query, code symbol, or concept to look for.',
+                },
+                library: {
+                    type: 'string',
+                    description: 'Optional library name to narrow search scope.',
+                },
+                version: {
+                    type: 'string',
+                    description: 'Target documentation version (e.g. "v14", "15.0").',
+                },
+                limit: {
+                    type: 'number',
+                    description: 'Maximum number of results to return (default: 10).',
+                },
+            },
+            required: ['query'],
+        },
+    };
+    async execute(args, ctx) {
+        const query = typeof args.query === 'string' ? args.query.trim() : '';
+        if (!query) {
+            return {
+                isError: true,
+                content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: query' }) }],
+            };
+        }
+        const version = typeof args.docVersion === 'string'
+            ? args.docVersion
+            : (typeof args.version === 'string' ? args.version : undefined);
+        const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 10;
+        const engine = new RetrievalEngine(ctx.repo);
+        const results = await engine.search(query, {
+            docVersion: version,
+            limit,
+            projectDir: ctx.workspaceRoot,
+        });
+        if (results.length === 0) {
+            const emptyPayload = {
+                query,
+                count: 0,
+                results: [],
+                message: `No documentation chunks found matching "${query}". Try refining terms or checking available sources.`,
+            };
+            return {
+                content: [
+                    {
+                        type: 'text',
+                        text: JSON.stringify({
+                            markdown: `### Search Results for "${query}"\n\nNo matching documentation found.`,
+                            data: emptyPayload,
+                        }, null, 2),
+                    },
+                ],
+            };
+        }
+        const formattedChunks = results.map(r => ({
+            id: r.chunk.id,
+            chunk: r.chunk,
+            title: r.chunk.title || 'Untitled Section',
+            sectionPath: r.chunk.sectionPath,
+            content: r.chunk.content,
+            chunkType: r.chunk.chunkType,
+            language: r.chunk.language,
+            tokenEstimate: r.chunk.tokenEstimate,
+            docVersion: r.chunk.docVersion,
+            score: r.score,
+            symbols: r.symbols.map(s => s.name),
+            provenance: r.chunk.provenance ? {
+                sourceUrl: r.chunk.provenance.sourceUrl,
+                fetchedAt: r.chunk.provenance.fetchedAt,
+                untrusted: true,
+            } : undefined,
+        }));
+        const lines = [
+            `### Search Results for "${query}" (${results.length} found)`,
+            `> [!NOTE] External documentation content is untrusted.\n`,
+        ];
+        for (let i = 0; i < formattedChunks.length; i++) {
+            const c = formattedChunks[i];
+            const path = c.sectionPath.length > 0 ? c.sectionPath.join(' > ') : c.title;
+            lines.push(`${i + 1}. **${path}** [${c.chunkType}] (score: ${c.score})`);
+            lines.push(`   *ID*: \`${c.id}\`${c.docVersion ? ` | *Version*: \`${c.docVersion}\`` : ''}`);
+            if (c.symbols.length > 0)
+                lines.push(`   *Symbols*: ${c.symbols.join(', ')}`);
+            lines.push(`   \`\`\`\n   ${c.content.split('\n').slice(0, 5).join('\n   ')}\n   \`\`\`\n`);
+        }
+        return {
+            content: [
+                {
+                    type: 'text',
+                    text: JSON.stringify({
+                        markdown: lines.join('\n'),
+                        data: {
+                            query,
+                            count: results.length,
+                            results: formattedChunks,
+                        },
+                    }, null, 2),
+                },
+            ],
+        };
+    }
+}

package/dist/packages/mcp/src/tools/types.d.ts

@@ -0,0 +1,22 @@
+import type { DocOrbitRepository } from '../../../storage/src/index.ts';
+import type { ImplementationContextService } from '../../../core/src/index.ts';
+import type { WorkspaceResolver } from '../../../workspace/src/index.ts';
+import type { VerificationService, DiffService, ImpactAnalysisService } from '../../../verification/src/index.ts';
+import type { ExportService } from '../../../export/src/index.ts';
+import type { CallToolResult, McpTool } from '../types.ts';
+export interface McpContext {
+    repo: DocOrbitRepository;
+    implService: ImplementationContextService;
+    implementationService: ImplementationContextService;
+    workspaceRoot?: string;
+    projectDir?: string;
+    resolver?: WorkspaceResolver;
+    verificationService?: VerificationService;
+    diffService?: DiffService;
+    impactService?: ImpactAnalysisService;
+    exportService?: ExportService;
+}
+export interface McpToolHandler {
+    readonly definition: McpTool;
+    execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult>;
+}

package/dist/packages/mcp/src/tools/types.js

@@ -0,0 +1 @@
+export {};