Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import type { CallToolResult } from "@modelcontextprotocol/server";
import { describe, expect, it, vi } from "vitest";
import { z } from "zod";
import { instrumentMcpToolHandler } from "./instrumentation";
import { type ToolAuthContext, type ToolContext } from "@/server/mcp/context";
import { AppError } from "@/server/lib/errors";
const mocks = vi.hoisted(() => ({
captureServerError: vi.fn(),
captureServerEvent: vi.fn(),
recordExternalMcpToolCall: vi.fn(),
incrementSelfHostMcpToolCallCount: vi.fn(),
}));
// waitUntil runs the capture promise inline so assertions see the call.
vi.mock("cloudflare:workers", () => ({
waitUntil: (promise: Promise<unknown>) => void promise,
}));
vi.mock("@/server/lib/posthog", () => ({
captureServerError: mocks.captureServerError,
captureServerEvent: mocks.captureServerEvent,
}));
// The real module pulls in @/db (cloudflare:workers env) — mock it out and
// assert the milestone hook at this boundary instead.
vi.mock("@/server/features/activation/mcpActivation", () => ({
recordExternalMcpToolCall: mocks.recordExternalMcpToolCall,
}));
vi.mock("@/server/lib/self-host-telemetry", () => ({
incrementSelfHostMcpToolCallCount: mocks.incrementSelfHostMcpToolCallCount,
}));
const outputSchema = z.object({
items: z.array(z.object({}).passthrough()),
});
function okResult(structuredContent: Record<string, unknown>): CallToolResult {
return { content: [{ type: "text", text: "ok" }], structuredContent };
}
const authContext: ToolAuthContext = {
userId: "user-1",
userEmail: "[email protected]",
organizationId: "org-1",
role: "owner",
clientId: "client-1",
scopes: ["mcp"],
baseUrl: "https://app.openseo.so",
};
const toolContext: ToolContext = { auth: authContext };
describe("instrumentMcpToolHandler", () => {
it("reports an output schema mismatch the SDK would silently reject and marks the usage failed", async () => {
const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () =>
okResult({ items: "not-an-array" }),
);
await wrapped({}, toolContext);
expect(mocks.captureServerError).toHaveBeenCalledTimes(1);
expect(mocks.captureServerError.mock.calls[0][1]).toMatchObject({
errorCode: "MCP_OUTPUT_VALIDATION",
tool: "demo",
});
expect(mocks.captureServerEvent.mock.calls[0][0]).toMatchObject({
event: "mcp:tool_call",
properties: { success: false, error_code: "MCP_OUTPUT_VALIDATION" },
});
});
it("reports and rethrows a reportable handler error", async () => {
const boom = new Error("upstream exploded");
const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () => {
throw boom;
});
await expect(wrapped({}, toolContext)).rejects.toThrow("upstream exploded");
expect(mocks.captureServerError).toHaveBeenCalledTimes(1);
expect(mocks.captureServerError.mock.calls[0][0]).toBe(boom);
expect(mocks.captureServerError.mock.calls[0][2]).toBe("user-1");
});
it("rethrows expected errors without reporting them, as failed usage with no activation", async () => {
const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () => {
throw new AppError("NOT_FOUND");
});
await expect(wrapped({}, toolContext)).rejects.toThrow("NOT_FOUND");
expect(mocks.captureServerError).not.toHaveBeenCalled();
expect(mocks.captureServerEvent.mock.calls[0][0]).toMatchObject({
event: "mcp:tool_call",
properties: { success: false, error_code: "NOT_FOUND" },
});
expect(mocks.recordExternalMcpToolCall).not.toHaveBeenCalled();
});
it("explains an out-of-credits call to the agent with a billing link instead of the bare code", async () => {
const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () => {
throw new AppError("INSUFFICIENT_CREDITS");
});
await expect(wrapped({}, toolContext)).rejects.toThrow(
"The organization owner can add credits at https://app.openseo.so/billing",
);
});
it("captures a usage event and the activation milestone for a successful external call", async () => {
const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () =>
okResult({ items: [{ domain: "example.com" }] }),
);
const result = await wrapped({}, toolContext);
expect(result.structuredContent).toEqual({
items: [{ domain: "example.com" }],
});
expect(mocks.captureServerError).not.toHaveBeenCalled();
expect(mocks.captureServerEvent).toHaveBeenCalledTimes(1);
expect(mocks.incrementSelfHostMcpToolCallCount).toHaveBeenCalledTimes(1);
expect(mocks.captureServerEvent.mock.calls[0][0]).toMatchObject({
distinctId: "user-1",
event: "mcp:tool_call",
organizationId: "org-1",
properties: {
tool: "demo",
success: true,
client_id: "client-1",
source: "mcp_client",
},
});
expect(mocks.recordExternalMcpToolCall).toHaveBeenCalledExactlyOnceWith(
"org-1",
);
});
it.each([
[
"structured error",
z.object({
status: z.enum(["ok", "error"]),
error: z.object({ code: z.string() }).optional(),
}),
{ status: "error", error: { code: "ga4_not_connected" } },
"ga4_not_connected",
],
[
"ok-false",
z.object({ ok: z.boolean(), reason: z.string().optional() }),
{ ok: false, reason: "audit_not_ready" },
"audit_not_ready",
],
])(
"marks a %s tool result as failed usage without recording activation",
async (_label, schema, structuredContent, errorCode) => {
const wrapped = instrumentMcpToolHandler("demo", schema, async () =>
okResult(structuredContent),
);
await wrapped({}, toolContext);
expect(mocks.captureServerEvent.mock.calls[0][0]).toMatchObject({
event: "mcp:tool_call",
properties: { success: false, error_code: errorCode },
});
expect(mocks.recordExternalMcpToolCall).not.toHaveBeenCalled();
},
);
it("skips the activation milestone for first-party (null clientId) calls", async () => {
const wrapped = instrumentMcpToolHandler("demo", outputSchema, async () =>
okResult({ items: [] }),
);
await wrapped({}, { auth: { ...authContext, clientId: null } });
expect(mocks.recordExternalMcpToolCall).not.toHaveBeenCalled();
});
});