@dokebi/mcp 0.0.0-stage → 0.1.0

package/dist/options.js

@@ -0,0 +1,161 @@
+import { defineOptions, option as o } from '@dokebi/core';
+import { appOption, routeIdsOption } from '@dokebi/web/points';
+/*
+ * dokebi-mcp options (D-0094, D-0063 §3, D-0071 vocabulary): this declaration is both the parser
+ * definePlugin runs and options.schema.json, which the build writes from it.
+ */
+/** A resource id of @dokebi/oauth (the audience of the tokens this route accepts). */
+const RESOURCE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,63}$/;
+/** The route path. */
+const PATH = /^\/(?![/\\])[A-Za-z0-9._~!$&'()*+,;=:@%/-]{0,255}$/;
+/** An origin: scheme, host and port, no path. */
+const ORIGIN = /^https?:\/\/(?:[A-Za-z0-9.-]{1,253}|\[[0-9A-Fa-f:.]{2,45}\])(?::[0-9]{1,5})?$/;
+/** A limit bucket (`read`, `write`, `trash`). */
+export const BUCKET = /^[a-z][a-z0-9-]{0,31}$/;
+/** A @dokebi/rate-limit policy name. */
+const POLICY = /^[a-z][a-z0-9-]{0,31}$/;
+/** Default of `uriMaxChars`: the longest resource URI of `resources/read` (R4 audit, 2026-10-26). */
+export const URI_MAX_CHARS = 8_192;
+/** The defaults of the image limits (D-0143), for `callTool` of @dokebi/mcp/testing too. */
+export const IMAGE_LIMITS = Object.freeze({
+    imageMaxBytes: 1_048_576,
+    imageTotalMaxBytes: 4_194_304,
+    maxImages: 8,
+});
+const declaration = defineOptions({
+    resource: o.string({
+        pattern: RESOURCE_ID,
+        default: 'mcp',
+        description: 'The @dokebi/oauth resource this server is (options.dokebi-oauth.resources.<id>): only its tokens are accepted, and tool scopes must be its scopes',
+    }),
+    app: appOption('The app or apps of @dokebi/app whose hosts answer the MCP route (D-0132): mcp, or [mcp, api]. Other hosts get the 404 of an unknown route. Unset: every host'),
+    path: o.string({
+        pattern: PATH,
+        description: 'The route path; default the path of the resource URI (https://example.com/mcp → /mcp). Set it when a proxy changes the path',
+    }),
+    routeIds: routeIdsOption('dokebi-mcp', {
+        endpoint: 'the MCP route (POST, and the 405 answer of GET and DELETE, at path)',
+    }),
+    name: o.string({
+        minLength: 1,
+        maxLength: 200,
+        description: 'serverInfo.name; default the resource name',
+    }),
+    title: o.string({
+        minLength: 1,
+        maxLength: 200,
+        description: 'serverInfo.title (a human title for client screens)',
+    }),
+    version: o.string({
+        minLength: 1,
+        maxLength: 64,
+        default: '1.0.0',
+        description: 'serverInfo.version (your server, not the protocol)',
+    }),
+    instructions: o.string({
+        minLength: 1,
+        maxLength: 16_000,
+        description: 'Server instructions the model reads (initialize, server/discover); the extension hook instructions() wins when it gives one',
+    }),
+    allowedOrigins: o.array(o.string({ pattern: ORIGIN }), {
+        reloadable: true,
+        default: [],
+        maxItems: 64,
+        uniqueItems: true,
+        description: 'Origins a browser page may call from (the resource origin is always allowed); a request with another Origin is 403. Requests without Origin (server-side clients) pass',
+    }),
+    bodyLimitBytes: o.integer({
+        minimum: 1_024,
+        maximum: 67_108_864,
+        default: 1_048_576,
+        description: 'Largest request body of this route only (default 1 MiB; dokebi-web maxBodyBytes stays for other routes); beyond it 413 BODY_TOO_LARGE',
+    }),
+    resultMaxChars: o.integer({
+        reloadable: true,
+        minimum: 1_024,
+        maximum: 10_000_000,
+        default: 60_000,
+        description: 'Largest tool result (characters of its JSON); a larger one is the tool error RESULT_TOO_LARGE, never cut silently (page() helps)',
+    }),
+    uriMaxChars: o.integer({
+        reloadable: true,
+        minimum: 256,
+        maximum: 1_048_576,
+        default: URI_MAX_CHARS,
+        description: 'Longest resource URI of resources/read (characters); a longer one is -32602 INVALID_INPUT before any template is matched. Matching costs a pass over the URI per template, and the URI is client input of up to bodyLimitBytes',
+    }),
+    imageMaxBytes: o.integer({
+        reloadable: true,
+        minimum: 1_024,
+        maximum: 20_971_520,
+        default: IMAGE_LIMITS.imageMaxBytes,
+        description: 'Largest picture of a tool result in bytes (D-0143; default 1 MiB, sent as base64, about 4/3 of it); a larger one is the tool error IMAGE_TOO_LARGE. Send a reduced copy (a thumbnail), not the original',
+    }),
+    imageTotalMaxBytes: o.integer({
+        reloadable: true,
+        minimum: 1_024,
+        maximum: 67_108_864,
+        default: IMAGE_LIMITS.imageTotalMaxBytes,
+        description: 'Largest sum of the pictures of one tool result in bytes (D-0143; default 4 MiB); beyond it the tool error IMAGE_TOTAL_TOO_LARGE. Counted apart from resultMaxChars',
+    }),
+    maxImages: o.integer({
+        reloadable: true,
+        minimum: 0,
+        maximum: 100,
+        default: IMAGE_LIMITS.maxImages,
+        description: 'Pictures of one tool result at most (D-0143); more is the tool error TOO_MANY_IMAGES. 0 refuses every result with pictures',
+    }),
+    toolTimeoutMs: o.integer({
+        reloadable: true,
+        minimum: 1_000,
+        maximum: 600_000,
+        default: 50_000,
+        description: 'Time budget of one tool call, prompt or resource read (clients give up at 60 seconds); beyond it the signal aborts and the answer is TOOL_TIMEOUT',
+    }),
+    maxBatch: o.integer({
+        reloadable: true,
+        minimum: 1,
+        maximum: 1_024,
+        default: 32,
+        description: 'Messages of one JSON-RPC batch at most (versions that have batches); more is 400 INVALID_REQUEST (D-0114). Each message is a tool call with its own time budget and rate limit',
+    }),
+    listTtlMs: o.integer({
+        reloadable: true,
+        minimum: 0,
+        maximum: 86_400_000,
+        default: 300_000,
+        description: 'ttlMs of the modern list results (tools/list, prompts/list, resources/list): how long a client may reuse the answer for this grant (D-0114). Lists change only with a deployment',
+    }),
+    logRepeatWindowMs: o.integer({
+        minimum: 1_000,
+        maximum: 3_600_000,
+        default: 10_000,
+        description: 'Window of the repeated tool failure logs in ms: the first of a tool and code is logged in full, the rest of the window are counted (repeated, intervalMs) (D-0114)',
+    }),
+    onCallMaxPending: o.integer({
+        minimum: 1,
+        maximum: 1_000_000,
+        default: 1_000,
+        description: 'Promises returned by the extension hook onCall that may be pending at once (D-0134); an ended call that finds them all pending is not handed to the hook (warn MCP_ON_CALL_DROPPED, counted). The hook is never awaited',
+    }),
+    limits: o.record(o.string({ pattern: POLICY }), {
+        default: {},
+        keys: { pattern: BUCKET },
+        maxProperties: 32,
+        description: 'A @dokebi/rate-limit policy per tool bucket: { read: mcp-read, write: mcp-write }, counted per grant and bucket. When set, every tool bucket needs one; empty: no limit',
+    }),
+}, {
+    checks: [
+        {
+            // The pattern admits shapes the URL parser refuses (`http://[1:2]`, `https://999.1.1.1`):
+            // such an origin is refused here, at start and at a reload, never at the first request.
+            path: 'allowedOrigins',
+            message: 'must be origins a browser can send (the URL parser reads them)',
+            test: (value) => value.allowedOrigins.every((origin) => URL.canParse(origin)),
+        },
+    ],
+});
+const same = true;
+void same;
+/** The `dokebi-mcp` options declaration (parser and options.schema.json). */
+export const options = declaration;

package/dist/plugin.d.ts

@@ -0,0 +1,32 @@
+import { type PluginFactory } from '@dokebi/core';
+import { type McpCallStats } from './calls.js';
+/** The plugin API: `app.get(plugin)` or `context.getDependency(dependency)`. */
+export interface McpApi {
+    /** The route path. */
+    readonly path: string;
+    /** The @dokebi/oauth resource id. */
+    readonly resource: string;
+    /** The resource URI, as clients use it. */
+    readonly uri: string;
+    /** Names of the contributed tools, prompts and resources, in contribution order. */
+    readonly tools: readonly string[];
+    readonly prompts: readonly string[];
+    readonly resources: readonly string[];
+    /** Protocol versions this server answers, newest first. */
+    readonly versions: readonly string[];
+    /**
+     * What the `onCall` hook got so far (D-0134): delivered, pending, failed and dropped entries;
+     * all 0 without the hook.
+     */
+    callStats(): McpCallStats;
+}
+/** The user entry module (`src/infra/mcp/extension.ts`), or an extension class. */
+export interface McpEntry {
+    /** `export default class AppMcp extends McpExtension { … }` */
+    readonly default?: unknown;
+}
+/**
+ * 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 declare const createPlugin: PluginFactory<McpApi>;