@smithery/sdk 1.3.3 → 1.4.1

package/README.md

@@ -19,7 +19,7 @@ import { createStatelessServer } from '@smithery/sdk/server/stateless.js'
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js"
 
 // Create your MCP server function
-function createMcpServer({ sessionId, config }) {
+function createMcpServer({ config }) {
   // Create and return a server instance
   // https://github.com/modelcontextprotocol/typescript-sdk?tab=readme-ov-file#core-concepts
   const mcpServer = new McpServer({
@@ -33,13 +33,9 @@ function createMcpServer({ sessionId, config }) {
 }
 
 // Create the stateless server using your MCP server function.
-const { app } = createStatelessServer(createMcpServer)
-
-// Start the server
-const PORT = process.env.PORT || 8081
-app.listen(PORT, () => {
-  console.log(`MCP server running on port ${PORT}`)
-})
+createStatelessServer(createMcpServer)
+  .app
+  .listen(process.env.PORT || 3000)
 ```
 
 This example:

package/dist/server/stateful.d.ts

@@ -1,4 +1,5 @@
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { z } from "zod";
 import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { type SessionStore } from "./session.js";
 /**
@@ -12,18 +13,23 @@ export type CreateServerFn<T = Record<string, unknown>> = (arg: CreateServerArg<
 /**
  * Configuration options for the stateful server
  */
-export interface StatefulServerOptions {
+export interface StatefulServerOptions<T = Record<string, unknown>> {
     /**
      * Session store to use for managing active sessions
      */
     sessionStore?: SessionStore<StreamableHTTPServerTransport>;
+    /**
+     * Zod schema for config validation
+     */
+    schema?: z.ZodSchema<T>;
 }
 /**
  * Creates a stateful server for handling MCP requests.
  * For every new session, we invoke createMcpServer to create a new instance of the server.
  * @param createMcpServer Function to create an MCP server
+ * @param options Configuration options including optional schema validation
  * @returns Express app
  */
-export declare function createStatefulServer<T = Record<string, unknown>>(createMcpServer: CreateServerFn<T>, options?: StatefulServerOptions): {
+export declare function createStatefulServer<T = Record<string, unknown>>(createMcpServer: CreateServerFn<T>, options?: StatefulServerOptions<T>): {
     app: import("express-serve-static-core").Express;
 };

package/dist/server/stateful.js

@@ -2,12 +2,13 @@ import { randomUUID } from "node:crypto";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
 import express from "express";
-import { parseExpressRequestConfig } from "../shared/config.js";
+import { parseAndValidateConfig } from "../shared/config.js";
 import { createLRUStore } from "./session.js";
 /**
  * Creates a stateful server for handling MCP requests.
  * For every new session, we invoke createMcpServer to create a new instance of the server.
  * @param createMcpServer Function to create an MCP server
+ * @param options Configuration options including optional schema validation
  * @returns Express app
  */
 export function createStatefulServer(createMcpServer, options) {
@@ -40,21 +41,14 @@ export function createStatefulServer(createMcpServer, options) {
                     sessionStore.delete?.(transport.sessionId);
                 }
             };
-            let config;
-            try {
-                config = parseExpressRequestConfig(req);
-            }
-            catch (error) {
-                res.status(400).json({
-                    jsonrpc: "2.0",
-                    error: {
-                        code: -32000,
-                        message: "Bad Request: Invalid configuration",
-                    },
-                    id: null,
-                });
+            // New session - validate config
+            const configResult = parseAndValidateConfig(req, options?.schema);
+            if (!configResult.ok) {
+                const status = configResult.error.status || 400;
+                res.status(status).json(configResult.error);
                 return;
             }
+            const config = configResult.value;
             try {
                 const server = createMcpServer({
                     sessionId: newSessionId,

package/dist/server/stateless.d.ts

@@ -1,3 +1,4 @@
+import type { z } from "zod";
 import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
 /**
  * Arguments when we create a new instance of your server
@@ -6,12 +7,16 @@ export interface CreateServerArg<T = Record<string, unknown>> {
     config: T;
 }
 export type CreateServerFn<T = Record<string, unknown>> = (arg: CreateServerArg<T>) => Server;
+export interface CreateStatelessServerOptions<T> {
+    schema?: z.ZodSchema<T>;
+}
 /**
  * Creates a stateless server for handling MCP requests
  * In stateless mode, each request creates a new server and transport instance
  * @param createMcpServer Function to create an MCP server
+ * @param options Optional configuration including Zod schema for validation
  * @returns Express app
  */
-export declare function createStatelessServer<T = Record<string, unknown>>(createMcpServer: CreateServerFn<T>): {
+export declare function createStatelessServer<T = Record<string, unknown>>(createMcpServer: CreateServerFn<T>, options?: CreateStatelessServerOptions<T>): {
     app: import("express-serve-static-core").Express;
 };

package/dist/server/stateless.js

@@ -1,13 +1,14 @@
-import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 import express from "express";
-import { parseExpressRequestConfig } from "../shared/config.js";
+import { parseAndValidateConfig } from "../shared/config.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
 /**
  * Creates a stateless server for handling MCP requests
  * In stateless mode, each request creates a new server and transport instance
  * @param createMcpServer Function to create an MCP server
+ * @param options Optional configuration including Zod schema for validation
  * @returns Express app
  */
-export function createStatelessServer(createMcpServer) {
+export function createStatelessServer(createMcpServer, options) {
     const app = express();
     app.use(express.json());
     app.post("/mcp", async (req, res) => {
@@ -15,24 +16,14 @@ export function createStatelessServer(createMcpServer) {
         // to ensure complete isolation. A single instance would cause request ID collisions
         // when multiple clients connect concurrently.
         try {
-            // Parse base64 encoded config from URL query parameter if present
-            let config = {};
-            if (req.query.config) {
-                try {
-                    config = parseExpressRequestConfig(req);
-                }
-                catch (configError) {
-                    res.status(400).json({
-                        jsonrpc: "2.0",
-                        error: {
-                            code: -32000,
-                            message: "Bad Request: Invalid configuration",
-                        },
-                        id: null,
-                    });
-                    return;
-                }
+            // Parse and validate config
+            const configResult = parseAndValidateConfig(req, options?.schema);
+            if (!configResult.ok) {
+                const status = configResult.error.status;
+                res.status(status).json(configResult.error);
+                return;
             }
+            const config = configResult.value;
             // Create a new server instance with config
             const server = createMcpServer({ config: config });
             // Create a new transport instance

package/dist/shared/config.d.ts

@@ -1,4 +1,5 @@
-import type express from "express";
+import type { Request as ExpressRequest } from "express";
+import type { z } from "zod";
 export interface SmitheryUrlOptions {
     apiKey?: string;
     profile?: string;
@@ -16,4 +17,34 @@ export declare function createSmitheryUrl(baseUrl: string, options?: SmitheryUrl
  * @param req The express request
  * @returns The config
  */
-export declare function parseExpressRequestConfig(req: express.Request): Record<string, unknown>;
+export declare function parseExpressRequestConfig(req: ExpressRequest): Record<string, unknown>;
+/**
+ * Parses and validates config from an Express request with optional Zod schema validation
+ * Supports both base64-encoded config and dot-notation config parameters
+ * @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<{
+    title: string;
+    status: number;
+    detail: string;
+    instance: string;
+}> | 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;
+    }[];
+}> | import("okay-error").Ok<T>;

package/dist/shared/config.js

@@ -1,3 +1,6 @@
+import _ from "lodash";
+import { err, ok } from "okay-error";
+import { zodToJsonSchema } from "zod-to-json-schema";
 /**
  * Creates a URL to connect to the Smithery MCP server.
  * @param baseUrl The base URL of the Smithery server
@@ -28,3 +31,89 @@ export function createSmitheryUrl(baseUrl, options) {
 export function parseExpressRequestConfig(req) {
     return JSON.parse(Buffer.from(req.query.config, "base64").toString());
 }
+/**
+ * Parses and validates config from an Express request with optional Zod schema validation
+ * Supports both base64-encoded config and dot-notation config parameters
+ * @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) {
+    // Parse config from request parameters
+    let config = {};
+    // 1. Process base64-encoded config parameter if present
+    if (req.query.config) {
+        try {
+            config = parseExpressRequestConfig(req);
+        }
+        catch (configError) {
+            return err({
+                title: "Invalid config parameter",
+                status: 400,
+                detail: "Failed to parse config parameter",
+                instance: req.originalUrl,
+            });
+        }
+    }
+    // 2. Process dot-notation config parameters (foo=bar, a.b=c)
+    // This allows URL params like ?server.host=localhost&server.port=8080&debug=true
+    for (const [key, value] of Object.entries(req.query)) {
+        // Skip reserved parameters
+        if (key === "config" || 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);
+    }
+    // Validate config against schema if provided
+    if (schema) {
+        const result = schema.safeParse(config);
+        if (!result.success) {
+            const jsonSchema = zodToJsonSchema(schema, {
+                name: "ConfigSchema",
+                $refStrategy: "none",
+            });
+            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,
+            });
+        }
+        return ok(result.data);
+    }
+    return ok(config);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smithery/sdk",
-	"version": "1.3.3",
+	"version": "1.4.1",
 	"description": "SDK to develop with Smithery",
 	"type": "module",
 	"main": "./dist/index.js",
@@ -25,12 +25,17 @@
 		"ai": "^4.3.15",
 		"express": "^5.1.0",
 		"json-schema": "^0.4.0",
+		"lodash": "^4.17.21",
+		"okay-error": "^1.0.2",
 		"openai": "^4.0.0",
-		"uuid": "^11.0.3"
+		"uuid": "^11.0.3",
+		"zod": "^3.23.8",
+		"zod-to-json-schema": "^3.24.1"
 	},
 	"devDependencies": {
 		"@types/express": "^5.0.1",
 		"@types/json-schema": "^7.0.15",
+		"@types/lodash": "^4.17.17",
 		"@types/node": "^20.0.0",
 		"@types/uuid": "^9.0.7",
 		"dotenv": "^16.4.7",