Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import type { CreateMcpHandlerOptions } from "agents/mcp/server";
import { McpServer } from "@modelcontextprotocol/server";
import { beforeEach, describe, expect, it, vi } from "vitest";
import {
createWorkersOAuthMcpProps,
MCP_AUTH_CONTEXT_PROP,
} from "@/server/mcp/context";
import {
handleAuthenticatedOpenSeoMcpRequest,
handleSelfHostedOpenSeoMcpRequest,
} from "@/server/mcp/transport";
const selfHostedAuthMocks = vi.hoisted(() => ({
resolveCloudflareAccessContext: vi.fn(),
resolveLocalNoAuthContext: vi.fn(),
createOpenSeoMcpServer: vi.fn(),
createMcpHandler: vi.fn(),
}));
const authRepositoryMocks = vi.hoisted(() => ({
getMembership: vi.fn(),
}));
vi.mock("cloudflare:workers", () => ({ env: {} }));
vi.mock("@/server/auth/repositories/AuthRepository", () => ({
AuthRepository: authRepositoryMocks,
}));
vi.mock("@/middleware/ensure-user/cloudflareAccess", () => ({
resolveCloudflareAccessContext:
selfHostedAuthMocks.resolveCloudflareAccessContext,
}));
vi.mock("@/middleware/ensure-user/delegated", () => ({
resolveLocalNoAuthContext: selfHostedAuthMocks.resolveLocalNoAuthContext,
}));
vi.mock("@/lib/auth", () => ({
getHostedBaseUrl: () => "https://open-seo.test",
}));
vi.mock("@/server/mcp/server", () => ({
createOpenSeoMcpServer: (props?: unknown) => {
selfHostedAuthMocks.createOpenSeoMcpServer(props);
return new McpServer({
name: "OpenSEO MCP",
title: "OpenSEO",
version: "0.0.11",
description: "SEO research tools for AI agents",
websiteUrl: "https://openseo.so",
icons: [
{
src: "https://openseo.so/android-chrome-512x512.png",
mimeType: "image/png",
sizes: ["512x512"],
},
],
});
},
}));
vi.mock("agents/mcp/server", () => ({
createMcpHandler: (
_createServer: () => McpServer,
options: CreateMcpHandlerOptions,
) => {
selfHostedAuthMocks.createMcpHandler(options);
return async () => Response.json({ handledBy: "modern" }, { status: 202 });
},
}));
const ctx: ExecutionContext = {
waitUntil() {},
passThroughOnException() {},
props: {},
};
function createMcpRequest(headers?: Record<string, string>) {
return new Request("https://open-seo.test/mcp", {
method: "POST",
headers: {
Accept: "application/json, text/event-stream",
"Content-Type": "application/json",
...headers,
},
body: JSON.stringify({
jsonrpc: "2.0",
id: 1,
method: "tools/list",
}),
});
}
// The modern (2026-07-28) era is selected by the per-request `_meta` envelope
// claim; without it every POST classifies as legacy traffic.
function createModernMcpRequest(headers?: Record<string, string>) {
return new Request("https://open-seo.test/mcp", {
method: "POST",
headers: {
Accept: "application/json, text/event-stream",
"Content-Type": "application/json",
...headers,
},
body: JSON.stringify({
jsonrpc: "2.0",
id: 1,
method: "tools/list",
params: {
_meta: {
"io.modelcontextprotocol/protocolVersion": "2026-07-28",
"io.modelcontextprotocol/clientCapabilities": {},
},
},
}),
});
}
function hostedProps(scopes: string[] = ["mcp"]) {
return createWorkersOAuthMcpProps({
userId: "user-1",
userEmail: "[email protected]",
organizationId: "org-1",
baseUrl: "https://open-seo.test",
clientId: "client-1",
scopes,
});
}
describe("handleSelfHostedOpenSeoMcpRequest", () => {
beforeEach(() => {
selfHostedAuthMocks.resolveLocalNoAuthContext.mockResolvedValue({
userId: "local-admin",
userEmail: "admin@localhost",
organizationId: "delegated-local-admin",
});
selfHostedAuthMocks.resolveCloudflareAccessContext.mockResolvedValue({
userId: "cloudflare-user",
userEmail: "[email protected]",
organizationId: "delegated-cloudflare-user",
});
});
it.each([
[
"local_noauth" as const,
selfHostedAuthMocks.resolveLocalNoAuthContext,
{
userId: "local-admin",
userEmail: "admin@localhost",
organizationId: "delegated-local-admin",
},
],
[
"cloudflare_access" as const,
selfHostedAuthMocks.resolveCloudflareAccessContext,
{
userId: "cloudflare-user",
userEmail: "[email protected]",
organizationId: "delegated-cloudflare-user",
},
],
])(
"accepts %s MCP requests with the resolved identity",
async (authMode, resolver, identity) => {
const response = await handleSelfHostedOpenSeoMcpRequest(
createMcpRequest(),
authMode,
{},
ctx,
);
expect(response.status).toBe(200);
expect(response.headers.get("content-type")).toContain(
"application/json",
);
expect(response.headers.get("connection")).not.toBe("keep-alive");
expect(resolver).toHaveBeenCalled();
expect(selfHostedAuthMocks.createOpenSeoMcpServer).toHaveBeenCalledWith({
[MCP_AUTH_CONTEXT_PROP]: {
...identity,
baseUrl: "https://open-seo.test",
},
});
// Self-hosted must not pin Origins to the request's own Host — the
// handler's localhost-class default is the rebinding-safe choice.
expect(selfHostedAuthMocks.createMcpHandler).toHaveBeenCalledWith(
expect.objectContaining({
allowedOriginHostnames: undefined,
legacy: "reject",
}),
);
},
);
it("answers OPTIONS preflight without resolving an auth context", async () => {
const response = await handleSelfHostedOpenSeoMcpRequest(
new Request("https://open-seo.test/mcp", { method: "OPTIONS" }),
"cloudflare_access",
{},
ctx,
);
expect(response.status).toBe(200);
expect(await response.text()).toBe("");
expect(
selfHostedAuthMocks.resolveCloudflareAccessContext,
).not.toHaveBeenCalled();
expect(selfHostedAuthMocks.createOpenSeoMcpServer).not.toHaveBeenCalled();
});
});
describe("handleAuthenticatedOpenSeoMcpRequest", () => {
beforeEach(() => {
authRepositoryMocks.getMembership.mockResolvedValue({ role: "owner" });
});
it("accepts the provider's encrypted identity and MCP scope fallback", async () => {
const props = hostedProps();
const response = await handleAuthenticatedOpenSeoMcpRequest(
createMcpRequest(),
props,
{},
{ ...ctx, props },
);
expect(response.status).toBe(200);
expect(response.headers.get("content-type")).toContain("application/json");
expect(response.headers.get("connection")).not.toBe("keep-alive");
expect(selfHostedAuthMocks.createMcpHandler).toHaveBeenCalledWith(
expect.objectContaining({
allowedOriginHostnames: [
"open-seo.test",
"pghallcbnfabbgfijhbcldaapmgidnaa",
],
legacy: "reject",
}),
);
// The transport checks membership in the token's org and stamps the
// member row's role into the props it hands the server; roles are never
// baked into tokens.
expect(authRepositoryMocks.getMembership).toHaveBeenCalledWith(
"user-1",
"org-1",
);
expect(selfHostedAuthMocks.createOpenSeoMcpServer).toHaveBeenCalledWith({
[MCP_AUTH_CONTEXT_PROP]: {
...props[MCP_AUTH_CONTEXT_PROP],
role: "owner",
},
});
});
it("routes modern-era requests to the SDK handler", async () => {
const props = hostedProps();
const response = await handleAuthenticatedOpenSeoMcpRequest(
createModernMcpRequest(),
props,
{},
{ ...ctx, props },
);
expect(response.status).toBe(202);
expect(await response.json()).toEqual({ handledBy: "modern" });
// The modern handler owns server construction; the legacy leg must not
// have built one.
expect(selfHostedAuthMocks.createOpenSeoMcpServer).not.toHaveBeenCalled();
});
it("accepts a legacy request from the SurfMind Chrome extension", async () => {
const props = hostedProps();
const response = await handleAuthenticatedOpenSeoMcpRequest(
createMcpRequest({
Origin: "chrome-extension://pghallcbnfabbgfijhbcldaapmgidnaa",
}),
props,
{},
{ ...ctx, props },
);
expect(response.status).toBe(200);
expect(selfHostedAuthMocks.createOpenSeoMcpServer).toHaveBeenCalledWith({
[MCP_AUTH_CONTEXT_PROP]: {
...props[MCP_AUTH_CONTEXT_PROP],
role: "owner",
},
});
});
it("rejects provider props missing the OAuth client identity", async () => {
// Hosted tokens always carry clientId/scopes; a token without them must
// fail closed rather than skip scope enforcement.
const props = createWorkersOAuthMcpProps({
userId: "user-1",
userEmail: "[email protected]",
organizationId: "org-1",
baseUrl: "https://open-seo.test",
});
const response = await handleAuthenticatedOpenSeoMcpRequest(
createMcpRequest(),
props,
{},
{ ...ctx, props },
);
expect(response.status).toBe(403);
});
// The grant is bound to its consent-time org for life: once the member row
// is gone the token is dead, never rebound to another org the user is in.
// The Bearer challenge sends compliant clients back through OAuth.
it("rejects a token whose consent-time membership is gone", async () => {
authRepositoryMocks.getMembership.mockResolvedValue(null);
const props = hostedProps();
const response = await handleAuthenticatedOpenSeoMcpRequest(
createMcpRequest(),
props,
{},
{ ...ctx, props },
);
expect(response.status).toBe(401);
expect(response.headers.get("WWW-Authenticate")).toBe(
'Bearer error="invalid_token"',
);
expect(selfHostedAuthMocks.createOpenSeoMcpServer).not.toHaveBeenCalled();
});
it("rejects an OAuth client without the MCP scope", async () => {
const props = hostedProps(["offline_access"]);
const response = await handleAuthenticatedOpenSeoMcpRequest(
createMcpRequest(),
props,
{},
{ ...ctx, props },
);
expect(response.status).toBe(403);
});
});