feat(cloudflare): add Cloudflare Docs provider (oomol-lab#170)

## Summary

Adds the Cloudflare Docs MCP provider as a runnable custom-credential
provider.

- Connects to the public Cloudflare Docs MCP endpoint at
`https://docs.mcp.cloudflare.com/mcp`.
- Uses `custom_credential` auth with no credential fields so the
provider is not auto-enabled — users must explicitly connect before use.
- Execution requires a stored connection via `requireCustomCredential`.

## Actions

- `search_cloudflare_documentation` — Search Cloudflare documentation
for Workers, Pages, R2, Images, Stream, D1, Durable Objects, KV,
Workflows, Hyperdrive, Queues, AI Gateway, Zero Trust, and more.
- `get_pages_to_workers_migration_guide` — Get the guide and
instructions for migrating Cloudflare Pages projects to Cloudflare
Workers.

## Changes

- Add provider definition, action schemas, executors, and Cloudflare
Docs MCP runtime.
- Use custom_credential auth with empty fields so the provider requires
explicit connection (not auto-enabled).
- Add `requireCustomCredential` gate in executor createContext.
- Use SSRF-guarded provider fetch for MCP transport.

## Testing

- `npm run fix-check`
- `npm run typecheck`
- `npm test`
- Live validation against a running instance: confirmed provider is not
auto-enabled, action is refused without connection (HTTP
403/authorization_failed), connect completes with zero credential
fields, action executes successfully after connecting.

Author: pr656d

src/providers/cloudflare_docs/actions.ts

@@ -0,0 +1,28 @@
+import type { ActionDefinition } from "../../core/types.ts";
+
+import { s } from "../../core/json-schema.ts";
+import { defineProviderAction } from "../../core/provider-definition.ts";
+
+const service = "cloudflare_docs" as const;
+
+export type CloudflareDocsActionName = "search_cloudflare_documentation" | "get_pages_to_workers_migration_guide";
+
+export const cloudflareDocsActions: ActionDefinition[] = [
+  defineProviderAction(service, {
+    name: "search_cloudflare_documentation",
+    description:
+      "Search Cloudflare documentation for Workers, Pages, R2, Images, Stream, D1, Durable Objects, KV, Workflows, Hyperdrive, Queues, AI Search, Workers AI, Vectorize, AI Gateway, Browser Run, Zero Trust, Access, Tunnel, Gateway, Browser Isolation, WARP, DDOS, Magic Transit, Magic WAN, CDN, Cache, DNS, Zaraz, Argo, Rulesets, Terraform, Account and Billing.",
+    requiredScopes: [],
+    inputSchema: s.object("Input payload for search_cloudflare_documentation", {
+      query: s.string("Search query for Cloudflare documentation.", { minLength: 1 }),
+    }),
+    outputSchema: s.looseObject("Documentation search results from Cloudflare Docs MCP."),
+  }),
+  defineProviderAction(service, {
+    name: "get_pages_to_workers_migration_guide",
+    description: "Get the guide and instructions for migrating Cloudflare Pages projects to Cloudflare Workers.",
+    requiredScopes: [],
+    inputSchema: s.object("Input payload for get_pages_to_workers_migration_guide", {}),
+    outputSchema: s.looseObject("Cloudflare Pages to Workers migration guide."),
+  }),
+];

src/providers/cloudflare_docs/definition.ts

@@ -0,0 +1,15 @@
+import type { ProviderDefinition } from "../../core/types.ts";
+
+import { cloudflareDocsActions } from "./actions.ts";
+
+const service = "cloudflare_docs";
+
+export const provider: ProviderDefinition = {
+  service,
+  displayName: "Cloudflare Docs",
+  categories: ["Developer Tools", "AI"],
+  authTypes: ["custom_credential"],
+  auth: [{ type: "custom_credential", fields: [] }],
+  homepageUrl: "https://developers.cloudflare.com",
+  actions: cloudflareDocsActions,
+};

src/providers/cloudflare_docs/executors.ts

@@ -0,0 +1,19 @@
+import type { ExecutionContext, ProviderExecutors } from "../../core/types.ts";
+import type { CloudflareDocsActionContext } from "./runtime.ts";
+
+import { defineProviderExecutors, requireCustomCredential } from "../provider-runtime.ts";
+import { cloudflareDocsActionHandlers } from "./runtime.ts";
+
+const service = "cloudflare_docs";
+
+export const executors: ProviderExecutors = defineProviderExecutors<CloudflareDocsActionContext>({
+  service,
+  handlers: cloudflareDocsActionHandlers,
+  async createContext(context: ExecutionContext, fetcher: typeof fetch): Promise<CloudflareDocsActionContext> {
+    await requireCustomCredential(context, service);
+    return {
+      fetcher,
+      signal: context.signal,
+    };
+  },
+});

src/providers/cloudflare_docs/runtime.test.ts

@@ -0,0 +1,55 @@
+import { describe, expect, it, vi } from "vitest";
+import { getPagesToWorkersMigrationGuide, searchCloudflareDocumentation } from "./runtime.ts";
+
+const mockSdk = vi.hoisted(() => {
+  // eslint-disable-next-line @typescript-eslint/no-explicit-any
+  let callToolImpl: any = vi.fn();
+  return {
+    Client: function () {
+      return {
+        connect: vi.fn().mockResolvedValue(undefined),
+        callTool: callToolImpl,
+        close: vi.fn().mockResolvedValue(undefined),
+      };
+    },
+    // eslint-disable-next-line @typescript-eslint/no-explicit-any
+    setCallToolImpl: (fn: any) => {
+      callToolImpl = fn;
+    },
+  };
+});
+
+vi.mock("@modelcontextprotocol/sdk/client/index.js", () => mockSdk);
+
+vi.mock("@modelcontextprotocol/sdk/client/streamableHttp.js", () => ({
+  StreamableHTTPClientTransport: vi.fn(),
+}));
+
+describe("Cloudflare Docs runtime", () => {
+  describe("searchCloudflareDocumentation", () => {
+    it("rejects empty or missing query parameter", async () => {
+      await expect(searchCloudflareDocumentation({}, {})).rejects.toThrow("query parameter is required");
+      await expect(searchCloudflareDocumentation({ query: "   " }, {})).rejects.toThrow("query parameter is required");
+    });
+
+    it("rejects when MCP tool returns isError", async () => {
+      mockSdk.setCallToolImpl(
+        // eslint-disable-next-line @typescript-eslint/no-explicit-any
+        vi.fn().mockResolvedValue({
+          content: [{ type: "text", text: "Tool execution failed" }],
+          isError: true,
+        } as any),
+      );
+
+      await expect(
+        searchCloudflareDocumentation({ query: "test" }, { fetcher: vi.fn() as unknown as typeof fetch }),
+      ).rejects.toThrow("Tool execution failed");
+    });
+  });
+
+  describe("getPagesToWorkersMigrationGuide", () => {
+    it("is defined as a function", () => {
+      expect(typeof getPagesToWorkersMigrationGuide).toBe("function");
+    });
+  });
+});

src/providers/cloudflare_docs/runtime.ts

@@ -0,0 +1,82 @@
+import type { ProviderRuntimeHandler } from "../provider-runtime.ts";
+import type { CloudflareDocsActionName } from "./actions.ts";
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import { optionalString } from "../../core/cast.ts";
+import { ProviderRequestError } from "../provider-runtime.ts";
+
+const cloudflareDocsMcpUrl = "https://docs.mcp.cloudflare.com/mcp";
+
+export interface CloudflareDocsActionContext {
+  fetcher?: typeof fetch;
+  signal?: AbortSignal;
+}
+
+export const cloudflareDocsActionHandlers: Record<
+  CloudflareDocsActionName,
+  ProviderRuntimeHandler<CloudflareDocsActionContext>
+> = {
+  search_cloudflare_documentation(input, context) {
+    return searchCloudflareDocumentation(input, context);
+  },
+  get_pages_to_workers_migration_guide(input, context) {
+    return getPagesToWorkersMigrationGuide(input, context);
+  },
+};
+
+export async function searchCloudflareDocumentation(
+  input: Record<string, unknown>,
+  context: CloudflareDocsActionContext,
+): Promise<Record<string, unknown>> {
+  const query = optionalString(input.query)?.trim();
+  if (!query) {
+    throw new ProviderRequestError(400, "query parameter is required");
+  }
+
+  return callCloudflareDocsTool("search_cloudflare_documentation", { query }, context);
+}
+
+export async function getPagesToWorkersMigrationGuide(
+  input: Record<string, unknown>,
+  context: CloudflareDocsActionContext,
+): Promise<Record<string, unknown>> {
+  return callCloudflareDocsTool("migrate_pages_to_workers_guide", input, context);
+}
+
+async function callCloudflareDocsTool(
+  toolName: string,
+  args: Record<string, unknown>,
+  context: CloudflareDocsActionContext,
+): Promise<Record<string, unknown>> {
+  try {
+    const transportOptions: Record<string, unknown> = {};
+    if (context.fetcher) {
+      transportOptions.fetch = context.fetcher;
+    }
+    const transport = new StreamableHTTPClientTransport(new URL(cloudflareDocsMcpUrl), transportOptions);
+    const client = new Client({ name: "open-connector", version: "1.0.0" }, { capabilities: {} });
+    await client.connect(transport);
+
+    try {
+      const result = await client.callTool({
+        name: toolName,
+        arguments: args,
+      });
+      if (result.isError) {
+        const content = result.content as Array<{ type?: string; text?: string }> | undefined;
+        const text = content?.find((c) => c.type === "text")?.text;
+        throw new ProviderRequestError(502, text ?? "Cloudflare Docs MCP tool returned an unknown error.");
+      }
+      return result as Record<string, unknown>;
+    } finally {
+      await client.close().catch(() => {});
+    }
+  } catch (error) {
+    if (error instanceof ProviderRequestError) throw error;
+    throw new ProviderRequestError(
+      502,
+      `Cloudflare Docs MCP request failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
+}