@dokebi/mcp 0.0.0-stage → 0.1.0

package/dist/plugin.js

@@ -0,0 +1,541 @@
+import { performance } from 'node:perf_hooks';
+import { Transform } from 'node:stream';
+import { addExtensionDependencies, createExtension, definePlugin, definePoint, optionalDependency, providerDependency, readExtensionEntry, } from '@dokebi/core';
+import { dependency as oauthDependency } from '@dokebi/oauth/dependency';
+import { appUrlMatch, errorTranslators, pluginRouteIds } from '@dokebi/web/points';
+import { McpCallReporter } from './calls.js';
+import { McpError } from './errors.js';
+import { EXTENSION_FILE, McpExtension, mcpHooks, } from './extension.js';
+import { rpcError } from './jsonrpc.js';
+import { options as declaration } from './options.js';
+import { INVALID_REQUEST, METHOD_NOT_ALLOWED, SUPPORTED_VERSIONS } from './protocol.js';
+import { compilePrompts, compileResources, compileTools } from './registry.js';
+import { McpRunner } from './runner.js';
+import { McpServer } from './server.js';
+import { mcpPrompts, mcpResources, mcpTools } from './tool.js';
+/** `core:describe` of @dokebi/core 0.4.2, declared by name so older cores keep working. */
+const describePoint = definePoint('core:describe');
+/** dokebi-web 0.4.3 or later: `register`, route `seal`, the error translator point. */
+const web = providerDependency({
+    name: 'dokebi-web',
+    version: '^0.4.3',
+    packageName: '@dokebi/web',
+    load: () => import('@dokebi/web'),
+});
+const rateLimit = optionalDependency({
+    name: 'dokebi-rate-limit',
+    version: '^0.1.1',
+});
+/** How this plugin reads its entry module (core readExtensionEntry, D-0111 §7). */
+const ENTRY = {
+    plugin: 'dokebi-mcp',
+    error: McpError,
+    file: EXTENSION_FILE,
+    base: 'McpExtension',
+    entry: 'The MCP entry',
+    noun: 'MCP',
+};
+/** The entry as given (optional: every hook has a default), resolved once. */
+class McpEntryInput {
+    #extension;
+    #resolved;
+    constructor(input) {
+        this.#extension = readExtensionEntry(input, ENTRY).extension;
+    }
+    resolve() {
+        this.#resolved ??= this.#resolve();
+        return this.#resolved;
+    }
+    #resolve() {
+        const dependencies = new Map([
+            [web.name, web],
+            [oauthDependency.name, oauthDependency],
+            [rateLimit.name, rateLimit],
+        ]);
+        if (this.#extension === undefined)
+            return Object.freeze({
+                hooks: undefined,
+                overridden: new Set(),
+                dependencies: Object.freeze([...dependencies.values()]),
+            });
+        const created = createExtension(this.#extension, McpExtension);
+        const overridden = new Set(created.overridden);
+        const hooks = mcpHooks(created.instance);
+        if (overridden.has('dependencies')) {
+            const declared = hooks.dependencies();
+            addExtensionDependencies(dependencies, declared, {
+                error: McpError,
+                code: 'INVALID_HOOK_RESULT',
+                file: EXTENSION_FILE,
+                data: { hook: 'dependencies' },
+            });
+        }
+        return Object.freeze({
+            hooks,
+            overridden,
+            dependencies: Object.freeze([...dependencies.values()]),
+        });
+    }
+}
+const JSON_TYPE = /^application\/(?:[\w.+-]+\+)?json\s*(?:;|$)/i;
+/**
+ * An allowed origin as browsers send it (the serialized origin: lower-case host, no default port,
+ * the short IPv6 form): `https://App.example:443` matches the `Origin: https://app.example` it
+ * stands for. The options pattern admits only origins the URL parser reads.
+ */
+function originKey(origin) {
+    return new URL(origin).origin.toLowerCase();
+}
+/** Counts body bytes before Fastify reads them: the limit answers BODY_TOO_LARGE, not 400. */
+class BodyLimit extends Transform {
+    #limit;
+    #seen = 0;
+    constructor(limit) {
+        super();
+        this.#limit = limit;
+    }
+    _transform(chunk, _encoding, done) {
+        this.#seen += chunk.length;
+        if (this.#seen > this.#limit)
+            done(tooLarge(this.#limit));
+        else
+            done(null, chunk);
+    }
+}
+function tooLarge(limit) {
+    return new McpError('BODY_TOO_LARGE', `The request body is larger than ${limit} bytes`, {
+        status: 413,
+        hint: `The request is too large: send tool arguments (attachments included) of at most ${limit} bytes, or split them over several calls.`,
+        fix: `Raise options.dokebi-mcp.bodyLimitBytes (now ${limit}) when tools must take larger arguments; it changes this route only. A proxy in front (nginx client_max_body_size) must allow it too.`,
+        data: { limit },
+    });
+}
+class McpRuntime {
+    #options;
+    #resolved;
+    /** What a reload changes (D-0154): set in setup. */
+    #live;
+    /**
+     * D-0154: the tool deadline, the result and picture limits, the batch size, the list cache time,
+     * the resource URI limit and the allowed origins, for the next request. The path, the resource, the route, the body
+     * limit, the rate limits and the server identity need a restart.
+     */
+    reload({ options }) {
+        return {
+            apply: () => {
+                const live = this.#live;
+                if (!live)
+                    return;
+                live.runner.update({
+                    timeoutMs: options.toolTimeoutMs,
+                    resultMaxChars: options.resultMaxChars,
+                    images: Object.freeze({
+                        imageMaxBytes: options.imageMaxBytes,
+                        imageTotalMaxBytes: options.imageTotalMaxBytes,
+                        maxImages: options.maxImages,
+                    }),
+                });
+                live.server.update({
+                    maxBatch: options.maxBatch,
+                    listTtlMs: options.listTtlMs,
+                    uriMaxChars: options.uriMaxChars,
+                });
+                live.origins.clear();
+                live.origins.add(live.own);
+                for (const origin of options.allowedOrigins)
+                    live.origins.add(originKey(origin));
+                live.logger.log('debug', 'MCP options reloaded', {
+                    code: 'MCP_RELOADED',
+                    toolTimeoutMs: options.toolTimeoutMs,
+                    resultMaxChars: options.resultMaxChars,
+                    allowedOrigins: options.allowedOrigins.length,
+                });
+            },
+        };
+    }
+    constructor(options, resolved) {
+        this.#options = options;
+        this.#resolved = resolved;
+    }
+    #declared(dependency) {
+        const declared = this.#resolved.dependencies.find((item) => item.name === dependency?.name);
+        return declared ?? dependency;
+    }
+    /** Bucket → limiter, every tool bucket covered when limits are set. */
+    #limiters(context, buckets) {
+        const limits = this.#options.limits;
+        const result = new Map();
+        if (Object.keys(limits).length === 0)
+            return result;
+        const api = context.getOptionalDependency(rateLimit);
+        if (api === undefined)
+            throw new McpError('RATE_LIMIT_REQUIRED', 'dokebi-mcp.limits is set but @dokebi/rate-limit is not registered', {
+                fix: 'npx dokebi add @dokebi/rate-limit (with the policies), or remove options.dokebi-mcp.limits.',
+            });
+        for (const [bucket, policy] of Object.entries(limits)) {
+            if (!api.names.includes(policy))
+                throw new McpError('RATE_LIMIT_REQUIRED', `dokebi-mcp.limits.${bucket} names ${policy}, which is not a policy of @dokebi/rate-limit`, {
+                    fix: `Add policies.${policy} to options.dokebi-rate-limit, or use one of: ${api.names.join(', ')}.`,
+                    data: { bucket, policy },
+                });
+            result.set(bucket, api.limiter(policy));
+        }
+        for (const [user, bucket] of buckets)
+            if (!result.has(bucket))
+                throw new McpError('RATE_LIMIT_REQUIRED', `dokebi-mcp.limits has no policy for the bucket ${bucket} (${user})`, {
+                    fix: `Add limits.${bucket}: <policy> to options.dokebi-mcp, or give the tool a bucket that has one (prompts and resources use read).`,
+                    data: { user, bucket },
+                });
+        return result;
+    }
+    async setup(context) {
+        const started = performance.now();
+        const options = this.#options;
+        const logger = context.logger;
+        const server = context.getDependency(web);
+        const oauth = context.getDependency(oauthDependency);
+        let info;
+        try {
+            info = oauth.resourceInfo(options.resource);
+        }
+        catch (cause) {
+            throw new McpError('INVALID_OPTIONS', `dokebi-mcp.resource ${options.resource} is not a resource of dokebi-oauth`, {
+                cause,
+                fix: `Set options.dokebi-mcp.resource to one of: ${oauth.resources.join(', ')} (options.dokebi-oauth.resources).`,
+            });
+        }
+        const uri = new URL(info.uri);
+        const path = options.path ?? (uri.pathname === '' ? '/' : uri.pathname);
+        if (options.path !== undefined && options.path !== uri.pathname)
+            logger.log('warn', 'The MCP route path differs from the path of its resource URI', {
+                code: 'MCP_PATH_DIFFERS',
+                path: options.path,
+                resource: info.uri,
+                fix: 'Leave options.dokebi-mcp.path out unless a proxy changes the path between clients and this app.',
+            });
+        const scopes = new Set(Object.keys(info.scopes));
+        const tools = compileTools(context.collect(mcpTools), scopes);
+        const prompts = compilePrompts(context.collect(mcpPrompts), scopes);
+        const resources = compileResources(context.collect(mcpResources), scopes);
+        const limiters = this.#limiters(context, new Map([
+            ...tools.map((tool) => [`the tool ${tool.name}`, tool.bucket]),
+            // Prompts and resources take tokens of the read bucket.
+            ...(prompts.length || resources.length ? [['prompts and resources', 'read']] : []),
+        ]));
+        const translators = context.collect(errorTranslators);
+        const hookBase = Object.freeze({
+            app: context.app,
+            getDependency: (dependency) => context.getDependency(this.#declared(dependency)),
+            logger,
+        });
+        const { hooks, overridden } = this.#resolved;
+        let instructions = options.instructions;
+        if (hooks && overridden.has('instructions')) {
+            const given = await hooks.instructions(Object.freeze({ ...hookBase, signal: context.signal, request: undefined }));
+            if (given !== undefined &&
+                (typeof given !== 'string' || given === '' || given.length > 16_000))
+                throw new McpError('INVALID_HOOK_RESULT', 'instructions() must return a string of 1-16000 characters or undefined', {
+                    fix: `Return the server instructions (or undefined) from instructions() in ${EXTENSION_FILE}.`,
+                    data: { hook: 'instructions' },
+                });
+            if (given !== undefined)
+                instructions = given;
+        }
+        const runner = new McpRunner({
+            logger,
+            timeoutMs: options.toolTimeoutMs,
+            resultMaxChars: options.resultMaxChars,
+            images: Object.freeze({
+                imageMaxBytes: options.imageMaxBytes,
+                imageTotalMaxBytes: options.imageTotalMaxBytes,
+                maxImages: options.maxImages,
+            }),
+            limiters,
+            hooks,
+            overridden,
+            hookContext: hookBase,
+            translators,
+            appSignal: context.signal,
+            logRepeatWindowMs: options.logRepeatWindowMs,
+        });
+        context.defer(() => runner.flush());
+        // D-0134: the onCall hook, after each response; never awaited, at most onCallMaxPending.
+        const reporter = hooks && overridden.has('onCall')
+            ? new McpCallReporter({
+                hooks,
+                logger,
+                hookContext: hookBase,
+                appSignal: context.signal,
+                maxPending: options.onCallMaxPending,
+                logRepeatWindowMs: options.logRepeatWindowMs,
+            })
+            : undefined;
+        if (reporter)
+            context.defer(() => reporter.close());
+        const serverInfo = Object.freeze({
+            name: options.name ?? info.name,
+            version: options.version,
+            ...(options.title === undefined ? {} : { title: options.title }),
+        });
+        const mcp = new McpServer({
+            runner,
+            tools,
+            prompts,
+            resources,
+            serverInfo,
+            instructions,
+            metadataUrl: info.metadataUrl,
+            logger,
+            maxBatch: options.maxBatch,
+            listTtlMs: options.listTtlMs,
+            uriMaxChars: options.uriMaxChars,
+        });
+        const origins = new Set([uri.origin.toLowerCase(), ...options.allowedOrigins.map(originKey)]);
+        this.#live = { runner, server: mcp, origins, own: uri.origin.toLowerCase(), logger };
+        const resource = options.resource;
+        const limit = options.bodyLimitBytes;
+        // D-0142: the route id (`mcp.endpoint`, or options.dokebi-mcp.routeIds.endpoint).
+        const routeIds = pluginRouteIds('dokebi-mcp', ['endpoint'], options.routeIds);
+        const routeId = routeIds.ids.endpoint;
+        // 1. Origin (when a browser sent one), 2. the token, before the body is read (D-0094 §1.4).
+        const checkOrigin = async (request) => {
+            const origin = request.headers.origin;
+            if (origin === undefined || origins.has(origin.toLowerCase()))
+                return;
+            debug(logger, 'MCP origin refused', { origin, routeId });
+            throw new McpError('ORIGIN_REFUSED', 'This origin may not call this MCP server', {
+                status: 403,
+                hint: 'Call the server from its own site or from a server-side client.',
+                fix: 'Add the origin to options.dokebi-mcp.allowedOrigins when a browser page on it must call the server.',
+            });
+        };
+        const authenticate = async (request) => {
+            await oauth.authenticate(request, { resource });
+        };
+        // 3. The body size of this route only, counted before Fastify buffers it.
+        const bodyLimit = async (request, _reply, payload) => {
+            const declared = Number(request.headers['content-length']);
+            if (Number.isFinite(declared) && declared > limit)
+                throw tooLarge(limit);
+            const counter = new BodyLimit(limit);
+            // A source error (a client that went away) reaches Fastify's body reader through the
+            // counter, which answers it. (pipeline() would also destroy the request on the limit error,
+            // and the 413 could not be sent.)
+            payload.on('error', (error) => counter.destroy(error));
+            payload.pipe(counter);
+            return counter;
+        };
+        const handler = async (request, reply) => {
+            const state = oauth.of(request);
+            const grant = state.grant;
+            if (grant === undefined)
+                throw new McpError('INTERNAL', 'The MCP route ran without a grant', {
+                    fix: 'Report this: the token check of dokebi-mcp did not run before the handler.',
+                });
+            const contentType = request.headers['content-type'];
+            if (typeof contentType !== 'string' || !JSON_TYPE.test(contentType))
+                return reply
+                    .code(415)
+                    .header('cache-control', 'no-store')
+                    .send(rpcError(null, INVALID_REQUEST, 'Content-Type must be application/json'));
+            const connection = Object.freeze({
+                id: grant.id,
+                userId: grant.userId,
+                clientId: grant.clientId,
+                clientName: grant.clientName,
+                scopes: state.scopes,
+                kind: grant.kind,
+                binding: grant.binding,
+            });
+            const controller = new AbortController();
+            // D-0134: the calls this request ends reach onCall once its response is written (closed).
+            const recorded = reporter ? [] : undefined;
+            let closed = false;
+            let afterClose;
+            reply.raw.once('close', () => {
+                closed = true;
+                if (!reply.raw.writableEnded)
+                    controller.abort(new McpError('CANCELLED', 'The client closed the request'));
+                afterClose?.();
+            });
+            try {
+                const answer = await mcp.handle(request.body, request.headers, {
+                    grant: connection,
+                    request,
+                    signal: controller.signal,
+                    ...(recorded ? { record: (entry) => void recorded.push(entry) } : {}),
+                });
+                reply.code(answer.status).header('cache-control', 'no-store');
+                if (answer.challenge)
+                    reply.header('www-authenticate', answer.challenge);
+                if (answer.body === undefined)
+                    return reply.send();
+                return reply.type('application/json; charset=utf-8').send(JSON.stringify(answer.body));
+            }
+            finally {
+                if (reporter && recorded?.length) {
+                    const deliver = () => reporter.later(recorded, request);
+                    if (closed)
+                        deliver();
+                    else
+                        afterClose = deliver;
+                }
+            }
+        };
+        const notAllowed = async (_request, reply) => reply
+            .code(405)
+            .header('allow', 'POST')
+            .header('cache-control', 'no-store')
+            .send(rpcError(null, METHOD_NOT_ALLOWED, 'This MCP server answers POST only: there is no stream and no session'));
+        // D-0132: the hosts that answer the route (dokebi-mcp.app); unset, every host.
+        const app = options.app;
+        const apps = app === undefined ? undefined : typeof app === 'string' ? [app] : [...app];
+        const routes = async (scope) => {
+            // At boot the app routing of @dokebi/app is final: the resource URI must be a host of
+            // these apps, or clients would reach a 404 (a route bound without it fails in dokebi-web).
+            const match = appUrlMatch(server.apps, info.uri, apps);
+            if (match.kind === 'other-app')
+                throw new McpError('INVALID_OPTIONS', `The MCP resource URI ${info.uri} is on ${match.host}, a domain of app ${match.app}, but dokebi-mcp.app is ${apps?.join(', ')}`, {
+                    fix: `Set options.dokebi-mcp.app to ${match.app} (the app of the resource host), or give options.dokebi-oauth.resources.${resource}.uri a host of ${apps?.join(' or ')}.`,
+                    data: { uri: info.uri, host: match.host, hostApp: match.app, apps },
+                });
+            if (match.kind === 'unconfigured')
+                logger.log('warn', 'The MCP resource host is no domain of dokebi-app', {
+                    code: 'MCP_HOST_UNMAPPED',
+                    uri: info.uri,
+                    host: match.host,
+                    apps,
+                    unknownDomain: match.fallback ?? null,
+                    fix: `Point ${match.host} at ${apps?.[0]} in options.dokebi-app.domains (npx dokebi app link ${apps?.[0]} ${match.host}), unless a proxy sends another Host.`,
+                });
+            // The body is read here as bytes: the JSON-RPC answer to broken JSON (-32700) and to a
+            // batch is the route's own, never a framework 400.
+            scope.removeAllContentTypeParsers();
+            scope.addContentTypeParser('*', { parseAs: 'buffer', bodyLimit: limit }, (_request, body, done) => done(null, body));
+            // MCP clients know nothing of seals and sessions: plain on seal hosts, no CSRF, no cookies.
+            const config = () => routeIds.config('endpoint', { auth: false, csrf: false });
+            scope.route({
+                method: 'POST',
+                url: path,
+                config: config(),
+                seal: false,
+                ...(app === undefined ? {} : { app }),
+                bodyLimit: limit,
+                onRequest: [checkOrigin, authenticate],
+                preParsing: bodyLimit,
+                handler,
+            });
+            scope.route({
+                method: ['GET', 'DELETE'],
+                url: path,
+                config: config(),
+                seal: false,
+                ...(app === undefined ? {} : { app }),
+                handler: notAllowed,
+            });
+        };
+        server.register(routes, {});
+        const buckets = Object.fromEntries([...new Set(tools.map((tool) => tool.bucket))].map((bucket) => [
+            bucket,
+            options.limits[bucket] ?? null,
+        ]));
+        logger.log('debug', 'MCP setup finished', {
+            path,
+            routeId,
+            app: apps ?? null,
+            resource,
+            uri: info.uri,
+            tools: tools.map((tool) => tool.name),
+            prompts: prompts.map((prompt) => prompt.name),
+            resources: resources.map((one) => one.name),
+            limits: buckets,
+            bodyLimitBytes: limit,
+            resultMaxChars: options.resultMaxChars,
+            uriMaxChars: options.uriMaxChars,
+            imageMaxBytes: options.imageMaxBytes,
+            imageTotalMaxBytes: options.imageTotalMaxBytes,
+            maxImages: options.maxImages,
+            toolTimeoutMs: options.toolTimeoutMs,
+            onCallMaxPending: options.onCallMaxPending,
+            allowedOrigins: [...options.allowedOrigins],
+            translators: translators.map((one) => one.plugin),
+            extension: [...overridden],
+            ms: Math.round(performance.now() - started),
+        });
+        // D-0077 B: only `dokebi describe` asks. Names, scopes and settings; never a token.
+        if (context.runtime.describing)
+            context.contribute(describePoint, {
+                section: 'mcp',
+                describe: () => ({
+                    path,
+                    app: apps ?? null,
+                    resource,
+                    uri: info.uri,
+                    metadata: info.metadataUrl,
+                    versions: [...SUPPORTED_VERSIONS],
+                    server: { ...serverInfo },
+                    tools: tools.map((tool) => ({
+                        name: tool.name,
+                        scope: tool.scope,
+                        scopes: tool.scopes,
+                        bucket: tool.bucket,
+                        readOnly: tool.readOnly,
+                        plugin: tool.plugin,
+                    })),
+                    prompts: prompts.map((prompt) => ({
+                        name: prompt.name,
+                        scope: prompt.scope,
+                        scopes: prompt.scopes,
+                        plugin: prompt.plugin,
+                    })),
+                    resources: resources.map((one) => ({
+                        name: one.name,
+                        scope: one.scope,
+                        scopes: one.scopes,
+                        ...(one.uri === undefined ? { template: one.template } : { uri: one.uri }),
+                        plugin: one.plugin,
+                    })),
+                    limits: { ...options.limits },
+                    bodyLimitBytes: limit,
+                    resultMaxChars: options.resultMaxChars,
+                    uriMaxChars: options.uriMaxChars,
+                    imageMaxBytes: options.imageMaxBytes,
+                    imageTotalMaxBytes: options.imageTotalMaxBytes,
+                    maxImages: options.maxImages,
+                    toolTimeoutMs: options.toolTimeoutMs,
+                    onCall: reporter !== undefined,
+                    onCallMaxPending: options.onCallMaxPending,
+                    allowedOrigins: [...options.allowedOrigins],
+                }),
+            });
+        return Object.freeze({
+            path,
+            resource,
+            uri: info.uri,
+            tools: Object.freeze(tools.map((tool) => tool.name)),
+            prompts: Object.freeze(prompts.map((prompt) => prompt.name)),
+            resources: Object.freeze(resources.map((one) => one.name)),
+            versions: SUPPORTED_VERSIONS,
+            callStats: () => reporter?.stats() ?? Object.freeze({ delivered: 0, pending: 0, failed: 0, dropped: 0 }),
+        });
+    }
+}
+function debug(logger, message, fields) {
+    if (logger.isEnabled('debug'))
+        logger.log('debug', message, fields);
+}
+/**
+ * Factory input: `{ app, options?, entry? }`. Options default to `app.config['dokebi-mcp']`;
+ * `entry` is the module of src/infra/mcp/extension.ts (D-0064), optional.
+ */
+export const createPlugin = definePlugin({
+    name: 'dokebi-mcp',
+    version: '0.1.0',
+    core: '^0.4.2',
+    options: declaration,
+    contributes: [describePoint],
+    collects: [mcpTools, mcpPrompts, mcpResources, errorTranslators],
+    entry: (input) => new McpEntryInput(input),
+    dependencies: ({ entry }) => entry.resolve().dependencies,
+    instance: ({ options, entry }) => new McpRuntime(options, entry.resolve()),
+});

package/dist/protocol.d.ts

@@ -0,0 +1,51 @@
+/**
+ * Versions opened with `initialize` and the `MCP-Protocol-Version` header, newest first. The first
+ * one answers an `initialize` that asks for a version this server does not know. claude.ai probes
+ * with 2025-11-25 before it has a token.
+ */
+export declare const LEGACY_VERSIONS: readonly string[];
+/**
+ * Versions without `initialize`: every request carries its version in
+ * `params._meta["io.modelcontextprotocol/protocolVersion"]` and the `MCP-Protocol-Version` and
+ * `Mcp-Method` headers (2026-07-28: claude.ai after sign-in, Claude Code first).
+ */
+export declare const MODERN_VERSIONS: readonly string[];
+/** Every supported version: the `data.supported` of an unsupported-version refusal, in full. */
+export declare const SUPPORTED_VERSIONS: readonly string[];
+/** A request without `MCP-Protocol-Version` (and without `_meta`) is read as this version. */
+export declare const IMPLICIT_VERSION = "2025-03-26";
+/** The only version that accepts JSON-RPC batches (2025-06-18 removed them). */
+export declare const BATCH_VERSION = "2025-03-26";
+/** Most messages in one batch. */
+export declare const MAX_BATCH = 32;
+export declare const META_PROTOCOL_VERSION = "io.modelcontextprotocol/protocolVersion";
+export declare const META_SERVER_INFO = "io.modelcontextprotocol/serverInfo";
+/** Request headers (Fastify gives them in lower case). */
+export declare const HEADER_PROTOCOL_VERSION = "mcp-protocol-version";
+export declare const HEADER_METHOD = "mcp-method";
+export declare const HEADER_NAME = "mcp-name";
+/** A header value that is not plain ASCII arrives as `=?base64?<base64 of UTF-8>?=`. */
+export declare const BASE64_PREFIX = "=?base64?";
+export declare const BASE64_SUFFIX = "?=";
+/** The body field `Mcp-Name` mirrors, per method (modern versions). */
+export declare const NAME_SOURCE: Readonly<Record<string, string>>;
+export declare const PARSE_ERROR = -32700;
+export declare const INVALID_REQUEST = -32600;
+export declare const METHOD_NOT_FOUND = -32601;
+export declare const INVALID_PARAMS = -32602;
+export declare const INTERNAL_ERROR = -32603;
+/** `resources/read` of an unknown URI. */
+export declare const RESOURCE_NOT_FOUND = -32002;
+/** The body of a 403 insufficient_scope answer (the header is what clients act on). */
+export declare const INSUFFICIENT_SCOPE = -32003;
+/** A header disagrees with the body (modern versions). */
+export declare const HEADER_MISMATCH = -32020;
+/** The body of the 405 to GET and DELETE (no stream, no session). */
+export declare const METHOD_NOT_ALLOWED = -32000;
+/** A protocol version this server does not support (`data: { supported, requested }`). */
+export declare const UNSUPPORTED_VERSION = -32022;
+/** Cache hint of modern list results: the same answer for this grant until a deployment. */
+export declare const LIST_TTL_MS = 300000;
+export declare const LIST_CACHE_SCOPE = "private";
+/** A tool name (MCP 2025-11-25): 1-128 of letters, digits, `_`, `-` and `.`. */
+export declare const TOOL_NAME: RegExp;

package/dist/protocol.js

@@ -0,0 +1,67 @@
+/*
+ * MCP protocol constants (D-0094 §1.2), in one place: when the specification moves, the version
+ * lists, the error numbers and the header names change here and nowhere else.
+ */
+/**
+ * Versions opened with `initialize` and the `MCP-Protocol-Version` header, newest first. The first
+ * one answers an `initialize` that asks for a version this server does not know. claude.ai probes
+ * with 2025-11-25 before it has a token.
+ */
+export const LEGACY_VERSIONS = Object.freeze([
+    '2025-11-25',
+    '2025-06-18',
+    '2025-03-26',
+]);
+/**
+ * Versions without `initialize`: every request carries its version in
+ * `params._meta["io.modelcontextprotocol/protocolVersion"]` and the `MCP-Protocol-Version` and
+ * `Mcp-Method` headers (2026-07-28: claude.ai after sign-in, Claude Code first).
+ */
+export const MODERN_VERSIONS = Object.freeze(['2026-07-28']);
+/** Every supported version: the `data.supported` of an unsupported-version refusal, in full. */
+export const SUPPORTED_VERSIONS = Object.freeze([
+    ...MODERN_VERSIONS,
+    ...LEGACY_VERSIONS,
+]);
+/** A request without `MCP-Protocol-Version` (and without `_meta`) is read as this version. */
+export const IMPLICIT_VERSION = '2025-03-26';
+/** The only version that accepts JSON-RPC batches (2025-06-18 removed them). */
+export const BATCH_VERSION = '2025-03-26';
+/** Most messages in one batch. */
+export const MAX_BATCH = 32;
+export const META_PROTOCOL_VERSION = 'io.modelcontextprotocol/protocolVersion';
+export const META_SERVER_INFO = 'io.modelcontextprotocol/serverInfo';
+/** Request headers (Fastify gives them in lower case). */
+export const HEADER_PROTOCOL_VERSION = 'mcp-protocol-version';
+export const HEADER_METHOD = 'mcp-method';
+export const HEADER_NAME = 'mcp-name';
+/** A header value that is not plain ASCII arrives as `=?base64?<base64 of UTF-8>?=`. */
+export const BASE64_PREFIX = '=?base64?';
+export const BASE64_SUFFIX = '?=';
+/** The body field `Mcp-Name` mirrors, per method (modern versions). */
+export const NAME_SOURCE = Object.freeze({
+    'tools/call': 'name',
+    'prompts/get': 'name',
+    'resources/read': 'uri',
+});
+// JSON-RPC error numbers (never mixed with tool errors, which are results with isError).
+export const PARSE_ERROR = -32700;
+export const INVALID_REQUEST = -32600;
+export const METHOD_NOT_FOUND = -32601;
+export const INVALID_PARAMS = -32602;
+export const INTERNAL_ERROR = -32603;
+/** `resources/read` of an unknown URI. */
+export const RESOURCE_NOT_FOUND = -32002;
+/** The body of a 403 insufficient_scope answer (the header is what clients act on). */
+export const INSUFFICIENT_SCOPE = -32003;
+/** A header disagrees with the body (modern versions). */
+export const HEADER_MISMATCH = -32020;
+/** The body of the 405 to GET and DELETE (no stream, no session). */
+export const METHOD_NOT_ALLOWED = -32000;
+/** A protocol version this server does not support (`data: { supported, requested }`). */
+export const UNSUPPORTED_VERSION = -32022;
+/** Cache hint of modern list results: the same answer for this grant until a deployment. */
+export const LIST_TTL_MS = 300_000;
+export const LIST_CACHE_SCOPE = 'private';
+/** A tool name (MCP 2025-11-25): 1-128 of letters, digits, `_`, `-` and `.`. */
+export const TOOL_NAME = /^[A-Za-z0-9_.-]{1,128}$/;