docorbit 0.1.0

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

@@ -0,0 +1,59 @@
+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 function createDefaultTools(): Map<string, McpToolHandler> {
+  const tools = new Map<string, McpToolHandler>();
+  const list: McpToolHandler[] = [
+    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/packages/mcp/src/tools/list-sources.ts

@@ -0,0 +1,85 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class ListSourcesTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    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: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    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: string[] = [`### 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/packages/mcp/src/tools/search-docs.ts

@@ -0,0 +1,123 @@
+import { RetrievalEngine } from '../../../retrieval/src/index.ts';
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class SearchDocsTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    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: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    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: string[] = [
+      `### 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/packages/mcp/src/tools/types.ts

@@ -0,0 +1,28 @@
+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/packages/mcp/src/transports/http.ts

@@ -0,0 +1,256 @@
+import * as http from 'node:http';
+import type { McpServer } from '../server.ts';
+import type { McpTransport } from './types.ts';
+import { JSONRPC_ERRORS } from '../types.ts';
+
+export interface HttpTransportOptions {
+  port?: number;
+  host?: string;
+  maxBodyBytes?: number;
+  noListen?: boolean;
+}
+
+export class StreamableHttpTransport implements McpTransport {
+  private port: number;
+  private host: string;
+  private maxBodyBytes: number;
+  private noListen: boolean;
+  private serverInstance: http.Server | null = null;
+  private mcpServer: McpServer | null = null;
+  private sseClients: Set<http.ServerResponse> = new Set();
+  private heartbeatTimer: NodeJS.Timeout | null = null;
+
+  constructor(options: HttpTransportOptions = {}) {
+    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(): http.Server | null {
+    return this.serverInstance;
+  }
+
+  async dispatch(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    return this.handleHttpRequest(req, res);
+  }
+
+  getPort(): number {
+    if (this.serverInstance) {
+      const addr = this.serverInstance.address();
+      if (addr && typeof addr === 'object') {
+        return addr.port;
+      }
+    }
+    return this.port;
+  }
+
+  async start(server: McpServer): Promise<void> {
+    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();
+      });
+    });
+  }
+
+  private setCorsHeaders(res: http.ServerResponse): void {
+    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');
+  }
+
+  private async handleHttpRequest(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    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}` }));
+  }
+
+  private handleSseConnection(req: http.IncomingMessage, res: http.ServerResponse): void {
+    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);
+    });
+  }
+
+  private async handleMcpPost(req: http.IncomingMessage, res: http.ServerResponse): Promise<void> {
+    const rawBody = await this.readBody(req);
+    let parsed: unknown;
+    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: unknown;
+    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));
+  }
+
+  private readBody(req: http.IncomingMessage): Promise<string> {
+    return new Promise((resolve, reject) => {
+      const chunks: Buffer[] = [];
+      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);
+    });
+  }
+
+  private startHeartbeats(): void {
+    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(): Promise<void> {
+    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<void>((resolve) => {
+        this.serverInstance!.close(() => resolve());
+      });
+      this.serverInstance = null;
+    }
+  }
+}

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

@@ -0,0 +1,105 @@
+import * as readline from 'node:readline';
+import type { Readable, Writable } from 'node:stream';
+import type { McpServer } from '../server.ts';
+import type { McpTransport } from './types.ts';
+import { JSONRPC_ERRORS } from '../types.ts';
+
+export interface StdioTransportOptions {
+  input?: Readable;
+  output?: Writable;
+  errorOutput?: Writable;
+}
+
+export class StdioServerTransport implements McpTransport {
+  private input: Readable;
+  private output: Writable;
+  private errorOutput: Writable;
+  private rl: readline.Interface | null = null;
+  private server: McpServer | null = null;
+  private running: boolean = false;
+
+  constructor(options: StdioTransportOptions = {}) {
+    this.input = options.input || process.stdin;
+    this.output = options.output || process.stdout;
+    this.errorOutput = options.errorOutput || process.stderr;
+  }
+
+  async start(server: McpServer): Promise<void> {
+    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: string) => {
+      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.');
+    });
+  }
+
+  private async processLine(line: string): Promise<void> {
+    let parsed: unknown;
+    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);
+    }
+  }
+
+  private send(payload: unknown): void {
+    if (!this.running) return;
+    const serialized = JSON.stringify(payload) + '\n';
+    this.output.write(serialized);
+  }
+
+  private log(message: string): void {
+    // Isolated to stderr to never corrupt stdout JSON-RPC stream
+    this.errorOutput.write(`${message}\n`);
+  }
+
+  async close(): Promise<void> {
+    this.running = false;
+    if (this.rl) {
+      this.rl.close();
+      this.rl = null;
+    }
+  }
+}

package/packages/mcp/src/transports/types.ts

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