@smithery/sdk 1.7.2 → 1.7.3

package/dist/server/auth/oauth.js

@@ -0,0 +1,155 @@
+import { authorizationHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/authorize.js";
+import { metadataHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/metadata.js";
+import { clientRegistrationHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/register.js";
+import { revocationHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/revoke.js";
+import { tokenHandler } from "@modelcontextprotocol/sdk/server/auth/handlers/token.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { createOAuthMetadata, mcpAuthMetadataRouter, } from "@modelcontextprotocol/sdk/server/auth/router.js";
+import { mountIdentity } from "./identity.js";
+function isOAuthProvider(provider) {
+    return !!provider && "authorize" in provider;
+}
+export function mountOAuth(app, opts) {
+    // Determine base path once based on OAuth provider or identity
+    const provider = opts.provider;
+    const hasOAuth = isOAuthProvider(provider);
+    const rawBasePath = hasOAuth
+        ? (provider.basePath ?? "/")
+        : (opts.identity?.basePath ?? "/");
+    const basePath = rawBasePath.endsWith("/") ? rawBasePath : `${rawBasePath}/`;
+    // Precompute endpoint pathnames from metadata
+    let authorizationPath;
+    let tokenPath;
+    let registrationPath;
+    let revocationPath;
+    if (isOAuthProvider(provider)) {
+        const placeholderIssuer = new URL("https://localhost");
+        const placeholderBaseUrl = new URL(basePath, placeholderIssuer);
+        const localMetadata = createOAuthMetadata({
+            provider,
+            issuerUrl: placeholderIssuer,
+            baseUrl: placeholderBaseUrl,
+        });
+        authorizationPath = new URL(localMetadata.authorization_endpoint).pathname;
+        tokenPath = new URL(localMetadata.token_endpoint).pathname;
+        if (localMetadata.registration_endpoint) {
+            registrationPath = new URL(localMetadata.registration_endpoint).pathname;
+        }
+        if (localMetadata.revocation_endpoint) {
+            revocationPath = new URL(localMetadata.revocation_endpoint).pathname;
+        }
+    }
+    // Metadata endpoints
+    if (isOAuthProvider(provider)) {
+        // Mount a per-request adapter so issuer/baseUrl reflect Host/Proto
+        app.use((req, res, next) => {
+            if (!req.path.startsWith("/.well-known/"))
+                return next();
+            const host = req.get("host") ?? "localhost";
+            if (req.protocol !== "https") {
+                console.warn("Detected http but using https for issuer URL in OAuth metadata since it will fail otherwise.");
+            }
+            const issuerUrl = new URL(`https://${host}`);
+            const baseUrl = new URL(basePath, issuerUrl);
+            const oauthMetadata = createOAuthMetadata({
+                provider,
+                issuerUrl,
+                baseUrl,
+            });
+            if (opts.identity) {
+                oauthMetadata.grant_types_supported = Array.from(new Set([
+                    ...(oauthMetadata.grant_types_supported ?? []),
+                    "urn:ietf:params:oauth:grant-type:jwt-bearer",
+                ]));
+            }
+            const resourceServerUrl = new URL("/mcp", issuerUrl);
+            const metadataRouter = mcpAuthMetadataRouter({
+                oauthMetadata,
+                resourceServerUrl,
+            });
+            return metadataRouter(req, res, next);
+        });
+    }
+    else if (opts.identity) {
+        // Identity-only: explicitly mount protected resource metadata endpoint
+        app.use("/.well-known/oauth-protected-resource", (req, res, next) => {
+            const host = req.get("host") ?? "localhost";
+            const issuerUrl = new URL(`https://${host}`);
+            const protectedResourceMetadata = {
+                resource: new URL("/mcp", issuerUrl).href,
+                authorization_servers: [issuerUrl.href],
+            };
+            return metadataHandler(protectedResourceMetadata)(req, res, next);
+        });
+        // Identity-only: also advertise minimal AS metadata for discovery per RFC 8414
+        app.use("/.well-known/oauth-authorization-server", (req, res, next) => {
+            const host = req.get("host") ?? "localhost";
+            const issuerUrl = new URL(`https://${host}`);
+            const oauthMetadata = {
+                issuer: issuerUrl.href,
+                token_endpoint: new URL(`${basePath}token`, issuerUrl).href,
+                grant_types_supported: ["urn:ietf:params:oauth:grant-type:jwt-bearer"],
+            };
+            return metadataHandler(oauthMetadata)(req, res, next);
+        });
+    }
+    // Mount identity (JWT bearer grant) first so OAuth token can fall through
+    if (opts.identity) {
+        const identityOptions = {
+            ...opts.identity,
+            basePath,
+            tokenPath: tokenPath ?? `${basePath}token`,
+        };
+        mountIdentity(app, identityOptions);
+    }
+    // Mount OAuth endpoints functionally if an OAuth provider is present
+    if (isOAuthProvider(provider)) {
+        // Authorization endpoint
+        const authPath = authorizationPath ?? `${basePath}authorize`;
+        app.use(authPath, authorizationHandler({ provider }));
+        // Token endpoint (OAuth); identity's token handler will handle JWT grant and call next() otherwise
+        const tokPath = tokenPath ?? `${basePath}token`;
+        app.use(tokPath, tokenHandler({ provider }));
+        // Dynamic client registration if supported
+        if (provider.clientsStore?.registerClient) {
+            const regPath = registrationPath ?? `${basePath}register`;
+            app.use(regPath, clientRegistrationHandler({ clientsStore: provider.clientsStore }));
+        }
+        // Token revocation if supported
+        if (provider.revokeToken) {
+            const revPath = revocationPath ?? `${basePath}revoke`;
+            app.use(revPath, revocationHandler({ provider }));
+        }
+        // Optional OAuth callback
+        const callbackHandler = provider.handleOAuthCallback?.bind(provider);
+        if (callbackHandler) {
+            const callbackPath = provider.callbackPath ?? "/callback";
+            app.get(callbackPath, async (req, res) => {
+                const code = typeof req.query.code === "string" ? req.query.code : undefined;
+                const state = typeof req.query.state === "string" ? req.query.state : undefined;
+                if (!code) {
+                    res.status(400).send("Invalid request parameters");
+                    return;
+                }
+                try {
+                    const redirectUrl = await callbackHandler(code, state, res);
+                    res.redirect(redirectUrl.toString());
+                }
+                catch (error) {
+                    console.error(error);
+                    res.status(500).send("Error during authentication callback");
+                }
+            });
+        }
+    }
+    // Protect MCP resource with bearer auth if a verifier/provider is present
+    if (provider) {
+        app.use("/mcp", (req, res, next) => {
+            return requireBearerAuth({
+                verifier: provider,
+                requiredScopes: provider.requiredScopes,
+                resourceMetadataUrl: provider.resourceMetadataUrl,
+            })(req, res, next);
+        });
+    }
+}

package/dist/server/index.d.ts

@@ -0,0 +1,7 @@
+export * from "./stateful.js";
+export * from "./stateless.js";
+export * from "./session.js";
+export * from "./auth/oauth.js";
+export * from "./auth/identity.js";
+export { createWidgetServer } from "./widget.js";
+export type { WidgetServerOptions } from "./widget.js";

package/dist/server/index.js

@@ -0,0 +1,6 @@
+export * from "./stateful.js";
+export * from "./stateless.js";
+export * from "./session.js";
+export * from "./auth/oauth.js";
+export * from "./auth/identity.js";
+export { createWidgetServer } from "./widget.js";

package/dist/server/logger.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Logger interface for structured logging
+ */
+export interface Logger {
+    info(msg: string, ...args: unknown[]): void;
+    info(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    error(msg: string, ...args: unknown[]): void;
+    error(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    warn(msg: string, ...args: unknown[]): void;
+    warn(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+    debug(msg: string, ...args: unknown[]): void;
+    debug(obj: Record<string, unknown>, msg?: string, ...args: unknown[]): void;
+}
+type LogLevel = "debug" | "info" | "warn" | "error";
+/**
+ * Creates a simple console-based logger with pretty formatting
+ */
+export declare function createLogger(logLevel?: LogLevel): Logger;
+export {};

package/dist/server/logger.js

@@ -0,0 +1,76 @@
+import chalk from "chalk";
+/**
+ * Lightweight stringify with depth limiting
+ */
+function stringifyWithDepth(obj, maxDepth = 3) {
+    let depth = 0;
+    const seen = new WeakSet();
+    try {
+        return JSON.stringify(obj, (key, value) => {
+            // Track depth
+            if (key === "")
+                depth = 0;
+            else if (typeof value === "object" && value !== null)
+                depth++;
+            // Depth limit
+            if (depth > maxDepth) {
+                return "[Object]";
+            }
+            // Circular reference check
+            if (typeof value === "object" && value !== null) {
+                if (seen.has(value))
+                    return "[Circular]";
+                seen.add(value);
+            }
+            // Handle special types
+            if (typeof value === "function")
+                return "[Function]";
+            if (typeof value === "bigint")
+                return `${value}n`;
+            if (value instanceof Error)
+                return { name: value.name, message: value.message };
+            if (value instanceof Date)
+                return value.toISOString();
+            return value;
+        }, 2);
+    }
+    catch {
+        return String(obj);
+    }
+}
+/**
+ * Creates a simple console-based logger with pretty formatting
+ */
+export function createLogger(logLevel = "info") {
+    const levels = { debug: 0, info: 1, warn: 2, error: 3 };
+    const currentLevel = levels[logLevel];
+    const formatLog = (level, color, msgOrObj, msg) => {
+        const time = new Date().toISOString().split("T")[1].split(".")[0];
+        const timestamp = chalk.dim(time);
+        const levelStr = color(level);
+        if (typeof msgOrObj === "string") {
+            return `${timestamp} ${levelStr} ${msgOrObj}`;
+        }
+        const message = msg || "";
+        const data = stringifyWithDepth(msgOrObj, 3);
+        return `${timestamp} ${levelStr} ${message}\n${chalk.dim(data)}`;
+    };
+    return {
+        debug: (msgOrObj, msg) => {
+            if (currentLevel <= 0)
+                console.error(formatLog("DEBUG", chalk.cyan, msgOrObj, msg));
+        },
+        info: (msgOrObj, msg) => {
+            if (currentLevel <= 1)
+                console.error(formatLog("INFO", chalk.blue, msgOrObj, msg));
+        },
+        warn: (msgOrObj, msg) => {
+            if (currentLevel <= 2)
+                console.error(formatLog("WARN", chalk.yellow, msgOrObj, msg));
+        },
+        error: (msgOrObj, msg) => {
+            if (currentLevel <= 3)
+                console.error(formatLog("ERROR", chalk.red, msgOrObj, msg));
+        },
+    };
+}

package/dist/server/session.d.ts

@@ -0,0 +1,17 @@
+import type { Transport } from "@modelcontextprotocol/sdk/shared/transport.js";
+export interface SessionStore<T extends Transport> {
+    /** return existing transport (or `undefined`) */
+    get(id: string): T | undefined;
+    /** insert / update */
+    set(id: string, t: T): void;
+    /** optional - explicit eviction */
+    delete?(id: string): void;
+}
+/**
+ * Minimal Map‑based LRU implementation that fulfils {@link SessionStore}.
+ * Keeps at most `max` transports; upon insert, the least‑recently‑used entry
+ * (oldest insertion order) is removed and the evicted transport is closed.
+ *
+ * @param max  maximum number of sessions to retain (default = 1000)
+ */
+export declare const createLRUStore: <T extends Transport>(max?: number) => SessionStore<T>;

package/dist/server/session.js

@@ -0,0 +1,36 @@
+/**
+ * Minimal Map‑based LRU implementation that fulfils {@link SessionStore}.
+ * Keeps at most `max` transports; upon insert, the least‑recently‑used entry
+ * (oldest insertion order) is removed and the evicted transport is closed.
+ *
+ * @param max  maximum number of sessions to retain (default = 1000)
+ */
+export const createLRUStore = (max = 1000) => {
+    // ECMA‑262 §23.1.3.13 - the order of keys in a Map object is the order of insertion; operations that remove a key drop it from that order, and set appends when the key is new or has just been removed.
+    const cache = new Map();
+    return {
+        get: id => {
+            const t = cache.get(id);
+            if (!t)
+                return undefined;
+            // refresh position
+            cache.delete(id);
+            cache.set(id, t);
+            return t;
+        },
+        set: (id, transport) => {
+            if (cache.has(id)) {
+                // key already present - refresh position
+                cache.delete(id);
+            }
+            else if (cache.size >= max) {
+                // evict oldest entry (first in insertion order)
+                const [lruId, lruTransport] = cache.entries().next().value;
+                lruTransport.close?.();
+                cache.delete(lruId);
+            }
+            cache.set(id, transport);
+        },
+        delete: id => cache.delete(id),
+    };
+};

package/dist/server/stateful.d.ts

@@ -0,0 +1,48 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import express from "express";
+import type { z } from "zod";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { type SessionStore } from "./session.js";
+import type { Logger } from "./logger.js";
+/**
+ * Arguments when we create a new instance of your server
+ */
+export interface CreateServerArg<T = Record<string, unknown>> {
+    sessionId: string;
+    config: T;
+    auth?: AuthInfo;
+    logger: Logger;
+}
+export type CreateServerFn<T = Record<string, unknown>> = (arg: CreateServerArg<T>) => Server;
+/**
+ * Configuration options for the stateful server
+ */
+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>;
+    /**
+     * Express app instance to use (optional)
+     */
+    app?: express.Application;
+    /**
+     * Log level for the server (default: 'info')
+     */
+    logLevel?: "debug" | "info" | "warn" | "error";
+}
+/**
+ * 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 and Express app
+ * @returns Express app
+ */
+export declare function createStatefulServer<T = Record<string, unknown>>(createMcpServer: CreateServerFn<T>, options?: StatefulServerOptions<T>): {
+    app: express.Application;
+};

package/dist/server/stateful.js

@@ -0,0 +1,176 @@
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import express from "express";
+import { randomUUID } from "node:crypto";
+import { parseAndValidateConfig } from "../shared/config.js";
+import { zodToJsonSchema } from "zod-to-json-schema";
+import { createLRUStore } from "./session.js";
+import { createLogger } from "./logger.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 and Express app
+ * @returns Express app
+ */
+export function createStatefulServer(createMcpServer, options) {
+    const app = options?.app ?? express();
+    app.use("/mcp", express.json());
+    const sessionStore = options?.sessionStore ?? createLRUStore();
+    const logger = createLogger(options?.logLevel ?? "info");
+    // Handle POST requests for client-to-server communication
+    app.post("/mcp", async (req, res) => {
+        // Log incoming MCP request
+        logger.debug({
+            method: req.body.method,
+            id: req.body.id,
+            sessionId: req.headers["mcp-session-id"],
+        }, "MCP Request");
+        // Check for existing session ID
+        const sessionId = req.headers["mcp-session-id"];
+        let transport;
+        if (sessionId && sessionStore.get(sessionId)) {
+            // Reuse existing transport
+            // biome-ignore lint/style/noNonNullAssertion: Not possible
+            transport = sessionStore.get(sessionId);
+        }
+        else if (!sessionId && isInitializeRequest(req.body)) {
+            // New initialization request
+            const newSessionId = randomUUID();
+            transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => newSessionId,
+                onsessioninitialized: sessionId => {
+                    // Store the transport by session ID
+                    sessionStore.set(sessionId, transport);
+                },
+            });
+            // Clean up transport when closed
+            transport.onclose = () => {
+                if (transport.sessionId) {
+                    sessionStore.delete?.(transport.sessionId);
+                }
+            };
+            // New session - validate config
+            const configResult = parseAndValidateConfig(req, options?.schema);
+            if (!configResult.ok) {
+                const status = configResult.error.status || 400;
+                logger.error({ error: configResult.error, sessionId: newSessionId }, "Config validation failed");
+                res.status(status).json(configResult.error);
+                return;
+            }
+            const config = configResult.value;
+            try {
+                logger.info({ sessionId: newSessionId }, "Creating new session");
+                const server = createMcpServer({
+                    sessionId: newSessionId,
+                    config: config,
+                    auth: req.auth,
+                    logger,
+                });
+                // Connect to the MCP server
+                await server.connect(transport);
+            }
+            catch (error) {
+                logger.error({ error, sessionId: newSessionId }, "Error initializing server");
+                res.status(500).json({
+                    jsonrpc: "2.0",
+                    error: {
+                        code: -32603,
+                        message: "Error initializing server.",
+                    },
+                    id: null,
+                });
+                return;
+            }
+        }
+        else {
+            // Invalid request
+            logger.warn({ sessionId }, "Session not found or expired");
+            res.status(400).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Session not found or expired",
+                },
+                id: null,
+            });
+            return;
+        }
+        // Handle the request
+        await transport.handleRequest(req, res, req.body);
+        // Log successful response
+        logger.debug({
+            method: req.body.method,
+            id: req.body.id,
+            sessionId: req.headers["mcp-session-id"],
+        }, "MCP Response sent");
+    });
+    // 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);
+    });
+    // Handle GET requests for server-to-client notifications via SSE
+    app.get("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId || !sessionStore.get(sessionId)) {
+            res.status(400).send("Invalid or expired session ID");
+            return;
+        }
+        // biome-ignore lint/style/noNonNullAssertion: Not possible
+        const transport = sessionStore.get(sessionId);
+        await transport.handleRequest(req, res);
+    });
+    // Handle DELETE requests for session termination
+    // https://modelcontextprotocol.io/specification/2025-03-26/basic/transports#session-management
+    app.delete("/mcp", async (req, res) => {
+        const sessionId = req.headers["mcp-session-id"];
+        if (!sessionId) {
+            logger.warn("Session termination request missing session ID");
+            res.status(400).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32600,
+                    message: "Missing mcp-session-id header",
+                },
+                id: null,
+            });
+            return;
+        }
+        const transport = sessionStore.get(sessionId);
+        if (!transport) {
+            logger.warn({ sessionId }, "Session termination failed - not found");
+            res.status(404).json({
+                jsonrpc: "2.0",
+                error: {
+                    code: -32000,
+                    message: "Session not found or expired",
+                },
+                id: null,
+            });
+            return;
+        }
+        // Close the transport
+        transport.close?.();
+        logger.info({ sessionId }, "Session terminated");
+        // Acknowledge session termination with 204 No Content
+        res.status(204).end();
+    });
+    return { app };
+}

package/dist/server/stateless.d.ts

@@ -0,0 +1,46 @@
+import express from "express";
+import type { z } from "zod";
+import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { OAuthMountOptions } from "./auth/oauth.js";
+import { type Logger } from "./logger.js";
+export type { Logger } from "./logger.js";
+/**
+ * Arguments when we create a stateless server instance
+ */
+export interface CreateStatelessServerArg<T = Record<string, unknown>> {
+    config: T;
+    auth?: AuthInfo;
+    logger: Logger;
+}
+export type CreateStatelessServerFn<T = Record<string, unknown>> = (arg: CreateStatelessServerArg<T>) => Server;
+/**
+ * Configuration options for the stateless server
+ */
+export interface StatelessServerOptions<T = Record<string, unknown>> {
+    /**
+     * Zod schema for config validation
+     */
+    schema?: z.ZodSchema<T>;
+    /**
+     * Express app instance to use (optional)
+     */
+    app?: express.Application;
+    oauth?: OAuthMountOptions;
+    /**
+     * Log level for the server (default: 'info')
+     */
+    logLevel?: "debug" | "info" | "warn" | "error";
+}
+/**
+ * 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 declare function createStatelessServer<T = Record<string, unknown>>(createMcpServer: CreateStatelessServerFn<T>, options?: StatelessServerOptions<T>): {
+    app: express.Application;
+};