Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import type { ServerContext } from "@modelcontextprotocol/server";
import { z } from "zod";
import type { BillingCustomerContext } from "@/server/billing/subscription";
import { resolveClientLabel } from "@/server/mcp/client-label";
import { buildDashboardUrl } from "@/server/mcp/urls";
export type ToolAuthContext = {
userId: string;
userEmail: string;
// The one organization every tool call is bound to. Hosted credentials
// (OAuth grants, API keys) are pinned at creation to the org that was active
// then and re-checked against a live membership on every request; self-host
// and SAM are bound to their single org / the chat's project org.
organizationId: string;
// Org role for permission gates (owner/admin/member, comma-joined when
// multiple). Hosted: stamped per request from the member row in
// transport.ts. Self-host/delegated: one implicit user per org → "owner".
role: string;
scopes: string[];
// OAuth client id, the literal "api_key", or null for first-party callers
// (self-host transports, SAM). See isHostedMcpClient.
clientId: string | null;
baseUrl: string;
// Which client made the call ("Claude Code", "Codex", "API key", …), for
// display only — a self-reported hint, never an identity. Reports stamp it
// into `created_by`; nothing authorizes, filters or bills on it. Always set
// on the MCP path; absent on hand-built contexts (SAM), which name
// themselves at the tool instead.
clientLabel?: string;
};
export type ToolContext = {
auth: ToolAuthContext;
// The in-app agent's turn id, so a tool call's telemetry can be joined to
// the `sam:turn` event of the turn that made it. Absent for MCP transports.
turnId?: string;
};
export const MCP_AUTH_CONTEXT_PROP = "openSeoAuth";
export const MCP_ROUTE = "/mcp";
const applicationAuthContextSchema = z.object({
userId: z.string().min(1),
userEmail: z.string().min(1),
organizationId: z.string().min(1),
// Absent from OAuth grant props (role is stamped per request by the hosted
// transport, never baked into tokens) and from delegated modes (implicit
// owner).
role: z.string().min(1).optional(),
baseUrl: z.string().url(),
// Compatibility fallback until workers-oauth-provider supplies the verified
// context marker consumed by Agents SDK 0.20.x (the
// cloudflare.workers-oauth-provider.verified-context.v1 symbol, which mints
// context.http.authInfo — watch the provider changelog). Once it ships,
// delete these two fields and the fallback in createMcpToolContext, and read
// clientId/scopes in transport.ts from authInfo instead of props.
clientId: z.string().min(1).nullable().optional(),
scopes: z.array(z.string()).optional(),
// Raw request User-Agent, stamped per request by the transport. The only
// client signal present on every call: initialize's clientInfo is not
// visible on a later tools/call, and this transport never populates
// ServerContext.http.req.
userAgent: z.string().optional(),
});
type ApplicationAuthContext = z.infer<typeof applicationAuthContextSchema>;
export const workersOAuthMcpPropsSchema = z.object({
[MCP_AUTH_CONTEXT_PROP]: applicationAuthContextSchema,
});
// The hosted /mcp route only ever sees provider-minted tokens, whose props
// always carry the OAuth client identity — require it so scope enforcement
// fails closed instead of silently degrading to first-party.
export const hostedWorkersOAuthMcpPropsSchema = z.object({
[MCP_AUTH_CONTEXT_PROP]: applicationAuthContextSchema.extend({
clientId: z.string().min(1),
scopes: z.array(z.string()),
}),
});
export type McpProps = z.infer<typeof workersOAuthMcpPropsSchema>;
export function createWorkersOAuthMcpProps(
context: ApplicationAuthContext,
): McpProps {
return {
[MCP_AUTH_CONTEXT_PROP]: context,
};
}
// Clients on the 2026-07-28 protocol may carry their identity per request in
// the reserved clientInfo key, which the SDK lifts out of `_meta` into
// `mcpReq.envelope` before any handler runs — so the envelope is the only place
// to look. It is client-supplied and typed as an open envelope, so parse it
// rather than reaching into it.
//
// The SDK's CLIENT_INFO_META_KEY, spelled out: a value import from
// @modelcontextprotocol/server would evaluate the whole SDK, protocol schemas
// included, at worker startup, and this module is on the eager path.
const CLIENT_INFO_META_KEY = "io.modelcontextprotocol/clientInfo";
const clientInfoMetaSchema = z.object({
[CLIENT_INFO_META_KEY]: z.object({ title: z.string().optional() }).optional(),
});
// Not named McpRequestContext: the SDK exports a type by that name. `mcpReq`
// is optional so the two auth-fallback tests do not have to build a request
// fixture.
type ToolCallContext = Pick<ServerContext, "http"> &
Partial<Pick<ServerContext, "mcpReq">>;
function readClientTitle(context: ToolCallContext): string | undefined {
const parsed = clientInfoMetaSchema.safeParse(context.mcpReq?.envelope);
return parsed.success ? parsed.data[CLIENT_INFO_META_KEY]?.title : undefined;
}
// Hosted credentials always carry a client identity: an OAuth client id or
// "api_key". First-party callers (self-host transports, SAM) have none. Gates
// hosted-only side effects such as finishing the onboarding wizard.
export function isHostedMcpClient(auth: Pick<ToolAuthContext, "clientId">) {
return auth.clientId !== null;
}
export function createMcpToolContext(
context: ToolCallContext,
props: McpProps,
): ToolContext {
const result = workersOAuthMcpPropsSchema.safeParse(props);
if (!result.success) {
throw new Error(`MCP auth context missing: ${result.error.message}`);
}
// Scope enforcement happens once, at the hosted transport boundary
// (handleAuthenticatedOpenSeoMcpRequest); this only assembles identity.
const applicationAuth = result.data[MCP_AUTH_CONTEXT_PROP];
const authInfo = context.http?.authInfo;
const clientId = authInfo?.clientId ?? applicationAuth.clientId ?? null;
const scopes = authInfo?.scopes ?? applicationAuth.scopes ?? [];
// Hosted credentials get their role stamped per request by transport.ts
// from the member row; one arriving without it bypassed that check, so fail
// closed. Delegated/self-hosted modes have no member rows and a single
// implicit owner per org.
if (isHostedMcpClient({ clientId }) && !applicationAuth.role) {
throw new Error("MCP auth context is missing a role for a hosted client");
}
const role = applicationAuth.role ?? "owner";
return {
auth: {
...applicationAuth,
role,
clientId,
scopes,
clientLabel: resolveClientLabel({
userAgent: applicationAuth.userAgent,
clientTitle: readClientTitle(context),
}),
},
};
}
export function buildBillingCustomer(
auth: Pick<ToolAuthContext, "userId" | "userEmail" | "organizationId">,
projectId: string,
): BillingCustomerContext {
return {
userId: auth.userId,
userEmail: auth.userEmail,
organizationId: auth.organizationId,
projectId,
};
}
export function buildProjectMeta(
context: {
baseUrl: string;
},
projectId: string,
path?: string,
params?: Record<string, string | number | undefined>,
) {
return {
projectId,
url: path ? buildDashboardUrl(context.baseUrl, path, params) : undefined,
};
}