mockpit 0.0.0-stage → 1.1.0

package/dist/server/mcpHttp.d.ts

@@ -0,0 +1,53 @@
+import type { Hono } from "hono";
+import type { FlowContext, FlowResult } from "./app.ts";
+import { type GuideTopic } from "./designGuide.ts";
+import type { Asset, AssetKind, Store } from "./types.ts";
+type Flow<A extends unknown[]> = (...args: A) => Promise<FlowResult>;
+export interface McpFlows {
+    publish: Flow<[body: any, ctx: FlowContext]>;
+    list: Flow<[query: {
+        project?: string;
+    }]>;
+    get: Flow<[ref: unknown, query: {
+        project?: unknown;
+        body?: boolean;
+        history?: boolean;
+    }]>;
+    ask: Flow<[ref: unknown, body: any, ctx: FlowContext]>;
+    exportMock: Flow<[
+        ref: unknown,
+        query: {
+            project?: unknown;
+            state?: unknown;
+            variant?: unknown;
+        },
+        ctx: FlowContext
+    ]>;
+    say: Flow<[ref: unknown, body: any]>;
+    feedback: Flow<[query: {
+        session?: unknown;
+        project?: unknown;
+    }]>;
+}
+export interface McpDeps {
+    store: Store;
+    basePath?: (request: Request) => string;
+    flows: McpFlows;
+    run: Flow<[body: any, ctx: FlowContext]>;
+    uploadAsset(input: {
+        data: Uint8Array;
+        contentType: string;
+        filename?: string;
+        kind?: AssetKind;
+        session?: string;
+    }): Promise<{
+        asset: Omit<Asset, "data">;
+    } | {
+        error: string;
+        status: number;
+    }>;
+    guide(project: string, topic?: GuideTopic): string | Promise<string>;
+}
+export declare function unwrap(result: FlowResult): unknown;
+export declare function registerMcp(app: Hono, deps: McpDeps): void;
+export {};

package/dist/server/mcpHttp.js

@@ -0,0 +1,143 @@
+import { decodeBase64 } from "./base64.js";
+import { isGuideTopic, unknownTopicMessage } from "./designGuide.js";
+import { HTTP_MCP_TOOLS, HTTP_RUN_TOOLS, MCP_INSTRUCTIONS, MCP_SERVER_INFO, runToolResult, toolResult, } from "./mcpSpec.js";
+import { RUN_INSTRUCTIONS } from "./runApi.js";
+// A flow's error status becomes a tool error carrying the same JSON body the
+// REST tier returns, so the agent sees the hint (states, variants) either way.
+export function unwrap(result) {
+    if (result.status >= 400) {
+        const { error, ...extra } = result.body ?? {};
+        throw new Error(Object.keys(extra).length ? `${error} ${JSON.stringify(extra)}` : String(error));
+    }
+    return result.body;
+}
+export function registerMcp(app, deps) {
+    const { flows, store } = deps;
+    async function projectOf(args) {
+        if (typeof args.project === "string" && args.project)
+            return args.project;
+        if (typeof args.session === "string") {
+            const session = await store.getSession(args.session);
+            if (session?.project)
+                return session.project;
+        }
+        const projects = await store.listProjects();
+        return projects[0]?.name ?? "workspace";
+    }
+    async function callTool(name, args, ctx) {
+        switch (name) {
+            case "publish":
+                return unwrap(await flows.publish(args, ctx));
+            case "ask":
+                return unwrap(await flows.ask(args.mock, args, ctx));
+            case "read":
+                if (args.mock === undefined)
+                    return unwrap(await flows.list({ project: args.project }));
+                return unwrap(await flows.get(args.mock, {
+                    project: args.project,
+                    body: args.body === true,
+                    history: args.history === true,
+                }));
+            case "feedback":
+                return unwrap(await flows.feedback({ session: args.session, project: args.project }));
+            case "say":
+                return unwrap(await flows.say(args.mock, args));
+            case "export":
+                return unwrap(await flows.exportMock(args.mock, args, ctx));
+            case "upload": {
+                if (typeof args.data !== "string" || args.data.length === 0) {
+                    throw new Error("upload needs base64 `data`");
+                }
+                const result = await deps.uploadAsset({
+                    data: decodeBase64(args.data),
+                    contentType: typeof args.contentType === "string" ? args.contentType : "",
+                    filename: typeof args.filename === "string" ? args.filename : undefined,
+                    kind: args.kind === "image" || args.kind === "file" ? args.kind : undefined,
+                    session: typeof args.session === "string" ? args.session : undefined,
+                });
+                if ("error" in result)
+                    throw new Error(result.error);
+                return {
+                    id: result.asset.id,
+                    sessionId: result.asset.sessionId,
+                    url: `${ctx.base}/a/${result.asset.id}`,
+                    contentType: result.asset.contentType,
+                    byteLength: result.asset.byteLength,
+                    kind: result.asset.kind,
+                };
+            }
+            case "guide": {
+                if (args.topic === undefined)
+                    return await deps.guide(await projectOf(args));
+                if (!isGuideTopic(args.topic))
+                    throw new Error(unknownTopicMessage(String(args.topic)));
+                return await deps.guide("", args.topic);
+            }
+            default:
+                throw new Error(`unknown tool: ${name}`);
+        }
+    }
+    app.post("/mcp", async (c) => {
+        const rpc = (id, result) => c.json({ jsonrpc: "2.0", id, result });
+        // `?mode=code` is the opt-in codemode catalog for clients without a
+        // harness of their own: one `run` tool instead of the mock tools.
+        const code = c.req.query("mode") === "code";
+        const rpcError = (id, code, message, status = 200) => c.json({ jsonrpc: "2.0", id, error: { code, message } }, status);
+        let msg;
+        try {
+            msg = await c.req.json();
+        }
+        catch {
+            return rpcError(null, -32700, "parse error", 400);
+        }
+        if (Array.isArray(msg)) {
+            return rpcError(null, -32600, "batch requests are not supported", 400);
+        }
+        if (msg.method === "initialize") {
+            return rpc(msg.id, {
+                protocolVersion: typeof msg.params?.protocolVersion === "string"
+                    ? msg.params.protocolVersion
+                    : "2025-03-26",
+                capabilities: { tools: { listChanged: false } },
+                serverInfo: MCP_SERVER_INFO,
+                instructions: code ? RUN_INSTRUCTIONS : MCP_INSTRUCTIONS,
+            });
+        }
+        if (msg.id === undefined)
+            return c.body(null, 202); // notifications
+        if (msg.method === "ping")
+            return rpc(msg.id, {});
+        if (msg.method === "tools/list") {
+            return rpc(msg.id, { tools: code ? HTTP_RUN_TOOLS : HTTP_MCP_TOOLS });
+        }
+        if (msg.method === "tools/call") {
+            const url = new URL(c.req.url);
+            const ctx = {
+                base: `${url.origin}${deps.basePath?.(c.req.raw) ?? ""}`,
+                // An MCP caller is an agent, never the viewer.
+                viewer: false,
+                strict: false,
+                request: c.req.raw,
+                signal: c.req.raw.signal,
+            };
+            try {
+                const name = msg.params?.name;
+                if (name === "run") {
+                    const args = msg.params?.arguments ?? {};
+                    return rpc(msg.id, runToolResult(unwrap(await deps.run(args, ctx))));
+                }
+                return rpc(msg.id, toolResult(name, await callTool(name, msg.params?.arguments ?? {}, ctx)));
+            }
+            catch (err) {
+                return rpc(msg.id, {
+                    content: [{ type: "text", text: `error: ${err instanceof Error ? err.message : err}` }],
+                    isError: true,
+                });
+            }
+        }
+        return rpcError(msg.id, -32601, `method not found: ${msg.method}`);
+    });
+    // Stateless server: no SSE stream to resume, no session to delete.
+    app.get("/mcp", (c) => c.text("mockpit MCP is stateless — POST JSON-RPC messages here", 405));
+    app.delete("/mcp", (c) => c.body(null, 405));
+}

package/dist/server/mcpSpec.d.ts

@@ -0,0 +1,191 @@
+import * as z from "zod/v4";
+export declare const MCP_SERVER_INFO: {
+    name: string;
+    version: string;
+};
+export declare const MCP_INSTRUCTIONS: string;
+export declare const mcpSurfaceSchema: z.ZodObject<{
+    id: z.ZodOptional<z.ZodString>;
+    kind: z.ZodOptional<z.ZodEnum<{
+        html: "html";
+        diff: "diff";
+        image: "image";
+        markdown: "markdown";
+        terminal: "terminal";
+        mermaid: "mermaid";
+        json: "json";
+        code: "code";
+    }>>;
+    html: z.ZodOptional<z.ZodString>;
+    kits: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    markdown: z.ZodOptional<z.ZodString>;
+    mermaid: z.ZodOptional<z.ZodString>;
+    patch: z.ZodOptional<z.ZodString>;
+    files: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        filename: z.ZodString;
+        before: z.ZodString;
+        after: z.ZodString;
+        language: z.ZodOptional<z.ZodString>;
+    }, z.core.$strip>>>;
+    layout: z.ZodOptional<z.ZodEnum<{
+        unified: "unified";
+        split: "split";
+    }>>;
+    assetId: z.ZodOptional<z.ZodString>;
+    alt: z.ZodOptional<z.ZodString>;
+    caption: z.ZodOptional<z.ZodString>;
+    title: z.ZodOptional<z.ZodString>;
+    text: z.ZodOptional<z.ZodString>;
+    cols: z.ZodOptional<z.ZodNumber>;
+    data: z.ZodOptional<z.ZodUnknown>;
+    code: z.ZodOptional<z.ZodString>;
+    language: z.ZodOptional<z.ZodString>;
+    lineStart: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strip>;
+type Param = {
+    t: "string" | "number" | "boolean" | "integer";
+    d?: string;
+    req?: boolean;
+} | {
+    t: "enum";
+    values: readonly [string, ...string[]];
+    d?: string;
+    req?: boolean;
+} | {
+    t: "surfaces" | "asks" | "object";
+    d?: string;
+    req?: boolean;
+};
+interface ToolDef {
+    name: string;
+    description: string;
+    params: Record<string, Param>;
+    httpOnly?: readonly string[];
+    stdioExtra?: Record<string, Param>;
+}
+export declare const MCP_TOOL_DEFS: ToolDef[];
+export declare const RUN_TOOL_DEF: ToolDef;
+type Json = Record<string, unknown>;
+export declare const HTTP_MCP_TOOLS: ({
+    _meta: {
+        "anthropic/alwaysLoad": boolean;
+    };
+    outputSchema?: Json | undefined;
+    name: string;
+    description: string;
+    inputSchema: Json;
+} | {
+    _meta?: undefined;
+    outputSchema?: Json | undefined;
+    name: string;
+    description: string;
+    inputSchema: Json;
+})[];
+export declare const STDIO_MCP_CATALOG: ({
+    _meta: {
+        "anthropic/alwaysLoad": boolean;
+    };
+    outputSchema?: Json | undefined;
+    name: string;
+    description: string;
+    inputSchema: Json;
+} | {
+    _meta?: undefined;
+    outputSchema?: Json | undefined;
+    name: string;
+    description: string;
+    inputSchema: Json;
+})[];
+export declare const HTTP_RUN_TOOLS: ({
+    _meta: {
+        "anthropic/alwaysLoad": boolean;
+    };
+    outputSchema?: Json | undefined;
+    name: string;
+    description: string;
+    inputSchema: Json;
+} | {
+    _meta?: undefined;
+    outputSchema?: Json | undefined;
+    name: string;
+    description: string;
+    inputSchema: Json;
+})[];
+export declare const STDIO_RUN_CATALOG: ({
+    _meta: {
+        "anthropic/alwaysLoad": boolean;
+    };
+    outputSchema?: Json | undefined;
+    name: string;
+    description: string;
+    inputSchema: Json;
+} | {
+    _meta?: undefined;
+    outputSchema?: Json | undefined;
+    name: string;
+    description: string;
+    inputSchema: Json;
+})[];
+export declare const STDIO_MCP_TOOLS: ({
+    _meta: {
+        "anthropic/alwaysLoad": boolean;
+    };
+    outputSchema?: z.ZodObject<Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }>, z.core.$loose> | undefined;
+    name: string;
+    description: string;
+    inputSchema: Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }>;
+} | {
+    _meta?: undefined;
+    outputSchema?: z.ZodObject<Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }>, z.core.$loose> | undefined;
+    name: string;
+    description: string;
+    inputSchema: Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }>;
+})[];
+export declare const STDIO_RUN_TOOLS: ({
+    _meta: {
+        "anthropic/alwaysLoad": boolean;
+    };
+    outputSchema?: z.ZodObject<Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }>, z.core.$loose> | undefined;
+    name: string;
+    description: string;
+    inputSchema: Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }>;
+} | {
+    _meta?: undefined;
+    outputSchema?: z.ZodObject<Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }>, z.core.$loose> | undefined;
+    name: string;
+    description: string;
+    inputSchema: Readonly<{
+        [k: string]: z.core.$ZodType<unknown, unknown, z.core.$ZodTypeInternals<unknown, unknown>>;
+    }>;
+})[];
+export declare const MCP_TOOL_NAMES: string[];
+export declare function toolResult(name: string, value: unknown): {
+    structuredContent?: Record<string, unknown> | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export declare function runToolResult(envelope: unknown): {
+    isError?: boolean | undefined;
+    structuredContent?: Record<string, unknown> | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+};
+export {};