docorbit 0.1.0

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

@@ -0,0 +1,100 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class FindExampleTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'find_example',
+    description: 'Find verified, framework-specific code examples by task, language, framework, or target API.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Implementation task or symbol to look for examples of (e.g. "verify webhook signature", "constructEvent").',
+        },
+        language: {
+          type: 'string',
+          description: 'Programming language filter (e.g. "typescript", "python", "go").',
+        },
+        framework: {
+          type: 'string',
+          description: 'Framework filter (e.g. "express", "fastapi", "next").',
+        },
+        version: {
+          type: 'string',
+          description: 'Target documentation version filter.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of examples 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()
+      : (typeof args.task === 'string' ? args.task.trim() : '');
+    if (!query) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: query (or task)' }) }],
+      };
+    }
+
+    const language = typeof args.language === 'string' ? args.language : undefined;
+    const framework = typeof args.framework === 'string' ? args.framework : undefined;
+    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 : 5;
+
+    const examples = ctx.repo.searchIndexedExamples(query, {
+      language,
+      framework,
+      docVersion: version,
+      limit,
+    });
+
+    if (examples.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              markdown: `### Code Examples for "${query}"\n\nNo verified code examples found.`,
+              data: { query, count: 0, examples: [] },
+            }, null, 2),
+          },
+        ],
+      };
+    }
+
+    const lines: string[] = [`### Verified Code Examples for "${query}" (${examples.length} found)\n`];
+    for (const ex of examples) {
+      lines.push(`#### ${ex.task} [${ex.language}${ex.framework ? ` / ${ex.framework}` : ''}] (${ex.sourceAuthority})`);
+      if (ex.relatedApi) lines.push(`*Target API*: \`${ex.relatedApi}\``);
+      lines.push('```' + ex.language);
+      lines.push(ex.code);
+      lines.push('```\n');
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            markdown: lines.join('\n'),
+            data: {
+              query,
+              count: examples.length,
+              examples,
+            },
+          }, null, 2),
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,94 @@
+import type { PitfallKind } from '../../../shared/src/index.ts';
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class FindPitfallTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'find_pitfall',
+    description: 'Search documented pitfalls, gotchas, deprecations, breaking changes, and runtime restrictions.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'Topic, feature, or symbol to inspect for pitfalls (e.g. "webhook raw body", "route params").',
+        },
+        kind: {
+          type: 'string',
+          description: 'Category filter for pitfalls.',
+          enum: ['deprecated', 'removed', 'breaking_change', 'gotcha', 'security', 'runtime_restriction', 'server_only', 'rate_limit'],
+        },
+        version: {
+          type: 'string',
+          description: 'Target documentation version filter.',
+        },
+        limit: {
+          type: 'number',
+          description: 'Maximum number of pitfalls 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()
+      : (typeof args.task === 'string' ? args.task.trim() : '');
+    if (!query) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: query (or task)' }) }],
+      };
+    }
+
+    const kind = typeof args.kind === 'string' ? (args.kind as PitfallKind) : undefined;
+    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 : 5;
+
+    const pitfalls = ctx.repo.searchPitfalls(query, {
+      kind,
+      docVersion: version,
+      limit,
+    });
+
+    if (pitfalls.length === 0) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              markdown: `### Pitfalls & Warnings for "${query}"\n\nNo matching pitfalls or warnings found.`,
+              data: { query, count: 0, pitfalls: [] },
+            }, null, 2),
+          },
+        ],
+      };
+    }
+
+    const lines: string[] = [`### Pitfalls & Warnings for "${query}" (${pitfalls.length} found)\n`];
+    for (const pf of pitfalls) {
+      lines.push(`- ⚠️ **[${pf.kind.toUpperCase()}] ${pf.title}**${pf.docVersion ? ` (${pf.docVersion})` : ''}`);
+      if (pf.relatedApi) lines.push(`  *Related API*: \`${pf.relatedApi}\``);
+      lines.push(`  ${pf.content}\n`);
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            markdown: lines.join('\n'),
+            data: {
+              query,
+              count: pitfalls.length,
+              pitfalls,
+            },
+          }, null, 2),
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,98 @@
+import { RecipeEngine } from '../../../retrieval/src/index.ts';
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class FindRecipeTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'find_recipe',
+    description: 'Assemble an evidence-grounded implementation recipe with explicit prerequisites, ordered steps, and validation steps.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        goal: {
+          type: 'string',
+          description: 'The implementation goal or workflow to construct a recipe for.',
+        },
+        version: {
+          type: 'string',
+          description: 'Target documentation version.',
+        },
+        projectPath: {
+          type: 'string',
+          description: 'Workspace root for project-aware dependency detection.',
+        },
+      },
+      required: ['goal'],
+    },
+  };
+
+  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    const goal = typeof args.goal === 'string'
+      ? args.goal.trim()
+      : (typeof args.task === 'string' ? args.task.trim() : (typeof args.query === 'string' ? args.query.trim() : ''));
+    if (!goal) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: goal (or task)' }) }],
+      };
+    }
+
+    const version = typeof args.docVersion === 'string'
+      ? args.docVersion
+      : (typeof args.version === 'string' ? args.version : undefined);
+    const projectPath = typeof args.projectPath === 'string'
+      ? args.projectPath
+      : (typeof args.project === 'string' ? args.project : ctx.workspaceRoot);
+
+    const engine = new RecipeEngine(ctx.repo);
+    const recipe = await engine.assembleRecipe(goal, {
+      docVersion: version,
+      projectDir: projectPath,
+    });
+
+    const lines: string[] = [
+      `### Implementation Recipe: ${recipe.goal}`,
+      `**Confidence**: ${Math.round(recipe.confidence * 100)}%${recipe.docVersion ? ` | **Version**: \`${recipe.docVersion}\`` : ''}\n`,
+    ];
+
+    if (recipe.prerequisites.length > 0) {
+      lines.push('#### Prerequisites');
+      for (const p of recipe.prerequisites) {
+        lines.push(`- [${p.evidenceLevel === 'documented_fact' ? 'FACT' : 'INFERRED'}] ${p.text}`);
+      }
+      lines.push('');
+    }
+
+    if (recipe.orderedSteps.length > 0) {
+      lines.push('#### Implementation Steps');
+      for (const s of recipe.orderedSteps) {
+        const badge = s.evidenceLevel === 'documented_fact' ? 'FACT' : (s.evidenceLevel === 'missing_information' ? 'MISSING' : 'INFERRED');
+        lines.push(`${s.step}. **[${badge}] ${s.title}**`);
+        if (s.apiEndpoint) lines.push(`   - Endpoint: \`${s.apiEndpoint}\``);
+        lines.push(`   - ${s.description}`);
+      }
+      lines.push('');
+    }
+
+    if (recipe.validationSteps.length > 0) {
+      lines.push('#### Validation Steps');
+      for (const vs of recipe.validationSteps) {
+        lines.push(`${vs.step}. **[FACT]** ${vs.description}`);
+        if (vs.expectedResponse) lines.push(`   - Expected: \`${vs.expectedResponse}\``);
+      }
+      lines.push('');
+    }
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            markdown: lines.join('\n'),
+            data: recipe,
+          }, null, 2),
+        },
+      ],
+    };
+  }
+}

package/packages/mcp/src/tools/get-doc.ts

@@ -0,0 +1,130 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class GetDocTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'get_doc',
+    description: 'Retrieve a specific documentation page or contextual chunk by ID or URL with complete metadata and security annotations.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        chunkId: {
+          type: 'string',
+          description: 'Unique chunk identifier (e.g. "chk_...").',
+        },
+        pageId: {
+          type: 'string',
+          description: 'Unique page identifier (e.g. "page_...").',
+        },
+        url: {
+          type: 'string',
+          description: 'Normalized source URL of the documentation page.',
+        },
+      },
+    },
+  };
+
+  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    const chunkId = typeof args.chunkId === 'string' ? args.chunkId.trim() : undefined;
+    const pageId = typeof args.pageId === 'string' ? args.pageId.trim() : undefined;
+    const url = typeof args.url === 'string' ? args.url.trim() : undefined;
+
+    if (!chunkId && !pageId && !url) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ error: 'Please provide at least one identifier: chunkId, pageId, or url.' }),
+          },
+        ],
+      };
+    }
+
+    if (chunkId) {
+      const chunk = ctx.repo.getChunk(chunkId);
+      if (!chunk) {
+        return {
+          isError: true,
+          content: [
+            {
+              type: 'text',
+              text: JSON.stringify({ error: `Chunk not found: ${chunkId}`, available: false }),
+            },
+          ],
+        };
+      }
+
+      const codeSnippets = ctx.repo.getChunkCode(chunkId);
+      const symbols = ctx.repo.getChunkSymbols(chunkId);
+      const relationships = ctx.repo.getChunkRelationships(chunkId);
+
+      const breadcrumb = chunk.sectionPath.length > 0 ? chunk.sectionPath.join(' > ') : (chunk.title || 'General');
+      const md = [
+        `### Chunk: ${breadcrumb}`,
+        `**ID**: \`${chunk.id}\` | **Type**: \`${chunk.chunkType}\` | **Est. Tokens**: ~${chunk.tokenEstimate}`,
+        chunk.docVersion ? `**Version**: \`${chunk.docVersion}\`` : '',
+        `> [!NOTE] External content is untrusted.\n`,
+        chunk.content,
+      ].filter(Boolean).join('\n\n');
+
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              markdown: md,
+              data: {
+                chunk,
+                codeSnippets,
+                symbols,
+                relationships,
+                untrusted: true,
+              },
+            }, null, 2),
+          },
+        ],
+      };
+    }
+
+    // Page lookup by ID or URL
+    const page = pageId ? ctx.repo.getPage(pageId) : (url ? ctx.repo.getPageByUrl(url) : null);
+    if (!page) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ error: `Page not found for ${pageId ? `pageId: ${pageId}` : `url: ${url}`}`, available: false }),
+          },
+        ],
+      };
+    }
+
+    const links = ctx.repo.getPageLinks(page.id);
+    const md = [
+      `### ${page.title}`,
+      `**URL**: ${page.url} | **Tokens**: ~${page.estimatedTokens} | **Hash**: \`${page.contentHash.slice(0, 8)}\``,
+      page.securityAnnotations.length > 0
+        ? `> [!WARNING] Security alerts detected: ${page.securityAnnotations.map(a => a.patternName).join(', ')}`
+        : `> [!NOTE] External content is untrusted.`,
+      `\n${page.content}`,
+    ].join('\n\n');
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            markdown: md,
+            data: {
+              page,
+              links,
+              untrusted: true,
+            },
+          }, null, 2),
+        },
+      ],
+    };
+  }
+}

package/packages/mcp/src/tools/get-docs-map.ts

@@ -0,0 +1,64 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+import { ExportService } from '../../../export/src/index.ts';
+
+export class GetDocumentationMapTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'get_documentation_map',
+    description: 'Retrieve the hierarchical documentation map, page tree, section headings, and estimated token budget footprints for indexed documentation.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        sourceId: {
+          type: 'string',
+          description: 'Optional source ID or source URL substring filter.',
+        },
+        docVersion: {
+          type: 'string',
+          description: 'Optional documentation version filter (e.g. "v14", "15.0").',
+        },
+      },
+    },
+  };
+
+  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    const sourceId = typeof args.sourceId === 'string' ? args.sourceId : undefined;
+    const docVersion = typeof args.docVersion === 'string' ? args.docVersion : undefined;
+
+    const exportService = ctx.exportService || new ExportService(ctx.repo);
+    const map = exportService.getDocumentationMap({ sourceId, docVersion });
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify(
+            {
+              markdown: map.markdownTree,
+              data: {
+                totalSources: map.totalSources,
+                totalPages: map.totalPages,
+                totalChunks: map.totalChunks,
+                totalEstimatedTokens: map.totalEstimatedTokens,
+                sources: map.sources,
+                pages: map.pages.map(p => ({
+                  id: p.id,
+                  title: p.title,
+                  url: p.url,
+                  version: p.version,
+                  chunkCount: p.chunkCount,
+                  estimatedTokens: p.estimatedTokens,
+                  apis: p.apis,
+                  pitfallCount: p.pitfallCount,
+                })),
+                untrusted: true,
+              },
+            },
+            null,
+            2
+          ),
+        },
+      ],
+    };
+  }
+}

package/packages/mcp/src/tools/get-version.ts

@@ -0,0 +1,118 @@
+import {
+  detectWorkspaceDependencies,
+  WorkspaceResolver,
+} from '../../../workspace/src/index.ts';
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class GetVersionTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    name: 'get_version',
+    description: 'Inspect workspace dependencies and resolve the exact compatible documentation version using the SemVer confidence ladder.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        library: {
+          type: 'string',
+          description: 'Package or library name to check (e.g. "next", "stripe", "fastapi").',
+        },
+        projectPath: {
+          type: 'string',
+          description: 'Workspace root directory containing package manifests (default: current directory).',
+        },
+      },
+      required: ['library'],
+    },
+  };
+
+  async execute(args: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    const library = typeof args.library === 'string' ? args.library.trim() : '';
+    if (!library) {
+      return {
+        isError: true,
+        content: [{ type: 'text', text: JSON.stringify({ error: 'Missing required parameter: library' }) }],
+      };
+    }
+
+    const projectPath = typeof args.projectPath === 'string' ? args.projectPath : (ctx.workspaceRoot || '.');
+
+    let scan;
+    try {
+      scan = detectWorkspaceDependencies(projectPath);
+    } catch (err: unknown) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({ error: `Failed to inspect workspace manifests at ${projectPath}: ${err instanceof Error ? err.message : String(err)}` }),
+          },
+        ],
+      };
+    }
+
+    const libLower = library.toLowerCase();
+    const matchedDep = scan.dependencies.find(d => d.name.toLowerCase() === libLower);
+
+    if (!matchedDep) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              markdown: `### Version Resolution for "${library}"\n\nNo installed dependency named \`${library}\` was found in workspace manifests.`,
+              data: {
+                library,
+                foundInWorkspace: false,
+                ecosystemsScanned: scan.ecosystems,
+              },
+            }, null, 2),
+          },
+        ],
+      };
+    }
+
+    const resolver = new WorkspaceResolver(ctx.repo);
+    const resolution = resolver.resolveWorkspace(scan);
+    const match = resolution.matches.find(m => m.dependency.name.toLowerCase() === libLower);
+
+    const data = {
+      library: matchedDep.name,
+      ecosystem: matchedDep.ecosystem,
+      requestedVersion: matchedDep.requestedVersion,
+      resolvedVersion: matchedDep.resolvedVersion,
+      sourceFile: matchedDep.sourceFile,
+      docVersionMatch: match ? {
+        targetVersion: match.targetVersion,
+        confidence: match.confidence,
+        snapshotId: match.snapshotId,
+        matchedBy: match.matchedBy,
+      } : {
+        targetVersion: 'unresolved',
+        confidence: 'unresolved',
+      },
+    };
+
+    const lines: string[] = [
+      `### Version Intelligence: \`${matchedDep.name}\``,
+      `- **Ecosystem**: \`${matchedDep.ecosystem}\``,
+      `- **Requested in Manifest**: \`${matchedDep.requestedVersion}\` (${matchedDep.sourceFile})`,
+      matchedDep.resolvedVersion ? `- **Resolved in Lockfile**: \`${matchedDep.resolvedVersion}\`` : '',
+      match?.targetVersion
+        ? `- **Recommended Doc Version**: \`${match.targetVersion}\` (Confidence: \`${match.confidence}\`, Matched via: \`${match.matchedBy}\`)`
+        : `- **Recommended Doc Version**: \`unresolved\` (No compatible indexed documentation found)`,
+    ].filter(Boolean);
+
+    return {
+      content: [
+        {
+          type: 'text',
+          text: JSON.stringify({
+            markdown: lines.join('\n'),
+            data,
+          }, null, 2),
+        },
+      ],
+    };
+  }
+}

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

@@ -0,0 +1,88 @@
+import type { CallToolResult, McpTool } from '../types.ts';
+import type { McpContext, McpToolHandler } from './types.ts';
+
+export class ImplementationContextTool implements McpToolHandler {
+  readonly definition: McpTool = {
+    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").',
+        },
+        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: Record<string, unknown>, ctx: McpContext): Promise<CallToolResult> {
+    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;
+
+    try {
+      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: unknown) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: 'text',
+            text: JSON.stringify({
+              error: `Failed to compile implementation context: ${err instanceof Error ? err.message : String(err)}`,
+            }),
+          },
+        ],
+      };
+    }
+  }
+}