@dokebi/mcp 0.0.0-stage → 0.1.0

package/dist/schema.d.ts

@@ -0,0 +1,43 @@
+/** A JSON Schema object (as tools declare it). */
+export type JsonSchema = Readonly<Record<string, unknown>>;
+/** One validation problem: where (`input.notes[2].title`) and what, never the value. */
+export interface SchemaProblem {
+    readonly path: string;
+    readonly message: string;
+}
+/** Most problems one validation reports. */
+export declare const MAX_PROBLEMS = 20;
+/**
+ * Deepest nesting of an input value (arrays and objects). Deeper input is refused before the
+ * schema is applied: comparisons (enum, const, uniqueItems) and serialization recurse.
+ */
+export declare const MAX_INPUT_DEPTH = 64;
+/** Largest schema text (a schema is sent with every tools/list). */
+export declare const MAX_SCHEMA_CHARS = 65536;
+/**
+ * Whether a pattern repeats a group that itself repeats without bound (`(a+)+`, `(\w*)*`,
+ * `(x{2,})+`): the shape whose backtracking grows exponentially. Alternation ambiguity such as
+ * `(a|aa)+` is not detected: keep patterns linear.
+ */
+export declare function nestedQuantifier(pattern: string): boolean;
+/**
+ * A checked, frozen copy of a tool's schema and its validator. `check` collects the start-time
+ * problems (unknown keywords, a property without a description, a pattern that does not compile).
+ */
+export declare class InputSchema {
+    #private;
+    readonly schema: JsonSchema;
+    private constructor();
+    /**
+     * The schema copied (as JSON, so no function, getter or cycle survives) and checked. `root`
+     * says whether this is a tool input (an object) or an output schema.
+     */
+    static check(value: unknown, root: 'input' | 'output'): {
+        schema?: InputSchema;
+        problems: string[];
+    };
+    /** The problems of `value` (at most MAX_PROBLEMS); empty when it is valid. */
+    validate(value: unknown): SchemaProblem[];
+}
+/** A frozen JSON copy (descriptions, schemas): nothing a tool changes later leaks into a list. */
+export declare function frozenJson<T>(value: T): T;

package/dist/schema.js

@@ -0,0 +1,482 @@
+/*
+ * The JSON Schema subset of tool inputs (D-0094 §1.5): checked once at start, then used to
+ * validate every call before the tool runs. A keyword this validator does not apply is refused at
+ * start instead of being ignored at run time (a constraint the model sees must also be enforced).
+ *
+ * Supported (draft 2020-12 meaning): type, enum, const, properties, required,
+ * additionalProperties, minProperties, maxProperties, items, minItems, maxItems, uniqueItems,
+ * minLength, maxLength, pattern (ECMAScript with the `u` flag), minimum, maximum,
+ * exclusiveMinimum, exclusiveMaximum, multipleOf, anyOf, oneOf. Annotations, kept and not checked:
+ * $schema, $comment, title, description, default, examples, deprecated, readOnly, writeOnly,
+ * format. Every property needs a non-empty `description`: it is the only text the model reads
+ * about the argument.
+ */
+const ANNOTATIONS = new Set([
+    '$schema',
+    '$comment',
+    'title',
+    'description',
+    'default',
+    'examples',
+    'deprecated',
+    'readOnly',
+    'writeOnly',
+    'format',
+]);
+const ASSERTIONS = new Set([
+    'type',
+    'enum',
+    'const',
+    'properties',
+    'required',
+    'additionalProperties',
+    'minProperties',
+    'maxProperties',
+    'items',
+    'minItems',
+    'maxItems',
+    'uniqueItems',
+    'minLength',
+    'maxLength',
+    'pattern',
+    'minimum',
+    'maximum',
+    'exclusiveMinimum',
+    'exclusiveMaximum',
+    'multipleOf',
+    'anyOf',
+    'oneOf',
+]);
+const TYPES = new Set(['string', 'number', 'integer', 'boolean', 'object', 'array', 'null']);
+const COUNTS = [
+    'minProperties',
+    'maxProperties',
+    'minItems',
+    'maxItems',
+    'minLength',
+    'maxLength',
+];
+const BOUNDS = ['minimum', 'maximum', 'exclusiveMinimum', 'exclusiveMaximum'];
+/** Most problems one validation reports. */
+export const MAX_PROBLEMS = 20;
+/**
+ * Deepest nesting of an input value (arrays and objects). Deeper input is refused before the
+ * schema is applied: comparisons (enum, const, uniqueItems) and serialization recurse.
+ */
+export const MAX_INPUT_DEPTH = 64;
+/** Largest schema text (a schema is sent with every tools/list). */
+export const MAX_SCHEMA_CHARS = 65_536;
+const MAX_DESCRIPTION = 4_096;
+function plain(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** A key that reads as a path segment: `a.b`, else `a["b c"]`. */
+function child(path, key) {
+    return /^[A-Za-z_$][\w$]*$/.test(key) ? `${path}.${key}` : `${path}[${JSON.stringify(key)}]`;
+}
+/** Stable text of a JSON value (object keys sorted): equality for enum, const, uniqueItems. */
+function canonical(value) {
+    if (Array.isArray(value))
+        return `[${value.map(canonical).join(',')}]`;
+    if (plain(value))
+        return `{${Object.keys(value)
+            .sort()
+            .map((key) => `${JSON.stringify(key)}:${canonical(value[key])}`)
+            .join(',')}}`;
+    return JSON.stringify(value) ?? 'null';
+}
+/**
+ * The first part of `value` that is nested deeper than MAX_INPUT_DEPTH or is a number that is not
+ * finite, walked without recursion (a 200,000-deep array fits in a 1 MiB body).
+ */
+function shapeProblem(value) {
+    const stack = [
+        { value, path: 'input', depth: 0 },
+    ];
+    while (stack.length) {
+        const { value: one, path, depth, } = stack.pop();
+        if (typeof one === 'number' && !Number.isFinite(one))
+            return { path, message: 'must be a finite number' };
+        if (one === null || typeof one !== 'object')
+            continue;
+        if (depth >= MAX_INPUT_DEPTH)
+            return { path, message: `is nested deeper than ${MAX_INPUT_DEPTH} levels` };
+        if (Array.isArray(one))
+            for (let index = one.length - 1; index >= 0; index--)
+                stack.push({ value: one[index], path: `${path}[${index}]`, depth: depth + 1 });
+        else
+            for (const key of Object.keys(one))
+                stack.push({
+                    value: one[key],
+                    path: child(path, key),
+                    depth: depth + 1,
+                });
+    }
+    return undefined;
+}
+/**
+ * Whether a pattern repeats a group that itself repeats without bound (`(a+)+`, `(\w*)*`,
+ * `(x{2,})+`): the shape whose backtracking grows exponentially. Alternation ambiguity such as
+ * `(a|aa)+` is not detected: keep patterns linear.
+ */
+export function nestedQuantifier(pattern) {
+    const frames = [false];
+    let index = 0;
+    const unboundedAt = (at) => {
+        const char = pattern[at];
+        if (char === '+' || char === '*')
+            return 1;
+        if (char === '{') {
+            const match = /^\{\d*,\}/.exec(pattern.slice(at));
+            if (match)
+                return match[0].length;
+        }
+        return 0;
+    };
+    const quantifiedAt = (at) => {
+        const char = pattern[at];
+        return (char === '+' || char === '*' || (char === '{' && /^\{\d*(,\d*)?\}/.test(pattern.slice(at))));
+    };
+    while (index < pattern.length) {
+        const char = pattern[index];
+        if (char === '\\') {
+            index += 2;
+            continue;
+        }
+        if (char === '[') {
+            index++;
+            while (index < pattern.length && pattern[index] !== ']')
+                index += pattern[index] === '\\' ? 2 : 1;
+            index++;
+            continue;
+        }
+        if (char === '(') {
+            frames.push(false);
+            index++;
+            continue;
+        }
+        if (char === ')') {
+            const inner = frames.length > 1 ? frames.pop() : false;
+            index++;
+            if (inner && quantifiedAt(index))
+                return true;
+            const step = unboundedAt(index);
+            frames[frames.length - 1] = frames[frames.length - 1] || inner || step > 0;
+            continue;
+        }
+        const step = unboundedAt(index);
+        if (step) {
+            frames[frames.length - 1] = true;
+            index += step;
+            continue;
+        }
+        index++;
+    }
+    return false;
+}
+function typeOf(value) {
+    if (value === null)
+        return 'null';
+    if (Array.isArray(value))
+        return 'array';
+    if (typeof value === 'number')
+        return Number.isInteger(value) ? 'integer' : 'number';
+    return typeof value;
+}
+function matchesType(value, type) {
+    const actual = typeOf(value);
+    if (type === 'number')
+        return (actual === 'number' || actual === 'integer') && Number.isFinite(value);
+    // An integer beyond 2^53 has lost digits already: refused rather than taken as exact.
+    if (type === 'integer')
+        return actual === 'integer' && Number.isSafeInteger(value);
+    return actual === type;
+}
+/** Code points, as JSON Schema counts string length. */
+function length(text) {
+    let count = 0;
+    for (const _ of text)
+        count++;
+    return count;
+}
+/**
+ * A checked, frozen copy of a tool's schema and its validator. `check` collects the start-time
+ * problems (unknown keywords, a property without a description, a pattern that does not compile).
+ */
+export class InputSchema {
+    schema;
+    #patterns = new Map();
+    constructor(schema) {
+        this.schema = schema;
+    }
+    /**
+     * The schema copied (as JSON, so no function, getter or cycle survives) and checked. `root`
+     * says whether this is a tool input (an object) or an output schema.
+     */
+    static check(value, root) {
+        const problems = [];
+        let copy;
+        try {
+            const text = JSON.stringify(value);
+            if (text === undefined)
+                problems.push(`${root}Schema is not a JSON value`);
+            else if (text.length > MAX_SCHEMA_CHARS)
+                problems.push(`${root}Schema is longer than ${MAX_SCHEMA_CHARS} characters`);
+            else
+                copy = JSON.parse(text);
+        }
+        catch (error) {
+            // A cycle or a BigInt: reported as the schema's problem (the start fails with it).
+            problems.push(`${root}Schema cannot be written as JSON (${error.message})`);
+        }
+        if (problems.length)
+            return { problems };
+        if (!plain(copy) || copy.type !== 'object') {
+            problems.push(`${root}Schema must be an object schema ({ type: 'object', properties })`);
+            return { problems };
+        }
+        const schema = new InputSchema(deepFreeze(copy));
+        schema.#walk(schema.schema, root === 'input' ? 'inputSchema' : 'outputSchema', problems);
+        return problems.length ? { problems } : { schema, problems };
+    }
+    #walk(node, where, problems) {
+        if (typeof node === 'boolean')
+            return;
+        if (!plain(node)) {
+            problems.push(`${where} must be a schema object`);
+            return;
+        }
+        for (const key of Object.keys(node))
+            if (!ANNOTATIONS.has(key) && !ASSERTIONS.has(key))
+                problems.push(`${where} uses ${key}, which this server does not apply (supported: ${[...ASSERTIONS].join(', ')})`);
+        if (node.description !== undefined && typeof node.description !== 'string')
+            problems.push(`${where}.description must be a string`);
+        if (typeof node.description === 'string' && node.description.length > MAX_DESCRIPTION)
+            problems.push(`${where}.description is longer than ${MAX_DESCRIPTION} characters`);
+        const type = node.type;
+        if (type !== undefined) {
+            const list = Array.isArray(type) ? type : [type];
+            if (!list.length || list.some((one) => typeof one !== 'string' || !TYPES.has(one)))
+                problems.push(`${where}.type must be one of ${[...TYPES].join(', ')} (or a list of them)`);
+        }
+        if (node.enum !== undefined && (!Array.isArray(node.enum) || node.enum.length === 0))
+            problems.push(`${where}.enum must be a non-empty list`);
+        for (const key of COUNTS) {
+            const count = node[key];
+            if (count !== undefined && !(Number.isSafeInteger(count) && count >= 0))
+                problems.push(`${where}.${key} must be a whole number of at least 0`);
+        }
+        for (const key of BOUNDS)
+            if (node[key] !== undefined && !Number.isFinite(node[key]))
+                problems.push(`${where}.${key} must be a number`);
+        if (node.multipleOf !== undefined &&
+            !(typeof node.multipleOf === 'number' && node.multipleOf > 0))
+            problems.push(`${where}.multipleOf must be a number above 0`);
+        if (node.uniqueItems !== undefined && typeof node.uniqueItems !== 'boolean')
+            problems.push(`${where}.uniqueItems must be a boolean`);
+        if (node.pattern !== undefined) {
+            if (typeof node.pattern !== 'string')
+                problems.push(`${where}.pattern must be a string`);
+            else
+                try {
+                    this.#patterns.set(node.pattern, new RegExp(node.pattern, 'u'));
+                    if (nestedQuantifier(node.pattern))
+                        problems.push(`${where}.pattern repeats a group that repeats without bound (catastrophic backtracking): write it linearly`);
+                }
+                catch (error) {
+                    problems.push(`${where}.pattern does not compile: ${error.message}`);
+                }
+        }
+        if (node.properties !== undefined) {
+            if (!plain(node.properties))
+                problems.push(`${where}.properties must be an object`);
+            else
+                for (const [name, property] of Object.entries(node.properties)) {
+                    const at = `${where}.properties.${name}`;
+                    if (!plain(property) ||
+                        typeof property.description !== 'string' ||
+                        property.description.trim() === '')
+                        problems.push(`${at} has no description (the model reads only that about it)`);
+                    this.#walk(property, at, problems);
+                }
+        }
+        if (node.required !== undefined) {
+            const required = node.required;
+            if (!Array.isArray(required) || required.some((name) => typeof name !== 'string'))
+                problems.push(`${where}.required must be a list of property names`);
+            else if (plain(node.properties)) {
+                const declared = node.properties;
+                for (const name of required)
+                    if (!Object.hasOwn(declared, name))
+                        problems.push(`${where}.required names ${name}, which is not in properties`);
+            }
+        }
+        if (node.additionalProperties !== undefined)
+            this.#walk(node.additionalProperties, `${where}.additionalProperties`, problems);
+        if (node.items !== undefined) {
+            if (Array.isArray(node.items))
+                problems.push(`${where}.items must be one schema (tuple items are not supported)`);
+            else
+                this.#walk(node.items, `${where}.items`, problems);
+        }
+        for (const key of ['anyOf', 'oneOf']) {
+            const branches = node[key];
+            if (branches === undefined)
+                continue;
+            if (!Array.isArray(branches) || branches.length === 0)
+                problems.push(`${where}.${key} must be a non-empty list of schemas`);
+            else
+                for (const [index, branch] of branches.entries())
+                    this.#walk(branch, `${where}.${key}[${index}]`, problems);
+        }
+    }
+    /** The problems of `value` (at most MAX_PROBLEMS); empty when it is valid. */
+    validate(value) {
+        const shape = shapeProblem(value);
+        if (shape)
+            return [shape];
+        const problems = [];
+        this.#check(this.schema, value, 'input', problems);
+        return problems.slice(0, MAX_PROBLEMS);
+    }
+    #check(node, value, path, problems) {
+        if (problems.length >= MAX_PROBLEMS)
+            return;
+        if (node === true || node === undefined)
+            return;
+        if (node === false || !plain(node)) {
+            problems.push({ path, message: 'is not allowed' });
+            return;
+        }
+        const add = (message, at = path) => problems.push({ path: at, message });
+        if (node.type !== undefined) {
+            const types = (Array.isArray(node.type) ? node.type : [node.type]);
+            if (!types.some((type) => matchesType(value, type))) {
+                add(`must be ${types.join(' or ')}`);
+                return;
+            }
+        }
+        if (node.const !== undefined && canonical(node.const) !== canonical(value))
+            add(`must be ${JSON.stringify(node.const)}`);
+        if (Array.isArray(node.enum)) {
+            const text = canonical(value);
+            if (!node.enum.some((option) => canonical(option) === text))
+                add(`must be one of ${node.enum
+                    .slice(0, 20)
+                    .map((option) => JSON.stringify(option))
+                    .join(', ')}`);
+        }
+        if (typeof value === 'string')
+            this.#string(node, value, add);
+        else if (typeof value === 'number')
+            this.#number(node, value, add);
+        else if (Array.isArray(value))
+            this.#array(node, value, path, problems, add);
+        else if (plain(value))
+            this.#object(node, value, path, problems, add);
+        for (const key of ['anyOf', 'oneOf']) {
+            const branches = node[key];
+            if (!Array.isArray(branches))
+                continue;
+            let matched = 0;
+            for (const branch of branches) {
+                const inner = [];
+                this.#check(branch, value, path, inner);
+                if (inner.length === 0)
+                    matched++;
+            }
+            if (key === 'anyOf' && matched === 0)
+                add('matches none of the allowed forms');
+            if (key === 'oneOf' && matched !== 1)
+                add(matched === 0 ? 'matches none of the allowed forms' : 'matches more than one form');
+        }
+    }
+    #string(node, value, add) {
+        const count = node.minLength !== undefined || node.maxLength !== undefined ? length(value) : 0;
+        let fits = true;
+        if (typeof node.minLength === 'number' && count < node.minLength) {
+            add(`must be at least ${node.minLength} characters`);
+            fits = false;
+        }
+        if (typeof node.maxLength === 'number' && count > node.maxLength) {
+            add(`must be at most ${node.maxLength} characters`);
+            fits = false;
+        }
+        // The pattern runs only on a string whose length is allowed (a long one never reaches it).
+        if (fits && typeof node.pattern === 'string') {
+            const pattern = this.#patterns.get(node.pattern);
+            if (!pattern.test(value))
+                add(`must match the pattern ${node.pattern}`);
+        }
+    }
+    #number(node, value, add) {
+        if (typeof node.minimum === 'number' && value < node.minimum)
+            add(`must be at least ${node.minimum}`);
+        if (typeof node.maximum === 'number' && value > node.maximum)
+            add(`must be at most ${node.maximum}`);
+        if (typeof node.exclusiveMinimum === 'number' && value <= node.exclusiveMinimum)
+            add(`must be above ${node.exclusiveMinimum}`);
+        if (typeof node.exclusiveMaximum === 'number' && value >= node.exclusiveMaximum)
+            add(`must be below ${node.exclusiveMaximum}`);
+        if (typeof node.multipleOf === 'number') {
+            const quotient = value / node.multipleOf;
+            if (Math.abs(quotient - Math.round(quotient)) > 1e-9)
+                add(`must be a multiple of ${node.multipleOf}`);
+        }
+    }
+    #array(node, value, path, problems, add) {
+        if (typeof node.minItems === 'number' && value.length < node.minItems)
+            add(`must have at least ${node.minItems} items`);
+        if (typeof node.maxItems === 'number' && value.length > node.maxItems) {
+            add(`must have at most ${node.maxItems} items`);
+            return;
+        }
+        if (node.uniqueItems === true) {
+            const seen = new Set();
+            for (const item of value) {
+                const text = canonical(item);
+                if (seen.has(text)) {
+                    add('must not repeat an item');
+                    break;
+                }
+                seen.add(text);
+            }
+        }
+        if (node.items !== undefined)
+            value.forEach((item, index) => {
+                this.#check(node.items, item, `${path}[${index}]`, problems);
+            });
+    }
+    #object(node, value, path, problems, add) {
+        const keys = Object.keys(value);
+        if (typeof node.minProperties === 'number' && keys.length < node.minProperties)
+            add(`must have at least ${node.minProperties} properties`);
+        if (typeof node.maxProperties === 'number' && keys.length > node.maxProperties)
+            add(`must have at most ${node.maxProperties} properties`);
+        const properties = plain(node.properties) ? node.properties : {};
+        if (Array.isArray(node.required))
+            for (const name of node.required)
+                if (!Object.hasOwn(value, name))
+                    add('is required', child(path, name));
+        for (const key of keys) {
+            if (Object.hasOwn(properties, key))
+                this.#check(properties[key], value[key], child(path, key), problems);
+            else if (node.additionalProperties === false)
+                add('is not a known property', child(path, key));
+            else if (node.additionalProperties !== undefined)
+                this.#check(node.additionalProperties, value[key], child(path, key), problems);
+        }
+    }
+}
+function deepFreeze(value) {
+    if (value !== null && typeof value === 'object') {
+        for (const inner of Object.values(value))
+            deepFreeze(inner);
+        Object.freeze(value);
+    }
+    return value;
+}
+/** A frozen JSON copy (descriptions, schemas): nothing a tool changes later leaks into a list. */
+export function frozenJson(value) {
+    return deepFreeze(JSON.parse(JSON.stringify(value)));
+}

package/dist/server.d.ts

@@ -0,0 +1,43 @@
+import type { Logger } from '@dokebi/core';
+import { type Headers } from './era.js';
+import { type CompiledPrompt, type CompiledResource, type CompiledTool } from './registry.js';
+import type { CallSettings, McpRunner } from './runner.js';
+/** What the route sends: a status, a JSON body (undefined: empty) and the 403 challenge. */
+export interface McpReply {
+    readonly status: number;
+    readonly body: unknown;
+    readonly challenge?: string;
+}
+export interface ServerInfo {
+    readonly name: string;
+    readonly version: string;
+    readonly title?: string;
+}
+export interface ServerSettings {
+    readonly runner: McpRunner;
+    readonly tools: readonly CompiledTool[];
+    readonly prompts: readonly CompiledPrompt[];
+    readonly resources: readonly CompiledResource[];
+    readonly serverInfo: ServerInfo;
+    readonly instructions: string | undefined;
+    /** The protected resource metadata URL (the 403 challenge). */
+    readonly metadataUrl: string;
+    readonly logger: Logger;
+    /** `maxBatch` (absent: MAX_BATCH, D-0114). */
+    readonly maxBatch?: number;
+    /** `listTtlMs` (absent: LIST_TTL_MS, D-0114). */
+    readonly listTtlMs?: number;
+    /** `uriMaxChars` (absent: URI_MAX_CHARS): the longest URI `resources/read` matches. */
+    readonly uriMaxChars?: number;
+}
+/** A call without its version: the route knows the grant, the request and the client signal. */
+export type RequestCall = Omit<CallSettings, 'version'>;
+export declare class McpServer {
+    #private;
+    readonly capabilities: Readonly<Record<string, unknown>>;
+    /** D-0154: the reloaded batch size, list cache time and URI limit, for the next request. */
+    update(next: Pick<ServerSettings, 'maxBatch' | 'listTtlMs' | 'uriMaxChars'>): void;
+    constructor(settings: ServerSettings);
+    /** One POST: the body bytes, the headers and who calls. */
+    handle(raw: Uint8Array | undefined, headers: Headers, call: RequestCall): Promise<McpReply>;
+}