docorbit 0.1.0

package/packages/mcp/src/server.ts

@@ -0,0 +1,278 @@
+import type { DocOrbitRepository } from '../../storage/src/index.ts';
+import type { WorkspaceResolver } from '../../workspace/src/index.ts';
+import { ImplementationContextService } from '../../core/src/index.ts';
+import {
+  VerificationService,
+  DiffService,
+  ImpactAnalysisService,
+} from '../../verification/src/index.ts';
+import { ExportService } from '../../export/src/index.ts';
+import type {
+  JsonRpcRequest,
+  JsonRpcResponse,
+  McpTool,
+  InitializeResult,
+} from './types.ts';
+import { JSONRPC_ERRORS } from './types.ts';
+import type { McpContext, McpToolHandler } from './tools/types.ts';
+import { createDefaultTools } from './tools/index.ts';
+import { McpResourceManager } from './resources/index.ts';
+
+export interface McpServerOptions {
+  repo: DocOrbitRepository;
+  resolver?: WorkspaceResolver;
+  projectDir?: string;
+  serverName?: string;
+  serverVersion?: string;
+  tools?: Map<string, McpToolHandler>;
+  maxResourceBytes?: number;
+}
+
+export class McpServer {
+  private repo: DocOrbitRepository;
+  private resolver?: WorkspaceResolver;
+  private projectDir?: string;
+  private serverName: string;
+  private serverVersion: string;
+  private tools: Map<string, McpToolHandler>;
+  private resourceManager: McpResourceManager;
+  private context: McpContext;
+  private initialized: boolean = false;
+
+  constructor(options: McpServerOptions) {
+    this.repo = options.repo;
+    this.resolver = options.resolver;
+    this.projectDir = options.projectDir;
+    this.serverName = options.serverName || 'docorbit-mcp';
+    this.serverVersion = options.serverVersion || '0.5.0';
+
+    this.tools = options.tools || createDefaultTools();
+    this.resourceManager = new McpResourceManager(this.repo, {
+      maxResourceBytes: options.maxResourceBytes,
+    });
+
+    const implService = new ImplementationContextService(this.repo, this.resolver);
+    const verificationService = new VerificationService(this.repo);
+    const diffService = new DiffService(this.repo);
+    const impactService = new ImpactAnalysisService(this.repo);
+    const exportService = new ExportService(this.repo);
+
+    this.context = {
+      repo: this.repo,
+      resolver: this.resolver,
+      projectDir: this.projectDir,
+      workspaceRoot: this.projectDir,
+      implService,
+      implementationService: implService,
+      verificationService,
+      diffService,
+      impactService,
+      exportService,
+    };
+  }
+
+  getContext(): McpContext {
+    return this.context;
+  }
+
+  getResourceManager(): McpResourceManager {
+    return this.resourceManager;
+  }
+
+  getTools(): McpTool[] {
+    return Array.from(this.tools.values()).map(h => h.definition);
+  }
+
+  async handleMessage(raw: unknown): Promise<JsonRpcResponse | null> {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+      return {
+        jsonrpc: '2.0',
+        id: null,
+        error: {
+          code: JSONRPC_ERRORS.INVALID_REQUEST,
+          message: 'Invalid JSON-RPC request: payload must be an object.',
+        },
+      };
+    }
+
+    const msg = raw as Record<string, unknown>;
+    const id = (msg.id !== undefined ? (msg.id as string | number | null) : undefined);
+    const isNotification = id === undefined;
+
+    if (msg.jsonrpc !== '2.0' || typeof msg.method !== 'string') {
+      if (isNotification) return null;
+      return {
+        jsonrpc: '2.0',
+        id: id ?? null,
+        error: {
+          code: JSONRPC_ERRORS.INVALID_REQUEST,
+          message: 'Invalid JSON-RPC 2.0 request structure: missing "jsonrpc: 2.0" or "method".',
+        },
+      };
+    }
+
+    const method = msg.method;
+    const params = (msg.params && typeof msg.params === 'object' && !Array.isArray(msg.params))
+      ? (msg.params as Record<string, unknown>)
+      : {};
+
+    try {
+      switch (method) {
+        case 'initialize': {
+          this.initialized = true;
+          const result: InitializeResult = {
+            protocolVersion: '2024-11-05',
+            serverInfo: {
+              name: this.serverName,
+              version: this.serverVersion,
+            },
+            capabilities: {
+              tools: {
+                listChanged: false,
+              },
+              resources: {
+                subscribe: false,
+                listChanged: false,
+              },
+              logging: {},
+            },
+          };
+          return { jsonrpc: '2.0', id: id ?? null, result };
+        }
+
+        case 'notifications/initialized': {
+          this.initialized = true;
+          return null; // Notifications have no response
+        }
+
+        case 'ping': {
+          if (isNotification) return null;
+          return { jsonrpc: '2.0', id: id ?? null, result: {} };
+        }
+
+        case 'tools/list': {
+          if (isNotification) return null;
+          return {
+            jsonrpc: '2.0',
+            id: id ?? null,
+            result: {
+              tools: this.getTools(),
+            },
+          };
+        }
+
+        case 'tools/call': {
+          if (isNotification) return null;
+          const toolName = typeof params.name === 'string' ? params.name : '';
+          const toolArgs = (params.arguments && typeof params.arguments === 'object' && !Array.isArray(params.arguments))
+            ? (params.arguments as Record<string, unknown>)
+            : {};
+
+          const handler = this.tools.get(toolName);
+          if (!handler) {
+            return {
+              jsonrpc: '2.0',
+              id: id ?? null,
+              error: {
+                code: JSONRPC_ERRORS.METHOD_NOT_FOUND,
+                message: `Tool not found: "${toolName}". Available tools: ${Array.from(this.tools.keys()).join(', ')}`,
+              },
+            };
+          }
+
+          try {
+            const toolResult = await handler.execute(toolArgs, this.context);
+            return {
+              jsonrpc: '2.0',
+              id: id ?? null,
+              result: toolResult,
+            };
+          } catch (toolErr) {
+            const message = toolErr instanceof Error ? toolErr.message : String(toolErr);
+            return {
+              jsonrpc: '2.0',
+              id: id ?? null,
+              result: {
+                isError: true,
+                content: [
+                  {
+                    type: 'text',
+                    text: JSON.stringify({ error: message, failure: true }),
+                  },
+                ],
+              },
+            };
+          }
+        }
+
+        case 'resources/list': {
+          if (isNotification) return null;
+          return {
+            jsonrpc: '2.0',
+            id: id ?? null,
+            result: {
+              resources: this.resourceManager.listResources(),
+            },
+          };
+        }
+
+        case 'resources/read': {
+          if (isNotification) return null;
+          const uri = typeof params.uri === 'string' ? params.uri : '';
+          if (!uri) {
+            return {
+              jsonrpc: '2.0',
+              id: id ?? null,
+              error: {
+                code: JSONRPC_ERRORS.INVALID_PARAMS,
+                message: 'Missing or empty "uri" parameter for resources/read.',
+              },
+            };
+          }
+
+          try {
+            const readResult = this.resourceManager.readResource(uri);
+            return {
+              jsonrpc: '2.0',
+              id: id ?? null,
+              result: readResult,
+            };
+          } catch (resErr) {
+            const message = resErr instanceof Error ? resErr.message : String(resErr);
+            return {
+              jsonrpc: '2.0',
+              id: id ?? null,
+              error: {
+                code: JSONRPC_ERRORS.INVALID_PARAMS,
+                message,
+              },
+            };
+          }
+        }
+
+        default: {
+          if (isNotification) return null;
+          return {
+            jsonrpc: '2.0',
+            id: id ?? null,
+            error: {
+              code: JSONRPC_ERRORS.METHOD_NOT_FOUND,
+              message: `Unknown or unhandled method: "${method}".`,
+            },
+          };
+        }
+      }
+    } catch (err) {
+      if (isNotification) return null;
+      const message = err instanceof Error ? err.message : String(err);
+      return {
+        jsonrpc: '2.0',
+        id: id ?? null,
+        error: {
+          code: JSONRPC_ERRORS.INTERNAL_ERROR,
+          message: `Internal server error: ${message}`,
+        },
+      };
+    }
+  }
+}

package/packages/mcp/src/tools/analyze-impact.ts

@@ -0,0 +1,74 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+import { ImpactAnalysisService } from '../../../verification/src/index.ts';
+
+export class AnalyzeImpactTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'analyze_impact',
+    description: 'Compare detected documentation and API changes against current project workspace files. Identifies affected files, exact line numbers, code snippets, matched patterns, and traceable reasons with certainty rankings (high, medium, heuristic).',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        project: {
+          type: 'string',
+          description: 'Workspace root directory containing code files to analyze.',
+        },
+        fromVersion: {
+          type: 'string',
+          description: 'Current or base documentation version (e.g. "v14").',
+        },
+        toVersion: {
+          type: 'string',
+          description: 'Target or upgraded documentation version (e.g. "v15").',
+        },
+        fromSnapshotId: {
+          type: 'string',
+          description: 'Optional base snapshot ID.',
+        },
+        toSnapshotId: {
+          type: 'string',
+          description: 'Optional target snapshot ID.',
+        },
+        sourceId: {
+          type: 'string',
+          description: 'Optional documentation source ID filter.',
+        },
+      },
+    },
+  };
+
+  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    const projectDir = typeof args.project === 'string' ? args.project : (ctx.projectDir || ctx.workspaceRoot || process.cwd());
+    const fromVersion = typeof args.fromVersion === 'string' ? args.fromVersion : undefined;
+    const toVersion = typeof args.toVersion === 'string' ? args.toVersion : undefined;
+    const fromSnapshotId = typeof args.fromSnapshotId === 'string' ? args.fromSnapshotId : undefined;
+    const toSnapshotId = typeof args.toSnapshotId === 'string' ? args.toSnapshotId : undefined;
+    const sourceId = typeof args.sourceId === 'string' ? args.sourceId : undefined;
+
+    const impactService = ctx.impactService || new ImpactAnalysisService(ctx.repo);
+    const { result, markdown } = impactService.analyzeImpact({
+      projectDir,
+      fromVersion,
+      toVersion,
+      fromSnapshotId,
+      toSnapshotId,
+      sourceId,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              markdown,
+              data: result,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+}

package/packages/mcp/src/tools/check-api.ts

@@ -0,0 +1,86 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+import { VerificationService } from '../../../verification/src/index.ts';
+
+export class CheckApiTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'check_api',
+    description: 'Verify agent/generated code against indexed OpenAPI schemas and documentation. Detects invalid endpoints, wrong HTTP methods, missing required parameters, deprecations, removed APIs, version syntax conflicts, and response assumptions. Distinguishes verified, warning, mismatch, and insufficient_evidence.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        code: {
+          type: 'string',
+          description: 'The generated code snippet, route handler, or API client call to verify.',
+        },
+        language: {
+          type: 'string',
+          description: 'Programming language of the code (e.g. "typescript", "javascript", "python", "curl").',
+        },
+        library: {
+          type: 'string',
+          description: 'Target library or SDK name (e.g. "stripe", "next").',
+        },
+        version: {
+          type: 'string',
+          description: 'Target documentation/API version (e.g. "v14", "v15", "1.0"). If omitted, project version is auto-detected.',
+        },
+        project: {
+          type: 'string',
+          description: 'Workspace root directory to auto-resolve project dependencies and versions.',
+        },
+        filePath: {
+          type: 'string',
+          description: 'Optional path of the file being verified for context.',
+        },
+      },
+      required: ['code'],
+    },
+  };
+
+  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    const code = typeof args.code === 'string' ? args.code : '';
+    if (!code) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required argument: code' }) }],
+      };
+    }
+
+    const language = typeof args.language === 'string' ? args.language : undefined;
+    const library = typeof args.library === 'string' ? args.library : undefined;
+    const version = typeof args.version === 'string' ? args.version : undefined;
+    const filePath = typeof args.filePath === 'string' ? args.filePath : undefined;
+    const projectDir =
+      (typeof args.projectDir === 'string' ? args.projectDir : undefined) ||
+      (typeof args.project === 'string' ? args.project : undefined) ||
+      ctx.projectDir ||
+      ctx.workspaceRoot;
+
+    const service = ctx.verificationService || new VerificationService(ctx.repo);
+    const { result, markdown } = service.verifyCode({
+      code,
+      language,
+      library,
+      version,
+      projectDir,
+      filePath,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              markdown,
+              data: result,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+}

package/packages/mcp/src/tools/diff-docs.ts

@@ -0,0 +1,68 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+import { DiffService } from '../../../verification/src/index.ts';
+
+export class DiffDocsTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'diff_docs',
+    description: 'Compare documentation snapshots and versions to detect added, removed, modified, and deprecated API endpoints, parameters, pitfalls, and content sections. Produces deterministic diffs ignoring formatting-only changes.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        fromVersion: {
+          type: 'string',
+          description: 'Base documentation version (e.g. "v14", "1.0").',
+        },
+        toVersion: {
+          type: 'string',
+          description: 'Target documentation version to compare against (e.g. "v15", "2.0").',
+        },
+        fromSnapshotId: {
+          type: 'string',
+          description: 'Base snapshot ID to compare.',
+        },
+        toSnapshotId: {
+          type: 'string',
+          description: 'Target snapshot ID to compare.',
+        },
+        sourceId: {
+          type: 'string',
+          description: 'Optional documentation source ID filter.',
+        },
+      },
+    },
+  };
+
+  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    const fromVersion = typeof args.fromVersion === 'string' ? args.fromVersion : undefined;
+    const toVersion = typeof args.toVersion === 'string' ? args.toVersion : undefined;
+    const fromSnapshotId = typeof args.fromSnapshotId === 'string' ? args.fromSnapshotId : undefined;
+    const toSnapshotId = typeof args.toSnapshotId === 'string' ? args.toSnapshotId : undefined;
+    const sourceId = typeof args.sourceId === 'string' ? args.sourceId : undefined;
+
+    const diffService = ctx.diffService || new DiffService(ctx.repo);
+    const { result, markdown } = diffService.diffDocs({
+      fromVersion,
+      toVersion,
+      fromSnapshotId,
+      toSnapshotId,
+      sourceId,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              markdown,
+              data: result,
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+}

package/packages/mcp/src/tools/export-context.ts

@@ -0,0 +1,73 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+import { ExportService } from '../../../export/src/index.ts';
+import type { ExportFormat } from '../../../shared/src/index.ts';
+
+export class ExportAgentContextTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'export_agent_context',
+    description: 'Deterministically generate and export agent-native documentation context files (AGENTS.md, CLAUDE.md, skill.md, llms.txt, docs-map.md) grounded in project dependency versions and authoritative documentation.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        format: {
+          type: 'string',
+          enum: ['agents.md', 'claude.md', 'skill.md', 'llms.txt', 'docs-map.md'],
+          description: 'Target agent file format to generate (default: "agents.md").',
+        },
+        docVersion: {
+          type: 'string',
+          description: 'Optional target documentation version (e.g. "v14", "v15").',
+        },
+        projectDir: {
+          type: 'string',
+          description: 'Optional project directory for resolving workspace dependency versions.',
+        },
+        targetSource: {
+          type: 'string',
+          description: 'Optional library or skill name label.',
+        },
+      },
+      required: ['format'],
+    },
+  };
+
+  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    const rawFormat = typeof args.format === 'string' ? args.format.toLowerCase() : 'agents.md';
+    const validFormats: ExportFormat[] = ['agents.md', 'claude.md', 'skill.md', 'llms.txt', 'docs-map.md'];
+    const format = validFormats.includes(rawFormat as ExportFormat) ? (rawFormat as ExportFormat) : 'agents.md';
+
+    const docVersion = typeof args.docVersion === 'string' ? args.docVersion : undefined;
+    const projectDir = typeof args.projectDir === 'string' ? args.projectDir : ctx.projectDir || ctx.workspaceRoot;
+    const targetSource = typeof args.targetSource === 'string' ? args.targetSource : undefined;
+
+    const exportService = ctx.exportService || new ExportService(ctx.repo);
+    const result = await exportService.generateExport({
+      format,
+      docVersion,
+      projectDir,
+      targetSource,
+    });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              markdown: result.content,
+              data: {
+                format: result.format,
+                metadata: result.metadata,
+                tokenEstimate: result.metadata.tokenEstimate,
+                untrusted: true,
+              },
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+}

package/packages/mcp/src/tools/find-api.ts

@@ -0,0 +1,99 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class FindApiTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'find_api',
+    description: 'Lookup structured OpenAPI endpoints by path, operation ID, or keyword with exact parameters, schemas, auth, and error responses.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'API path or keyword search (e.g. "/v1/webhook_endpoints", "create subscription").',
+        },
+        method: {
+          type: 'string',
+          description: 'HTTP method filter (e.g. "get", "post", "delete").',
+          enum: ['get', 'post', 'put', 'delete', 'patch', 'head', 'options'],
+        },
+        version: {
+          type: 'string',
+          description: 'Target API / documentation version filter.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of endpoints to return (default: 5).',
+        },
+      },
+      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 method = typeof args.method === 'string' ? args.method.toLowerCase() : undefined;
+    const version = typeof args.version === 'string' ? args.version : undefined;
+    const limit = typeof args.limit === 'number' && args.limit > 0 ? args.limit : 5;
+
+    const endpoints = ctx.repo.searchApiEndpoints(query, {
+      method,
+      docVersion: version,
+      limit,
+    });
+
+    if (endpoints.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              markdown: `### API Search for "${query}"\n\nNo matching API endpoints found.`,
+              data: { query, count: 0, endpoints: [] },
+            }, null, 2),
+          },
+        ],
+      };
+    }
+
+    const lines: string[] = [`### API Intelligence for "${query}" (${endpoints.length} found)\n`];
+    for (const ep of endpoints) {
+      lines.push(`#### \`${ep.method.toUpperCase()} ${ep.path}\`${ep.deprecated ? ' [DEPRECATED]' : ''}`);
+      if (ep.summary) lines.push(`*${ep.summary}*`);
+      if (ep.parameters.length > 0) {
+        const pList = ep.parameters.map(p => `${p.name}${p.required ? '*' : ''} (${p.in}:${p.type || 'any'})`).join(', ');
+        lines.push(`- **Parameters**: ${pList}`);
+      }
+      if (ep.auth.length > 0) {
+        lines.push(`- **Auth**: ${ep.auth.map(a => `${a.type}${a.scheme ? `:${a.scheme}` : ''}`).join(', ')}`);
+      }
+      if (ep.pagination) {
+        lines.push(`- **Pagination**: ${ep.pagination.type} (${ep.pagination.parameters.join(', ')})`);
+      }
+      lines.push('');
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            markdown: lines.join('\n'),
+            data: {
+              query,
+              count: endpoints.length,
+              endpoints,
+            },
+          }, null, 2),
+        },
+      ],
+    };
+  }
+}