Open source alternative to Semrush and Ahrefs
TypeScript backlink-analysisgoogle-search-console-mcpkeyword-researchmcpseoseo-agentseo-auditseo-automationseo-skillsseo-toolssite-audit
import {
ToolError,
defineTools,
everyApp,
toolResult,
type EveryAppUser,
type ToolDefinition,
type ToolRisk,
} from "@every-app/sdk/server";
import type { CallToolResult } from "@modelcontextprotocol/server";
import { resolveEveryAppUserContext } from "@/middleware/ensure-user/everyApp";
import { asAppError } from "@/server/lib/errors";
import { serveEveryAppRequest } from "@/server/lib/gateway-attribution";
import type { ToolContext } from "@/server/mcp/context";
import { instrumentMcpToolHandler } from "@/server/mcp/instrumentation";
import { objectSchema } from "@/server/mcp/output-schemas";
import {
registerOpenSeoTools,
type OpenSeoToolDefinition,
type ToolArgs,
type ToolSchema,
} from "@/server/mcp/server";
// OpenSEO's MCP tools, served by the Every App gateway: its one MCP
// connector lists them as `openseo_<tool>` beside every other app's, and this
// app's own host serves them under their names. The gateway signs in the
// person, applies the connection's read-only or read-write choice, and calls
// a tool here with a verified identity; OpenSEO never speaks MCP for it.
const INSTRUCTIONS =
"OpenSEO's research tools call DataForSEO, which bills this organization's DataForSEO account per request through the gateway. Start with list_projects: most tools take a projectId. Ask before planned batches of more than a few hundred keywords or pages.";
/**
* Read or write, never destructive: the gateway hides destructive tools from
* AI clients until it has an approval step, and every OpenSEO tool should
* reach them, deletes included.
*/
function riskOf(tool: OpenSeoToolDefinition<ToolSchema>): ToolRisk {
return tool.config.annotations?.readOnlyHint ? "read" : "write";
}
function toolContext(user: EveryAppUser, request: Request) {
return resolveEveryAppUserContext(user).then(
(context): ToolContext => ({
auth: {
userId: context.userId,
userEmail: context.userEmail,
organizationId: context.organizationId,
role: context.role,
// The signed identity names one organization per call; "pinned" keeps
// every tool on it and off member rows, which never authorize here.
scopes: user.scopes,
// The gateway's connection (`oauth:…`, `pat:…`): an external client.
clientId: user.actor.sub,
// The gateway calls the app on its public host.
baseUrl: new URL(request.url).origin,
clientLabel: "Every App",
},
}),
);
}
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
function textOf(result: CallToolResult): string {
return result.content
.flatMap((part) => (part.type === "text" ? [part.text] : []))
.join("\n\n");
}
function everyAppTool<Input extends ToolSchema>(
tool: OpenSeoToolDefinition<Input>,
): ToolDefinition {
const output = objectSchema(tool.config.outputSchema);
const handler = instrumentMcpToolHandler(tool.name, output, tool.handler);
return {
title: tool.config.title,
description: tool.config.description ?? tool.name,
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- riskOf reads only the name and annotations, which don't depend on Input
risk: riskOf(tool as unknown as OpenSeoToolDefinition<ToolSchema>),
idempotent: tool.config.annotations?.idempotentHint,
openWorld: tool.config.annotations?.openWorldHint,
input: objectSchema(tool.config.inputSchema),
output,
handler: async (args, { user, request }) => {
let result: CallToolResult;
try {
// The tool's gateway calls forward the call's identity
// (gateway-attribution.ts).
result = await serveEveryAppRequest(request, user, async () => {
const context = await toolContext(user, request);
return handler(
// oxlint-disable-next-line typescript/no-unsafe-type-assertion -- the SDK validated args against this tool's own inputSchema before calling
args as ToolArgs<Input>,
context,
);
});
} catch (error) {
// What OpenSEO's MCP server shows an agent; anything else stays a
// masked internal error with a reference.
const appError = asAppError(error);
if (appError) throw new ToolError(appError.message);
throw error;
}
const text = textOf(result);
if (result.isError) throw new ToolError(text || "The tool failed.");
const structured = result.structuredContent;
return isRecord(structured) ? toolResult({ text, structured }) : text;
},
};
}
function openSeoToolSet() {
const tools: Record<string, ToolDefinition> = {};
registerOpenSeoTools((tool) => {
tools[tool.name] = everyAppTool(tool);
});
return defineTools(tools, { instructions: INSTRUCTIONS });
}
/**
* Answers the gateway's tools contract (`/__everyapp/tools/*`): the catalog
* at deploy, and each call. Loaded on the first tools request only, like the
* MCP stack in the other modes.
*/
export const everyAppTools = everyApp<Env>(
() => new Response("Not found", { status: 404 }),
{ tools: openSeoToolSet() },
);