docorbit 0.1.0 → 0.1.1

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

@@ -0,0 +1,18 @@
+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';
+export * from './types.ts';
+export { SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, ImplementationContextTool, ImplementationContextTool as GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, };
+export declare function createDefaultTools(): Map<string, McpToolHandler>;

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

@@ -0,0 +1,39 @@
+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";
+export * from "./types.js";
+export { SearchDocsTool, GetDocTool, FindApiTool, FindExampleTool, FindPitfallTool, FindRecipeTool, GetVersionTool, ListSourcesTool, ImplementationContextTool, ImplementationContextTool as GetImplementationContextTool, CheckApiTool, DiffDocsTool, AnalyzeImpactTool, GetDocumentationMapTool, ExportAgentContextTool, };
+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(),
+    ];
+    for (const tool of list) {
+        tools.set(tool.definition.name, tool);
+    }
+    return tools;
+}

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 {};

package/dist/packages/mcp/src/transports/http.d.ts

@@ -0,0 +1,31 @@
+import * as http from 'node:http';
+import type { McpServer } from '../server.ts';
+import type { McpTransport } from './types.ts';
+export interface HttpTransportOptions {
+    port?: number;
+    host?: string;
+    maxBodyBytes?: number;
+    noListen?: boolean;
+}
+export declare class StreamableHttpTransport implements McpTransport {
+    private port;
+    private host;
+    private maxBodyBytes;
+    private noListen;
+    private serverInstance;
+    private mcpServer;
+    private sseClients;
+    private heartbeatTimer;
+    constructor(options?: HttpTransportOptions);
+    getServerInstance(): http.Server | null;
+    dispatch(req: http.IncomingMessage, res: http.ServerResponse): Promise<void>;
+    getPort(): number;
+    start(server: McpServer): Promise<void>;
+    private setCorsHeaders;
+    private handleHttpRequest;
+    private handleSseConnection;
+    private handleMcpPost;
+    private readBody;
+    private startHeartbeats;
+    close(): Promise<void>;
+}

package/dist/packages/mcp/src/transports/http.js

@@ -0,0 +1,215 @@
+import * as http from 'node:http';
+import { JSONRPC_ERRORS } from "../types.js";
+export class StreamableHttpTransport {
+    port;
+    host;
+    maxBodyBytes;
+    noListen;
+    serverInstance = null;
+    mcpServer = null;
+    sseClients = new Set();
+    heartbeatTimer = null;
+    constructor(options = {}) {
+        this.port = options.port ?? 3000;
+        this.host = options.host ?? '127.0.0.1';
+        this.maxBodyBytes = options.maxBodyBytes ?? 10 * 1024 * 1024; // 10MB
+        this.noListen = options.noListen ?? false;
+    }
+    getServerInstance() {
+        return this.serverInstance;
+    }
+    async dispatch(req, res) {
+        return this.handleHttpRequest(req, res);
+    }
+    getPort() {
+        if (this.serverInstance) {
+            const addr = this.serverInstance.address();
+            if (addr && typeof addr === 'object') {
+                return addr.port;
+            }
+        }
+        return this.port;
+    }
+    async start(server) {
+        this.mcpServer = server;
+        this.serverInstance = http.createServer((req, res) => {
+            this.handleHttpRequest(req, res).catch(err => {
+                if (!res.headersSent) {
+                    res.writeHead(500, { 'Content-Type': 'application/json' });
+                    res.end(JSON.stringify({ error: err instanceof Error ? err.message : String(err) }));
+                }
+            });
+        });
+        if (this.noListen) {
+            return;
+        }
+        return new Promise((resolve, reject) => {
+            this.serverInstance.on('error', reject);
+            this.serverInstance.listen(this.port, this.host, () => {
+                this.startHeartbeats();
+                resolve();
+            });
+        });
+    }
+    setCorsHeaders(res) {
+        res.setHeader('Access-Control-Allow-Origin', '*');
+        res.setHeader('Access-Control-Allow-Methods', 'GET, POST, OPTIONS');
+        res.setHeader('Access-Control-Allow-Headers', 'Content-Type, Authorization, Accept');
+    }
+    async handleHttpRequest(req, res) {
+        this.setCorsHeaders(res);
+        if (req.method === 'OPTIONS') {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        const url = new URL(req.url || '/', `http://${this.host}:${this.port}`);
+        const pathname = url.pathname;
+        if (req.method === 'GET' && (pathname === '/health' || pathname === '/')) {
+            res.writeHead(200, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                status: 'ok',
+                server: 'docorbit-mcp',
+                version: '0.5.0',
+                endpoints: {
+                    mcp: '/mcp',
+                    sse: '/sse',
+                    health: '/health',
+                },
+            }));
+            return;
+        }
+        if (req.method === 'GET' && pathname === '/sse') {
+            this.handleSseConnection(req, res);
+            return;
+        }
+        if (req.method === 'POST' && pathname === '/mcp') {
+            await this.handleMcpPost(req, res);
+            return;
+        }
+        res.writeHead(404, { 'Content-Type': 'application/json' });
+        res.end(JSON.stringify({ error: `Not found: ${req.method} ${pathname}` }));
+    }
+    handleSseConnection(req, res) {
+        res.writeHead(200, {
+            'Content-Type': 'text/event-stream',
+            'Cache-Control': 'no-cache',
+            'Connection': 'keep-alive',
+        });
+        // Send endpoint notification so client knows where to POST messages
+        res.write('event: endpoint\ndata: /mcp\n\n');
+        this.sseClients.add(res);
+        req.on('close', () => {
+            this.sseClients.delete(res);
+        });
+    }
+    async handleMcpPost(req, res) {
+        const rawBody = await this.readBody(req);
+        let parsed;
+        try {
+            parsed = JSON.parse(rawBody);
+        }
+        catch {
+            res.writeHead(400, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: JSONRPC_ERRORS.PARSE_ERROR,
+                    message: 'Parse error: invalid JSON payload.',
+                },
+            }));
+            return;
+        }
+        if (!this.mcpServer) {
+            res.writeHead(503, { 'Content-Type': 'application/json' });
+            res.end(JSON.stringify({ error: 'Server not initialized' }));
+            return;
+        }
+        let responsePayload;
+        if (Array.isArray(parsed)) {
+            const responses = await Promise.all(parsed.map(item => this.mcpServer.handleMessage(item)));
+            responsePayload = responses.filter(r => r !== null);
+        }
+        else {
+            responsePayload = await this.mcpServer.handleMessage(parsed);
+        }
+        const acceptHeader = req.headers['accept'] || '';
+        const wantsSse = acceptHeader.includes('text/event-stream');
+        if (wantsSse) {
+            // Modern Streamable HTTP response over SSE chunk
+            res.writeHead(200, {
+                'Content-Type': 'text/event-stream',
+                'Cache-Control': 'no-cache',
+                'Connection': 'keep-alive',
+            });
+            if (responsePayload !== null && responsePayload !== undefined) {
+                res.write(`event: message\ndata: ${JSON.stringify(responsePayload)}\n\n`);
+            }
+            res.end();
+            return;
+        }
+        // Standard JSON response
+        if (responsePayload === null || responsePayload === undefined) {
+            res.writeHead(204);
+            res.end();
+            return;
+        }
+        res.writeHead(200, { 'Content-Type': 'application/json; charset=utf-8' });
+        res.end(JSON.stringify(responsePayload));
+    }
+    readBody(req) {
+        return new Promise((resolve, reject) => {
+            const chunks = [];
+            let totalLength = 0;
+            req.on('data', chunk => {
+                const buf = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+                totalLength += buf.length;
+                if (totalLength > this.maxBodyBytes) {
+                    req.destroy(new Error(`Payload exceeds maximum limit of ${this.maxBodyBytes} bytes`));
+                    return;
+                }
+                chunks.push(buf);
+            });
+            req.on('end', () => {
+                resolve(Buffer.concat(chunks).toString('utf-8'));
+            });
+            req.on('error', reject);
+        });
+    }
+    startHeartbeats() {
+        if (this.heartbeatTimer)
+            clearInterval(this.heartbeatTimer);
+        this.heartbeatTimer = setInterval(() => {
+            for (const client of this.sseClients) {
+                try {
+                    client.write(': ping\n\n');
+                }
+                catch {
+                    this.sseClients.delete(client);
+                }
+            }
+        }, 15000);
+    }
+    async close() {
+        if (this.heartbeatTimer) {
+            clearInterval(this.heartbeatTimer);
+            this.heartbeatTimer = null;
+        }
+        for (const client of this.sseClients) {
+            try {
+                client.end();
+            }
+            catch {
+                // Continue
+            }
+        }
+        this.sseClients.clear();
+        if (this.serverInstance) {
+            await new Promise((resolve) => {
+                this.serverInstance.close(() => resolve());
+            });
+            this.serverInstance = null;
+        }
+    }
+}

package/dist/packages/mcp/src/transports/stdio.d.ts

@@ -0,0 +1,22 @@
+import type { Readable, Writable } from 'node:stream';
+import type { McpServer } from '../server.ts';
+import type { McpTransport } from './types.ts';
+export interface StdioTransportOptions {
+    input?: Readable;
+    output?: Writable;
+    errorOutput?: Writable;
+}
+export declare class StdioServerTransport implements McpTransport {
+    private input;
+    private output;
+    private errorOutput;
+    private rl;
+    private server;
+    private running;
+    constructor(options?: StdioTransportOptions);
+    start(server: McpServer): Promise<void>;
+    private processLine;
+    private send;
+    private log;
+    close(): Promise<void>;
+}

package/dist/packages/mcp/src/transports/stdio.js

@@ -0,0 +1,86 @@
+import * as readline from 'node:readline';
+import { JSONRPC_ERRORS } from "../types.js";
+export class StdioServerTransport {
+    input;
+    output;
+    errorOutput;
+    rl = null;
+    server = null;
+    running = false;
+    constructor(options = {}) {
+        this.input = options.input || process.stdin;
+        this.output = options.output || process.stdout;
+        this.errorOutput = options.errorOutput || process.stderr;
+    }
+    async start(server) {
+        this.server = server;
+        this.running = true;
+        this.rl = readline.createInterface({
+            input: this.input,
+            terminal: false,
+        });
+        this.log('[DocOrbit MCP] Stdio transport started.');
+        this.rl.on('line', async (line) => {
+            try {
+                await this.processLine(line);
+            }
+            catch (err) {
+                this.log(`[DocOrbit MCP] Stdio error processing line: ${err instanceof Error ? err.message : String(err)}`);
+            }
+        });
+        this.rl.on('close', () => {
+            this.running = false;
+            this.log('[DocOrbit MCP] Stdio transport stream closed.');
+        });
+    }
+    async processLine(line) {
+        let parsed;
+        try {
+            parsed = JSON.parse(line);
+        }
+        catch {
+            const parseError = {
+                jsonrpc: '2.0',
+                id: null,
+                error: {
+                    code: JSONRPC_ERRORS.PARSE_ERROR,
+                    message: 'Parse error: invalid JSON payload.',
+                },
+            };
+            this.send(parseError);
+            return;
+        }
+        if (!this.server)
+            return;
+        if (Array.isArray(parsed)) {
+            // JSON-RPC Batch
+            const responses = await Promise.all(parsed.map(item => this.server.handleMessage(item)));
+            const filtered = responses.filter(r => r !== null);
+            if (filtered.length > 0) {
+                this.send(filtered);
+            }
+            return;
+        }
+        const response = await this.server.handleMessage(parsed);
+        if (response !== null) {
+            this.send(response);
+        }
+    }
+    send(payload) {
+        if (!this.running)
+            return;
+        const serialized = JSON.stringify(payload) + '\n';
+        this.output.write(serialized);
+    }
+    log(message) {
+        // Isolated to stderr to never corrupt stdout JSON-RPC stream
+        this.errorOutput.write(`${message}\n`);
+    }
+    async close() {
+        this.running = false;
+        if (this.rl) {
+            this.rl.close();
+            this.rl = null;
+        }
+    }
+}

package/{packages/mcp/src/transports/types.ts → dist/packages/mcp/src/transports/types.d.ts}

@@ -1,6 +1,5 @@
 import type { McpServer } from '../server.ts';
-
 export interface McpTransport {
-  start(server: McpServer): Promise<void>;
-  close(): Promise<void>;
+    start(server: McpServer): Promise<void>;
+    close(): Promise<void>;
 }

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

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