@smithery/sdk 1.7.2 → 1.7.3

package/dist/server/stateless.js

@@ -0,0 +1,123 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import express from "express";
+import { parseAndValidateConfig } from "../shared/config.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { createLogger } from "./logger.js";
+/**
+ * Creates a stateless server for handling MCP requests.
+ * Each request creates a new server instance - no session state is maintained.
+ * This is ideal for stateless API integrations and serverless environments.
+ *
+ * @param createMcpServer Function to create an MCP server
+ * @param options Configuration options including optional schema validation and Express app
+ * @returns Express app
+ */
+export function createStatelessServer(createMcpServer, options) {
+    const app = options?.app ?? express();
+    const logger = createLogger(options?.logLevel ?? "info");
+    app.use("/mcp", express.json());
+    // Handle POST requests for client-to-server communication
+    app.post("/mcp", async (req, res) => {
+        // In stateless mode, create a new instance of transport and server for each request
+        // to ensure complete isolation. A single instance would cause request ID collisions
+        // when multiple clients connect concurrently.
+        try {
+            // Log incoming MCP request
+            logger.debug({
+                method: req.body.method,
+                id: req.body.id,
+                params: req.body.params,
+            }, "MCP Request");
+            // Validate config for all requests in stateless mode
+            const configResult = parseAndValidateConfig(req, options?.schema);
+            if (!configResult.ok) {
+                const status = configResult.error.status || 400;
+                logger.error({ error: configResult.error }, "Config validation failed");
+                res.status(status).json(configResult.error);
+                return;
+            }
+            const config = configResult.value;
+            // Create a fresh server instance for each request
+            const server = createMcpServer({
+                config,
+                auth: req.auth,
+                logger,
+            });
+            // Create a new transport for this request (no session management)
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: undefined,
+            });
+            // Clean up resources when request closes
+            res.on("close", () => {
+                transport.close();
+                server.close();
+            });
+            // Connect to the MCP server
+            await server.connect(transport);
+            // Handle the request directly
+            await transport.handleRequest(req, res, req.body);
+            // Log successful response
+            logger.debug({
+                method: req.body.method,
+                id: req.body.id,
+            }, "MCP Response sent");
+        }
+        catch (error) {
+            logger.error({ error }, "Error handling MCP request");
+            if (!res.headersSent) {
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: "Internal server error",
+                    },
+                    id: null,
+                });
+            }
+        }
+    });
+    // SSE notifications not supported in stateless mode
+    app.get("/mcp", async (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed.",
+            },
+            id: null,
+        });
+    });
+    // Session termination not needed in stateless mode
+    app.delete("/mcp", async (_req, res) => {
+        res.status(405).json({
+            jsonrpc: "2.0",
+            error: {
+                code: -32000,
+                message: "Method not allowed.",
+            },
+            id: null,
+        });
+    });
+    // Add .well-known/mcp-config endpoint for configuration discovery
+    app.get("/.well-known/mcp-config", (req, res) => {
+        // Set proper content type for JSON Schema
+        res.set("Content-Type", "application/schema+json; charset=utf-8");
+        const baseSchema = options?.schema
+            ? zodToJsonSchema(options.schema)
+            : {
+                type: "object",
+                properties: {},
+                required: [],
+            };
+        const configSchema = {
+            $schema: "https://json-schema.org/draft/2020-12/schema",
+            $id: `${req.protocol}://${req.get("host")}/.well-known/mcp-config`,
+            title: "MCP Session Configuration",
+            description: "Schema for the /mcp endpoint configuration",
+            "x-query-style": "dot+bracket",
+            ...baseSchema,
+        };
+        res.json(configSchema);
+    });
+    return { app };
+}

package/dist/server/widget.d.ts

@@ -0,0 +1,6 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface WidgetServerOptions {
+    name: string;
+    version: string;
+}
+export declare function createWidgetServer(options: WidgetServerOptions): McpServer;

package/dist/server/widget.js

@@ -0,0 +1,7 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export function createWidgetServer(options) {
+    return new McpServer({
+        name: options.name,
+        version: options.version,
+    });
+}

package/dist/shared/config.d.ts

@@ -0,0 +1,42 @@
+import type { Request as ExpressRequest } from "express";
+import type { z } from "zod";
+export interface SmitheryUrlOptions {
+    apiKey?: string;
+    profile?: string;
+    config?: object;
+}
+export declare function appendConfigAsDotParams(url: URL, config: unknown): void;
+/**
+ * Creates a URL to connect to the Smithery MCP server.
+ * @param baseUrl The base URL of the Smithery server
+ * @param options Optional configuration object
+ * @returns A URL with config encoded using dot-notation query params (e.g. model.name=gpt-4&debug=true)
+ */
+export declare function createSmitheryUrl(baseUrl: string, options?: SmitheryUrlOptions): URL;
+/**
+ * Parses and validates config from an Express request with optional Zod schema validation
+ * Supports dot-notation config parameters (e.g., foo=bar, a.b=c)
+ * @param req The express request
+ * @param schema Optional Zod schema for validation
+ * @returns Result with either parsed data or error response
+ */
+export declare function parseAndValidateConfig<T = Record<string, unknown>>(req: ExpressRequest, schema?: z.ZodSchema<T>): import("okay-error").Err<{
+    readonly title: "Invalid configuration parameters";
+    readonly status: 422;
+    readonly detail: "One or more config parameters are invalid.";
+    readonly instance: string;
+    readonly configSchema: import("zod-to-json-schema").JsonSchema7Type & {
+        $schema?: string | undefined;
+        definitions?: {
+            [key: string]: import("zod-to-json-schema").JsonSchema7Type;
+        } | undefined;
+    };
+    readonly errors: {
+        param: string;
+        pointer: string;
+        reason: string;
+        received: unknown;
+    }[];
+    readonly help: "Pass config as URL query params. Example: /mcp?param1=value1&param2=value2";
+}> | import("okay-error").Ok<T>;
+export declare function parseConfigFromQuery(query: Iterable<[string, unknown]>): Record<string, unknown>;

package/dist/shared/config.js

@@ -0,0 +1,133 @@
+import _ from "lodash";
+import { err, ok } from "okay-error";
+import { zodToJsonSchema } from "zod-to-json-schema";
+function isPlainObject(value) {
+    return value !== null && typeof value === "object" && !Array.isArray(value);
+}
+export function appendConfigAsDotParams(url, config) {
+    function add(pathParts, value) {
+        if (Array.isArray(value)) {
+            for (let index = 0; index < value.length; index++) {
+                add([...pathParts, String(index)], value[index]);
+            }
+            return;
+        }
+        if (isPlainObject(value)) {
+            for (const [key, nested] of Object.entries(value)) {
+                add([...pathParts, key], nested);
+            }
+            return;
+        }
+        const key = pathParts.join(".");
+        let stringValue;
+        switch (typeof value) {
+            case "string":
+                stringValue = value;
+                break;
+            case "number":
+            case "boolean":
+                stringValue = String(value);
+                break;
+            default:
+                stringValue = JSON.stringify(value);
+        }
+        url.searchParams.set(key, stringValue);
+    }
+    if (isPlainObject(config)) {
+        for (const [key, value] of Object.entries(config)) {
+            add([key], value);
+        }
+    }
+}
+/**
+ * Creates a URL to connect to the Smithery MCP server.
+ * @param baseUrl The base URL of the Smithery server
+ * @param options Optional configuration object
+ * @returns A URL with config encoded using dot-notation query params (e.g. model.name=gpt-4&debug=true)
+ */
+export function createSmitheryUrl(baseUrl, options) {
+    const url = new URL(`${baseUrl}/mcp`);
+    if (options?.config) {
+        appendConfigAsDotParams(url, options.config);
+    }
+    if (options?.apiKey) {
+        url.searchParams.set("api_key", options.apiKey);
+    }
+    if (options?.profile) {
+        url.searchParams.set("profile", options.profile);
+    }
+    return url;
+}
+/**
+ * Parses and validates config from an Express request with optional Zod schema validation
+ * Supports dot-notation config parameters (e.g., foo=bar, a.b=c)
+ * @param req The express request
+ * @param schema Optional Zod schema for validation
+ * @returns Result with either parsed data or error response
+ */
+export function parseAndValidateConfig(req, schema) {
+    const config = parseConfigFromQuery(Object.entries(req.query));
+    // Validate config against schema if provided
+    if (schema) {
+        const result = schema.safeParse(config);
+        if (!result.success) {
+            const jsonSchema = zodToJsonSchema(schema);
+            const errors = result.error.issues.map(issue => {
+                // Safely traverse the config object to get the received value
+                let received = config;
+                for (const key of issue.path) {
+                    if (received && typeof received === "object" && key in received) {
+                        received = received[key];
+                    }
+                    else {
+                        received = undefined;
+                        break;
+                    }
+                }
+                return {
+                    param: issue.path.join(".") || "root",
+                    pointer: `/${issue.path.join("/")}`,
+                    reason: issue.message,
+                    received,
+                };
+            });
+            return err({
+                title: "Invalid configuration parameters",
+                status: 422,
+                detail: "One or more config parameters are invalid.",
+                instance: req.originalUrl,
+                configSchema: jsonSchema,
+                errors,
+                help: "Pass config as URL query params. Example: /mcp?param1=value1&param2=value2",
+            });
+        }
+        return ok(result.data);
+    }
+    return ok(config);
+}
+// Process dot-notation config parameters from query parameters (foo=bar, a.b=c)
+// This allows URL params like ?server.host=localhost&server.port=8080&debug=true
+export function parseConfigFromQuery(query) {
+    const config = {};
+    for (const [key, value] of query) {
+        // Skip reserved parameters
+        if (key === "api_key" || key === "profile")
+            continue;
+        const pathParts = key.split(".");
+        // Handle array values from Express query parsing
+        const rawValue = Array.isArray(value) ? value[0] : value;
+        if (typeof rawValue !== "string")
+            continue;
+        // Try to parse value as JSON (for booleans, numbers, objects)
+        let parsedValue = rawValue;
+        try {
+            parsedValue = JSON.parse(rawValue);
+        }
+        catch {
+            // If parsing fails, use the raw string value
+        }
+        // Use lodash's set method to handle nested paths
+        _.set(config, pathParts, parsedValue);
+    }
+    return config;
+}

package/dist/shared/patch.d.ts

@@ -0,0 +1,12 @@
+/**
+ * Patches a function on an object
+ * @param obj
+ * @param key
+ * @param patcher
+ */
+export declare function patch<T extends {
+    [P in K]: (...args: any[]) => any;
+}, K extends keyof T & string>(obj: T, key: K, patcher: (fn: T[K]) => T[K]): void;
+export declare function patch<T extends {
+    [P in K]?: (...args: any[]) => any;
+}, K extends keyof T & string>(obj: T, key: K, patcher: (fn?: T[K]) => T[K]): void;

package/dist/shared/patch.js

@@ -0,0 +1,12 @@
+/**
+ * Patches a function on an object
+ * @param obj
+ * @param key
+ * @param patcher
+ */
+// Unified implementation (not type-checked by callers)
+export function patch(obj, key, patcher) {
+    // If the property is actually a function, bind it; otherwise undefined
+    const original = typeof obj[key] === "function" ? obj[key].bind(obj) : undefined;
+    obj[key] = patcher(original);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smithery/sdk",
-	"version": "1.7.2",
+	"version": "1.7.3",
 	"description": "SDK to develop with Smithery",
 	"type": "module",
 	"repository": {
@@ -39,7 +39,8 @@
 		"build": "tsc",
 		"build:all": "npm run build -ws --include-workspace-root",
 		"watch": "tsc --watch",
-		"check": "npx @biomejs/biome check --write --unsafe"
+		"check": "npx @biomejs/biome check --write --unsafe",
+		"prepare": "npm run build"
 	},
 	"packageManager": "npm@11.4.1",
 	"license": "MIT",