sailfork / t3code-github / .repos/ alchemy-effect/ packages/ cloudflare/ src/ Access/ McpServer.ts

import * as zeroTrust from "@distilled.cloud/cloudflare/zero-trust";
import { Unowned } from "alchemy/AdoptPolicy";
import { isResolved } from "alchemy/Diff";
import { createPhysicalName } from "alchemy/PhysicalName";
import * as Provider from "alchemy/Provider";
import { Resource } from "alchemy/Resource";
import * as Effect from "effect/Effect";
import * as Predicate from "effect/Predicate";
import * as Redacted from "effect/Redacted";
import * as Stream from "effect/Stream";
import { CloudflareEnvironment } from "../CloudflareEnvironment.ts";
import type { Providers } from "../Providers.ts";

const TypeId = "Cloudflare.Access.McpServer" as const;
type TypeId = typeof TypeId;

/**
 * Authentication method the gateway uses to reach the upstream MCP server.
 */
export type McpServerAuthType = "oauth" | "bearer" | "unauthenticated";

/**
 * Capability sync state reported by Cloudflare for an MCP server.
 */
export type McpServerStatus = "waiting" | "ready" | "stale" | "error";

/**
 * Whether administrative authentication is required before the server's
 * capabilities can be synced.
 */
export type McpServerAuthenticationStatus =
  | "not_required"
  | "required"
  | "connected"
  | "stale"
  | "manual";

/**
 * A server-wide override for a single tool or prompt exposed by the
 * upstream MCP server.
 */
export interface McpServerCapabilityOverride {
  /**
   * Name of the tool or prompt capability to override.
   */
  name: string;
  /**
   * Custom name exposed for the capability.
   */
  alias?: string;
  /**
   * Custom description exposed for the capability.
   */
  description?: string;
  /**
   * Whether the capability is available through the MCP server.
   */
  enabled?: boolean;
}

/**
 * A tool or prompt discovered from the upstream MCP server by a capability
 * sync. The shape is whatever the upstream advertises (typically `name`,
 * `description`, and an input schema).
 */
export type McpServerCapability = Record<string, unknown>;

export interface McpServerProps {
  /**
   * The client-supplied server identifier. Immutable — changing it
   * triggers a replacement. If omitted, a deterministic id is generated
   * from the stack, stage, logical ID, and resource instance, capped at
   * the API's 32-character limit.
   * @default a generated ID of at most 32 characters
   */
  serverId?: string;
  /**
   * Display name of the server. If omitted, the server id is reused.
   * @default the server id
   */
  name?: string;
  /**
   * URL of the upstream MCP endpoint, e.g. `https://mcp.example.com/mcp`.
   * Create-only on the API: changing it triggers a delete-first replacement.
   */
  hostname: string;
  /**
   * Authentication method used to connect to the upstream MCP server.
   * Create-only on the API: changing it triggers a delete-first replacement.
   */
  authType: McpServerAuthType;
  /**
   * Static credential for the upstream MCP server. For `bearer`, either a
   * raw token (sent as `Authorization: Bearer <token>`) or a JSON-encoded
   * `{"headers":{...}}` object for custom or multiple static headers, e.g.
   * a Cloudflare Access service token. For `oauth`, the JSON-encoded OAuth
   * configuration. Write-only — the API never returns it, so rotation is
   * detected by comparing against the previously deployed value.
   */
  authCredentials?: Redacted.Redacted<string>;
  /**
   * Pre-registered OAuth `client_secret` for manually configured OAuth
   * servers. Write-only — never returned by the API.
   */
  clientSecret?: Redacted.Redacted<string>;
  /**
   * Optional description of the server.
   */
  description?: string;
  /**
   * Route outbound traffic to this server through the Zero Trust Secure
   * Web Gateway.
   * @default false
   */
  secureWebGateway?: boolean;
  /**
   * Use the shared Cloudflare-owned OAuth callback endpoint as the
   * `redirect_uri` for upstream on-behalf OAuth instead of the portal
   * hostname.
   * @default false
   */
  isSharedOauthCallbackEnabled?: boolean;
  /**
   * Server-wide tool overrides: disable, rename, or re-describe tools the
   * upstream advertises. When omitted, the observed overrides are kept.
   */
  updatedTools?: McpServerCapabilityOverride[];
  /**
   * Server-wide prompt overrides: disable, rename, or re-describe prompts
   * the upstream advertises. When omitted, the observed overrides are kept.
   */
  updatedPrompts?: McpServerCapabilityOverride[];
  /**
   * Run a capability sync (tool and prompt discovery against the upstream)
   * after the server is created, its configuration changes, or sync is
   * enabled after being disabled. Discovery
   * problems are reported on the `status` and `error` attributes and never
   * fail the deploy. Skipped while the server still requires an
   * administrator to complete its OAuth authentication. Cloudflare may
   * independently discover capabilities even when this option is false.
   * @default true
   */
  sync?: boolean;
}

export type McpServerAttributes = {
  /** The server id. */
  serverId: string;
  /** Account that owns the server. */
  accountId: string;
  /** Observed display name. */
  name: string;
  /** Observed upstream MCP endpoint URL. */
  hostname: string;
  /** Observed authentication method. */
  authType: McpServerAuthType;
  /** Observed description, if any. */
  description: string | undefined;
  /** Whether outbound traffic routes through the gateway. */
  secureWebGateway: boolean;
  /** Whether the shared Cloudflare OAuth callback is used. */
  isSharedOauthCallbackEnabled: boolean;
  /** Observed server-wide tool overrides. */
  updatedTools: McpServerCapabilityOverride[];
  /** Observed server-wide prompt overrides. */
  updatedPrompts: McpServerCapabilityOverride[];
  /** Tools discovered by the last successful capability sync. */
  tools: McpServerCapability[];
  /** Prompts discovered by the last successful capability sync. */
  prompts: McpServerCapability[];
  /** Current capability sync state, if reported. */
  status: McpServerStatus | undefined;
  /** Whether administrative OAuth authentication is still required. */
  authenticationStatus: McpServerAuthenticationStatus | undefined;
  /** Error from the last capability sync, if any. */
  error: string | undefined;
  /** RFC 3339 timestamp of the last sync attempt, if reported. */
  lastSynced: string | undefined;
  /** RFC 3339 timestamp of the last successful sync, if reported. */
  lastSuccessfulSync: string | undefined;
  /** RFC 3339 timestamp of when the server was created, if reported. */
  createdAt: string | undefined;
};

export type McpServer = Resource<TypeId, McpServerProps, McpServerAttributes, never, Providers>;

/**
 * A Cloudflare Zero Trust **AI Controls MCP server** — an upstream MCP
 * endpoint registered on the account so its tools and prompts can be
 * discovered, governed, and exposed to users through an MCP portal.
 *
 * Use {@link McpPortal} to create the gateway. Creating a server does not
 * attach it to a portal; portal membership is managed outside Alchemy.
 *
 * The product surface is in beta and requires the AI Controls
 * entitlement; accounts without it receive the typed `Forbidden` error
 * on all writes. The upstream `hostname` and `authType` are create-only
 * on the API — changing either triggers a delete-first replacement.
 * Credentials are write-only: the API never returns them, so a rotation
 * is detected by comparing against the previously deployed value.
 * Existing servers without saved stack state require explicit adoption;
 * their IDs alone do not prove ownership.
 *
 * ### Registering an MCP server
 * **Example:** Public server without authentication
 * ```typescript
 * const docs = yield* Cloudflare.Access.McpServer("CloudflareDocs", {
 *   hostname: "https://docs.mcp.cloudflare.com/mcp",
 *   authType: "unauthenticated",
 * });
 * ```
 *
 * **Example:** Server behind a static bearer token
 * ```typescript
 * const internal = yield* Cloudflare.Access.McpServer("InternalTools", {
 *   hostname: "https://mcp.internal.example.com/mcp",
 *   authType: "bearer",
 *   authCredentials: yield* Config.Redacted("MCP_BEARER_TOKEN"),
 *   description: "Internal engineering tools",
 *   secureWebGateway: true,
 * });
 * ```
 *
 * **Example:** Server protected by a Cloudflare Access service token
 * ```typescript
 * const token = yield* Cloudflare.Access.ServiceToken("McpToken", {});
 *
 * const guarded = yield* Cloudflare.Access.McpServer("GuardedTools", {
 *   hostname: "https://mcp.example.com/mcp",
 *   authType: "bearer",
 *   authCredentials: Output.all(token.clientId, token.clientSecret).pipe(
 *     Output.map(([clientId, clientSecret]) =>
 *       Redacted.make(JSON.stringify({
 *         headers: {
 *           "cf-access-client-id": clientId,
 *           "cf-access-client-secret": Redacted.value(clientSecret!),
 *         },
 *       })),
 *     ),
 *   ),
 * });
 * ```
 *
 * ### Governing capabilities
 * **Example:** Disable one tool and rename another
 * ```typescript
 * const curated = yield* Cloudflare.Access.McpServer("Curated", {
 *   hostname: "https://docs.mcp.cloudflare.com/mcp",
 *   authType: "unauthenticated",
 *   updatedTools: [
 *     { name: "migrate_pages_to_workers_guide", enabled: false },
 *     { name: "search_cloudflare_documentation", alias: "search_docs" },
 *   ],
 * });
 * ```
 *
 * **Example:** Register without an explicit capability sync
 * ```typescript
 * const deferred = yield* Cloudflare.Access.McpServer("Deferred", {
 *   hostname: "https://mcp.example.com/mcp",
 *   authType: "bearer",
 *   authCredentials: yield* Config.Redacted("MCP_BEARER_TOKEN"),
 *   sync: false,
 * });
 * ```
 *
 * ### Adopting an existing server
 * **Example:** Take ownership of a server registered outside Alchemy
 * ```typescript
 * const server = yield* Cloudflare.Access.McpServer("Existing", {
 *   serverId: "existing-server",
 *   hostname: "https://mcp.example.com/mcp",
 *   authType: "unauthenticated",
 * }).pipe(adopt(true));
 * ```
 *
 * @see https://developers.cloudflare.com/cloudflare-one/access-controls/ai-controls/
 *
 * @resource
 * @product Access
 * @category Cloudflare One (Zero Trust)
 */
export const McpServer = Resource<McpServer>(TypeId);

/**
 * Returns true if the given value is an McpServer resource.
 */
export const isMcpServer = (value: unknown): value is McpServer =>
  Predicate.hasProperty(value, "Type") && value.Type === TypeId;

export const McpServerProvider = () =>
  Provider.succeed(McpServer, {
    stables: ["serverId", "accountId"],

    list: Effect.fn(function* () {
      const { accountId } = yield* yield* CloudflareEnvironment;
      // Account-scoped collection; exhaustively paginate. The list rows
      // carry the full server shape, so each maps directly into the same
      // Attributes `read` returns. Accounts without the AI Controls
      // entitlement reject the route with the typed `Forbidden` — treat
      // them as having no servers.
      return yield* zeroTrust.listAccessAiControlMcpServers.pages({ accountId }).pipe(
        Stream.runCollect,
        Effect.map((chunk) =>
          Array.from(chunk).flatMap((page) =>
            (page.result ?? []).map((server) => toAttributes(server, accountId)),
          ),
        ),
        Effect.catchTag("Forbidden", () => Effect.succeed([])),
      );
    }),

    diff: Effect.fn(function* ({ olds, news, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      if (!isResolved(news)) return undefined;
      if (output !== undefined && output.accountId !== accountId) {
        return { action: "replace" } as const;
      }
      // The server id is the API identity — changing it is a replacement.
      const oldId = output?.serverId ?? olds?.serverId;
      if (news.serverId !== undefined && oldId !== undefined && oldId !== news.serverId) {
        return { action: "replace" } as const;
      }
      if (
        (output?.hostname ?? olds?.hostname) !== news.hostname ||
        (output?.authType ?? olds?.authType) !== news.authType
      ) {
        return { action: "replace", deleteFirst: true } as const;
      }
      return undefined;
    }),

    read: Effect.fn(function* ({ id, output, olds, previous }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const acct = output?.accountId ?? accountId;

      // The server id is deterministic (client-supplied or derived from
      // the logical id), so a direct read covers the cold case too.
      const serverId = output?.serverId ?? (yield* createServerId(id, olds?.serverId));
      const observed = yield* observeServer(acct, serverId).pipe(
        // A failed create can leave props with an invalid ID but no output.
        // That generation cannot exist; let destroy recover the saved state.
        Effect.catchTag("McpServerInvalidId", (error) =>
          output === undefined ? Effect.undefined : Effect.fail(error),
        ),
      );
      if (!observed) return undefined;
      const attrs = toAttributes(observed, acct);
      // MCP servers carry no ownership tags. An ID match alone does not
      // authorize taking over a server when the stack has no saved output,
      // unless it is the generation a replacement is replacing.
      return output === undefined &&
        !(previous?.serverId === observed.id && previous.accountId === acct)
        ? Unowned(attrs)
        : attrs;
    }),

    reconcile: Effect.fn(function* ({ id, news, olds, output }) {
      const { accountId } = yield* yield* CloudflareEnvironment;
      const serverId = output?.serverId ?? (yield* createServerId(id, news.serverId));
      const name = news.name ?? serverId;

      // 1. Observe.
      let observed = yield* observeServer(accountId, serverId);

      // 2. Ensure — immutable changes are handled by engine replacement.
      let changed = false;
      if (observed === undefined) {
        observed = yield* zeroTrust.createAccessAiControlMcpServer({
          accountId,
          id: serverId,
          authType: news.authType,
          hostname: news.hostname,
          ...mutableBody(news, name),
        });
        changed = true;
      } else {
        // 3. Sync — update only when the observed state differs. Unset
        //    optional props mean "keep the observed value". Credentials are
        //    write-only, so a rotation is detected against the previously
        //    deployed props rather than the cloud.
        const dirty =
          observed.name !== name ||
          (news.description !== undefined &&
            (observed.description || undefined) !== news.description) ||
          (news.secureWebGateway !== undefined &&
            (observed.secureWebGateway ?? false) !== news.secureWebGateway) ||
          (news.isSharedOauthCallbackEnabled !== undefined &&
            (observed.isSharedOauthCallbackEnabled ?? false) !==
              news.isSharedOauthCallbackEnabled) ||
          (news.updatedTools !== undefined &&
            !overridesEqual(observed.updatedTools, news.updatedTools)) ||
          (news.updatedPrompts !== undefined &&
            !overridesEqual(observed.updatedPrompts, news.updatedPrompts)) ||
          secretRotated(news.authCredentials, olds?.authCredentials) ||
          secretRotated(news.clientSecret, olds?.clientSecret);
        if (dirty) {
          observed = yield* zeroTrust.updateAccessAiControlMcpServer({
            accountId,
            id: serverId,
            ...mutableBody(news, name),
          });
          changed = true;
        }
      }

      // 4. Capability sync — best effort after a configuration change or
      //    when sync is enabled, and never while an administrator still
      //    has to complete the OAuth flow.
      //    Upstream discovery problems come back in the response body
      //    (`status`/`error`) and are matched as typed McpServerSyncFailure errors.
      if (
        (changed || olds?.sync === false) &&
        news.sync !== false &&
        observed.authenticationStatus !== "required"
      ) {
        yield* zeroTrust
          .syncAccessAiControlMcpServer({ accountId, id: serverId })
          .pipe(
            Effect.catchTag("McpServerSyncFailure", (error) =>
              Effect.logDebug(`capability sync for MCP server ${serverId} failed`, error.body),
            ),
          );
        // 5. Return — re-read so the discovered capabilities are reported.
        observed = (yield* observeServer(accountId, serverId)) ?? observed;
      }

      return toAttributes(observed, accountId);
    }),

    delete: Effect.fn(function* ({ output }) {
      yield* zeroTrust
        .deleteAccessAiControlMcpServer({
          accountId: output.accountId,
          id: output.serverId,
        })
        .pipe(Effect.catchTag("McpServerNotFound", () => Effect.void));
    }),
  });

/**
 * Structural shape of a capability override as returned by the API.
 */
type ObservedOverride = {
  name: string;
  alias?: string | null;
  description?: string | null;
  enabled?: boolean | null;
};

/**
 * Structural shape shared by create/read/update/list responses.
 */
type ObservedServer = zeroTrust.ReadAccessAiControlMcpServerResponse;

/**
 * Read a server by id, mapping "gone" to `undefined`.
 */
const observeServer = (accountId: string, id: string) =>
  zeroTrust
    .readAccessAiControlMcpServer({ accountId, id })
    .pipe(Effect.catchTag("McpServerNotFound", () => Effect.undefined));

const createServerId = (id: string, serverId: string | undefined) =>
  Effect.gen(function* () {
    return serverId ?? (yield* createPhysicalName({ id, lowercase: true, maxLength: 32 }));
  });

/**
 * The request members shared by create and update, derived from the
 * desired props. Unset optional props are omitted so the API keeps (or
 * defaults) the server-side value.
 */
const mutableBody = (news: McpServerProps, name: string) => ({
  name,
  ...(news.description !== undefined ? { description: news.description } : {}),
  ...(news.secureWebGateway !== undefined ? { secureWebGateway: news.secureWebGateway } : {}),
  ...(news.isSharedOauthCallbackEnabled !== undefined
    ? { isSharedOauthCallbackEnabled: news.isSharedOauthCallbackEnabled }
    : {}),
  ...(news.updatedTools !== undefined ? { updatedTools: news.updatedTools } : {}),
  ...(news.updatedPrompts !== undefined ? { updatedPrompts: news.updatedPrompts } : {}),
  ...(news.authCredentials !== undefined
    ? { authCredentials: Redacted.value(news.authCredentials) }
    : {}),
  ...(news.clientSecret !== undefined ? { clientSecret: Redacted.value(news.clientSecret) } : {}),
});

/**
 * A write-only secret changed when it is set and differs from what was
 * last deployed (including the first time it is set).
 */
const secretRotated = (
  desired: Redacted.Redacted<string> | undefined,
  previous: Redacted.Redacted<string> | undefined,
): boolean =>
  desired !== undefined &&
  (previous === undefined || Redacted.value(previous) !== Redacted.value(desired));

/**
 * Drop null/undefined members so API echoes and desired overrides compare
 * structurally.
 */
const normalizeOverride = (override: ObservedOverride): McpServerCapabilityOverride => ({
  name: override.name,
  ...(override.alias != null ? { alias: override.alias } : {}),
  ...(override.description != null ? { description: override.description } : {}),
  ...(override.enabled != null ? { enabled: override.enabled } : {}),
});

const normalizeOverrides = (
  overrides: ReadonlyArray<ObservedOverride> | null | undefined,
): McpServerCapabilityOverride[] => (overrides ?? []).map(normalizeOverride);

const overridesEqual = (
  observed: ReadonlyArray<ObservedOverride> | null | undefined,
  desired: ReadonlyArray<ObservedOverride>,
): boolean => {
  const byName = (a: McpServerCapabilityOverride, b: McpServerCapabilityOverride) =>
    a.name.localeCompare(b.name);
  return (
    JSON.stringify(normalizeOverrides(observed).sort(byName)) ===
    JSON.stringify(normalizeOverrides(desired).sort(byName))
  );
};

const toAttributes = (server: ObservedServer, accountId: string): McpServerAttributes => ({
  serverId: server.id,
  accountId,
  name: server.name,
  hostname: server.hostname,
  authType: server.authType,
  description: server.description || undefined,
  secureWebGateway: server.secureWebGateway ?? false,
  isSharedOauthCallbackEnabled: server.isSharedOauthCallbackEnabled ?? false,
  updatedTools: normalizeOverrides(server.updatedTools),
  updatedPrompts: normalizeOverrides(server.updatedPrompts),
  tools: Array.from(server.tools ?? []),
  prompts: Array.from(server.prompts ?? []),
  status: server.status ?? undefined,
  authenticationStatus: server.authenticationStatus ?? undefined,
  error: server.error || undefined,
  lastSynced: server.lastSynced ?? undefined,
  lastSuccessfulSync: server.lastSuccessfulSync ?? undefined,
  createdAt: server.createdAt ?? undefined,
});