@dokebi/mcp 0.0.0-stage → 0.1.1

package/dist/era.js

@@ -0,0 +1,84 @@
+import { refusal } from './jsonrpc.js';
+import { BASE64_PREFIX, BASE64_SUFFIX, HEADER_METHOD, HEADER_MISMATCH, HEADER_NAME, HEADER_PROTOCOL_VERSION, IMPLICIT_VERSION, LEGACY_VERSIONS, META_PROTOCOL_VERSION, MODERN_VERSIONS, NAME_SOURCE, SUPPORTED_VERSIONS, UNSUPPORTED_VERSION, } from './protocol.js';
+export function headerOf(headers, name) {
+    const value = headers[name];
+    if (value === undefined)
+        return undefined;
+    // Two copies of one header are joined: the comparison then fails instead of picking one.
+    return typeof value === 'string' ? value : value.join(',');
+}
+const utf8 = new TextDecoder('utf-8', { fatal: true });
+/** `=?base64?…?=` decoded (other values as they are); undefined when the marker is broken. */
+export function decodeHeaderValue(raw) {
+    if (!(raw.startsWith(BASE64_PREFIX) && raw.endsWith(BASE64_SUFFIX)))
+        return raw;
+    const inner = raw.slice(BASE64_PREFIX.length, raw.length - BASE64_SUFFIX.length);
+    if (!/^[A-Za-z0-9+/]*={0,2}$/.test(inner) || inner.length % 4 !== 0)
+        return undefined;
+    try {
+        return utf8.decode(Buffer.from(inner, 'base64'));
+    }
+    catch (error) {
+        // Not UTF-8: the header cannot match the body, which is what the caller reports.
+        if (!(error instanceof TypeError))
+            throw error;
+        return undefined;
+    }
+}
+export function unsupported(id, requested) {
+    return refusal(400, id, UNSUPPORTED_VERSION, `Unsupported MCP protocol version ${requested}; supported: ${SUPPORTED_VERSIONS.join(', ')}`, { supported: [...SUPPORTED_VERSIONS], requested });
+}
+/** The version of a message and the header checks of modern versions. */
+export function classify(message, headers) {
+    const id = message.kind === 'request' ? message.id : null;
+    const header = headerOf(headers, HEADER_PROTOCOL_VERSION);
+    const meta = message.params._meta;
+    const claimed = meta !== null && typeof meta === 'object' && !Array.isArray(meta)
+        ? meta[META_PROTOCOL_VERSION]
+        : undefined;
+    if (claimed !== undefined) {
+        const requested = typeof claimed === 'string' ? claimed : JSON.stringify(claimed);
+        if (typeof claimed !== 'string' || !MODERN_VERSIONS.includes(claimed))
+            return unsupported(id, requested);
+        if (header !== undefined && header !== claimed)
+            return refusal(400, id, HEADER_MISMATCH, `MCP-Protocol-Version ${header} differs from the version in params._meta (${claimed})`);
+        const method = headerOf(headers, HEADER_METHOD);
+        // Notifications may come without the headers; when present they must agree.
+        if (message.kind === 'request') {
+            if (header === undefined)
+                return refusal(400, id, HEADER_MISMATCH, `MCP-Protocol-Version is missing: a ${claimed} request carries its version in the header and in params._meta`);
+            if (method === undefined)
+                return refusal(400, id, HEADER_MISMATCH, `Mcp-Method is missing: a ${claimed} request repeats its method (${message.method}) in the header`);
+        }
+        if (method !== undefined && method !== message.method)
+            return refusal(400, id, HEADER_MISMATCH, `Mcp-Method ${method} differs from the method of the body (${message.method})`);
+        const source = Object.hasOwn(NAME_SOURCE, message.method)
+            ? NAME_SOURCE[message.method]
+            : undefined;
+        if (source !== undefined) {
+            const value = message.params[source];
+            const name = headerOf(headers, HEADER_NAME);
+            if (typeof value === 'string') {
+                if (name === undefined && message.kind === 'request')
+                    return refusal(400, id, HEADER_MISMATCH, `Mcp-Name is missing: ${message.method} repeats params.${source} in the header`);
+                if (name !== undefined && decodeHeaderValue(name) !== value)
+                    return refusal(400, id, HEADER_MISMATCH, `Mcp-Name differs from params.${source} of the body`);
+            }
+        }
+        return { kind: 'version', era: 'modern', version: claimed };
+    }
+    if (header === undefined)
+        return { kind: 'version', era: 'legacy', version: IMPLICIT_VERSION };
+    if (MODERN_VERSIONS.includes(header))
+        // A modern header without the envelope is not quietly read as a legacy request.
+        return refusal(400, id, HEADER_MISMATCH, `MCP-Protocol-Version is ${header} but params._meta has no ${META_PROTOCOL_VERSION}: ${header} requests carry it in every message`);
+    if (LEGACY_VERSIONS.includes(header))
+        return { kind: 'version', era: 'legacy', version: header };
+    return unsupported(id, header);
+}
+/** The version an `initialize` is answered with: the one asked for when known, else the newest. */
+export function negotiate(requested) {
+    if (typeof requested === 'string' && LEGACY_VERSIONS.includes(requested))
+        return requested;
+    return LEGACY_VERSIONS[0];
+}

package/dist/errors.d.ts

@@ -0,0 +1,57 @@
+import { DokebiError, type DokebiErrorOptions } from '@dokebi/core';
+export type McpErrorCode = 
+/** Start: options the schema cannot judge (an unknown resource, a bucket without a policy). */
+'INVALID_OPTIONS'
+/** The entry module (src/infra/mcp/extension.ts) has the wrong shape. */
+ | 'INVALID_ENTRY'
+/** Start: a contributed tool breaks the contract (`data.tool`, `details.problems`). */
+ | 'INVALID_TOOL'
+/** Start: a contributed prompt breaks the contract (`data.prompt`, `details.problems`). */
+ | 'INVALID_PROMPT'
+/** Start: a contributed resource breaks the contract (`data.resource`, `details.problems`). */
+ | 'INVALID_RESOURCE'
+/** Start: `limits` without @dokebi/rate-limit, or with a policy it does not have. */
+ | 'RATE_LIMIT_REQUIRED'
+/** A hook returned something the plugin cannot use (`data.hook`). */
+ | 'INVALID_HOOK_RESULT'
+/** A helper (`envelope`, `page`, `item`) or the API got a wrong argument. */
+ | 'INVALID_ARGUMENT'
+/** A tool returned something other than an `envelope()` (the cause of an INTERNAL answer). */
+ | 'INVALID_RESULT'
+/** 413: the request body is larger than `bodyLimitBytes` (before it is read). */
+ | 'BODY_TOO_LARGE'
+/** 403: the request has an `Origin` that is neither the resource's nor in `allowedOrigins`. */
+ | 'ORIGIN_REFUSED'
+/** 403 with `WWW-Authenticate: Bearer error="insufficient_scope"`: the grant lacks the scope. */
+ | 'INSUFFICIENT_SCOPE'
+/** Tool error: the arguments do not match the tool's input schema (`data.problems`). */
+ | 'INVALID_INPUT'
+/** Tool error: the grant's bucket is empty (`retry_after` seconds). */
+ | 'LIMIT_EXCEEDED'
+/** Tool error: `checkGrant` said no (the connection may not reach this any more). */
+ | 'GRANT_REFUSED'
+/** Tool error: the result is larger than `resultMaxChars` (never cut silently). */
+ | 'RESULT_TOO_LARGE'
+/** Tool error: the tool ran longer than `toolTimeoutMs`; its signal was aborted. */
+ | 'TOOL_TIMEOUT'
+/** Tool error: a `page()` cursor that is not one of this list. */
+ | 'INVALID_CURSOR'
+/** `envelope({ images })`: a type other than image/png, image/jpeg, image/webp, image/gif. */
+ | 'IMAGE_TYPE_REFUSED'
+/** `envelope({ images })`: the bytes are not the declared type (`data.declared`, `detected`). */
+ | 'IMAGE_TYPE_MISMATCH'
+/** Tool error: one picture is larger than `imageMaxBytes` (`data.index`, `bytes`, `max`). */
+ | 'IMAGE_TOO_LARGE'
+/** Tool error: a result has more pictures than `maxImages` (`data.count`, `max`). */
+ | 'TOO_MANY_IMAGES'
+/** Tool error: the pictures of a result are larger than `imageTotalMaxBytes` together. */
+ | 'IMAGE_TOTAL_TOO_LARGE'
+/** The client closed the request or the app stopped before the call ended (the log's result). */
+ | 'CANCELLED'
+/** Tool error: an unexpected failure (no details; the cause is in the error log). */
+ | 'INTERNAL';
+export declare class McpError extends DokebiError<McpErrorCode> {
+    /** Fastify reads `statusCode` of a body stream error; it matches `status`. */
+    readonly statusCode: number | undefined;
+    constructor(code: McpErrorCode, message: string, options?: DokebiErrorOptions);
+}

package/dist/errors.js

@@ -0,0 +1,10 @@
+import { DokebiError } from '@dokebi/core';
+export class McpError extends DokebiError {
+    /** Fastify reads `statusCode` of a body stream error; it matches `status`. */
+    statusCode;
+    constructor(code, message, options = {}) {
+        super(code, message, { ...options, plugin: options.plugin ?? 'dokebi-mcp' });
+        this.name = 'McpError';
+        this.statusCode = options.status;
+    }
+}

package/dist/extension.d.ts

@@ -0,0 +1,139 @@
+import type { ApplicationView, Awaitable, Logger, PluginDependency } from '@dokebi/core';
+import type { FastifyRequest } from 'fastify';
+import type { McpEnvelope } from './envelope.js';
+import type { McpGrant, McpPrompt, McpResource, McpTool } from './tool.js';
+/** What hooks receive besides their input. */
+export interface McpHookContext {
+    readonly app: ApplicationView;
+    /** Providers declared by `dependencies()`. */
+    getDependency<TApi>(dependency: PluginDependency<TApi>): TApi;
+    /** The plugin's logger. */
+    readonly logger: Logger;
+    /**
+     * Aborted when the call's budget is over, its client left or the app stops; in `onCall` (the
+     * call is over) when the app stops.
+     */
+    readonly signal: AbortSignal;
+    /** The HTTP request of the call; undefined at setup and in @dokebi/mcp/testing. */
+    readonly request: FastifyRequest | undefined;
+}
+/** What a call is about, for `checkGrant`. */
+export type McpTarget = {
+    readonly kind: 'tool';
+    readonly name: string;
+    /** The first scope of the target (the one asked for). */
+    readonly scope: string;
+    /** Every scope of which any one lets the grant use it. */
+    readonly scopes: readonly string[];
+    /** The first of `scopes` the grant holds: the one that let this call through. */
+    readonly matched: string;
+    readonly value: McpTool;
+} | {
+    readonly kind: 'prompt';
+    readonly name: string;
+    /** The first scope of the target (the one asked for). */
+    readonly scope: string;
+    /** Every scope of which any one lets the grant use it. */
+    readonly scopes: readonly string[];
+    /** The first of `scopes` the grant holds: the one that let this call through. */
+    readonly matched: string;
+    readonly value: McpPrompt;
+} | {
+    readonly kind: 'resource';
+    readonly name: string;
+    /** The first scope of the target (the one asked for). */
+    readonly scope: string;
+    /** Every scope of which any one lets the grant use it. */
+    readonly scopes: readonly string[];
+    /** The first of `scopes` the grant holds: the one that let this call through. */
+    readonly matched: string;
+    readonly value: McpResource;
+};
+/** The requests `onCall` hears of (D-0134): the calls of a tool, a prompt or a resource. */
+export type McpCallMethod = 'tools/call' | 'prompts/get' | 'resources/read';
+/**
+ * One ended call, as `onCall` receives it (D-0134): the values of its `MCP_CALL` info line, frozen.
+ * Never a token, the input, prompt arguments, a resource URI or its content.
+ */
+export interface McpCallEntry {
+    readonly method: McpCallMethod;
+    /**
+     * The tool, prompt or resource name (a resource's `name`, never its URI); '' when the request
+     * named nothing this server has (the requested name is client input and never leaves).
+     */
+    readonly name: string;
+    /** The grant id (the connection). */
+    readonly grant: string;
+    /** The OAuth client id of the grant. */
+    readonly client: string;
+    /** The grant's user id. */
+    readonly userId: string;
+    /** Milliseconds from the start of the call to its answer. */
+    readonly ms: number;
+    /** Bytes of the answer's JSON (a tool error's JSON; 0 for a JSON-RPC error). */
+    readonly bytes: number;
+    /** `ok`, or the code the call ended with (`LIMIT_EXCEEDED`, `INVALID_INPUT`, an app code, …). */
+    readonly result: string;
+    /**
+     * Only for `tools/call` with `result` `ok`: the envelope the client received, after
+     * `transformResult` (what it masked is masked here too). Count `content`, read `fields`, and
+     * drop the text you must not keep: it is what the tool returned.
+     */
+    readonly envelope?: McpEnvelope;
+}
+/** The hooks the plugin calls, as plain methods (internal: the runtime's view of a subclass). */
+export interface McpHooks {
+    dependencies(): readonly PluginDependency[];
+    instructions(context: McpHookContext): Awaitable<unknown>;
+    checkGrant(grant: McpGrant, target: McpTarget, context: McpHookContext): Awaitable<unknown>;
+    transformResult(result: McpEnvelope, call: {
+        readonly tool: McpTool;
+        readonly grant: McpGrant;
+    }, context: McpHookContext): Awaitable<unknown>;
+    onCall(entry: McpCallEntry, context: McpHookContext): Awaitable<unknown>;
+}
+export declare const EXTENSION_FILE = "src/infra/mcp/extension.ts";
+declare const McpExtension_base: import("@dokebi/core").ExtensionRoot;
+/**
+ * Subclass this in `src/infra/mcp/extension.ts` (`export default class AppMcp extends
+ * McpExtension { … }`) and override hooks with `protected override`. Hooks run with their inputs
+ * only: no constructor parameters, and hooks never call each other.
+ */
+export declare class McpExtension extends McpExtension_base {
+    /** Providers the other hooks use through `context.getDependency`. Called once. Default: none. */
+    protected dependencies(): readonly PluginDependency[];
+    /**
+     * The server instructions (`initialize` and `server/discover`), called once at setup; a string
+     * of at most 16,000 characters or undefined (then the `instructions` option). Default: undefined.
+     */
+    protected instructions(context: McpHookContext): Awaitable<string | undefined>;
+    /**
+     * Called before every tool call, prompt and resource read, after the scope and limit checks:
+     * may this grant still reach `target`? (The connection's binding names a project the user has
+     * left: false.) False answers GRANT_REFUSED; a thrown DokebiError answers its own code.
+     * Default: true.
+     */
+    protected checkGrant(grant: McpGrant, target: McpTarget, context: McpHookContext): Awaitable<boolean>;
+    /**
+     * Changes a tool result once before it leaves (hide values, list them in `masked`). Return an
+     * envelope: `amend(result, { content, masked: [...] })`. Runs before the size check. Default: the
+     * result unchanged.
+     */
+    protected transformResult(result: McpEnvelope, call: {
+        readonly tool: McpTool;
+        readonly grant: McpGrant;
+    }, context: McpHookContext): Awaitable<McpEnvelope>;
+    /**
+     * Hears once that a call ended (D-0134): every `tools/call`, `prompts/get` and `resources/read`
+     * the route dispatched, whatever the outcome (ok, a refusal before the handler such as
+     * LIMIT_EXCEEDED, INSUFFICIENT_SCOPE, INVALID_INPUT or GRANT_REFUSED, an error, TOOL_TIMEOUT,
+     * CANCELLED). It runs after the response was written and is never awaited: it cannot delay
+     * or change an answer. A throw or a rejection is logged at warn (MCP_ON_CALL_FAILED) and
+     * counted; at most `onCallMaxPending` returned promises are pending at once, and an entry over
+     * that is dropped with warn MCP_ON_CALL_DROPPED. Default: nothing.
+     */
+    protected onCall(entry: McpCallEntry, context: McpHookContext): Awaitable<void>;
+}
+/** The plugin's handle on a subclass instance (not exported from the package). */
+export declare function mcpHooks(extension: McpExtension): McpHooks;
+export {};

package/dist/extension.js

@@ -0,0 +1,75 @@
+import { defineExtension } from '@dokebi/core';
+export const EXTENSION_FILE = 'src/infra/mcp/extension.ts';
+let bridge;
+/**
+ * Subclass this in `src/infra/mcp/extension.ts` (`export default class AppMcp extends
+ * McpExtension { … }`) and override hooks with `protected override`. Hooks run with their inputs
+ * only: no constructor parameters, and hooks never call each other.
+ */
+export class McpExtension extends defineExtension({
+    plugin: 'dokebi-mcp',
+    api: 1,
+    hooks: ['dependencies', 'instructions', 'checkGrant', 'transformResult', 'onCall'],
+    file: EXTENSION_FILE,
+}) {
+    static {
+        bridge = (extension) => Object.freeze({
+            dependencies: () => extension.dependencies(),
+            instructions: (context) => extension.instructions(context),
+            checkGrant: (grant, target, context) => extension.checkGrant(grant, target, context),
+            transformResult: (result, call, context) => extension.transformResult(result, call, context),
+            onCall: (entry, context) => extension.onCall(entry, context),
+        });
+    }
+    /** Providers the other hooks use through `context.getDependency`. Called once. Default: none. */
+    dependencies() {
+        return [];
+    }
+    /**
+     * The server instructions (`initialize` and `server/discover`), called once at setup; a string
+     * of at most 16,000 characters or undefined (then the `instructions` option). Default: undefined.
+     */
+    instructions(context) {
+        void context;
+        return undefined;
+    }
+    /**
+     * Called before every tool call, prompt and resource read, after the scope and limit checks:
+     * may this grant still reach `target`? (The connection's binding names a project the user has
+     * left: false.) False answers GRANT_REFUSED; a thrown DokebiError answers its own code.
+     * Default: true.
+     */
+    checkGrant(grant, target, context) {
+        void grant;
+        void target;
+        void context;
+        return true;
+    }
+    /**
+     * Changes a tool result once before it leaves (hide values, list them in `masked`). Return an
+     * envelope: `amend(result, { content, masked: [...] })`. Runs before the size check. Default: the
+     * result unchanged.
+     */
+    transformResult(result, call, context) {
+        void call;
+        void context;
+        return result;
+    }
+    /**
+     * Hears once that a call ended (D-0134): every `tools/call`, `prompts/get` and `resources/read`
+     * the route dispatched, whatever the outcome (ok, a refusal before the handler such as
+     * LIMIT_EXCEEDED, INSUFFICIENT_SCOPE, INVALID_INPUT or GRANT_REFUSED, an error, TOOL_TIMEOUT,
+     * CANCELLED). It runs after the response was written and is never awaited: it cannot delay
+     * or change an answer. A throw or a rejection is logged at warn (MCP_ON_CALL_FAILED) and
+     * counted; at most `onCallMaxPending` returned promises are pending at once, and an entry over
+     * that is dropped with warn MCP_ON_CALL_DROPPED. Default: nothing.
+     */
+    onCall(entry, context) {
+        void entry;
+        void context;
+    }
+}
+/** The plugin's handle on a subclass instance (not exported from the package). */
+export function mcpHooks(extension) {
+    return bridge(extension);
+}

package/dist/index.d.ts

@@ -0,0 +1,21 @@
+export type { McpCallStats } from './calls.js';
+/** Use with `context.getDependency(dependency)`; a registered `dokebi-mcp` is reused. */
+export { dependency, provider } from './dependency.js';
+export { amend, envelope, IMAGE_MIME_TYPES, isEnvelope, item, type McpContentItem, type McpEnvelope, type McpEnvelopeInput, type McpHumanTurn, type McpImage, type McpImageInput, type McpImageMimeType, type McpMasked, type McpPage, type McpSource, type McpWrittenBy, PAGE_MAX_CHARS, page, } from './envelope.js';
+export { McpError, type McpErrorCode } from './errors.js';
+/**
+ * The extension base (D-0064): `export default class AppMcp extends McpExtension {}` in
+ * src/infra/mcp/extension.ts. Hooks: dependencies, instructions, checkGrant, transformResult,
+ * onCall (D-0134).
+ */
+export { type McpCallEntry, type McpCallMethod, McpExtension, type McpHookContext, type McpTarget, } from './extension.js';
+export type { McpOptions } from './options.js';
+/** The options declaration (D-0063): `options.parse(input)`, `options.schema`. */
+export { options } from './options.js';
+export type { McpApi, McpEntry } from './plugin.js';
+/** Factory input: `{ app, options?, entry? }`. */
+export { createPlugin } from './plugin.js';
+export { LEGACY_VERSIONS, MODERN_VERSIONS, SUPPORTED_VERSIONS } from './protocol.js';
+export type { JsonSchema, SchemaProblem } from './schema.js';
+export { MAX_INPUT_DEPTH } from './schema.js';
+export { type McpContext, type McpGrant, type McpImageLimits, McpPrompt, type McpPromptArgument, type McpPromptMessage, type McpPromptResult, type McpRateLimit, McpResource, type McpResourceContent, type McpResourceContext, McpTool, type McpToolAnnotations, type McpToolContext, mcpPrompts, mcpResources, mcpTools, } from './tool.js';

package/dist/index.js

@@ -0,0 +1,23 @@
+/*
+ * @dokebi/mcp (D-0094): an MCP server on @dokebi/web and @dokebi/oauth — stateless Streamable
+ * HTTP on one route, tool classes with checked input schemas and one scope each, a forced result
+ * envelope with paging, pictures (D-0143) and size limits, per grant and bucket limits on @dokebi/rate-limit, coded
+ * tool errors, and the hooks checkGrant, transformResult and onCall.
+ */
+/** Use with `context.getDependency(dependency)`; a registered `dokebi-mcp` is reused. */
+export { dependency, provider } from './dependency.js';
+export { amend, envelope, IMAGE_MIME_TYPES, isEnvelope, item, PAGE_MAX_CHARS, page, } from './envelope.js';
+export { McpError } from './errors.js';
+/**
+ * The extension base (D-0064): `export default class AppMcp extends McpExtension {}` in
+ * src/infra/mcp/extension.ts. Hooks: dependencies, instructions, checkGrant, transformResult,
+ * onCall (D-0134).
+ */
+export { McpExtension, } from './extension.js';
+/** The options declaration (D-0063): `options.parse(input)`, `options.schema`. */
+export { options } from './options.js';
+/** Factory input: `{ app, options?, entry? }`. */
+export { createPlugin } from './plugin.js';
+export { LEGACY_VERSIONS, MODERN_VERSIONS, SUPPORTED_VERSIONS } from './protocol.js';
+export { MAX_INPUT_DEPTH } from './schema.js';
+export { McpPrompt, McpResource, McpTool, mcpPrompts, mcpResources, mcpTools, } from './tool.js';

package/dist/install.d.ts

@@ -0,0 +1,29 @@
+interface InstallContext {
+    readonly options: Readonly<Record<string, unknown>>;
+}
+interface Diagnostic {
+    readonly code: string;
+    readonly severity: 'error' | 'warning';
+    readonly optionPath?: readonly string[];
+    readonly hint?: string;
+}
+export declare function planInstall(context: InstallContext): {
+    requires: string[];
+    entry: {
+        source: string;
+        target: string;
+    };
+};
+/** An existing entry file is never replaced. */
+export declare function planUpgrade(context: InstallContext): {
+    requires: string[];
+    entry: {
+        source: string;
+        target: string;
+    };
+};
+export declare function check(context: InstallContext): {
+    requires: string[];
+    diagnostics: Diagnostic[];
+};
+export {};

package/dist/install.js

@@ -0,0 +1,35 @@
+// Install lifecycle module (`dokebi.installModule`). It runs isolated in the CLI, so it imports
+// nothing and only reads the plain options it is given. Invalid options are left to the schema.
+const RATE_LIMIT_PROVIDER = 'dokebi-rate-limit';
+/** The user-owned extension entry (D-0064): optional hooks (checkGrant, transformResult, …). */
+const ENTRY = Object.freeze({
+    source: 'templates/extension.ts',
+    target: 'src/infra/mcp/extension.ts',
+});
+function plain(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Limits need @dokebi/rate-limit (its policies count per grant and bucket). */
+function requires(context) {
+    const limits = plain(context.options) ? context.options.limits : undefined;
+    return plain(limits) && Object.keys(limits).length ? [RATE_LIMIT_PROVIDER] : [];
+}
+export function planInstall(context) {
+    return { requires: requires(context), entry: ENTRY };
+}
+/** An existing entry file is never replaced. */
+export function planUpgrade(context) {
+    return { requires: requires(context), entry: ENTRY };
+}
+export function check(context) {
+    const diagnostics = [];
+    const limits = plain(context.options) ? context.options.limits : undefined;
+    if (!plain(limits) || Object.keys(limits).length === 0)
+        diagnostics.push({
+            code: 'MCP_NO_LIMITS',
+            severity: 'warning',
+            optionPath: ['limits'],
+            hint: 'no per-connection limits: set limits.read and limits.write to @dokebi/rate-limit policies (a redis driver shares them between workers)',
+        });
+    return { requires: requires(context), diagnostics };
+}

package/dist/jsonrpc.d.ts

@@ -0,0 +1,29 @@
+export type JsonRpcId = string | number;
+export interface JsonRpcRequest {
+    readonly kind: 'request';
+    readonly id: JsonRpcId;
+    readonly method: string;
+    readonly params: Readonly<Record<string, unknown>>;
+}
+export interface JsonRpcNotification {
+    readonly kind: 'notification';
+    readonly method: string;
+    readonly params: Readonly<Record<string, unknown>>;
+}
+export type JsonRpcMessage = JsonRpcRequest | JsonRpcNotification;
+/** A refusal before dispatch: an HTTP status and a JSON-RPC error body. */
+export interface JsonRpcRefusal {
+    readonly kind: 'refusal';
+    readonly status: number;
+    readonly body: Record<string, unknown>;
+}
+export declare function rpcResult(id: JsonRpcId, result: Record<string, unknown>): Record<string, unknown>;
+export declare function rpcError(id: JsonRpcId | null, code: number, message: string, data?: Record<string, unknown>): Record<string, unknown>;
+export declare function refusal(status: number, id: JsonRpcId | null, code: number, message: string, data?: Record<string, unknown>): JsonRpcRefusal;
+export declare function isPlainObject(value: unknown): value is Record<string, unknown>;
+/** The body as JSON: a value, or a -32700 refusal (empty, not UTF-8, not JSON). */
+export declare function parseBody(raw: Uint8Array | undefined): {
+    value: unknown;
+} | JsonRpcRefusal;
+/** One message of the body (or of a batch): a request, a notification or a -32600 refusal. */
+export declare function readMessage(value: unknown): JsonRpcMessage | JsonRpcRefusal;

package/dist/jsonrpc.js

@@ -0,0 +1,64 @@
+import { INVALID_REQUEST, PARSE_ERROR } from './protocol.js';
+export function rpcResult(id, result) {
+    return { jsonrpc: '2.0', id, result };
+}
+export function rpcError(id, code, message, data) {
+    return {
+        jsonrpc: '2.0',
+        id,
+        error: data === undefined ? { code, message } : { code, message, data },
+    };
+}
+export function refusal(status, id, code, message, data) {
+    return { kind: 'refusal', status, body: rpcError(id, code, message, data) };
+}
+export function isPlainObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** MCP ids are strings or integers, never null. */
+function validId(value) {
+    return typeof value === 'string' || (typeof value === 'number' && Number.isSafeInteger(value));
+}
+const decoder = new TextDecoder('utf-8', { fatal: true });
+/** The body as JSON: a value, or a -32700 refusal (empty, not UTF-8, not JSON). */
+export function parseBody(raw) {
+    let text;
+    try {
+        text = raw === undefined ? '' : decoder.decode(raw);
+    }
+    catch (error) {
+        // A decoding failure is the client's broken body: answered as a parse error, nothing lost.
+        if (!(error instanceof TypeError))
+            throw error;
+        return refusal(400, null, PARSE_ERROR, 'The body is not UTF-8: send one JSON-RPC message');
+    }
+    try {
+        return { value: JSON.parse(text) };
+    }
+    catch (error) {
+        if (!(error instanceof SyntaxError))
+            throw error;
+        return refusal(400, null, PARSE_ERROR, 'The body is not JSON: send one JSON-RPC message');
+    }
+}
+/** One message of the body (or of a batch): a request, a notification or a -32600 refusal. */
+export function readMessage(value) {
+    if (!isPlainObject(value))
+        return refusal(400, null, INVALID_REQUEST, 'A JSON-RPC message is an object');
+    const hasId = Object.hasOwn(value, 'id');
+    const id = hasId && validId(value.id) ? value.id : null;
+    if (value.jsonrpc !== '2.0')
+        return refusal(400, id, INVALID_REQUEST, 'jsonrpc must be "2.0"');
+    if (typeof value.method !== 'string' || value.method === '')
+        // A posted response lands here too: this server sends no requests, so it expects none.
+        return refusal(400, id, INVALID_REQUEST, 'method is missing: send a request or a notification');
+    const params = value.params;
+    if (params !== undefined && !isPlainObject(params))
+        return refusal(400, id, INVALID_REQUEST, 'params must be an object (MCP has no positional params)');
+    const method = value.method;
+    if (!hasId)
+        return { kind: 'notification', method, params: params ?? {} };
+    if (!validId(value.id))
+        return refusal(400, null, INVALID_REQUEST, 'id must be a string or an integer (not null)');
+    return { kind: 'request', id: value.id, method, params: params ?? {} };
+}

package/dist/options.d.ts

@@ -0,0 +1,50 @@
+import { type OptionsDeclaration } from '@dokebi/core';
+/** A limit bucket (`read`, `write`, `trash`). */
+export declare const BUCKET: RegExp;
+/** Default of `uriMaxChars`: the longest resource URI of `resources/read` (R4 audit, 2026-10-26). */
+export declare const URI_MAX_CHARS = 8192;
+/** The defaults of the image limits (D-0143), for `callTool` of @dokebi/mcp/testing too. */
+export declare const IMAGE_LIMITS: Readonly<{
+    imageMaxBytes: 1048576;
+    imageTotalMaxBytes: 4194304;
+    maxImages: 8;
+}>;
+export interface McpOptions {
+    readonly resource: string;
+    /** The apps whose hosts answer the route (D-0132); absent: every host. */
+    readonly app?: string | readonly string[];
+    /** Absent: the path of the resource URI. */
+    readonly path?: string;
+    /** Route id overrides (D-0142); absent: `mcp.endpoint`. */
+    readonly routeIds?: {
+        readonly endpoint?: string;
+    };
+    /** Absent: the resource name. */
+    readonly name?: string;
+    readonly title?: string;
+    readonly version: string;
+    readonly instructions?: string;
+    readonly allowedOrigins: readonly string[];
+    readonly bodyLimitBytes: number;
+    readonly resultMaxChars: number;
+    /** Longest resource URI of resources/read in characters (default 8192). */
+    readonly uriMaxChars: number;
+    /** Largest picture of a tool result in bytes (default 1048576, D-0143). */
+    readonly imageMaxBytes: number;
+    /** Largest sum of the pictures of one tool result in bytes (default 4194304, D-0143). */
+    readonly imageTotalMaxBytes: number;
+    /** Pictures of one tool result at most (default 8, D-0143). */
+    readonly maxImages: number;
+    readonly toolTimeoutMs: number;
+    /** Messages of one JSON-RPC batch at most (default 32, D-0114). */
+    readonly maxBatch: number;
+    /** ttlMs of the modern list results (default 300000, D-0114). */
+    readonly listTtlMs: number;
+    /** Window of the repeated tool failure logs (default 10000, D-0114). */
+    readonly logRepeatWindowMs: number;
+    /** Pending onCall promises at most (default 1000, D-0134). */
+    readonly onCallMaxPending: number;
+    readonly limits: Readonly<Record<string, string>>;
+}
+/** The `dokebi-mcp` options declaration (parser and options.schema.json). */
+export declare const options: OptionsDeclaration<McpOptions>;