@bodhi-ventures/aiocs 0.1.0

package/dist/mcp-server.js

@@ -0,0 +1,720 @@
+#!/usr/bin/env node
+import {
+  AIOCS_ERROR_CODES,
+  AiocsError,
+  backfillEmbeddings,
+  clearEmbeddings,
+  diffSnapshotsForSource,
+  exportCatalogBackup,
+  fetchSources,
+  getDoctorReport,
+  getEmbeddingStatus,
+  importCatalogBackup,
+  initBuiltInSources,
+  linkProjectSources,
+  listSnapshotsForSource,
+  listSources,
+  packageDescription,
+  packageName,
+  packageVersion,
+  refreshDueSources,
+  runEmbeddingWorker,
+  runSourceCanaries,
+  searchCatalog,
+  showChunk,
+  toAiocsError,
+  unlinkProjectSources,
+  upsertSourceFromSpecFile,
+  verifyCoverage
+} from "./chunk-ID3PUSMY.js";
+
+// src/mcp-server.ts
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+var doctorCheckSchema = z.object({
+  id: z.string(),
+  status: z.enum(["pass", "warn", "fail"]),
+  summary: z.string(),
+  details: z.record(z.string(), z.unknown()).optional()
+});
+var doctorReportSchema = z.object({
+  summary: z.object({
+    status: z.enum(["healthy", "degraded", "unhealthy"]),
+    checkCount: z.number().int().nonnegative(),
+    passCount: z.number().int().nonnegative(),
+    warnCount: z.number().int().nonnegative(),
+    failCount: z.number().int().nonnegative()
+  }),
+  checks: z.array(doctorCheckSchema)
+});
+var sourceSchema = z.object({
+  id: z.string(),
+  label: z.string(),
+  specPath: z.string().nullable(),
+  nextDueAt: z.string(),
+  isDue: z.boolean(),
+  nextCanaryDueAt: z.string().nullable(),
+  isCanaryDue: z.boolean(),
+  lastCheckedAt: z.string().nullable(),
+  lastSuccessfulSnapshotAt: z.string().nullable(),
+  lastSuccessfulSnapshotId: z.string().nullable(),
+  lastCanaryCheckedAt: z.string().nullable(),
+  lastSuccessfulCanaryAt: z.string().nullable(),
+  lastCanaryStatus: z.enum(["pass", "fail"]).nullable()
+});
+var fetchResultSchema = z.object({
+  sourceId: z.string(),
+  snapshotId: z.string(),
+  pageCount: z.number().int().nonnegative(),
+  reused: z.boolean()
+});
+var searchResultSchema = z.object({
+  chunkId: z.number().int().nonnegative(),
+  sourceId: z.string(),
+  snapshotId: z.string(),
+  pageUrl: z.string(),
+  pageTitle: z.string(),
+  sectionTitle: z.string(),
+  markdown: z.string(),
+  score: z.number().optional(),
+  signals: z.array(z.enum(["lexical", "vector"])).optional()
+});
+var mcpErrorSchema = z.object({
+  code: z.string(),
+  message: z.string(),
+  details: z.unknown().optional()
+});
+var coverageVerificationSchema = z.object({
+  sourceId: z.string(),
+  snapshotId: z.string(),
+  complete: z.boolean(),
+  summary: z.object({
+    fileCount: z.number().int().nonnegative(),
+    headingCount: z.number().int().nonnegative(),
+    matchedHeadingCount: z.number().int().nonnegative(),
+    missingHeadingCount: z.number().int().nonnegative(),
+    matchCounts: z.object({
+      pageTitle: z.number().int().nonnegative(),
+      sectionTitle: z.number().int().nonnegative(),
+      body: z.number().int().nonnegative()
+    })
+  }),
+  files: z.array(z.object({
+    referenceFile: z.string(),
+    headingCount: z.number().int().nonnegative(),
+    matchedHeadingCount: z.number().int().nonnegative(),
+    missingHeadingCount: z.number().int().nonnegative(),
+    missingHeadings: z.array(z.string()),
+    matchCounts: z.object({
+      pageTitle: z.number().int().nonnegative(),
+      sectionTitle: z.number().int().nonnegative(),
+      body: z.number().int().nonnegative()
+    })
+  }))
+});
+var canaryResultSchema = z.object({
+  sourceId: z.string(),
+  status: z.enum(["pass", "fail"]),
+  checkedAt: z.string(),
+  summary: z.object({
+    checkCount: z.number().int().nonnegative(),
+    passCount: z.number().int().nonnegative(),
+    failCount: z.number().int().nonnegative()
+  }),
+  checks: z.array(z.object({
+    url: z.string(),
+    status: z.enum(["pass", "fail"]),
+    title: z.string().optional(),
+    markdownLength: z.number().int().nonnegative().optional(),
+    errorMessage: z.string().optional()
+  }))
+});
+var snapshotDiffSchema = z.object({
+  sourceId: z.string(),
+  fromSnapshotId: z.string(),
+  toSnapshotId: z.string(),
+  summary: z.object({
+    addedPageCount: z.number().int().nonnegative(),
+    removedPageCount: z.number().int().nonnegative(),
+    changedPageCount: z.number().int().nonnegative(),
+    unchangedPageCount: z.number().int().nonnegative()
+  }),
+  addedPages: z.array(z.object({
+    url: z.string(),
+    title: z.string()
+  })),
+  removedPages: z.array(z.object({
+    url: z.string(),
+    title: z.string()
+  })),
+  changedPages: z.array(z.object({
+    url: z.string(),
+    beforeTitle: z.string(),
+    afterTitle: z.string(),
+    lineSummary: z.object({
+      addedLineCount: z.number().int().nonnegative(),
+      removedLineCount: z.number().int().nonnegative()
+    })
+  }))
+});
+var backupManifestSchema = z.object({
+  formatVersion: z.literal(1),
+  createdAt: z.string(),
+  packageVersion: z.string(),
+  entries: z.array(z.object({
+    relativePath: z.string(),
+    type: z.enum(["file", "directory"]),
+    size: z.number().int().nonnegative()
+  }))
+});
+var embeddingStatusSchema = z.object({
+  queue: z.object({
+    pendingJobs: z.number().int().nonnegative(),
+    runningJobs: z.number().int().nonnegative(),
+    failedJobs: z.number().int().nonnegative()
+  }),
+  sources: z.array(z.object({
+    sourceId: z.string(),
+    snapshotId: z.string().nullable(),
+    totalChunks: z.number().int().nonnegative(),
+    indexedChunks: z.number().int().nonnegative(),
+    pendingChunks: z.number().int().nonnegative(),
+    failedChunks: z.number().int().nonnegative(),
+    staleChunks: z.number().int().nonnegative(),
+    coverageRatio: z.number()
+  }))
+});
+var server = new McpServer({
+  name: packageName,
+  version: packageVersion,
+  title: "aiocs MCP server"
+}, {
+  instructions: `${packageDescription} Prefer these tools before live browsing when supported or already-fetched docs may exist locally. Check source_list before assuming a source is missing or stale. Use search mode auto by default, lexical for exact identifiers, and refresh_due for targeted freshness checks before force fetch. Avoid fetch all as a normal answering path, use batch to reduce repeated round trips, and cite sourceId, snapshotId, and pageUrl when returning results.`
+});
+var toolInputSchemas = /* @__PURE__ */ new Map();
+function asToolResult(data) {
+  const structuredContent = {
+    ok: true,
+    data
+  };
+  return {
+    structuredContent,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(structuredContent, null, 2)
+      }
+    ]
+  };
+}
+function asToolError(error) {
+  const normalized = toAiocsError(error);
+  const structuredContent = {
+    ok: false,
+    error: {
+      code: normalized.code,
+      message: normalized.message,
+      ...typeof normalized.details !== "undefined" ? { details: normalized.details } : {}
+    }
+  };
+  return {
+    isError: true,
+    structuredContent,
+    content: [
+      {
+        type: "text",
+        text: JSON.stringify(structuredContent, null, 2)
+      }
+    ]
+  };
+}
+var toolHandlers = {
+  version: async () => ({
+    name: packageName,
+    version: packageVersion
+  }),
+  doctor: async () => getDoctorReport(),
+  init: async (args = {}) => initBuiltInSources({
+    ...typeof args.fetch === "boolean" ? { fetch: args.fetch } : {}
+  }),
+  source_upsert: async (args = {}) => upsertSourceFromSpecFile(args.specFile),
+  source_list: async () => listSources(),
+  fetch: async (args = {}) => fetchSources(args.sourceIdOrAll),
+  canary: async (args = {}) => runSourceCanaries(args.sourceIdOrAll),
+  refresh_due: async (args = {}) => refreshDueSources(args.sourceIdOrAll ?? "all"),
+  snapshot_list: async (args = {}) => listSnapshotsForSource(args.sourceId),
+  diff_snapshots: async (args = {}) => diffSnapshotsForSource({
+    sourceId: args.sourceId,
+    ...typeof args.fromSnapshotId === "string" ? { fromSnapshotId: args.fromSnapshotId } : {},
+    ...typeof args.toSnapshotId === "string" ? { toSnapshotId: args.toSnapshotId } : {}
+  }),
+  project_link: async (args = {}) => linkProjectSources(args.projectPath, args.sourceIds),
+  project_unlink: async (args = {}) => unlinkProjectSources(args.projectPath, args.sourceIds ?? []),
+  search: async (args = {}) => searchCatalog(args.query, {
+    source: args.sourceIds ?? [],
+    ...typeof args.snapshotId === "string" ? { snapshot: args.snapshotId } : {},
+    ...typeof args.all === "boolean" ? { all: args.all } : {},
+    ...typeof args.project === "string" ? { project: args.project } : {},
+    ...typeof args.mode === "string" ? { mode: args.mode } : {},
+    ...typeof args.limit === "number" ? { limit: args.limit } : {},
+    ...typeof args.offset === "number" ? { offset: args.offset } : {}
+  }),
+  show: async (args = {}) => showChunk(args.chunkId),
+  embeddings_status: async () => getEmbeddingStatus(),
+  embeddings_backfill: async (args = {}) => backfillEmbeddings(args.sourceIdOrAll),
+  embeddings_clear: async (args = {}) => clearEmbeddings(args.sourceIdOrAll),
+  embeddings_run: async () => runEmbeddingWorker(),
+  backup_export: async (args = {}) => exportCatalogBackup({
+    outputDir: args.outputDir,
+    ...typeof args.replaceExisting === "boolean" ? { replaceExisting: args.replaceExisting } : {}
+  }),
+  backup_import: async (args = {}) => importCatalogBackup({
+    inputDir: args.inputDir,
+    ...typeof args.replaceExisting === "boolean" ? { replaceExisting: args.replaceExisting } : {}
+  }),
+  verify_coverage: async (args = {}) => verifyCoverage({
+    sourceId: args.sourceId,
+    referenceFiles: args.referenceFiles,
+    ...typeof args.snapshotId === "string" ? { snapshotId: args.snapshotId } : {}
+  })
+};
+var batchableToolNames = Object.keys(toolHandlers);
+async function runToolHandler(name, args) {
+  return toolHandlers[name](args);
+}
+function registerAiocsTool(name, config) {
+  toolInputSchemas.set(name, config.inputSchema);
+  server.registerTool(
+    name,
+    {
+      ...config,
+      outputSchema: z.object({
+        ok: z.boolean(),
+        data: config.outputSchema.optional(),
+        error: mcpErrorSchema.optional()
+      })
+    },
+    async (args) => {
+      try {
+        return asToolResult(await runToolHandler(name, args));
+      } catch (error) {
+        return asToolError(error);
+      }
+    }
+  );
+}
+function formatZodIssues(error) {
+  return error.issues.map((issue) => {
+    const path = issue.path.length > 0 ? issue.path.join(".") : "input";
+    return `${path}: ${issue.message}`;
+  }).join("; ");
+}
+function validateBatchOperationArguments(tool, args) {
+  const schema = toolInputSchemas.get(tool);
+  if (!schema) {
+    return args;
+  }
+  const parsed = schema.safeParse(args);
+  if (!parsed.success) {
+    throw new AiocsError(
+      AIOCS_ERROR_CODES.invalidArgument,
+      `Invalid arguments for tool ${tool}: ${formatZodIssues(parsed.error)}`,
+      {
+        issues: parsed.error.issues
+      }
+    );
+  }
+  return parsed.data;
+}
+registerAiocsTool(
+  "version",
+  {
+    title: "Version",
+    description: "Return the current aiocs package name and version.",
+    outputSchema: z.object({
+      name: z.string(),
+      version: z.string()
+    })
+  }
+);
+registerAiocsTool(
+  "doctor",
+  {
+    title: "Doctor",
+    description: "Validate catalog, Playwright, daemon config, source-spec directories, freshness, embeddings, Qdrant, Ollama, and Docker readiness.",
+    outputSchema: doctorReportSchema
+  }
+);
+registerAiocsTool(
+  "init",
+  {
+    title: "Init",
+    description: "Bootstrap the bundled built-in source specs and optionally fetch them.",
+    inputSchema: z.object({
+      fetch: z.boolean().optional()
+    }),
+    outputSchema: z.object({
+      sourceSpecDir: z.string(),
+      userSourceDir: z.string(),
+      fetched: z.boolean(),
+      initializedSources: z.array(z.object({
+        sourceId: z.string(),
+        specPath: z.string(),
+        configHash: z.string(),
+        configChanged: z.boolean()
+      })),
+      removedSourceIds: z.array(z.string()),
+      fetchResults: z.array(fetchResultSchema)
+    })
+  }
+);
+registerAiocsTool(
+  "source_upsert",
+  {
+    title: "Source upsert",
+    description: "Load or update a source spec file in the local catalog.",
+    inputSchema: z.object({
+      specFile: z.string()
+    }),
+    outputSchema: z.object({
+      sourceId: z.string(),
+      configHash: z.string(),
+      specPath: z.string()
+    })
+  }
+);
+registerAiocsTool(
+  "source_list",
+  {
+    title: "Source list",
+    description: "List all registered documentation sources.",
+    outputSchema: z.object({
+      sources: z.array(sourceSchema)
+    })
+  }
+);
+registerAiocsTool(
+  "fetch",
+  {
+    title: "Fetch",
+    description: "Fetch one source or all registered sources and record a snapshot.",
+    inputSchema: z.object({
+      sourceIdOrAll: z.string()
+    }),
+    outputSchema: z.object({
+      results: z.array(fetchResultSchema)
+    })
+  }
+);
+registerAiocsTool(
+  "canary",
+  {
+    title: "Canary",
+    description: "Run lightweight source extraction canaries without creating snapshots.",
+    inputSchema: z.object({
+      sourceIdOrAll: z.string()
+    }),
+    outputSchema: z.object({
+      results: z.array(canaryResultSchema)
+    })
+  }
+);
+registerAiocsTool(
+  "refresh_due",
+  {
+    title: "Refresh due",
+    description: "Fetch all due sources, or refresh one specific source only if it is currently due.",
+    inputSchema: z.object({
+      sourceIdOrAll: z.string().optional()
+    }),
+    outputSchema: z.object({
+      results: z.array(fetchResultSchema)
+    })
+  }
+);
+registerAiocsTool(
+  "snapshot_list",
+  {
+    title: "Snapshot list",
+    description: "List recorded snapshots for a source.",
+    inputSchema: z.object({
+      sourceId: z.string()
+    }),
+    outputSchema: z.object({
+      sourceId: z.string(),
+      snapshots: z.array(z.object({
+        snapshotId: z.string(),
+        sourceId: z.string(),
+        detectedVersion: z.string().nullable(),
+        createdAt: z.string(),
+        pageCount: z.number().int().nonnegative()
+      }))
+    })
+  }
+);
+registerAiocsTool(
+  "diff_snapshots",
+  {
+    title: "Diff snapshots",
+    description: "Compare two source snapshots and report added, removed, and changed pages.",
+    inputSchema: z.object({
+      sourceId: z.string(),
+      fromSnapshotId: z.string().optional(),
+      toSnapshotId: z.string().optional()
+    }),
+    outputSchema: snapshotDiffSchema
+  }
+);
+registerAiocsTool(
+  "project_link",
+  {
+    title: "Project link",
+    description: "Link one or more sources to a project path for scoped search.",
+    inputSchema: z.object({
+      projectPath: z.string(),
+      sourceIds: z.array(z.string()).min(1)
+    }),
+    outputSchema: z.object({
+      projectPath: z.string(),
+      sourceIds: z.array(z.string())
+    })
+  }
+);
+registerAiocsTool(
+  "project_unlink",
+  {
+    title: "Project unlink",
+    description: "Remove one or more source links from a project path.",
+    inputSchema: z.object({
+      projectPath: z.string(),
+      sourceIds: z.array(z.string()).optional()
+    }),
+    outputSchema: z.object({
+      projectPath: z.string(),
+      sourceIds: z.array(z.string())
+    })
+  }
+);
+registerAiocsTool(
+  "search",
+  {
+    title: "Search",
+    description: "Search the shared aiocs catalog by query and optional scope filters.",
+    inputSchema: z.object({
+      query: z.string(),
+      sourceIds: z.array(z.string()).optional(),
+      snapshotId: z.string().optional(),
+      all: z.boolean().optional(),
+      project: z.string().optional(),
+      mode: z.enum(["auto", "lexical", "hybrid", "semantic"]).optional(),
+      limit: z.number().int().positive().optional(),
+      offset: z.number().int().nonnegative().optional()
+    }),
+    outputSchema: z.object({
+      query: z.string(),
+      total: z.number().int().nonnegative(),
+      limit: z.number().int().positive(),
+      offset: z.number().int().nonnegative(),
+      hasMore: z.boolean(),
+      modeRequested: z.enum(["auto", "lexical", "hybrid", "semantic"]),
+      modeUsed: z.enum(["lexical", "hybrid", "semantic"]),
+      results: z.array(searchResultSchema)
+    })
+  }
+);
+registerAiocsTool(
+  "show",
+  {
+    title: "Show",
+    description: "Return a specific chunk by numeric chunk id.",
+    inputSchema: z.object({
+      chunkId: z.number().int().nonnegative()
+    }),
+    outputSchema: z.object({
+      chunk: searchResultSchema
+    })
+  }
+);
+registerAiocsTool(
+  "embeddings_status",
+  {
+    title: "Embeddings status",
+    description: "Return embedding backlog and latest-snapshot coverage details.",
+    outputSchema: embeddingStatusSchema
+  }
+);
+registerAiocsTool(
+  "embeddings_backfill",
+  {
+    title: "Embeddings backfill",
+    description: "Queue latest snapshots for embedding rebuild for one source or all sources.",
+    inputSchema: z.object({
+      sourceIdOrAll: z.string()
+    }),
+    outputSchema: z.object({
+      queuedJobs: z.number().int().nonnegative()
+    })
+  }
+);
+registerAiocsTool(
+  "embeddings_clear",
+  {
+    title: "Embeddings clear",
+    description: "Clear derived embedding state for one source or all sources.",
+    inputSchema: z.object({
+      sourceIdOrAll: z.string()
+    }),
+    outputSchema: z.object({
+      clearedSources: z.array(z.string())
+    })
+  }
+);
+registerAiocsTool(
+  "embeddings_run",
+  {
+    title: "Embeddings run",
+    description: "Process queued embedding jobs immediately.",
+    outputSchema: z.object({
+      processedJobs: z.number().int().nonnegative(),
+      succeededJobs: z.array(z.object({
+        sourceId: z.string(),
+        snapshotId: z.string(),
+        chunkCount: z.number().int().nonnegative()
+      })),
+      failedJobs: z.array(z.object({
+        sourceId: z.string(),
+        snapshotId: z.string(),
+        errorMessage: z.string()
+      }))
+    })
+  }
+);
+registerAiocsTool(
+  "backup_export",
+  {
+    title: "Backup export",
+    description: "Export the local aiocs data and config into a manifest-backed backup directory.",
+    inputSchema: z.object({
+      outputDir: z.string(),
+      replaceExisting: z.boolean().optional()
+    }),
+    outputSchema: z.object({
+      outputDir: z.string(),
+      manifestPath: z.string(),
+      manifest: backupManifestSchema
+    })
+  }
+);
+registerAiocsTool(
+  "backup_import",
+  {
+    title: "Backup import",
+    description: "Import a manifest-backed aiocs backup into the local data and config directories.",
+    inputSchema: z.object({
+      inputDir: z.string(),
+      replaceExisting: z.boolean().optional()
+    }),
+    outputSchema: z.object({
+      inputDir: z.string(),
+      dataDir: z.string(),
+      configDir: z.string().optional(),
+      manifest: backupManifestSchema
+    })
+  }
+);
+registerAiocsTool(
+  "verify_coverage",
+  {
+    title: "Verify coverage",
+    description: "Verify a fetched source snapshot against one or more reference markdown files.",
+    inputSchema: z.object({
+      sourceId: z.string(),
+      referenceFiles: z.array(z.string()).min(1),
+      snapshotId: z.string().optional()
+    }),
+    outputSchema: coverageVerificationSchema
+  }
+);
+server.registerTool(
+  "batch",
+  {
+    title: "Batch",
+    description: "Execute multiple aiocs MCP operations in one call and return per-operation success or error results.",
+    inputSchema: z.object({
+      operations: z.array(z.object({
+        tool: z.string().refine(
+          (value) => batchableToolNames.includes(value),
+          {
+            message: `tool must be one of: ${batchableToolNames.join(", ")}`
+          }
+        ),
+        arguments: z.record(z.string(), z.unknown()).optional()
+      })).min(1).max(25)
+    }),
+    outputSchema: z.object({
+      ok: z.boolean(),
+      data: z.object({
+        results: z.array(z.object({
+          index: z.number().int().nonnegative(),
+          tool: z.string(),
+          ok: z.boolean(),
+          data: z.unknown().optional(),
+          error: z.object({
+            code: z.string(),
+            message: z.string(),
+            details: z.unknown().optional()
+          }).optional()
+        }))
+      }).optional(),
+      error: mcpErrorSchema.optional()
+    })
+  },
+  async ({ operations }) => {
+    try {
+      const results = [];
+      for (const [index, operation] of operations.entries()) {
+        try {
+          const validatedArgs = validateBatchOperationArguments(
+            operation.tool,
+            operation.arguments ?? {}
+          );
+          const data = await runToolHandler(
+            operation.tool,
+            validatedArgs
+          );
+          results.push({
+            index,
+            tool: operation.tool,
+            ok: true,
+            data
+          });
+        } catch (error) {
+          const normalized = toAiocsError(error);
+          results.push({
+            index,
+            tool: operation.tool,
+            ok: false,
+            error: {
+              code: normalized.code,
+              message: normalized.message,
+              ...typeof normalized.details !== "undefined" ? { details: normalized.details } : {}
+            }
+          });
+        }
+      }
+      return asToolResult({ results });
+    } catch (error) {
+      return asToolError(error);
+    }
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((error) => {
+  process.stderr.write(`${error instanceof Error ? error.stack ?? error.message : String(error)}
+`);
+  process.exitCode = 1;
+});