@dokebi/mcp 0.0.0-stage → 0.1.0

package/dist/server.js

@@ -0,0 +1,349 @@
+import { performance } from 'node:perf_hooks';
+import { diagnostics } from '@dokebi/core/libraries';
+import { classify, headerOf, negotiate, unsupported } from './era.js';
+import { isPlainObject, parseBody, readMessage, rpcError, rpcResult, } from './jsonrpc.js';
+import { URI_MAX_CHARS } from './options.js';
+import { BATCH_VERSION, HEADER_PROTOCOL_VERSION, IMPLICIT_VERSION, INSUFFICIENT_SCOPE, INVALID_PARAMS, INVALID_REQUEST, LIST_CACHE_SCOPE, LIST_TTL_MS, MAX_BATCH, META_SERVER_INFO, METHOD_NOT_FOUND, RESOURCE_NOT_FOUND, SUPPORTED_VERSIONS, } from './protocol.js';
+import { matchResource, } from './registry.js';
+const answer = (status, body) => ({ status, body });
+export class McpServer {
+    #s;
+    #tools;
+    #prompts;
+    capabilities;
+    /** D-0154: the reloaded batch size, list cache time and URI limit, for the next request. */
+    update(next) {
+        this.#s = { ...this.#s, ...next };
+    }
+    constructor(settings) {
+        this.#s = settings;
+        this.#tools = new Map(settings.tools.map((tool) => [tool.name, tool]));
+        this.#prompts = new Map(settings.prompts.map((prompt) => [prompt.name, prompt]));
+        // listChanged: false — a stateless server has no stream to announce changes on (§1.12).
+        this.capabilities = Object.freeze({
+            ...(settings.tools.length ? { tools: { listChanged: false } } : {}),
+            ...(settings.prompts.length ? { prompts: { listChanged: false } } : {}),
+            ...(settings.resources.length ? { resources: { listChanged: false, subscribe: false } } : {}),
+        });
+    }
+    /** One POST: the body bytes, the headers and who calls. */
+    async handle(raw, headers, call) {
+        const parsed = parseBody(raw);
+        if ('kind' in parsed)
+            return this.#refused(parsed.status, parsed.body, 'parse');
+        if (Array.isArray(parsed.value))
+            return this.#batch(parsed.value, headers, call);
+        const message = readMessage(parsed.value);
+        if (message.kind === 'refusal')
+            return this.#refused(message.status, message.body, 'message');
+        const version = classify(message, headers);
+        if (version.kind === 'refusal')
+            return this.#refused(version.status, version.body, message.method);
+        if (message.kind === 'notification') {
+            // Nothing to do: no session to initialize, no in-flight request of this process to cancel.
+            diagnostics.logDebug(this.#s.logger, 'MCP notification', () => ({
+                method: message.method,
+                version: version.version,
+            }));
+            return { status: 202, body: undefined };
+        }
+        const denied = this.#scope([message], call);
+        if (denied)
+            return denied;
+        const started = performance.now();
+        const result = await this.#dispatch(message, version.era, version.version, call);
+        if (message.method !== 'tools/call')
+            diagnostics.logDebug(this.#s.logger, 'MCP request', () => ({
+                method: message.method,
+                version: version.version,
+                status: result.status,
+                ms: Math.round(performance.now() - started),
+            }));
+        return result;
+    }
+    #refused(status, body, method) {
+        diagnostics.logDebug(this.#s.logger, 'MCP request refused', () => ({
+            method,
+            status,
+            error: body.error?.code,
+        }));
+        return { status, body };
+    }
+    /**
+     * The scope a request needs and the name of its target, by its method and target (undefined:
+     * none beyond the grant). The name is the registered one (a resource's, never the URI).
+     */
+    #needed(message) {
+        const params = message.params;
+        if (message.method === 'tools/call' && typeof params.name === 'string')
+            return this.#tools.get(params.name);
+        if (message.method === 'prompts/get' && typeof params.name === 'string')
+            return this.#prompts.get(params.name);
+        if (message.method === 'resources/read' && typeof params.uri === 'string')
+            return this.#fits(params.uri)
+                ? matchResource(this.#s.resources, params.uri)?.resource
+                : undefined;
+        return undefined;
+    }
+    /**
+     * Whether a resource URI is short enough to be matched (`uriMaxChars`): matching is a pass over
+     * the URI per template, and the URI is client input of up to the body limit. A longer one
+     * matches nothing here and is refused by the dispatch.
+     */
+    #fits(uri) {
+        return uri.length <= (this.#s.uriMaxChars ?? URI_MAX_CHARS);
+    }
+    /**
+     * 403 insufficient_scope before anything runs (D-0094 §1.4), with every needed scope and the
+     * granted ones in the challenge, so a client's step-up keeps what already works. A tool whose
+     * scope is a list passes with any one of them; refused, the client is asked for the first.
+     */
+    #scope(messages, call) {
+        const missing = new Set();
+        /** Each refused target with the scopes of which any one would do (R18: never mixed). */
+        const targets = [];
+        let first;
+        let firstName = '';
+        for (const message of messages) {
+            if (message.kind !== 'request')
+                continue;
+            const needed = this.#needed(message);
+            if (needed !== undefined && !holdsAny(call.grant.scopes, needed.scopes)) {
+                missing.add(needed.scope);
+                targets.push({ name: needed.name, anyOf: needed.scopes });
+                if (!first) {
+                    first = message;
+                    firstName = needed.name;
+                }
+            }
+        }
+        if (!first)
+            return undefined;
+        const scopes = [...new Set([...call.grant.scopes, ...missing])];
+        // One MCP_CALL line (and one onCall entry) for the refused request, or a batch's first.
+        this.#s.runner.report(call, first.method, firstName, 0, 0, 'INSUFFICIENT_SCOPE');
+        return {
+            status: 403,
+            challenge: `Bearer error="insufficient_scope", scope="${scopes.join(' ')}", resource_metadata="${this.#s.metadataUrl}"`,
+            body: rpcError(messages.length === 1 ? first.id : null, INSUFFICIENT_SCOPE, `This connection lacks a scope for ${targets
+                .map((target) => `${target.name} (${target.anyOf.join(' or ')})`)
+                .join(', ')}`, { code: 'INSUFFICIENT_SCOPE', scopes: [...missing], targets }),
+        };
+    }
+    /** A JSON-RPC batch: only for 2025-03-26 (later versions removed batches). */
+    async #batch(values, headers, call) {
+        const version = headerOf(headers, HEADER_PROTOCOL_VERSION) ?? IMPLICIT_VERSION;
+        if (!SUPPORTED_VERSIONS.includes(version) && version !== IMPLICIT_VERSION) {
+            const refused = unsupported(null, version);
+            return this.#refused(refused.status, refused.body, 'batch');
+        }
+        if (version !== BATCH_VERSION)
+            return this.#refused(400, rpcError(null, INVALID_REQUEST, `MCP ${version} has no JSON-RPC batches: send one message per POST`), 'batch');
+        if (values.length === 0)
+            return this.#refused(400, rpcError(null, INVALID_REQUEST, 'The batch is empty'), 'batch');
+        const maxBatch = this.#s.maxBatch ?? MAX_BATCH;
+        if (values.length > maxBatch)
+            return this.#refused(400, rpcError(null, INVALID_REQUEST, `A batch holds at most ${maxBatch} messages`), 'batch');
+        const messages = values.map(readMessage);
+        const valid = messages.filter((one) => one.kind !== 'refusal');
+        const denied = this.#scope(valid, call);
+        if (denied)
+            return denied;
+        const responses = [];
+        // One after the other: writes keep their order, and one batch cannot occupy every core.
+        for (const message of messages) {
+            // The client left (or the app stops): nothing more of the batch runs.
+            if (call.signal?.aborted) {
+                diagnostics.logDebug(this.#s.logger, 'MCP batch stopped', () => ({
+                    answered: responses.length,
+                    of: messages.length,
+                }));
+                break;
+            }
+            if (message.kind === 'refusal') {
+                responses.push(message.body);
+                continue;
+            }
+            const classified = classify(message, headers);
+            if (classified.kind === 'refusal') {
+                if (message.kind === 'request')
+                    responses.push(classified.body);
+                continue;
+            }
+            if (message.kind === 'notification')
+                continue;
+            if (classified.era === 'modern' || message.method === 'initialize') {
+                responses.push(rpcError(message.id, INVALID_REQUEST, classified.era === 'modern'
+                    ? 'A batch carries 2025-03-26 messages only'
+                    : 'initialize cannot be part of a batch'));
+                continue;
+            }
+            responses.push((await this.#dispatch(message, 'legacy', classified.version, call)).body);
+        }
+        if (responses.length === 0)
+            return { status: 202, body: undefined };
+        return { status: 200, body: responses };
+    }
+    #serverInfo() {
+        return { ...this.#s.serverInfo };
+    }
+    /** A result in the shape of its era (modern: resultType, the cache hint, _meta). */
+    #shape(era, body, cacheable = false) {
+        if (era === 'legacy')
+            return body;
+        return {
+            resultType: 'complete',
+            ...body,
+            ...(cacheable
+                ? { ttlMs: this.#s.listTtlMs ?? LIST_TTL_MS, cacheScope: LIST_CACHE_SCOPE }
+                : {}),
+            _meta: { [META_SERVER_INFO]: this.#serverInfo() },
+        };
+    }
+    #result(id, era, body, cacheable = false) {
+        return answer(200, rpcResult(id, this.#shape(era, body, cacheable)));
+    }
+    /**
+     * An unknown method: 200 with -32601 for the 2025 versions (JSON-RPC over HTTP answers 200), 404
+     * for 2026-07-28 (its transport answers an unknown method with 404).
+     */
+    #notFound(id, method, era) {
+        return answer(era === 'modern' ? 404 : 200, rpcError(id, METHOD_NOT_FOUND, `Unknown method ${method}`));
+    }
+    #invalid(id, message, data) {
+        return answer(200, rpcError(id, INVALID_PARAMS, message, data));
+    }
+    #rpc(id, era, outcome) {
+        if (outcome.kind === 'result')
+            return this.#result(id, era, outcome.result);
+        return answer(200, rpcError(id, outcome.error, outcome.message, outcome.data));
+    }
+    async #dispatch(message, era, version, call) {
+        const { id, method, params } = message;
+        const visible = (scopes) => holdsAny(call.grant.scopes, scopes);
+        if (era === 'legacy' && method === 'initialize')
+            return this.#result(id, era, {
+                protocolVersion: negotiate(params.protocolVersion),
+                capabilities: this.capabilities,
+                serverInfo: this.#serverInfo(),
+                ...(this.#s.instructions === undefined ? {} : { instructions: this.#s.instructions }),
+            });
+        if (era === 'modern' && method === 'server/discover')
+            return this.#result(id, era, {
+                supportedVersions: [...SUPPORTED_VERSIONS],
+                capabilities: this.capabilities,
+                serverInfo: this.#serverInfo(),
+                ...(this.#s.instructions === undefined ? {} : { instructions: this.#s.instructions }),
+            }, true);
+        const full = { ...call, version };
+        const started = performance.now();
+        /** A call the route answers itself (an unknown name, a missing one): its MCP_CALL line. */
+        const refused = (code, reply, name = '') => {
+            this.#s.runner.report(call, method, name, Math.round(performance.now() - started), 0, code);
+            return reply;
+        };
+        switch (method) {
+            case 'ping':
+                return this.#result(id, era, {});
+            case 'tools/list':
+                if (!this.#s.tools.length)
+                    return this.#notFound(id, method, era);
+                return this.#result(id, era, {
+                    tools: this.#s.tools.filter((tool) => visible(tool.scopes)).map((tool) => tool.listing),
+                }, true);
+            case 'tools/call': {
+                if (!this.#s.tools.length)
+                    return refused('NOT_FOUND', this.#notFound(id, method, era));
+                if (typeof params.name !== 'string')
+                    return refused('INVALID_INPUT', this.#invalid(id, 'tools/call needs params.name'));
+                const tool = this.#tools.get(params.name);
+                if (!tool)
+                    return refused('NOT_FOUND', this.#invalid(id, `Unknown tool ${params.name}`, { name: params.name }));
+                const outcome = await this.#s.runner.callTool(tool, params.arguments, full);
+                return this.#result(id, era, outcome.result);
+            }
+            case 'prompts/list':
+                if (!this.#s.prompts.length)
+                    return this.#notFound(id, method, era);
+                return this.#result(id, era, {
+                    prompts: this.#s.prompts
+                        .filter((prompt) => visible(prompt.scopes))
+                        .map((prompt) => prompt.listing),
+                }, true);
+            case 'prompts/get': {
+                if (!this.#s.prompts.length)
+                    return refused('NOT_FOUND', this.#notFound(id, method, era));
+                if (typeof params.name !== 'string')
+                    return refused('INVALID_INPUT', this.#invalid(id, 'prompts/get needs params.name'));
+                const prompt = this.#prompts.get(params.name);
+                if (!prompt)
+                    return refused('NOT_FOUND', this.#invalid(id, `Unknown prompt ${params.name}`, { name: params.name }));
+                const args = params.arguments ?? {};
+                const problems = [];
+                if (!isPlainObject(args))
+                    problems.push({ path: 'arguments', message: 'must be an object of strings' });
+                else {
+                    const declared = new Set(prompt.arguments.map((one) => one.name));
+                    for (const [name, value] of Object.entries(args)) {
+                        if (!declared.has(name))
+                            problems.push({
+                                path: `arguments.${name}`,
+                                message: 'is not an argument of this prompt',
+                            });
+                        else if (typeof value !== 'string')
+                            problems.push({ path: `arguments.${name}`, message: 'must be a string' });
+                    }
+                    for (const one of prompt.arguments)
+                        if (one.required && !Object.hasOwn(args, one.name))
+                            problems.push({ path: `arguments.${one.name}`, message: 'is required' });
+                }
+                if (problems.length)
+                    return refused('INVALID_INPUT', this.#invalid(id, `The arguments do not match the prompt ${prompt.name}`, {
+                        code: 'INVALID_INPUT',
+                        problems,
+                    }), prompt.name);
+                return this.#rpc(id, era, await this.#s.runner.getPrompt(prompt, args, full));
+            }
+            case 'resources/list':
+                if (!this.#s.resources.length)
+                    return this.#notFound(id, method, era);
+                return this.#result(id, era, {
+                    resources: this.#s.resources
+                        .filter((one) => one.uri !== undefined && visible(one.scopes))
+                        .map((one) => one.listing),
+                }, true);
+            case 'resources/templates/list':
+                if (!this.#s.resources.length)
+                    return this.#notFound(id, method, era);
+                return this.#result(id, era, {
+                    resourceTemplates: this.#s.resources
+                        .filter((one) => one.template !== undefined && visible(one.scopes))
+                        .map((one) => one.listing),
+                }, true);
+            case 'resources/read': {
+                if (!this.#s.resources.length)
+                    return refused('NOT_FOUND', this.#notFound(id, method, era));
+                if (typeof params.uri !== 'string')
+                    return refused('INVALID_INPUT', this.#invalid(id, 'resources/read needs params.uri'));
+                if (!this.#fits(params.uri)) {
+                    // Refused before any template sees it, and never echoed back.
+                    const max = this.#s.uriMaxChars ?? URI_MAX_CHARS;
+                    return refused('INVALID_INPUT', this.#invalid(id, `The resource URI is longer than ${max} characters`, {
+                        code: 'INVALID_INPUT',
+                        problems: [{ path: 'uri', message: `must be at most ${max} characters` }],
+                    }));
+                }
+                const found = matchResource(this.#s.resources, params.uri);
+                if (!found)
+                    return refused('NOT_FOUND', answer(200, rpcError(id, RESOURCE_NOT_FOUND, 'There is no such resource', { uri: params.uri })));
+                return this.#rpc(id, era, await this.#s.runner.readResource(found.resource, found.params, params.uri, full));
+            }
+            default:
+                return this.#notFound(id, method, era);
+        }
+    }
+}
+/** Whether the grant holds any one of `scopes` (a tool's scope list: any one is enough). */
+function holdsAny(granted, scopes) {
+    return scopes.some((scope) => granted.includes(scope));
+}

package/dist/testing.d.ts

@@ -0,0 +1,168 @@
+import { type Logger } from '@dokebi/core';
+import type { FastifyRequest } from 'fastify';
+import { McpExtension } from './extension.js';
+import { type Limiter } from './runner.js';
+import type { McpGrant, McpTool } from './tool.js';
+/** What `callTool` takes besides the tool and its input. */
+export interface CallToolSettings {
+    /** The grant (default id `test-grant`, user `1`, client `test-client`, the tool's scope). */
+    readonly grant?: Partial<McpGrant>;
+    readonly logger?: Logger;
+    /**
+     * An extension class whose checkGrant and transformResult run as on the route; its onCall gets
+     * the call's entry one setImmediate after the result (D-0134).
+     */
+    readonly extension?: typeof McpExtension;
+    /** Providers the extension's hooks read through `context.getDependency`, by name. */
+    readonly dependencies?: Readonly<Record<string, unknown>>;
+    readonly timeoutMs?: number;
+    readonly resultMaxChars?: number;
+    /** Largest picture in bytes (default 1048576, as `imageMaxBytes`; D-0143). */
+    readonly imageMaxBytes?: number;
+    /** Largest sum of the pictures of the result (default 4194304, as `imageTotalMaxBytes`). */
+    readonly imageTotalMaxBytes?: number;
+    /** Pictures of the result at most (default 8, as `maxImages`). */
+    readonly maxImages?: number;
+    /** The protocol version the tool sees (default 2025-11-25). */
+    readonly version?: string;
+    readonly signal?: AbortSignal;
+    readonly request?: FastifyRequest;
+    /**
+     * The limiter of the tool's bucket (a @dokebi/rate-limit `limiter()`, or anything with
+     * `consume`): the call takes one token of `<bucket>:<grant id>` as on the route, and the
+     * handler sees the decision as `context.rateLimit` (D-0131). Absent: no limit, `rateLimit`
+     * undefined.
+     */
+    readonly limiter?: McpLimiter;
+}
+/** What `callTool` needs of a limiter: `consume` of @dokebi/rate-limit (by shape). */
+export type McpLimiter = Limiter;
+/** A tool result as a client receives it. */
+export interface McpToolResult {
+    readonly isError: boolean;
+    /** `ok`, or the error code (`INVALID_INPUT`, an application code, …). */
+    readonly code: string;
+    /** The envelope, or the error object `{ code, message, hint?, next?, data? }`. */
+    readonly structuredContent: Record<string, unknown>;
+    /** `content[0].text`: the same JSON. */
+    readonly text: string;
+    /** The image blocks after the text block (D-0143): `{ type: 'image', data, mimeType }`. */
+    readonly images: readonly McpImageBlock[];
+    /** The whole `CallToolResult`. */
+    readonly result: Record<string, unknown>;
+}
+/** One MCP image content block of a tool result (D-0143): base64 `data` and its `mimeType`. */
+export interface McpImageBlock {
+    readonly type: 'image';
+    readonly data: string;
+    readonly mimeType: string;
+}
+/** The grant `callTool` uses when none is given. */
+export declare const TEST_GRANT: Omit<McpGrant, 'scopes'>;
+/**
+ * Runs one tool as `tools/call` would, without HTTP or a token. A grant without the tool's scope
+ * rejects with INSUFFICIENT_SCOPE (on the route: the 403 that makes a client ask again).
+ */
+export declare function callTool(tool: McpTool, input: unknown, settings?: CallToolSettings): Promise<McpToolResult>;
+/** An HTTP answer of the test helpers. */
+export interface TestResponse {
+    readonly status: number;
+    readonly url: string;
+    readonly headers: Headers;
+    readonly text: string;
+    /** The `Location` header resolved against the request URL, when there is one. */
+    readonly location: string | undefined;
+    json<T = Record<string, unknown>>(): T;
+}
+/** A browser for tests: keeps cookies, never follows redirects, can rewrite hosts. */
+export declare class TestBrowser {
+    #private;
+    readonly cookies: Map<string, string>;
+    /** `rewrite` changes a URL before it is fetched (`http://localhost:…` → `http://127.0.0.1:…`). */
+    constructor(rewrite?: (url: string) => string);
+    get(url: string): Promise<TestResponse>;
+    /** A form post (`application/x-www-form-urlencoded`; a list value repeats the name). */
+    post(url: string, form: Readonly<Record<string, string | readonly string[]>>): Promise<TestResponse>;
+}
+/** What `McpTestClient` takes. */
+export interface McpTestClientSettings {
+    /** The access token (`Authorization: Bearer`); absent: no header. */
+    readonly token?: string;
+    /** The protocol version: a legacy one sends `MCP-Protocol-Version`, 2026-07-28 adds `_meta`. */
+    readonly version?: string;
+    readonly headers?: Readonly<Record<string, string>>;
+    /** Rewrites the URL before it is fetched. */
+    readonly rewrite?: (url: string) => string;
+}
+/** A JSON-RPC response with its HTTP status. */
+export interface McpRpcResponse {
+    readonly status: number;
+    readonly headers: Headers;
+    /** The parsed body (an object, a batch array) or undefined for an empty body. */
+    readonly body: unknown;
+    /** `body.result` when there is one. */
+    readonly result: Record<string, unknown> | undefined;
+    /** `body.error` when there is one. */
+    readonly error: {
+        readonly code: number;
+        readonly message: string;
+        readonly data?: unknown;
+    } | undefined;
+}
+/** A minimal MCP client over real HTTP (JSON answers only, which is what this server sends). */
+export declare class McpTestClient {
+    #private;
+    readonly url: string;
+    constructor(url: string, settings?: McpTestClientSettings);
+    get version(): string;
+    /** A raw POST: `body` as given (a string is sent as is), the headers of the settings added. */
+    post(body: unknown, headers?: Readonly<Record<string, string>>): Promise<McpRpcResponse>;
+    /** One request in the shape of this client's version (headers, `_meta`). */
+    request(method: string, params?: Record<string, unknown>): Promise<McpRpcResponse>;
+    initialize(): Promise<McpRpcResponse>;
+    listTools(): Promise<McpRpcResponse>;
+    callTool(name: string, args?: Record<string, unknown>): Promise<McpRpcResponse>;
+}
+/** What `pkceFlow` takes. */
+export interface PkceFlowSettings {
+    /** The MCP endpoint as clients use it (`http://localhost:4000/mcp`). */
+    readonly resourceUrl: string;
+    readonly clientId: string;
+    /** A redirect URI registered for the client (a loopback one may use any port). */
+    readonly redirectUri: string;
+    /** The scopes to ask for; default the `scope` of the 401 challenge. */
+    readonly scopes?: readonly string[];
+    /** The browser (keeps the session between flows); default a new one. */
+    readonly browser?: TestBrowser;
+    /**
+     * Called when authorize sends the browser to a sign-in page: sign in through `browser` and
+     * return the URL to go back to (your login handler's redirect).
+     */
+    readonly signIn?: (browser: TestBrowser, loginUrl: string) => Promise<string>;
+    /**
+     * The fields the consent page posts. Default: every hidden input of the page's HTML (the
+     * request id, the CSRF field) and `decision: allow`.
+     */
+    readonly decide?: (page: TestResponse) => Readonly<Record<string, string | readonly string[]>>;
+    /** Rewrites a URL before it is fetched. */
+    readonly rewrite?: (url: string) => string;
+}
+/** What `pkceFlow` gives: the tokens and what the client learned on the way. */
+export interface PkceTokens {
+    readonly accessToken: string;
+    readonly refreshToken: string;
+    readonly expiresIn: number;
+    readonly scope: string | undefined;
+    /** The resource of the protected resource metadata (what the token is for). */
+    readonly resource: string;
+    readonly issuer: string;
+    readonly metadataUrl: string;
+    readonly tokenEndpoint: string;
+}
+/**
+ * The hidden inputs of an HTML page (name → value): the `type`, `name` and `value` attributes
+ * themselves (never `data-type` or `data-name`), double-quoted, single-quoted or bare.
+ */
+export declare function hiddenInputs(html: string): Record<string, string>;
+/** The OAuth flow of an MCP client against @dokebi/oauth, over real HTTP (see the top). */
+export declare function pkceFlow(settings: PkceFlowSettings): Promise<PkceTokens>;