Dedupe: one shared operation feeds API + MCP; set OpenAPI info

worker/operations.ts holds each op's schema + handler once; api.ts (REST +
/openapi.json) and registry.ts (MCP) both project from it — sharing the Effect
Schema directly (no duplicate declarations, no lossy OpenAPI round-trip since
both are Effect). Set OpenAPI title/version/description.

Author: RhysSullivan

worker/api.ts

@@ -1,42 +1,31 @@
 /**
- * The API — the single source of truth.
- *
- * Endpoints are defined once as an Effect `HttpApi`; the typed server, the
- * OpenAPI document (`/openapi.json`), and downstream artifacts (MCP, CLI) all
- * derive from this. Runs as a pure web fetch handler on Cloudflare Workers.
+ * The REST API — defined once as an Effect HttpApi. The typed server and the
+ * OpenAPI document (/openapi.json) both derive from this. Runs as a pure web
+ * fetch handler on Cloudflare Workers.
  */
-import { Effect, FileSystem, Layer, Path, Schema } from "effect";
+import { FileSystem, Layer, Path } from "effect";
 import { Etag, HttpPlatform } from "effect/unstable/http";
 import * as HttpRouter from "effect/unstable/http/HttpRouter";
 import { HttpApi, HttpApiBuilder, HttpApiEndpoint, HttpApiGroup } from "effect/unstable/httpapi";
-import { detect } from "../src/lib/detect.ts";
-
-// Response shape (top-level typed; per-format detail kept loose for now).
-const DetectionResult = Schema.Struct({
-  domain: Schema.String,
-  found: Schema.Array(Schema.String),
-  apiCatalog: Schema.optional(Schema.Unknown),
-  apiSchema: Schema.optional(Schema.Unknown),
-  mcp: Schema.Array(Schema.Unknown),
-  agentCard: Schema.optional(Schema.Unknown),
-  agentSkills: Schema.optional(Schema.Unknown),
-  llmsTxt: Schema.Boolean,
-  errors: Schema.Array(Schema.String),
-});
+import * as OpenApi from "effect/unstable/httpapi/OpenApi";
+import { DetectionResult, DetectParams, runDetect } from "./operations.ts";
 
 const Detect = HttpApiEndpoint.get("detect", "/api/:domain/detect", {
-  params: Schema.Struct({ domain: Schema.String }),
+  params: DetectParams,
   success: DetectionResult,
 });
 
-export const Api = HttpApi.make("integrations.sh").add(
-  HttpApiGroup.make("detect").add(Detect),
-);
+export const Api = HttpApi.make("integrations.sh")
+  .add(HttpApiGroup.make("detect").add(Detect))
+  .annotate(OpenApi.Title, "integrations.sh")
+  .annotate(OpenApi.Version, "0.1.0")
+  .annotate(
+    OpenApi.Description,
+    "Discover how to integrate with any service — APIs, MCP servers, GraphQL, CLIs — and detect what a domain exposes to agents.",
+  );
 
 const DetectGroup = HttpApiBuilder.group(Api, "detect", (handlers) =>
-  handlers.handle("detect", (req: { readonly params: { readonly domain: string } }) =>
-    Effect.promise(() => detect(req.params.domain.trim().toLowerCase()) as Promise<typeof DetectionResult.Type>),
-  ),
+  handlers.handle("detect", (req: { readonly params: { readonly domain: string } }) => runDetect(req.params.domain)),
 );
 
 const Platform = Layer.mergeAll(Path.layer, Etag.layerWeak, HttpPlatform.layer).pipe(

worker/operations.ts

@@ -0,0 +1,34 @@
+/**
+ * Operations — the single source of truth, written once.
+ *
+ * Each operation's input schema, output schema, description, and handler live
+ * here exactly once. The REST API (worker/api.ts → also emits /openapi.json) and
+ * the MCP server (worker/registry.ts) are both projected from these — sharing
+ * the Effect Schema directly rather than round-tripping through OpenAPI (lossless,
+ * fully typed, since both transports are Effect).
+ */
+import { Effect, Schema } from "effect";
+import { detect } from "../src/lib/detect.ts";
+
+export const DetectParams = Schema.Struct({ domain: Schema.String });
+
+export const DetectionResult = Schema.Struct({
+  domain: Schema.String,
+  found: Schema.Array(Schema.String),
+  apiCatalog: Schema.optional(Schema.Unknown),
+  apiSchema: Schema.optional(Schema.Unknown),
+  mcp: Schema.Array(Schema.Unknown),
+  agentCard: Schema.optional(Schema.Unknown),
+  agentSkills: Schema.optional(Schema.Unknown),
+  llmsTxt: Schema.Boolean,
+  errors: Schema.Array(Schema.String),
+});
+
+export const DETECT_DESCRIPTION =
+  "Detect a domain's agent-readiness: well-known manifests (api-catalog, MCP " +
+  "server-card, agent-card, agent-skills, llms.txt) plus live capability " +
+  "detection — MCP self-onboarding (DCR/CIMD) and the live OpenAPI schema.";
+
+/** The detect handler, shared by REST and MCP. */
+export const runDetect = (domain: string): Effect.Effect<typeof DetectionResult.Type> =>
+  Effect.promise(() => detect(domain.trim().toLowerCase()) as Promise<typeof DetectionResult.Type>);

worker/registry.ts

@@ -1,35 +1,27 @@
 /**
- * The tool registry — write once, projected to MCP (here) and REST (the worker's
- * /api routes). Each tool declares its schema + handler once; the same handler
- * backs every transport. The `integrations` CLI is the local client.
- *
- * Runs as a pure web fetch handler (Effect v4), so it lives in the Cloudflare
- * Worker alongside the static site.
+ * MCP projection — the same operations (worker/operations.ts), exposed as MCP
+ * tools. Schema + handler are shared with the REST API; only the transport
+ * differs. Served over HTTP at /mcp (via a Durable Object for session state).
  */
-import { Effect, Layer, Schema } from "effect";
+import { Layer } from "effect";
 import * as McpServer from "effect/unstable/ai/McpServer";
 import * as Tool from "effect/unstable/ai/Tool";
 import * as Toolkit from "effect/unstable/ai/Toolkit";
 import * as HttpRouter from "effect/unstable/http/HttpRouter";
-import { detect } from "../src/lib/detect.ts";
+import { DETECT_DESCRIPTION, DetectionResult, DetectParams, runDetect } from "./operations.ts";
 
-// ── tools ─────────────────────────────────────────────────────────────────────
 const Detect = Tool.make("detect", {
-  description:
-    "Detect a domain's agent-readiness: well-known manifests (api-catalog, MCP " +
-    "server-card, agent-card, agent-skills, llms.txt) plus live capability " +
-    "detection — MCP self-onboarding (DCR/CIMD) and the live OpenAPI schema.",
-  parameters: Schema.Struct({ domain: Schema.String }),
-  success: Schema.Unknown,
+  description: DETECT_DESCRIPTION,
+  parameters: DetectParams,
+  success: DetectionResult,
 });
 
 export const toolkit = Toolkit.make(Detect);
 
 const HandlersLayer = toolkit.toLayer({
-  detect: ({ domain }) => Effect.promise(() => detect(String(domain).trim().toLowerCase())),
+  detect: ({ domain }) => runDetect(domain),
 } as never);
 
-// ── MCP over HTTP at /mcp ─────────────────────────────────────────────────────
 const McpLayer = Layer.mergeAll(
   McpServer.layerHttp({ name: "integrations.sh", version: "0.1.0", path: "/mcp" }),
   McpServer.toolkit(toolkit),