@theoremjs/react 0.3.1 → 0.3.3

package/README.md

@@ -3,6 +3,7 @@
 [![npm](https://img.shields.io/npm/v/@theoremjs/react?logo=npm&label=npm&color=cb3837)](https://www.npmjs.com/package/@theoremjs/react)
 [![CI](https://github.com/masudl-hub/theoremai/actions/workflows/ci.yml/badge.svg)](https://github.com/masudl-hub/theoremai/actions/workflows/ci.yml)
 [![MIT License](https://img.shields.io/badge/license-MIT-blue)](https://github.com/masudl-hub/theoremai/blob/main/LICENSE)
+[![Ask DeepWiki](https://deepwiki.com/badge.svg)](https://deepwiki.com/masudl-hub/theoremai)
 
 Define an agent once. Get the server and the user interface from the same definition.
 
@@ -250,6 +251,23 @@ The handler accepts these requests:
 
 The console builds a form from the input schema. It shows the result as figures, charts, tables, images, audio, or Markdown, with the raw JSON beside it. If the data renderer fails, the view switches to JSON so the selected view matches what is shown. For your own UI, use `createHostTransport` and `useTheoremHost`.
 
+#### Serve a host profile over MCP
+
+`createTheoremMcpHandler` serves the same profile to MCP clients, such as coding agents and chat apps, at one endpoint. It answers MCP clients of the current revision and clients that still open with `initialize`, and it keeps no session between requests.
+
+```ts
+import { createTheoremMcpHandler } from '@theoremjs/react/server';
+
+export const mcp = createTheoremMcpHandler({ profile: docsTools, version: '1.0.0' }); // mount at /mcp
+```
+
+- `tools/list` gives each allowed tool with its input schema. A tool's `access` becomes the read-only and destructive hints of MCP.
+- Clients of the current revision may cache the tool list for 5 minutes and the discovery result for an hour. Neither holds anything about the caller, so a shared cache may keep them.
+- `tools/call` runs the tool through the gates, the guardrails, and the trace of the kernel. The client receives the text a model would read, not the raw output.
+- A tool that fails returns a result marked `isError`, so the model can read it and try again.
+- No one can approve a call over MCP. The handler refuses a profile when an allowed tool has a permission other than `auto`.
+- A browser page on another origin is refused unless `origins` lists it.
+
 ### Decision
 
 A `decision` profile has no conversation. You give it a JSON state and questions. It answers the questions about the state.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@theoremjs/react",
-  "version": "0.3.1",
+  "version": "0.3.3",
   "description": "React bindings for Theorem: headless hooks + transport, an Astryx chat UI, and a Web-standard server handler.",
   "license": "MIT",
   "type": "module",
@@ -60,7 +60,7 @@
     "@stylexjs/stylex": "0.19.0",
     "react": "^19.0.0",
     "react-dom": "^19.0.0",
-    "@theoremjs/agents": "^0.3.1"
+    "@theoremjs/agents": "^0.3.3"
   },
   "peerDependenciesMeta": {
     "@astryxdesign/core": {

package/server/handler.d.ts

@@ -150,3 +150,9 @@ export declare function createTheoremHandler(options: TheoremHandlerOptions): (r
  * directly, and every call runs through the kernel's gates and guardrails.
  */
 export declare function createTheoremHostHandler(options: TheoremHostHandlerOptions): (request: Request) => Promise<Response>;
+/** The host profile a handler serves; any other type is the builder's mistake, refused at setup. */
+export declare function defineHostProfile(handler: string, definition: TheoremHostHandlerOptions['profile']): Extract<Profile, {
+    type: 'host';
+}>;
+/** A registered tool a host profile can serve: builtins run only inside a model's turn. */
+export declare function hostTool(name: string): import("../../../src/kernel/tools/types.ts").RegisteredAgentTool | import("../../../src/kernel/tools/types.ts").FunctionToolDef<unknown, unknown> | import("../../../src/kernel/tools/types.ts").HttpToolDef<unknown, unknown> | import("../../../src/kernel/tools/types.ts").McpToolDef<unknown, unknown> | undefined;

package/server/handler.js

@@ -652,13 +652,8 @@ async function settlingOf(ctx, request, session, body) {
 }
 async function hostRoute(ctx, request, session) {
     const target = routeOf(request);
-    if (request.method === 'GET' && target === '') {
-        const tool = (name) => {
-            const registered = defaultKernelScope.tools.get(name);
-            return registered?.type === 'builtin' ? undefined : registered;
-        };
-        return jsonResponse(200, { interface: hostInterface(ctx.profile, tool) });
-    }
+    if (request.method === 'GET' && target === '')
+        return jsonResponse(200, { interface: hostInterface(ctx.profile, hostTool) });
     if (request.method === 'POST' && target === 'call') {
         const body = await readBody(request, theoremHostCallRequestSchema, ctx.options.maxRequestBytes);
         return eventStream(ctx, request, () => callEvents(ctx, request, session, body));
@@ -731,12 +726,21 @@ export function createTheoremHandler(options) {
  * directly, and every call runs through the kernel's gates and guardrails.
  */
 export function createTheoremHostHandler(options) {
-    const profile = defineProfile(options.profile);
+    return serve('createTheoremHostHandler', defineHostProfile('createTheoremHostHandler', options.profile), options);
+}
+/** The host profile a handler serves; any other type is the builder's mistake, refused at setup. */
+export function defineHostProfile(handler, definition) {
+    const profile = defineProfile(definition);
     if (profile.type !== 'host') {
         // labels-exempt: builder config error at setup; no user sees it
-        throw new Error(`createTheoremHostHandler serves type 'host'; got type '${profile.type}'.`);
+        throw new Error(`${handler} serves type 'host'; got type '${profile.type}'.`);
     }
-    return serve('createTheoremHostHandler', profile, options);
+    return profile;
+}
+/** A registered tool a host profile can serve: builtins run only inside a model's turn. */
+export function hostTool(name) {
+    const registered = defaultKernelScope.tools.get(name);
+    return registered?.type === 'builtin' ? undefined : registered;
 }
 function serve(name, profile, options, chatOptions = {}) {
     const gateTtlMs = resolveGateTtlMs(name, options.gateTtlMs);

package/server/mcp-handler.d.ts

@@ -0,0 +1,46 @@
+/**
+ * One Web-standard handler that serves a host profile's tools to MCP clients over
+ * Streamable HTTP, at one endpoint that takes POST.
+ *
+ * - Clients on the current revision (`2026-07-28`) send each request with its version and
+ *   capabilities in `_meta`; nothing is kept between requests.
+ * - Clients on an earlier revision open with `initialize`; the handler answers it and serves
+ *   them the same way, without a session.
+ *
+ * Every call runs through the kernel as a host call does: the profile's gates, guardrails and
+ * trace. The client reads what a model would: the call's guarded text, never its raw output.
+ *
+ * @module
+ */
+import { type ClientTurnOptions } from '@theoremjs/agents/host';
+import { type TheoremHostHandlerOptions } from './handler.ts';
+export type TheoremMcpHandlerOptions = {
+    /** Host profile to serve. Registered with the kernel when the handler is created. */
+    profile: TheoremHostHandlerOptions['profile'];
+    /** The server's version, as clients show it. */
+    version: string;
+    /** The server's name, as clients show it. Defaults to the profile's id. */
+    name?: string;
+    /** How a model should use these tools; clients may add it to the model's context. */
+    instructions?: string;
+    /**
+     * Origins a browser page may call from, besides the endpoint's own. A request whose
+     * `Origin` is neither is refused with 403, as MCP requires against DNS rebinding.
+     */
+    origins?: readonly string[];
+    /** Handed to each tool as `ctx.host`. */
+    host?: (request: Request) => unknown;
+    /** Largest request body read, in bytes. */
+    maxRequestBytes?: number;
+    /** Who reads this host's replies: forwarded to `clientError` for a failure the handler catches. */
+    clientEvents?: ClientTurnOptions;
+    /** Called with any error the handler catches, for reporting. */
+    onError?: (err: unknown, ctx: {
+        request: Request;
+    }) => void;
+};
+/**
+ * Serves a host profile's tools to MCP clients. Every tool the profile allows must run
+ * without a person's approval: an MCP client has no one to ask.
+ */
+export declare function createTheoremMcpHandler(options: TheoremMcpHandlerOptions): (request: Request) => Promise<Response>;

package/server/mcp-handler.js

@@ -0,0 +1,312 @@
+/**
+ * One Web-standard handler that serves a host profile's tools to MCP clients over
+ * Streamable HTTP, at one endpoint that takes POST.
+ *
+ * - Clients on the current revision (`2026-07-28`) send each request with its version and
+ *   capabilities in `_meta`; nothing is kept between requests.
+ * - Clients on an earlier revision open with `initialize`; the handler answers it and serves
+ *   them the same way, without a session.
+ *
+ * Every call runs through the kernel as a host call does: the profile's gates, guardrails and
+ * trace. The client reads what a model would: the call's guarded text, never its raw output.
+ *
+ * @module
+ */
+import { invokeTool, labelText, registerProfile, } from '@theoremjs/agents';
+import { caughtStatus, clientError } from '@theoremjs/agents/host';
+import { hostInterface } from "../client/host-transport.js";
+import { defineHostProfile, hostTool } from "./handler.js";
+import { boundedRequestJson, requestByteLimit } from "./request-body.js";
+/** The revision that carries its version on every request. */
+const MODERN_VERSION = '2026-07-28';
+/** Revisions that open with `initialize`, newest first. */
+const LEGACY_VERSIONS = ['2025-11-25', '2025-06-18', '2025-03-26'];
+const SUPPORTED_VERSIONS = [MODERN_VERSION, ...LEGACY_VERSIONS];
+const META_VERSION = 'io.modelcontextprotocol/protocolVersion';
+const META_CAPABILITIES = 'io.modelcontextprotocol/clientCapabilities';
+const META_SERVER = 'io.modelcontextprotocol/serverInfo';
+/**
+ * How long a current-revision client may keep each cacheable result, in milliseconds. Neither
+ * holds anything of the caller's, so any cache may share them.
+ */
+const CACHED = {
+    'server/discover': 3_600_000,
+    'tools/list': 300_000,
+};
+const PARSE_ERROR = -32700;
+const INVALID_REQUEST = -32600;
+const METHOD_NOT_FOUND = -32601;
+const INVALID_PARAMS = -32602;
+const INTERNAL_ERROR = -32603;
+const HEADER_MISMATCH = -32020;
+const UNSUPPORTED_VERSION = -32022;
+class RpcError extends Error {
+    status;
+    code;
+    data;
+    constructor(status, code, message, data) {
+        super(message);
+        this.status = status;
+        this.code = code;
+        this.data = data;
+    }
+}
+function reply(status, body) {
+    return new Response(JSON.stringify(body), {
+        status,
+        headers: { 'content-type': 'application/json', 'cache-control': 'no-store' },
+    });
+}
+function rpcError(id, error) {
+    return reply(error.status, {
+        jsonrpc: '2.0',
+        id,
+        error: {
+            code: error.code,
+            message: error.message,
+            ...(error.data !== undefined ? { data: error.data } : {}),
+        },
+    });
+}
+function isRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value);
+}
+/** The JSON-RPC message in `body`; one message per POST, never a batch or a response. */
+function rpcRequest(body) {
+    if (!isRecord(body) ||
+        body.jsonrpc !== '2.0' ||
+        typeof body.method !== 'string' ||
+        (body.id !== undefined && typeof body.id !== 'string' && typeof body.id !== 'number') ||
+        (body.params !== undefined && !isRecord(body.params)))
+        // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+        throw new RpcError(400, INVALID_REQUEST, 'Invalid request');
+    return {
+        ...(body.id !== undefined ? { id: body.id } : {}),
+        method: body.method,
+        params: isRecord(body.params) ? body.params : {},
+    };
+}
+/** A mirrored header's value, decoded from the `=?base64?…?=` form MCP uses for unsafe values. */
+function headerValue(value) {
+    const encoded = /^=\?base64\?(.*)\?=$/.exec(value);
+    if (!encoded)
+        return value;
+    const bytes = Uint8Array.from(atob(encoded[1]), (char) => char.charCodeAt(0));
+    return new TextDecoder().decode(bytes);
+}
+/**
+ * The current revision's request checks: a version this server speaks, the capabilities the
+ * client declares, and headers that agree with the body they mirror.
+ */
+function checkModern(request, message, meta) {
+    const version = meta[META_VERSION];
+    if (version !== MODERN_VERSION)
+        // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+        throw new RpcError(400, UNSUPPORTED_VERSION, 'Unsupported protocol version', {
+            supported: SUPPORTED_VERSIONS,
+            requested: version,
+        });
+    if (!isRecord(meta[META_CAPABILITIES]))
+        // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+        throw new RpcError(400, INVALID_PARAMS, `Missing _meta field ${META_CAPABILITIES}`);
+    const mirrored = [
+        ['mcp-protocol-version', version],
+        ['mcp-method', message.method],
+    ];
+    if (message.method === 'tools/call')
+        mirrored.push(['mcp-name', message.params.name]);
+    for (const [name, body] of mirrored) {
+        const header = request.headers.get(name);
+        if (header === null || headerValue(header) !== body)
+            // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+            throw new RpcError(400, HEADER_MISMATCH, `Header mismatch: ${name}`);
+    }
+}
+/** The legacy revision a client asked for in `initialize`, or the newest one this server speaks. */
+function legacyVersion(params) {
+    const asked = params.protocolVersion;
+    return LEGACY_VERSIONS.find((version) => version === asked) ?? LEGACY_VERSIONS[0];
+}
+/** What the client reads of one call, from the kernel's events for it. */
+function callResult(events, labels) {
+    for (const event of events) {
+        if (event.type === 'error')
+            return {
+                content: [
+                    { type: 'text', text: event.error ?? labelText(`error.${event.errorKind}`, {}, labels) },
+                ],
+                isError: true,
+            };
+        if (event.type !== 'tool' || !('phase' in event.tool))
+            continue;
+        const tool = event.tool;
+        if (tool.phase === 'complete')
+            return {
+                content: [
+                    { type: 'text', text: tool.readBack ?? '' },
+                    ...(tool.parts ?? []).map(partContent),
+                ],
+                isError: false,
+            };
+        if (tool.phase === 'error')
+            return {
+                content: [{ type: 'text', text: tool.readBack ?? tool.failure.message }],
+                isError: true,
+            };
+        // why: No one can answer a gate here; the client reads why the call stopped, as a model would.
+        if (tool.phase === 'gate')
+            return {
+                content: [{ type: 'text', text: tool.readBack ?? labelText('error.blocked', {}, labels) }],
+                isError: true,
+            };
+    }
+    return {
+        content: [{ type: 'text', text: labelText('error.internal', {}, labels) }],
+        isError: true,
+    };
+}
+function partContent(part, index) {
+    if (part.type === 'text')
+        return { type: 'text', text: part.text };
+    if ('uri' in part)
+        return { type: 'resource_link', uri: part.uri, name: part.uri, mimeType: part.mimeType };
+    if (part.type === 'image' || part.type === 'audio')
+        return { type: part.type, data: part.data, mimeType: part.mimeType };
+    return {
+        type: 'resource',
+        resource: { uri: `part:${index}`, mimeType: part.mimeType, blob: part.data },
+    };
+}
+/** Same origin, or one the host lists; a request with no `Origin` is not from a page. */
+function originAllowed(request, origins) {
+    const origin = request.headers.get('origin');
+    return origin === null || origin === new URL(request.url).origin || origins.includes(origin);
+}
+/**
+ * Serves a host profile's tools to MCP clients. Every tool the profile allows must run
+ * without a person's approval: an MCP client has no one to ask.
+ */
+export function createTheoremMcpHandler(options) {
+    const host = defineHostProfile('createTheoremMcpHandler', options.profile);
+    for (const name of host.tools.allow) {
+        const permission = hostTool(name)?.permission;
+        if (permission !== undefined && permission !== 'auto') {
+            // labels-exempt: builder config error at setup; no user sees it
+            throw new Error(`createTheoremMcpHandler serves tools that run without approval; '${name}' has permission '${permission}'.`);
+        }
+    }
+    const maxBytes = requestByteLimit(options.maxRequestBytes);
+    registerProfile(host);
+    const serverInfo = { name: options.name ?? host.id, version: options.version };
+    const instructions = options.instructions ? { instructions: options.instructions } : {};
+    const listed = () => hostInterface(host, hostTool).tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        annotations: {
+            readOnlyHint: tool.access === 'read-only',
+            ...(tool.access === 'destructive' ? { destructiveHint: true } : {}),
+        },
+    }));
+    async function call(request, params) {
+        const name = params.name;
+        if (typeof name !== 'string' || !listed().some((tool) => tool.name === name))
+            // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+            throw new RpcError(200, INVALID_PARAMS, `Unknown tool: ${String(name)}`);
+        const events = [];
+        for await (const event of invokeTool({
+            profile: host.id,
+            name,
+            input: params.arguments ?? {},
+            signal: request.signal,
+            host: await options.host?.(request),
+        }))
+            events.push(event);
+        return callResult(events, host.labels);
+    }
+    async function result(request, message, modern) {
+        switch (message.method) {
+            case 'server/discover':
+                if (!modern)
+                    break;
+                return {
+                    supportedVersions: SUPPORTED_VERSIONS,
+                    capabilities: { tools: {} },
+                    ...instructions,
+                };
+            case 'initialize':
+                if (modern)
+                    break;
+                return {
+                    protocolVersion: legacyVersion(message.params),
+                    capabilities: { tools: {} },
+                    serverInfo,
+                    ...instructions,
+                };
+            case 'ping':
+                if (modern)
+                    break;
+                return {};
+            case 'tools/list':
+                return { tools: listed() };
+            case 'tools/call':
+                return await call(request, message.params);
+        }
+        // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+        throw new RpcError(modern ? 404 : 200, METHOD_NOT_FOUND, `Method not found: ${message.method}`);
+    }
+    return async (request) => {
+        if (!originAllowed(request, options.origins ?? []))
+            // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+            return rpcError(null, new RpcError(403, INVALID_REQUEST, 'Origin not allowed'));
+        if (request.method !== 'POST')
+            return new Response(null, { status: 405, headers: { allow: 'POST' } });
+        let id = null;
+        try {
+            let body;
+            try {
+                body = await boundedRequestJson(request, maxBytes);
+            }
+            catch (err) {
+                if (err instanceof SyntaxError)
+                    // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+                    throw new RpcError(400, PARSE_ERROR, 'Parse error');
+                throw err;
+            }
+            const message = rpcRequest(body);
+            id = message.id ?? null;
+            const meta = isRecord(message.params._meta) ? message.params._meta : {};
+            const modern = META_VERSION in meta;
+            if (modern)
+                checkModern(request, message, meta);
+            else if (request.headers.get('mcp-protocol-version') === MODERN_VERSION)
+                // labels-exempt: protocol diagnostic for the MCP client, not end-user copy
+                throw new RpcError(400, INVALID_PARAMS, `Missing _meta field ${META_VERSION}`);
+            // invariant: A notification has no reply; the client needs only to know it arrived.
+            if (message.id === undefined)
+                return new Response(null, { status: 202 });
+            const answered = await result(request, message, modern);
+            const ttlMs = CACHED[message.method];
+            return reply(200, {
+                jsonrpc: '2.0',
+                id: message.id,
+                result: modern
+                    ? {
+                        resultType: 'complete',
+                        ...answered,
+                        ...(ttlMs !== undefined ? { ttlMs, cacheScope: 'public' } : {}),
+                        _meta: { [META_SERVER]: serverInfo },
+                    }
+                    : answered,
+            });
+        }
+        catch (err) {
+            if (err instanceof RpcError)
+                return rpcError(id, err);
+            options.onError?.(err, { request });
+            const failure = clientError(err, host.labels, options.clientEvents);
+            const code = failure.errorKind === 'request' ? INVALID_REQUEST : INTERNAL_ERROR;
+            return rpcError(id, new RpcError(caughtStatus(err), code, failure.error));
+        }
+    };
+}

package/server/mod.d.ts

@@ -1,6 +1,6 @@
 /**
  * Server half of `@theoremjs/react`: serve one profile to the chat UI, a
- * decision profile to the decision UI, or a host profile's tools to the host UI.
+ * decision profile to the decision UI, or a host profile's tools to the host UI or to MCP clients.
  *
  * @module
  */
@@ -13,6 +13,7 @@ export { createMemoryCredentialStore, type TheoremCredentialStore, type TheoremC
 export { createTheoremDecisionHandler, type TheoremDecisionHandlerOptions, } from './decision-handler.ts';
 export { createTheoremEmbeddingHandler, embedBodySchema, embedRequest, type TheoremEmbeddingHandlerOptions, } from './embedding-handler.ts';
 export { createTheoremHandler, createTheoremHostHandler, readBody, type TheoremHandlerOptions, type TheoremHostHandlerOptions, type TheoremRequestContext, theoremSession, theoremSessionId, } from './handler.ts';
+export { createTheoremMcpHandler, type TheoremMcpHandlerOptions } from './mcp-handler.ts';
 export { createMemoryPageToolBroker, type PageToolBroker, type PageToolResult, pageToolResultSchema, sessionPageDispatch, } from './page-dispatch.ts';
 export { checkRequest, parseLiveClientMessage, parseLiveOpenMessage } from './request-check.ts';
 export { sessionStateStore } from './session-authority.ts';

package/server/mod.js

@@ -1,6 +1,6 @@
 /**
  * Server half of `@theoremjs/react`: serve one profile to the chat UI, a
- * decision profile to the decision UI, or a host profile's tools to the host UI.
+ * decision profile to the decision UI, or a host profile's tools to the host UI or to MCP clients.
  *
  * @module
  */
@@ -12,6 +12,7 @@ export { createMemoryCredentialStore, } from "./credential-store.js";
 export { createTheoremDecisionHandler, } from "./decision-handler.js";
 export { createTheoremEmbeddingHandler, embedBodySchema, embedRequest, } from "./embedding-handler.js";
 export { createTheoremHandler, createTheoremHostHandler, readBody, theoremSession, theoremSessionId, } from "./handler.js";
+export { createTheoremMcpHandler } from "./mcp-handler.js";
 export { createMemoryPageToolBroker, pageToolResultSchema, sessionPageDispatch, } from "./page-dispatch.js";
 export { checkRequest, parseLiveClientMessage, parseLiveOpenMessage } from "./request-check.js";
 export { sessionStateStore } from "./session-authority.js";