@smithery/sdk 1.7.2 → 1.7.3

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+export * from "./shared/config.js";
+export * from "./shared/patch.js";
+export { createStatefulServer, type StatefulServerOptions, } from "./server/stateful.js";
+export * from "./server/session.js";
+export * from "./server/auth/identity.js";
+export * from "./server/auth/oauth.js";
+export { createWidgetServer } from "./server/widget.js";
+export type { WidgetServerOptions } from "./server/widget.js";
+export { widget } from "./openai/index.js";
+export type { WidgetToolOptions, WidgetResponseOptions, WidgetResourceOptions, } from "./openai/index.js";
+export type { Theme, DisplayMode, OpenAiGlobals, CallToolResponse, } from "./react/types.js";

package/dist/index.js

@@ -0,0 +1,19 @@
+// Smithery SDK – Main exports
+// Use subpath imports for tree-shaking: @smithery/sdk/server, /helpers, /react
+// === Shared Utilities ===
+export * from "./shared/config.js";
+export * from "./shared/patch.js";
+// === Server Primitives ===
+// Stateful/stateless server patterns, session management, auth
+export { createStatefulServer, } from "./server/stateful.js";
+export * from "./server/session.js";
+export * from "./server/auth/identity.js";
+export * from "./server/auth/oauth.js";
+// === Widget SDK - Server ===
+// createWidgetServer() - MCP server wrapper for widgets
+export { createWidgetServer } from "./server/widget.js";
+// === Widget SDK - OpenAI ===
+// widget.response() - Standard success response
+// widget.error() - Standard error response
+// widget.resource() - Auto-generate widget HTML
+export { widget } from "./openai/index.js";

package/dist/openai/index.d.ts

@@ -0,0 +1,2 @@
+export { widget } from "./widget.js";
+export type { WidgetResponseOptions, WidgetResourceOptions, WidgetToolOptions, } from "./widget.js";

package/dist/openai/index.js

@@ -0,0 +1 @@
+export { widget } from "./widget.js";

package/dist/openai/widget.d.ts

@@ -0,0 +1,67 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export interface WidgetResponseOptions<TState = Record<string, unknown>> {
+    structuredData: TState;
+    message: string;
+    meta?: Record<string, unknown>;
+}
+export interface WidgetResourceOptions {
+    name: string;
+    description?: string;
+    prefersBorder?: boolean;
+    csp?: {
+        connect_domains?: string[];
+        resource_domains?: string[];
+    };
+    bundlePath?: string;
+    bundleURL?: string;
+    cssURLs?: string | string[];
+}
+export interface WidgetToolOptions {
+    template: string;
+    invoking?: string;
+    invoked?: string;
+    widgetAccessible?: boolean;
+}
+export interface WidgetErrorOptions {
+    message: string;
+    details?: unknown;
+    meta?: Record<string, unknown>;
+}
+export declare function response<TState = Record<string, unknown>>(options: WidgetResponseOptions<TState>): {
+    structuredContent: Record<string, unknown>;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    _meta: Record<string, unknown>;
+};
+export declare function error(options: string | WidgetErrorOptions): {
+    _meta?: Record<string, unknown> | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    isError: boolean;
+};
+export declare function resource<TState = Record<string, unknown>>(options: WidgetResourceOptions): {
+    name: string;
+    uri: string;
+    handler: () => Promise<{
+        contents: Array<{
+            uri: string;
+            text: string;
+            mimeType: "text/html+skybridge";
+            _meta?: Record<string, unknown>;
+        }>;
+    }>;
+    toolConfig: (options?: Omit<WidgetToolOptions, "template">) => Record<string, unknown>;
+    response: (options: WidgetResponseOptions<TState>) => ReturnType<typeof response<TState>>;
+    register: (server: Pick<McpServer, "registerResource">) => void;
+};
+export declare function toolConfig(options: WidgetToolOptions): Record<string, unknown>;
+export declare const widget: {
+    response: typeof response;
+    error: typeof error;
+    resource: typeof resource;
+    toolConfig: typeof toolConfig;
+};

package/dist/openai/widget.js

@@ -0,0 +1,126 @@
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+export function response(options) {
+    const { structuredData, message, meta = {} } = options;
+    return {
+        structuredContent: structuredData,
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+        _meta: meta,
+    };
+}
+export function error(options) {
+    const isString = typeof options === "string";
+    const message = isString ? options : options.message;
+    const details = isString ? undefined : options.details;
+    const meta = isString ? undefined : options.meta;
+    const finalMeta = {
+        ...(meta || {}),
+    };
+    if (details) {
+        finalMeta.errorDetails = details;
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: message,
+            },
+        ],
+        isError: true,
+        ...(Object.keys(finalMeta).length > 0 && { _meta: finalMeta }),
+    };
+}
+export function resource(options) {
+    const { name, description, prefersBorder, csp, bundlePath = `.smithery/${name}.js`, bundleURL, } = options;
+    const uri = `ui://widget/${name}.html`;
+    const handler = async () => {
+        let scriptTag;
+        if (bundleURL) {
+            scriptTag = `<script type="module" src="${bundleURL}"></script>`;
+        }
+        else {
+            const js = await readFile(resolve(process.cwd(), bundlePath), "utf-8");
+            scriptTag = `<script type="module">${js}</script>`;
+        }
+        const cssUrls = Array.isArray(options.cssURLs)
+            ? options.cssURLs
+            : options.cssURLs
+                ? [options.cssURLs]
+                : [];
+        const cssLinks = cssUrls
+            .map(url => `<link rel="stylesheet" href="${url}">`)
+            .join("\n");
+        const html = `
+<div id="${name}-root"></div>
+${cssLinks}
+${scriptTag}
+    `.trim();
+        const _meta = {};
+        if (description)
+            _meta["openai/widgetDescription"] = description;
+        if (prefersBorder !== undefined)
+            _meta["openai/widgetPrefersBorder"] = prefersBorder;
+        if (csp)
+            _meta["openai/widgetCSP"] = csp;
+        return {
+            contents: [
+                {
+                    uri,
+                    text: html,
+                    mimeType: "text/html+skybridge",
+                    ...(Object.keys(_meta).length > 0 && { _meta }),
+                },
+            ],
+        };
+    };
+    const toolConfig = (options) => {
+        return {
+            "openai/outputTemplate": uri,
+            "openai/widgetAccessible": options?.widgetAccessible ?? true,
+            ...(options?.invoking && {
+                "openai/toolInvocation/invoking": options.invoking,
+            }),
+            ...(options?.invoked && {
+                "openai/toolInvocation/invoked": options.invoked,
+            }),
+        };
+    };
+    const typedResponse = (options) => {
+        return response(options);
+    };
+    const register = (server) => {
+        server.registerResource(name, uri, {}, handler);
+    };
+    return {
+        name,
+        uri,
+        handler,
+        toolConfig,
+        response: typedResponse,
+        register,
+    };
+}
+export function toolConfig(options) {
+    const meta = {
+        "openai/outputTemplate": `ui://widget/${options.template}.html`,
+        "openai/widgetAccessible": options.widgetAccessible ?? true,
+    };
+    if (options.invoking) {
+        meta["openai/toolInvocation/invoking"] = options.invoking;
+    }
+    if (options.invoked) {
+        meta["openai/toolInvocation/invoked"] = options.invoked;
+    }
+    return meta;
+}
+export const widget = {
+    response,
+    error,
+    resource,
+    toolConfig,
+};

package/dist/react/ErrorBoundary.d.ts

@@ -0,0 +1,18 @@
+import { Component, type ReactNode } from "react";
+interface ErrorBoundaryProps {
+    children: ReactNode;
+    fallback?: (error: Error) => ReactNode;
+}
+interface ErrorBoundaryState {
+    hasError: boolean;
+    error: Error | null;
+}
+export declare class ErrorBoundary extends Component<ErrorBoundaryProps, ErrorBoundaryState> {
+    constructor(props: ErrorBoundaryProps);
+    static getDerivedStateFromError(error: Error): ErrorBoundaryState;
+    componentDidCatch(error: Error, errorInfo: {
+        componentStack?: string;
+    }): void;
+    render(): ReactNode;
+}
+export {};

package/dist/react/ErrorBoundary.js

@@ -0,0 +1,28 @@
+import { Component, createElement } from "react";
+export class ErrorBoundary extends Component {
+    constructor(props) {
+        super(props);
+        this.state = { hasError: false, error: null };
+    }
+    static getDerivedStateFromError(error) {
+        return { hasError: true, error };
+    }
+    componentDidCatch(error, errorInfo) {
+        console.error("Widget error:", error, errorInfo);
+    }
+    render() {
+        if (this.state.hasError && this.state.error) {
+            if (this.props.fallback) {
+                return this.props.fallback(this.state.error);
+            }
+            return createElement("div", {
+                style: {
+                    padding: "16px",
+                    color: "#d32f2f",
+                    fontFamily: "system-ui, sans-serif",
+                },
+            }, createElement("h3", { style: { margin: "0 0 8px 0", fontSize: "14px" } }, "Widget Error"), createElement("p", { style: { margin: "0", fontSize: "12px", opacity: 0.8 } }, this.state.error.message || "An error occurred"));
+        }
+        return this.props.children;
+    }
+}

package/dist/react/hooks.d.ts

@@ -0,0 +1,32 @@
+import { type SetStateAction } from "react";
+import type { OpenAiGlobals } from "./types.js";
+export declare function useOpenAiGlobal<K extends keyof OpenAiGlobals>(key: K): OpenAiGlobals[K] | undefined;
+export declare function useTheme(): import("./types.js").Theme;
+export declare function useDisplayMode(): import("./types.js").DisplayMode;
+export declare function useUserAgent(): import("./types.js").UserAgent | undefined;
+export declare function useMaxHeight(): number | undefined;
+export declare function useSafeArea(): import("./types.js").SafeArea | undefined;
+export declare function useLocale(): string;
+export declare function useToolInput<T = Record<string, unknown>>(): T | undefined;
+export declare function useToolOutput<T = unknown>(): {
+    content: {
+        type: string;
+        text: string;
+    }[];
+    structuredContent: T | undefined;
+};
+export declare function useToolResponseMetadata<T = Record<string, unknown>>(): T | undefined;
+export declare function useCallTool<TArgs = Record<string, unknown>, TResult = unknown>(toolName: string): {
+    call: (args: TArgs) => Promise<void>;
+    isPending: boolean;
+    error: Error | null;
+    data: TResult | null;
+};
+export declare function useSendFollowUp(): {
+    send: (prompt: string) => Promise<void>;
+    isPending: boolean;
+    error: Error | null;
+};
+export declare function useRequestDisplayMode(): (mode: "inline" | "pip" | "fullscreen") => Promise<void>;
+export declare function useWidgetState<T extends Record<string, unknown>>(defaultState: T | (() => T)): readonly [T, (state: SetStateAction<T>) => void];
+export declare function useWidgetState<T extends Record<string, unknown>>(defaultState?: T | (() => T | null) | null): readonly [T | null, (state: SetStateAction<T | null>) => void];

package/dist/react/hooks.js

@@ -0,0 +1,135 @@
+import { useSyncExternalStore, useCallback, useState, useEffect, } from "react";
+const SET_GLOBALS_EVENT_TYPE = "openai:set_globals";
+function getOpenAiGlobal(key) {
+    if (!window.openai)
+        return undefined;
+    return window.openai[key];
+}
+function subscribeToOpenAi(callback) {
+    const handler = () => callback();
+    window.addEventListener(SET_GLOBALS_EVENT_TYPE, handler);
+    return () => window.removeEventListener(SET_GLOBALS_EVENT_TYPE, handler);
+}
+export function useOpenAiGlobal(key) {
+    return useSyncExternalStore(subscribeToOpenAi, () => getOpenAiGlobal(key), () => undefined);
+}
+export function useTheme() {
+    return useOpenAiGlobal("theme") ?? "dark";
+}
+export function useDisplayMode() {
+    return useOpenAiGlobal("displayMode") ?? "inline";
+}
+export function useUserAgent() {
+    return useOpenAiGlobal("userAgent");
+}
+export function useMaxHeight() {
+    return useOpenAiGlobal("maxHeight");
+}
+export function useSafeArea() {
+    return useOpenAiGlobal("safeArea");
+}
+export function useLocale() {
+    return useOpenAiGlobal("locale") ?? "en";
+}
+export function useToolInput() {
+    return useOpenAiGlobal("toolInput");
+}
+export function useToolOutput() {
+    const output = useOpenAiGlobal("toolOutput");
+    return {
+        content: output?.content ?? [],
+        structuredContent: output?.structuredContent,
+    };
+}
+export function useToolResponseMetadata() {
+    return useOpenAiGlobal("toolResponseMetadata");
+}
+export function useCallTool(toolName) {
+    const [isPending, setIsPending] = useState(false);
+    const [error, setError] = useState(null);
+    const [data, setData] = useState(null);
+    const callTool = useOpenAiGlobal("callTool");
+    const call = useCallback(async (args) => {
+        if (!callTool) {
+            setError(new Error("callTool not available"));
+            return;
+        }
+        setIsPending(true);
+        setError(null);
+        try {
+            const result = await callTool(toolName, args);
+            if (result.isError) {
+                throw new Error(result.content?.[0]?.text ?? "Unknown error");
+            }
+            setData((result._meta?.gameState ??
+                result.structuredContent ??
+                null));
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsPending(false);
+        }
+    }, [callTool, toolName]);
+    return { call, isPending, error, data };
+}
+export function useSendFollowUp() {
+    const [isPending, setIsPending] = useState(false);
+    const [error, setError] = useState(null);
+    const sendFollowUpMessage = useOpenAiGlobal("sendFollowUpMessage");
+    const send = useCallback(async (prompt) => {
+        if (!sendFollowUpMessage) {
+            setError(new Error("sendFollowUpMessage not available"));
+            return;
+        }
+        setIsPending(true);
+        setError(null);
+        try {
+            await sendFollowUpMessage({ prompt });
+        }
+        catch (err) {
+            setError(err instanceof Error ? err : new Error(String(err)));
+        }
+        finally {
+            setIsPending(false);
+        }
+    }, [sendFollowUpMessage]);
+    return { send, isPending, error };
+}
+export function useRequestDisplayMode() {
+    const requestDisplayMode = useOpenAiGlobal("requestDisplayMode");
+    const request = useCallback(async (mode) => {
+        if (!requestDisplayMode) {
+            return;
+        }
+        await requestDisplayMode({ mode });
+    }, [requestDisplayMode]);
+    return request;
+}
+export function useWidgetState(defaultState) {
+    const widgetStateFromWindow = useOpenAiGlobal("widgetState");
+    const [widgetState, _setWidgetState] = useState(() => {
+        if (widgetStateFromWindow != null) {
+            return widgetStateFromWindow;
+        }
+        return typeof defaultState === "function"
+            ? defaultState()
+            : (defaultState ?? null);
+    });
+    useEffect(() => {
+        if (widgetStateFromWindow != null) {
+            _setWidgetState(widgetStateFromWindow);
+        }
+    }, [widgetStateFromWindow]);
+    const setWidgetState = useCallback((state) => {
+        _setWidgetState((prevState) => {
+            const newState = typeof state === "function" ? state(prevState) : state;
+            if (newState != null && window.openai?.setWidgetState) {
+                window.openai.setWidgetState(newState);
+            }
+            return newState;
+        });
+    }, []);
+    return [widgetState, setWidgetState];
+}

package/dist/react/index.d.ts

@@ -0,0 +1,3 @@
+export { useOpenAiGlobal, useTheme, useDisplayMode, useUserAgent, useMaxHeight, useSafeArea, useLocale, useToolInput, useToolOutput, useToolResponseMetadata, useWidgetState, useCallTool, useSendFollowUp, useRequestDisplayMode, } from "./hooks.js";
+export type { Theme, DisplayMode, DeviceType, UserAgent, SafeAreaInsets, SafeArea, CallToolResponse, OpenAiGlobals, } from "./types.js";
+export { ErrorBoundary } from "./ErrorBoundary.js";

package/dist/react/index.js

@@ -0,0 +1,2 @@
+export { useOpenAiGlobal, useTheme, useDisplayMode, useUserAgent, useMaxHeight, useSafeArea, useLocale, useToolInput, useToolOutput, useToolResponseMetadata, useWidgetState, useCallTool, useSendFollowUp, useRequestDisplayMode, } from "./hooks.js";
+export { ErrorBoundary } from "./ErrorBoundary.js";

package/dist/react/types.d.ts

@@ -0,0 +1,66 @@
+export type Theme = "light" | "dark";
+export type DisplayMode = "inline" | "pip" | "fullscreen";
+export interface DeviceType {
+    type: "mobile" | "tablet" | "desktop" | "unknown";
+}
+export interface UserAgent {
+    device: DeviceType;
+    capabilities: {
+        hover: boolean;
+        touch: boolean;
+    };
+}
+export interface SafeAreaInsets {
+    top: number;
+    bottom: number;
+    left: number;
+    right: number;
+}
+export interface SafeArea {
+    insets: SafeAreaInsets;
+}
+export interface CallToolResponse {
+    content?: Array<{
+        type: string;
+        text: string;
+    }>;
+    structuredContent?: unknown;
+    _meta?: Record<string, unknown>;
+    isError?: boolean;
+}
+export interface OpenAiGlobals {
+    theme: Theme;
+    displayMode: DisplayMode;
+    userAgent: UserAgent;
+    locale: string;
+    maxHeight: number;
+    safeArea: SafeArea;
+    toolInput: Record<string, unknown>;
+    toolOutput: {
+        content?: Array<{
+            type: string;
+            text: string;
+        }>;
+        structuredContent?: unknown;
+    } | null;
+    toolResponseMetadata: Record<string, unknown> | null;
+    widgetState: Record<string, unknown> | null;
+    callTool: (name: string, args: Record<string, unknown>) => Promise<CallToolResponse>;
+    sendFollowUpMessage: (args: {
+        prompt: string;
+    }) => Promise<void>;
+    openExternal: (payload: {
+        href: string;
+    }) => void;
+    requestDisplayMode: (args: {
+        mode: DisplayMode;
+    }) => Promise<{
+        mode: DisplayMode;
+    }>;
+    setWidgetState: (state: Record<string, unknown>) => Promise<void>;
+}
+declare global {
+    interface Window {
+        openai?: OpenAiGlobals;
+    }
+}

package/dist/react/types.js

@@ -0,0 +1 @@
+export {};

package/dist/server/auth/identity.d.ts

@@ -0,0 +1,18 @@
+import type { Application, Request, Router } from "express";
+import { type JWTPayload } from "jose";
+import type { OAuthTokens } from "@modelcontextprotocol/sdk/shared/auth.js";
+export type IdentityJwtClaims = JWTPayload & Record<string, unknown>;
+export interface IdentityHandler {
+    /** Base path to mount metadata and token endpoints. Default: "/" */
+    basePath?: string;
+    /** Expected JWT issuer. Default: "https://server.smithery.ai" */
+    issuer?: string;
+    /** JWKS URL for issuer. Default: "https://server.smithery.ai/.well-known/jwks.json" */
+    jwksUrl?: string;
+    /** Optional explicit token path. Overrides basePath+"token". */
+    tokenPath?: string;
+    /** Handle a JWT grant provided by an external identity provider (i.e., Smithery) and mint access tokens */
+    handleJwtGrant: (claims: IdentityJwtClaims, req: Request) => Promise<OAuthTokens | null>;
+}
+export declare function createIdentityTokenRouter(options: IdentityHandler): Router;
+export declare function mountIdentity(app: Application, options: IdentityHandler): void;

package/dist/server/auth/identity.js

@@ -0,0 +1,55 @@
+import express from "express";
+import { createRemoteJWKSet, jwtVerify } from "jose";
+function normalizeBasePath(basePath) {
+    const value = basePath ?? "/";
+    return value.endsWith("/") ? value : `${value}/`;
+}
+export function createIdentityTokenRouter(options) {
+    const basePath = normalizeBasePath(options.basePath);
+    const issuer = options.issuer ?? "https://server.smithery.ai";
+    const jwksUrl = new URL(options.jwksUrl ?? "https://server.smithery.ai/.well-known/jwks.json");
+    const tokenPath = typeof options.tokenPath === "string" && options.tokenPath.length > 0
+        ? options.tokenPath
+        : `${basePath}token`;
+    // Create JWKS resolver once; jose caches keys internally
+    const JWKS = createRemoteJWKSet(jwksUrl);
+    const tokenRouter = express.Router();
+    // urlencoded parser required for OAuth token requests
+    tokenRouter.use(express.urlencoded({ extended: false }));
+    tokenRouter.post(tokenPath, async (req, res, next) => {
+        try {
+            const grantType = typeof req.body?.grant_type === "string"
+                ? req.body.grant_type
+                : undefined;
+            if (grantType !== "urn:ietf:params:oauth:grant-type:jwt-bearer")
+                return next();
+            const assertion = typeof req.body?.assertion === "string" ? req.body.assertion : undefined;
+            if (!assertion) {
+                res.status(400).json({
+                    error: "invalid_request",
+                    error_description: "Missing assertion",
+                });
+                return;
+            }
+            const host = req.get("host") ?? "localhost";
+            const audience = `https://${host}${tokenPath}`;
+            const { payload } = await jwtVerify(assertion, JWKS, {
+                issuer,
+                audience,
+                algorithms: ["RS256"],
+            });
+            const result = await options.handleJwtGrant(payload, req);
+            if (!result)
+                return next();
+            res.json(result);
+        }
+        catch (error) {
+            console.error(error);
+            res.status(400).json({ error: "invalid_grant" });
+        }
+    });
+    return tokenRouter;
+}
+export function mountIdentity(app, options) {
+    app.use(createIdentityTokenRouter(options));
+}

package/dist/server/auth/oauth.d.ts

@@ -0,0 +1,21 @@
+import type { OAuthServerProvider, OAuthTokenVerifier } from "@modelcontextprotocol/sdk/server/auth/provider.js";
+import type { AuthInfo } from "@modelcontextprotocol/sdk/server/auth/types.js";
+import type { Application, Response } from "express";
+import { type IdentityHandler } from "./identity.js";
+export interface TokenVerifier extends OAuthTokenVerifier {
+    verifyAccessToken: (token: string) => Promise<AuthInfo>;
+    requiredScopes?: string[];
+    resourceMetadataUrl?: string;
+}
+type ProviderVerifier = OAuthServerProvider & TokenVerifier;
+export interface OAuthProvider extends ProviderVerifier {
+    basePath?: string;
+    callbackPath?: string;
+    handleOAuthCallback?: (code: string, state: string | undefined, res: Response) => Promise<URL>;
+}
+export interface OAuthMountOptions {
+    provider?: OAuthProvider | TokenVerifier;
+    identity?: IdentityHandler;
+}
+export declare function mountOAuth(app: Application, opts: OAuthMountOptions): void;
+export {};