mcp-server.mjs

Functions

Imports

It imports mcp-login.mjs, rate-limit/limit.mjs. No module of this repo imports it.

Source

1// The admin MCP servers' shared scaffold (shared-code sweep round 2, item 4): the era router with its prior-era shim, the
2// API leg's transport, the rate limit on the MCP door, and the per-call scope check. Each admin MCP (dustinedwards-info,
3// foxing) is a wrapper over its site's own API, which owns every rule; nothing here interprets one.
4//
5// No dependency, like the rest of the package: the MCP SDK and `agents` are the caller's, and the era router is handed
6// their two functions.
7
8import { limit } from "./rate-limit/limit.mjs";
9import { isAdminUser } from "./mcp-login.mjs";
10
11// ---------------------------------------------------------------------------------------------------------------------
12// THE ERA ROUTER, and the prior-era shim.
13//
14// MCP 2026-07-28 removed the `initialize` handshake, sessions and the GET stream. The primary handler is built
15// `legacy: "reject"`: stateless and modern-only, with no compatibility thinking in it. A legacy client against a
16// modern-only server fails with no fall-forward, and the clients these servers serve still open legacy, so prior-era
17// traffic is diverted here, in front of it, as the library documents on `isLegacyRequest`. `createMcpHandler` could
18// serve both eras from one handler with `legacy: "stateless"`, but then the compatibility path would live inside the
19// library behind a flag; routing in front makes the seam real.
20//
21// REMOVAL CONDITION. Stop passing `isLegacyRequest` when dustinedwards-info's probe (`mcp/scripts/probe-report.mjs`)
22// shows the target clients opening with `server/discover` instead of `initialize`. Last measured: Claude Code 2.1.203
23// (2026-07-29) and claude.ai (2026-07-30), both LEGACY (initialize, 2025-11-25). Delete on a capture, never on a release
24// note. Without `isLegacyRequest` the router is a modern-only server.
25// ---------------------------------------------------------------------------------------------------------------------
26
27/**
28 * Answers one MCP request in the era that can. A request `isLegacyRequest` calls legacy goes to a `legacy: "stateless"`
29 * handler (a fresh server per request; GET and DELETE answered 405, as the modern handler does); everything else,
30 * malformed envelopes included, to the `legacy: "reject"` handler, which owns those error answers. The predicate reads
31 * the body, so it is given a clone. Both handlers are built per call over the same factory.
32 *
33 * @param {Request} request
34 * @param {unknown} env
35 * @param {unknown} ctx
36 * @param {{ factory: unknown, options: Record<string, unknown>, createMcpHandler: Function, isLegacyRequest?: (request: Request) => Promise<boolean> | boolean }} sdk
37 * @returns {Promise<Response>}
38 */
39export async function routeMcpEra(request, env, ctx, { factory, options, createMcpHandler, isLegacyRequest }) {
40  const legacy = isLegacyRequest && (await isLegacyRequest(request.clone())) ? "stateless" : "reject";
41  return createMcpHandler(factory, { ...options, legacy })(request, env, ctx);
42}
43
44// ---------------------------------------------------------------------------------------------------------------------
45// THE API LEG: this Worker to its site, over a service binding. Still HTTP, not an in-process call: the request carries
46// the same bearer and crosses the same authentication and rate limit as any other. The bearer identifies WHAT this Worker
47// may do and is never the client's OAuth token. A failure here reads differently from a refusal by the API.
48// ---------------------------------------------------------------------------------------------------------------------
49
50/** Why the API leg could not produce an answer: not configured, not reachable, or not JSON. Never an API refusal. */
51export class ApiLegError extends Error {
52  /**
53   * @param {string} message
54   * @param {"unconfigured" | "unreachable" | "malformed"} kind
55   * @param {number} [status] the HTTP status, when an answer came back (malformed)
56   */
57  constructor(message, kind, status) {
58    super(message);
59    this.name = "ApiLegError";
60    /** @type {"unconfigured" | "unreachable" | "malformed"} */
61    this.kind = kind;
62    /** @type {number | undefined} */
63    this.status = status;
64  }
65}
66
67/**
68 * One request over the API leg, to `SITE_ORIGIN + path` through the `binding` named in `leg`, with the bearer from the
69 * `token` var (refused under 32 characters, which the sites' APIs refuse anyway) unless `anonymous`. Returns the status,
70 * whether it was 2xx, and the JSON body (null when empty). Throws ApiLegError when unconfigured, unreachable or not JSON.
71 *
72 * @param {Record<string, unknown>} env
73 * @param {{ binding: string, token: string, api: string, userAgent: string, require?: string[] }} leg
74 * @param {string} path
75 * @param {{ method?: string, headers?: Record<string, string>, json?: unknown, anonymous?: boolean }} [init]
76 * @returns {Promise<{ status: number, ok: boolean, body: unknown }>}
77 */
78export async function callApi(env, leg, path, init = {}) {
79  const unconfigured = (/** @type {string} */ what) => new ApiLegError(`The MCP server is not configured: ${what}. Not configured means not open.`, "unconfigured");
80  const fetcher = /** @type {{ fetch?: unknown } | undefined} */ (env[leg.binding]);
81  if (!fetcher || typeof fetcher.fetch !== "function") throw unconfigured(`the ${leg.binding} service binding is missing`);
82  if (!env.SITE_ORIGIN) throw unconfigured("SITE_ORIGIN is unset");
83  const token = env[leg.token];
84  if (!init.anonymous && (typeof token !== "string" || token.length < 32)) throw unconfigured(`${leg.token} is unset or shorter than 32 characters`);
85  for (const name of leg.require ?? []) if (typeof env[name] !== "string" || !String(env[name]).trim()) throw unconfigured(`${name} is unset`);
86
87  const headers = new Headers({ accept: "application/json", "user-agent": leg.userAgent, ...init.headers });
88  if (!init.anonymous) headers.set("authorization", `Bearer ${token}`);
89  if (init.json !== undefined) headers.set("content-type", "application/json");
90  /** @type {Response} */
91  let response;
92  try {
93    response = await /** @type {{ fetch: (url: string, init: RequestInit) => Promise<Response> }} */ (fetcher).fetch(new URL(path, String(env.SITE_ORIGIN)).toString(), {
94      method: init.method ?? (init.json === undefined ? "GET" : "POST"),
95      headers,
96      body: init.json === undefined ? undefined : JSON.stringify(init.json),
97    });
98  } catch (cause) {
99    throw new ApiLegError(`${leg.api} could not be reached: ${cause instanceof Error ? cause.message : String(cause)}`, "unreachable");
100  }
101  const raw = await response.text();
102  try {
103    return { status: response.status, ok: response.ok, body: raw ? JSON.parse(raw) : null };
104  } catch {
105    throw new ApiLegError(`${leg.api} returned status ${response.status} with a body that is not JSON.`, "malformed", response.status);
106  }
107}
108
109// ---------------------------------------------------------------------------------------------------------------------
110// THE DOOR'S RATE LIMIT, on the family's one limiter. Verify with a concurrent burst: a sequential loop straddles the
111// window boundary and refuses nothing, which reads exactly like a dead limiter.
112// ---------------------------------------------------------------------------------------------------------------------
113
114/** Requests one identity may make per minute through the MCP door. */
115export const MCP_PER_MINUTE = 30;
116
117/**
118 * One request by `identity` (`admin:<email>`, `agent:<name>`, `register:<ip>`). A caller may ask for a lower ceiling
119 * (registration does), never a higher one. Fails CLOSED when the binding is missing or failing, and then asks the
120 * client to wait the whole window.
121 *
122 * @param {Parameters<typeof limit>[0]} namespace
123 * @param {string} identity
124 * @param {number} [perMinute]
125 * @returns {Promise<{ allowed: boolean, retryAfter: number }>}
126 */
127export async function checkRateLimit(namespace, identity, perMinute) {
128  const ceiling = perMinute !== undefined && Number.isInteger(perMinute) && perMinute >= 1 && perMinute < MCP_PER_MINUTE ? perMinute : MCP_PER_MINUTE;
129  const verdict = await limit(namespace, identity, [{ limit: ceiling, windowSeconds: 60 }], { onUnavailable: "refuse" });
130  return { allowed: verdict.status === "ok", retryAfter: verdict.status === "unavailable" ? 60 : verdict.retryAfterSeconds };
131}
132
133/**
134 * A plain-text refusal that is never cached or indexed.
135 * @param {string} body
136 * @param {number} status
137 * @param {Record<string, string>} [headers]
138 */
139export function refuse(body, status, headers = {}) {
140  return new Response(body, {
141    status,
142    headers: { "content-type": "text/plain; charset=utf-8", "cache-control": "no-store", "x-robots-tag": "noindex, nofollow", ...headers },
143  });
144}
145
146// ---------------------------------------------------------------------------------------------------------------------
147// LEAST SCOPE FIRST, AND THE PER-CALL OWNERSHIP CHECK (ruling mcp-2026-10-10, rules 12.1 and 12.3). Read is what every
148// connection gets; write is ticked on the consent page (or, on dustinedwards-info, named for an agent in AGENT_WRITE).
149// Every id a tool takes names a record only the site's administrator owns, so proving the caller owns it is proving the
150// caller IS that administrator, on every call: a grant is long lived.
151// ---------------------------------------------------------------------------------------------------------------------
152
153/**
154 * The read and write scopes for a server's scope prefix (`dei` gives `dei.read` and `dei.write`).
155 * @param {string} prefix
156 */
157export function mcpScopes(prefix) {
158  const read = `${prefix}.read`;
159  const write = `${prefix}.write`;
160  return { read, write, all: [read, write] };
161}
162
163/**
164 * The audit name of a caller: the signed-in email or the agent principal, never a credential.
165 * @param {{ kind: "admin", props: { email: string } } | { kind: "agent", principal: string }} caller
166 */
167export function callerName(caller) {
168  return caller.kind === "admin" ? `access:${caller.props.email}` : `agent:${caller.principal}`;
169}
170
171/**
172 * Null when the call may proceed, or the refusal to show the caller.
173 * @param {{ ADMIN_EMAIL?: string }} env
174 * @param {({ kind: "admin", props: { email: string }, scopes: readonly string[] } | { kind: "agent", principal: string, scopes: readonly string[] }) | undefined} caller
175 * @param {string} scope
176 * @param {{ site: string, scopes: { read: string, write: string } }} server
177 * @returns {string | null}
178 */
179export function authorizeCall(env, caller, scope, { site, scopes }) {
180  if (!caller) return "Refused: no caller identity reached this tool call. Connect again through the OAuth flow.";
181  if (caller.kind === "admin" && !isAdminUser(env, caller.props)) {
182    return `Refused: this grant does not belong to the administrator of ${site}, so it owns none of the records this tool names.`;
183  }
184  if (caller.kind === "agent" && !/^[a-z0-9_]+$/.test(caller.principal)) return "Refused: the agent principal is malformed.";
185  if (caller.scopes.includes(scope)) return null;
186  if (scope !== scopes.write) return "Refused: this connection holds no read scope. Reconnect through the OAuth flow.";
187  return caller.kind === "agent"
188    ? `Refused: this agent key holds read access only (${scopes.read}), and this tool changes ${site}. Add the agent's name to AGENT_WRITE.`
189    : `Refused: this connection holds read access only (${scopes.read}), and this tool changes ${site}. Reconnect and tick "Allow changes" on the consent page.`;
190}