skybridge 0.0.0-dev.f49389e → 0.0.0-dev.f4ecc17

package/dist/server/express.js

@@ -0,0 +1,72 @@
+import path from "node:path";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import cors from "cors";
+import express from "express";
+export async function createApp({ mcpServer, httpServer, customMiddleware = [], }) {
+    const app = express();
+    app.use(express.json());
+    const env = process.env.NODE_ENV || "development";
+    for (const middleware of customMiddleware) {
+        if (middleware.path) {
+            app.use(middleware.path, ...middleware.handlers);
+        }
+        else {
+            app.use(...middleware.handlers);
+        }
+    }
+    if (env !== "production") {
+        const { devtoolsStaticServer } = await import("@skybridge/devtools");
+        app.use(await devtoolsStaticServer());
+        const { widgetsDevServer } = await import("./widgetsDevServer.js");
+        app.use(await widgetsDevServer(httpServer));
+    }
+    if (env === "production") {
+        const assetsPath = path.join(process.cwd(), "dist", "assets");
+        app.use("/assets", cors());
+        app.use("/assets", express.static(assetsPath));
+    }
+    app.use("/mcp", mcpMiddleware(mcpServer));
+    return app;
+}
+const mcpMiddleware = (server) => {
+    return async (req, res, _next) => {
+        if (req.method !== "POST") {
+            res.writeHead(405).end(JSON.stringify({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Method not allowed.",
+                },
+                id: null,
+            }));
+            return;
+        }
+        try {
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            res.on("close", () => {
+                transport.close();
+            });
+            await server.connect(transport);
+            // Express strips the mount path from req.url (e.g. "/mcp" becomes "/").
+            // Restore it so the SDK builds the correct requestInfo.url.
+            req.url = req.originalUrl;
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch (error) {
+            console.error("Error handling MCP request:", error);
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: "Internal server error",
+                    },
+                    id: null,
+                });
+            }
+        }
+    };
+};
+//# sourceMappingURL=express.js.map

package/dist/server/express.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.js","sourceRoot":"","sources":["../../src/server/express.ts"],"names":[],"mappings":"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"}

package/dist/server/express.test.js

@@ -0,0 +1,80 @@
+import http from "node:http";
+import { afterEach, describe, expect, it, vi } from "vitest";
+vi.mock("@skybridge/devtools", () => ({
+    devtoolsStaticServer: () => ((_req, _res, next) => next()),
+}));
+vi.mock("./widgetsDevServer.js", () => ({
+    widgetsDevServer: (_httpServer) => ((_req, _res, next) => next()),
+}));
+const fakeServer = {};
+async function listen(app) {
+    const server = http.createServer(app);
+    await new Promise((resolve) => server.listen(0, resolve));
+    const port = server.address().port;
+    return { port, server };
+}
+let openServer;
+afterEach(() => openServer?.close());
+async function postMcp(port) {
+    return fetch(`http://localhost:${port}/mcp`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ jsonrpc: "2.0", method: "initialize", id: 1 }),
+    });
+}
+describe("createApp", () => {
+    it("runs global custom middleware before the /mcp handler", async () => {
+        const { createApp } = await import("./express.js");
+        const calls = [];
+        const mw = (_req, _res, next) => {
+            calls.push("custom");
+            next();
+        };
+        const httpServer = http.createServer();
+        const app = await createApp({
+            mcpServer: fakeServer,
+            httpServer,
+            customMiddleware: [{ handlers: [mw] }],
+        });
+        const { port, server } = await listen(app);
+        openServer = server;
+        await postMcp(port);
+        expect(calls).toEqual(["custom"]);
+    });
+    it("runs path-scoped middleware on /mcp", async () => {
+        const { createApp } = await import("./express.js");
+        const calls = [];
+        const mw = (_req, _res, next) => {
+            calls.push("auth");
+            next();
+        };
+        const httpServer = http.createServer();
+        const app = await createApp({
+            mcpServer: fakeServer,
+            httpServer,
+            customMiddleware: [{ path: "/mcp", handlers: [mw] }],
+        });
+        const { port, server } = await listen(app);
+        openServer = server;
+        await postMcp(port);
+        expect(calls).toEqual(["auth"]);
+    });
+    it("allows middleware to short-circuit with 401", async () => {
+        const { createApp } = await import("./express.js");
+        const reject = (_req, res) => {
+            res.status(401).json({ error: "Unauthorized" });
+        };
+        const httpServer = http.createServer();
+        const app = await createApp({
+            mcpServer: fakeServer,
+            httpServer,
+            customMiddleware: [{ path: "/mcp", handlers: [reject] }],
+        });
+        const { port, server } = await listen(app);
+        openServer = server;
+        const res = await postMcp(port);
+        expect(res.status).toBe(401);
+        expect(await res.json()).toEqual({ error: "Unauthorized" });
+    });
+});
+//# sourceMappingURL=express.test.js.map

package/dist/server/express.test.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"express.test.js","sourceRoot":"","sources":["../../src/server/express.test.ts"],"names":[],"mappings":"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"}

package/dist/server/index.d.ts

@@ -0,0 +1,5 @@
+export type { AnyToolRegistry, InferTools, ToolInput, ToolNames, ToolOutput, ToolResponseMetadata, } from "./inferUtilityTypes.js";
+export type { McpExtra, McpMethodString, McpMiddlewareFilter, McpMiddlewareFn, McpResultFor, McpTypedMiddlewareFn, McpWildcard, } from "./middleware.js";
+export type { McpServerTypes, ToolDef, WidgetHostType } from "./server.js";
+export { McpServer } from "./server.js";
+export { widgetsDevServer } from "./widgetsDevServer.js";

package/dist/server/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/server/index.ts"],"names":[],"mappings":"AAkBA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,gBAAgB,EAAE,MAAM,uBAAuB,CAAC"}

package/dist/server/inferUtilityTypes.d.ts

@@ -0,0 +1,64 @@
+import type { McpServerTypes, ToolDef } from "./server.js";
+/**
+ * Any tool registry shape (includes both widgets and regular tools).
+ * Used as a constraint for type parameters that accept tool registries.
+ */
+export type AnyToolRegistry = Record<string, ToolDef>;
+/**
+ * Extract the tool registry type from an McpServer instance.
+ * This includes both widgets (registered via widget()) and regular tools (registered via registerTool()).
+ *
+ * Uses the `$types` property pattern for cross-package type inference.
+ * This works across package boundaries because TypeScript uses structural typing
+ * on the shape of `$types`, rather than nominal typing on the McpServer class itself.
+ *
+ * @example
+ * ```ts
+ * type MyTools = InferTools<MyServer>;
+ * // { "search": ToolDef<...>, "calculate": ToolDef<...> }
+ * ```
+ */
+export type InferTools<ServerType> = ServerType extends {
+    $types: McpServerTypes<infer W>;
+} ? W : never;
+type ExtractTool<ServerType, K extends ToolNames<ServerType>> = InferTools<ServerType>[K];
+/**
+ * Get a union of all tool names from an McpServer instance.
+ * This includes both widgets and regular tools.
+ *
+ * @example
+ * ```ts
+ * type Names = ToolNames<MyServer>;
+ * // "search" | "calculate" | "details"
+ * ```
+ */
+export type ToolNames<ServerType> = keyof InferTools<ServerType> & string;
+/**
+ * Get the input type for a specific tool (widget or regular tool).
+ *
+ * @example
+ * ```ts
+ * type SearchInput = ToolInput<MyServer, "search">;
+ * ```
+ */
+export type ToolInput<ServerType, ToolName extends ToolNames<ServerType>> = ExtractTool<ServerType, ToolName>["input"];
+/**
+ * Get the output type for a specific tool (widget or regular tool).
+ *
+ * @example
+ * ```ts
+ * type SearchOutput = ToolOutput<MyServer, "search">;
+ * ```
+ */
+export type ToolOutput<ServerType, ToolName extends ToolNames<ServerType>> = ExtractTool<ServerType, ToolName>["output"];
+/**
+ * Get the responseMetadata type for a specific tool (widget or regular tool).
+ * This is inferred from the `_meta` property of the tool callback's return value.
+ *
+ * @example
+ * ```ts
+ * type SearchMeta = ToolResponseMetadata<MyServer, "search">;
+ * ```
+ */
+export type ToolResponseMetadata<ServerType, ToolName extends ToolNames<ServerType>> = ExtractTool<ServerType, ToolName>["responseMetadata"];
+export {};

package/dist/server/inferUtilityTypes.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=inferUtilityTypes.js.map

package/dist/server/inferUtilityTypes.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"inferUtilityTypes.js","sourceRoot":"","sources":["../../src/server/inferUtilityTypes.ts"],"names":[],"mappings":""}

package/dist/server/middleware.d.ts

@@ -0,0 +1,124 @@
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { RequestHandlerExtra } from "@modelcontextprotocol/sdk/shared/protocol.js";
+import type { CallToolResult, CancelTaskResult, ClientNotification, ClientRequest, CompleteResult, EmptyResult, GetPromptResult, GetTaskPayloadResult, GetTaskResult, InitializeResult, ListPromptsResult, ListResourcesResult, ListResourceTemplatesResult, ListTasksResult, ListToolsResult, ReadResourceResult, ServerNotification, ServerRequest, ServerResult } from "@modelcontextprotocol/sdk/types.js";
+/**
+ * The `extra` context object provided by the MCP SDK to request handlers.
+ */
+export type McpExtra = RequestHandlerExtra<ServerRequest, ServerNotification>;
+/**
+ * A single MCP middleware function following the onion model.
+ * Call `next()` to invoke the next middleware or the final handler.
+ * For notifications, `extra` is `undefined` (SDK does not provide extra context)
+ * and `next()` resolves to `undefined`.
+ */
+export type McpMiddlewareFn = (request: {
+    method: string;
+    params: Record<string, unknown>;
+}, extra: McpExtra | undefined, next: () => Promise<unknown>) => Promise<unknown> | unknown;
+/**
+ * MCP methods the server handles (incoming from client).
+ */
+export type McpMethodString = ClientRequest["method"] | ClientNotification["method"];
+/** Extract params type for a specific MCP method from SDK unions. */
+export type McpRequestParams<M extends string> = Extract<ClientRequest, {
+    method: M;
+}> extends {
+    params: infer P;
+} ? P : Extract<ClientNotification, {
+    method: M;
+}> extends {
+    params: infer P;
+} ? P : Record<string, unknown>;
+/** Resolve extra type: McpExtra for requests, undefined for notifications. */
+export type McpExtraFor<M extends string> = M extends ClientRequest["method"] ? McpExtra : M extends ClientNotification["method"] ? undefined : McpExtra | undefined;
+/** Maps each MCP request method to its SDK result type. */
+interface McpResultMap {
+    ping: EmptyResult;
+    initialize: InitializeResult;
+    "tools/list": ListToolsResult;
+    "tools/call": CallToolResult;
+    "resources/list": ListResourcesResult;
+    "resources/templates/list": ListResourceTemplatesResult;
+    "resources/read": ReadResourceResult;
+    "resources/subscribe": EmptyResult;
+    "resources/unsubscribe": EmptyResult;
+    "prompts/list": ListPromptsResult;
+    "prompts/get": GetPromptResult;
+    "completion/complete": CompleteResult;
+    "logging/setLevel": EmptyResult;
+    "tasks/get": GetTaskResult;
+    "tasks/result": GetTaskPayloadResult;
+    "tasks/list": ListTasksResult;
+    "tasks/cancel": CancelTaskResult;
+}
+/**
+ * Map an MCP method string to its corresponding result type.
+ * For request methods, resolves to the specific SDK result type.
+ * For wildcard patterns (e.g. `"tools/*"`), resolves to the union of matching result types.
+ * For notification methods, resolves to `undefined`.
+ * For unknown/unmatched methods, falls back to `ServerResult`.
+ */
+export type McpResultFor<M extends string> = M extends keyof McpResultMap ? McpResultMap[M] : M extends `${infer Prefix}/*` ? [McpResultMap[keyof McpResultMap & `${Prefix}/${string}`]] extends [never] ? M extends ToWildcard<ClientNotification["method"]> ? undefined : ServerResult : McpResultMap[keyof McpResultMap & `${Prefix}/${string}`] : M extends ClientNotification["method"] ? undefined : ServerResult;
+/** Typed middleware fn for a specific method — narrows params, extra, and next() result. */
+export type McpTypedMiddlewareFn<M extends string> = (request: {
+    method: M;
+    params: McpRequestParams<M>;
+}, extra: McpExtraFor<M>, next: () => Promise<McpResultFor<M>>) => Promise<unknown> | unknown;
+/** Extracts `"prefix/*"` from `"prefix/anything"` — distributive over unions. */
+type ToWildcard<T extends string> = T extends `${infer Prefix}/${string}` ? `${Prefix}/*` : never;
+/** Wildcard prefixes derived from method strings (e.g. `"tools/*"` from `"tools/call"`). */
+export type McpWildcard = ToWildcard<McpMethodString>;
+/** Category keywords matching all requests or all notifications. */
+type McpCategory = "request" | "notification";
+/**
+ * A single filter pattern for MCP middleware:
+ * - Exact method: `"tools/call"`
+ * - Wildcard: `"tools/*"`
+ * - Category: `"request"` | `"notification"`
+ * - Escape hatch: arbitrary string via `string & {}`
+ */
+type McpMiddlewareFilterPattern = McpMethodString | McpWildcard | McpCategory | (string & {});
+/**
+ * Filter determining which MCP methods a middleware applies to.
+ * A single pattern or an array of patterns (OR logic).
+ */
+export type McpMiddlewareFilter = McpMiddlewareFilterPattern | McpMiddlewareFilterPattern[];
+/**
+ * Internal entry stored for each registered middleware.
+ * `filter: null` means catch-all (matches everything).
+ */
+export type McpMiddlewareEntry = {
+    filter: McpMiddlewareFilter | null;
+    handler: McpMiddlewareFn;
+};
+type HandlerMap = Map<string, (...args: unknown[]) => Promise<unknown>>;
+/**
+ * Extract the TS-private `_requestHandlers` and `_notificationHandlers` maps
+ * from the SDK's `Server` (extends `Protocol`). These are runtime-accessible
+ * but declared `private` in TypeScript.
+ *
+ * Validates with `instanceof Map` so an incompatible SDK version fails fast
+ * instead of silently breaking.
+ */
+export declare function getHandlerMaps(server: Server): {
+    requestHandlers: HandlerMap;
+    notificationHandlers: HandlerMap;
+};
+/**
+ * Check if a single filter pattern matches a given method.
+ *
+ * - Exact: `"tools/call"` matches only `"tools/call"`
+ * - Wildcard: `"tools/*"` matches any method starting with `"tools/"`
+ * - Category `"request"`: matches when `isNotification` is false
+ * - Category `"notification"`: matches when `isNotification` is true
+ */
+export declare function matchesFilter(method: string, filter: string, isNotification: boolean): boolean;
+/**
+ * Build an onion-model middleware chain for a specific method.
+ *
+ * Filters `entries` to those matching `method`, then composes them
+ * so the first registered middleware is the outermost layer.
+ * `next()` is guarded against multiple calls within a single middleware.
+ */
+export declare function buildMiddlewareChain(method: string, isNotification: boolean, originalHandler: (...args: unknown[]) => Promise<unknown>, entries: McpMiddlewareEntry[]): (...args: unknown[]) => Promise<unknown>;
+export {};

package/dist/server/middleware.js

@@ -0,0 +1,93 @@
+/**
+ * Extract the TS-private `_requestHandlers` and `_notificationHandlers` maps
+ * from the SDK's `Server` (extends `Protocol`). These are runtime-accessible
+ * but declared `private` in TypeScript.
+ *
+ * Validates with `instanceof Map` so an incompatible SDK version fails fast
+ * instead of silently breaking.
+ */
+export function getHandlerMaps(server) {
+    const obj = server;
+    if (!("_requestHandlers" in obj && obj._requestHandlers instanceof Map) ||
+        !("_notificationHandlers" in obj && obj._notificationHandlers instanceof Map)) {
+        throw new Error("Incompatible MCP SDK version: expected _requestHandlers and _notificationHandlers on Server");
+    }
+    return {
+        requestHandlers: obj._requestHandlers,
+        notificationHandlers: obj._notificationHandlers,
+    };
+}
+/**
+ * Check if a single filter pattern matches a given method.
+ *
+ * - Exact: `"tools/call"` matches only `"tools/call"`
+ * - Wildcard: `"tools/*"` matches any method starting with `"tools/"`
+ * - Category `"request"`: matches when `isNotification` is false
+ * - Category `"notification"`: matches when `isNotification` is true
+ */
+export function matchesFilter(method, filter, isNotification) {
+    if (filter === "request") {
+        return !isNotification;
+    }
+    if (filter === "notification") {
+        return isNotification;
+    }
+    if (filter.endsWith("/*")) {
+        const prefix = filter.slice(0, -1); // "tools/*" → "tools/"
+        return method.startsWith(prefix);
+    }
+    return method === filter;
+}
+function matchesAnyFilter(method, filter, isNotification) {
+    if (filter === null) {
+        return true;
+    }
+    if (typeof filter === "string") {
+        return matchesFilter(method, filter, isNotification);
+    }
+    return filter.some((pattern) => matchesFilter(method, pattern, isNotification));
+}
+/**
+ * Build an onion-model middleware chain for a specific method.
+ *
+ * Filters `entries` to those matching `method`, then composes them
+ * so the first registered middleware is the outermost layer.
+ * `next()` is guarded against multiple calls within a single middleware.
+ */
+export function buildMiddlewareChain(method, isNotification, originalHandler, entries) {
+    const applicable = entries.filter((entry) => matchesAnyFilter(method, entry.filter, isNotification));
+    if (applicable.length === 0) {
+        return originalHandler;
+    }
+    return (...args) => {
+        const rawRequest = args[0];
+        // SDK calls request handlers as handler(request, extra) but
+        // notification handlers as handler(notification) — no extra arg.
+        const extra = isNotification ? undefined : args[1];
+        const mcpRequest = {
+            method,
+            params: rawRequest?.params ?? {},
+        };
+        let index = 0;
+        const executeLayer = () => {
+            const entry = applicable[index++];
+            if (!entry) {
+                if (rawRequest) {
+                    rawRequest.params = mcpRequest.params;
+                }
+                return originalHandler(...args);
+            }
+            let nextCalled = false;
+            const next = () => {
+                if (nextCalled) {
+                    throw new Error(`next() called multiple times in middleware for "${method}"`);
+                }
+                nextCalled = true;
+                return executeLayer();
+            };
+            return Promise.resolve(entry.handler(mcpRequest, extra, next));
+        };
+        return executeLayer();
+    };
+}
+//# sourceMappingURL=middleware.js.map

package/dist/server/middleware.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.js","sourceRoot":"","sources":["../../src/server/middleware.ts"],"names":[],"mappings":"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"}

package/dist/server/middleware.test-d.js

@@ -0,0 +1,75 @@
+import { expectTypeOf, test } from "vitest";
+const server = null;
+test("request category narrows extra and next() result", () => {
+    server.mcpMiddleware("request", async (_request, extra, next) => {
+        expectTypeOf(extra).toEqualTypeOf();
+        extra.signal;
+        const result = await next();
+        expectTypeOf(result).toEqualTypeOf();
+        return result;
+    });
+});
+test("notification category narrows extra and next() result", () => {
+    server.mcpMiddleware("notification", async (_request, extra, next) => {
+        expectTypeOf(extra).toEqualTypeOf();
+        // @ts-expect-error extra is undefined, cannot access .signal
+        extra.signal;
+        const result = await next();
+        expectTypeOf(result).toEqualTypeOf();
+    });
+});
+test("exact method tools/call narrows params, extra, and next() result", () => {
+    server.mcpMiddleware("tools/call", async (request, extra, next) => {
+        expectTypeOf(request.params.name).toBeString();
+        expectTypeOf(extra).toEqualTypeOf();
+        const result = await next();
+        expectTypeOf(result).toEqualTypeOf();
+        return result;
+    });
+});
+test("exact method tools/list narrows next() to ListToolsResult", () => {
+    server.mcpMiddleware("tools/list", async (_request, _extra, next) => {
+        const result = await next();
+        expectTypeOf(result).toEqualTypeOf();
+        return result;
+    });
+});
+test("exact notification method narrows extra and next() result", () => {
+    server.mcpMiddleware("notifications/initialized", async (_request, extra, next) => {
+        expectTypeOf(extra).toEqualTypeOf();
+        // @ts-expect-error extra is undefined
+        extra.signal;
+        const result = await next();
+        expectTypeOf(result).toEqualTypeOf();
+    });
+});
+test("McpTypedMiddlewareFn narrows params, extra, and next() per method", () => {
+    expectTypeOf().toBeString();
+    expectTypeOf().toEqualTypeOf();
+    expectTypeOf().toEqualTypeOf();
+    expectTypeOf().toEqualTypeOf();
+    expectTypeOf().toEqualTypeOf();
+});
+test("McpResultFor maps methods to correct result types", () => {
+    expectTypeOf().toEqualTypeOf();
+    expectTypeOf().toEqualTypeOf();
+    expectTypeOf().toEqualTypeOf();
+});
+test("wildcard tools/* narrows next() to union of tools result types", () => {
+    server.mcpMiddleware("tools/*", async (_request, _extra, next) => {
+        const result = await next();
+        expectTypeOf(result).toEqualTypeOf();
+        return result;
+    });
+});
+test("McpResultFor resolves wildcards to union of matching result types", () => {
+    expectTypeOf().toEqualTypeOf();
+});
+test("catch-all middleware has no narrowing on extra or params", () => {
+    server.mcpMiddleware((_request, extra, next) => {
+        expectTypeOf(extra).toEqualTypeOf();
+        expectTypeOf(_request.params).toEqualTypeOf();
+        return next();
+    });
+});
+//# sourceMappingURL=middleware.test-d.js.map

package/dist/server/middleware.test-d.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"middleware.test-d.js","sourceRoot":"","sources":["../../src/server/middleware.test-d.ts"],"names":[],"mappings":"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"}