@smithery/sdk 4.0.1 → 4.2.0

package/LICENSE

@@ -0,0 +1,20 @@
+The MIT License (MIT)
+Copyright (c) 2025 Smithery
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,6 +1,88 @@
-# Smithery TypeScript SDK
+# Smithery SDK
 
-The SDK provides the types and bundle manifest schemas for building and deploying MCP servers on Smithery.
+[![npm version](https://img.shields.io/npm/v/@smithery/sdk)](https://www.npmjs.com/package/@smithery/sdk)
 
-For getting started, see the official documentation:
-[https://smithery.ai/docs/getting_started/quickstart_build_typescript](https://smithery.ai/docs/getting_started/quickstart_build_typescript)
+TypeScript types for building MCP servers on the Smithery hosted runtime.
+
+Docs: https://smithery.ai/docs/build
+
+## Installation
+
+```bash
+npm install @smithery/sdk
+```
+
+## Usage
+
+The SDK provides types for the Smithery runtime context that your MCP server receives when deployed.
+
+```typescript
+import type {
+  ServerModule,
+  ServerContext,
+  Session,
+} from "@smithery/sdk"
+import { z } from "zod"
+
+// Define your configuration schema
+export const configSchema = z.object({
+  apiKey: z.string(),
+})
+
+// Create your server
+export default const createServer = async (context: ServerContext<z.infer<typeof configSchema>>) => {
+  const { config, env } = context
+
+  // Access user configuration
+  console.log(config.apiKey)
+
+  // Access environment variables
+  console.log(env.MY_SECRET)
+
+  // For stateful servers, access session storage
+  if ("session" in context) {
+    await context.session.set("key", "value")
+    const value = await context.session.get("key")
+  }
+
+  // Return your MCP server instance
+  return new Server({ name: "my-server", version: "1.0.0" }, { capabilities: {} })
+}
+
+```
+
+## Types
+
+### `ServerContext<TConfig>`
+
+The context object passed to your server factory function:
+
+- `config: TConfig` - User-provided configuration (validated against your `configSchema`)
+- `env: Record<string, string | undefined>` - Environment variables
+- `session?: Session` - Session storage (only for stateful servers)
+
+### `Session`
+
+Key-value storage scoped to the user session:
+
+- `get<T>(key: string): Promise<T | undefined>`
+- `set(key: string, value: unknown): Promise<void>`
+- `delete(key: string): Promise<void>`
+
+### `ServerModule<TConfig>`
+
+The expected exports from your server entry point:
+
+- `default: CreateServerFn<TConfig>` - Factory function that creates your MCP server
+- `configSchema?: z.ZodSchema<TConfig>` - Zod schema for configuration validation
+- `createSandboxServer?: CreateSandboxServerFn` - Optional function for deployment scanning
+- `stateful?: boolean` - Whether the server maintains state between requests (default: `false`)
+
+## Documentation
+
+For complete documentation, see:
+- [Quickstart Guide](https://smithery.ai/docs/build/quickstart)
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -1,2 +1 @@
 export * from "./types/index.js";
-export * from "./bundle/index.js";

package/dist/index.js

@@ -1,5 +1,2 @@
-// Smithery SDK – Main exports
-// Types for MCP server authors
+// Smithery SDK – Runtime types for MCP server authors
 export * from "./types/index.js";
-// Bundle manifest schema (for CLI/registry)
-export * from "./bundle/index.js";

package/dist/types/index.d.ts

@@ -1,4 +1,5 @@
 import type { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import type { Notification } from "@modelcontextprotocol/sdk/types.js";
 import type { z } from "zod";
 export type Session = {
     id: string;
@@ -21,6 +22,70 @@ export type SandboxServerContext = {
 };
 export type CreateServerFn<TConfig = unknown> = (context: ServerContext<TConfig>) => Server | Promise<Server>;
 export type CreateSandboxServerFn = (context: SandboxServerContext) => Server | Promise<Server>;
+/**
+ * OAuth adapter for servers that require user authorization.
+ * @unstable This interface is subject to change.
+ */
+export interface AuthAdapter {
+    getAuthorizationUrl(args: {
+        callbackUrl: string;
+        state: string;
+        codeChallenge?: string;
+        config: unknown;
+    }): Promise<{
+        authorizationUrl: string;
+    }>;
+    exchangeCode(args: {
+        code: string;
+        callbackUrl: string;
+        codeVerifier?: string;
+        config: unknown;
+    }): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }>;
+    refreshToken(args: {
+        refreshToken: string;
+        config: unknown;
+    }): Promise<{
+        accessToken: string;
+        refreshToken?: string;
+        expiresIn?: number;
+    }>;
+}
+/**
+ * Context passed to handleHttp for stateless servers.
+ * @unstable This type is subject to change.
+ */
+export type StatelessHttpContext = {
+    env: Record<string, string | undefined>;
+};
+/**
+ * Context passed to handleHttp for stateful servers.
+ * @unstable This type is subject to change.
+ */
+export type StatefulHttpContext = {
+    env: Record<string, string | undefined>;
+    sessions: {
+        /**
+         * Send a notification directly to the connected client (via `transport.send()`),
+         * bypassing the server's notification handler chain.
+         * Use this for webhook → client notification routing.
+         */
+        notify(sessionId: string, notification: Notification): Promise<void>;
+        /**
+         * Inject a raw JSON-RPC message into the server's handler chain for processing.
+         * The server's registered request/notification handlers will be invoked.
+         */
+        dispatch(sessionId: string, message: unknown): Promise<void>;
+    };
+};
+/**
+ * Handler for non-MCP HTTP requests (e.g. webhook endpoints on subpaths).
+ * @unstable This type is subject to change.
+ */
+export type HandleHttpFn = (request: Request, context: StatelessHttpContext | StatefulHttpContext) => Promise<Response>;
 /**
  * ServerModule - expected exports from an MCP server entry point
  */
@@ -35,4 +100,8 @@ export interface ServerModule<TConfig = unknown> {
      * @default false
      */
     stateful?: boolean;
+    createAuthAdapter?: (context: {
+        env: Record<string, unknown>;
+    }) => Promise<AuthAdapter>;
+    handleHttp?: HandleHttpFn;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@smithery/sdk",
-	"version": "4.0.1",
+	"version": "4.2.0",
 	"description": "SDK to develop with Smithery",
 	"type": "module",
 	"repository": {
@@ -13,10 +13,6 @@
 		".": {
 			"types": "./dist/index.d.ts",
 			"default": "./dist/index.js"
-		},
-		"./bundle": {
-			"types": "./dist/bundle/index.d.ts",
-			"default": "./dist/bundle/index.js"
 		}
 	},
 	"files": [

package/dist/bundle/config.d.ts

@@ -1,16 +0,0 @@
-/**
- * Config - loaded from smithery.config.ts
- */
-export interface Config {
-    build?: {
-        /**
-         * Path to the server's entry point.
-         * Default: detected from package.json "module" or "main"
-         */
-        entry?: string;
-        /**
-         * Optional esbuild overrides for bundling
-         */
-        esbuild?: Record<string, unknown>;
-    };
-}

package/dist/bundle/config.js

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

package/dist/bundle/deploy-payload.d.ts

@@ -1,120 +0,0 @@
-import { z } from "zod";
-export declare const DeployPayloadSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
-    type: z.ZodLiteral<"hosted">;
-    stateful: z.ZodDefault<z.ZodBoolean>;
-    configSchema: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-    serverCard: z.ZodOptional<z.ZodObject<{
-        serverInfo: z.ZodObject<{
-            version: z.ZodString;
-            websiteUrl: z.ZodOptional<z.ZodString>;
-            description: z.ZodOptional<z.ZodString>;
-            icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                src: z.ZodString;
-                mimeType: z.ZodOptional<z.ZodString>;
-                sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                theme: z.ZodOptional<z.ZodEnum<{
-                    light: "light";
-                    dark: "dark";
-                }>>;
-            }, z.core.$strip>>>;
-            name: z.ZodString;
-            title: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>;
-        authentication: z.ZodOptional<z.ZodObject<{
-            required: z.ZodBoolean;
-            schemes: z.ZodArray<z.ZodString>;
-        }, z.core.$strip>>;
-        tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            description: z.ZodOptional<z.ZodString>;
-            inputSchema: z.ZodObject<{
-                type: z.ZodLiteral<"object">;
-                properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<object, object>>>;
-                required: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$catchall<z.ZodUnknown>>;
-            outputSchema: z.ZodOptional<z.ZodObject<{
-                type: z.ZodLiteral<"object">;
-                properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<object, object>>>;
-                required: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            }, z.core.$catchall<z.ZodUnknown>>>;
-            annotations: z.ZodOptional<z.ZodObject<{
-                title: z.ZodOptional<z.ZodString>;
-                readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-                destructiveHint: z.ZodOptional<z.ZodBoolean>;
-                idempotentHint: z.ZodOptional<z.ZodBoolean>;
-                openWorldHint: z.ZodOptional<z.ZodBoolean>;
-            }, z.core.$strip>>;
-            execution: z.ZodOptional<z.ZodObject<{
-                taskSupport: z.ZodOptional<z.ZodEnum<{
-                    optional: "optional";
-                    required: "required";
-                    forbidden: "forbidden";
-                }>>;
-            }, z.core.$strip>>;
-            _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-            icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                src: z.ZodString;
-                mimeType: z.ZodOptional<z.ZodString>;
-                sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                theme: z.ZodOptional<z.ZodEnum<{
-                    light: "light";
-                    dark: "dark";
-                }>>;
-            }, z.core.$strip>>>;
-            name: z.ZodString;
-            title: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-        resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            uri: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            mimeType: z.ZodOptional<z.ZodString>;
-            annotations: z.ZodOptional<z.ZodObject<{
-                audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-                    user: "user";
-                    assistant: "assistant";
-                }>>>;
-                priority: z.ZodOptional<z.ZodNumber>;
-                lastModified: z.ZodOptional<z.ZodISODateTime>;
-            }, z.core.$strip>>;
-            _meta: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
-            icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                src: z.ZodString;
-                mimeType: z.ZodOptional<z.ZodString>;
-                sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                theme: z.ZodOptional<z.ZodEnum<{
-                    light: "light";
-                    dark: "dark";
-                }>>;
-            }, z.core.$strip>>>;
-            name: z.ZodString;
-            title: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-        prompts: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            description: z.ZodOptional<z.ZodString>;
-            arguments: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                name: z.ZodString;
-                description: z.ZodOptional<z.ZodString>;
-                required: z.ZodOptional<z.ZodBoolean>;
-            }, z.core.$strip>>>;
-            _meta: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
-            icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
-                src: z.ZodString;
-                mimeType: z.ZodOptional<z.ZodString>;
-                sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-                theme: z.ZodOptional<z.ZodEnum<{
-                    light: "light";
-                    dark: "dark";
-                }>>;
-            }, z.core.$strip>>>;
-            name: z.ZodString;
-            title: z.ZodOptional<z.ZodString>;
-        }, z.core.$strip>>>;
-    }, z.core.$loose>>;
-    source: z.ZodOptional<z.ZodObject<{
-        commit: z.ZodOptional<z.ZodString>;
-        branch: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>;
-}, z.core.$strip>, z.ZodObject<{
-    type: z.ZodLiteral<"external">;
-    upstreamUrl: z.ZodString;
-}, z.core.$strip>], "type">;
-export type DeployPayload = z.infer<typeof DeployPayloadSchema>;

package/dist/bundle/deploy-payload.js

@@ -1,22 +0,0 @@
-import { z } from "zod";
-import { ServerCardSchema } from "./server-card.js";
-const HostedDeployPayloadSchema = z.object({
-    type: z.literal("hosted"),
-    stateful: z.boolean().default(false),
-    configSchema: z.record(z.string(), z.unknown()).optional(),
-    serverCard: ServerCardSchema.optional(),
-    source: z
-        .object({
-        commit: z.string().optional(),
-        branch: z.string().optional(),
-    })
-        .optional(),
-});
-const ExternalDeployPayloadSchema = z.object({
-    type: z.literal("external"),
-    upstreamUrl: z.string().url(),
-});
-export const DeployPayloadSchema = z.discriminatedUnion("type", [
-    HostedDeployPayloadSchema,
-    ExternalDeployPayloadSchema,
-]);

package/dist/bundle/index.d.ts

@@ -1,7 +0,0 @@
-/**
- * The bundle package is not guaranteed to be backwards compatible or stable, and is used internally for Smithery CLI.
- */
-export * from "./limits.js";
-export * from "./config.js";
-export * from "./deploy-payload.js";
-export * from "./server-card.js";

package/dist/bundle/index.js

@@ -1,7 +0,0 @@
-/**
- * The bundle package is not guaranteed to be backwards compatible or stable, and is used internally for Smithery CLI.
- */
-export * from "./limits.js";
-export * from "./config.js";
-export * from "./deploy-payload.js";
-export * from "./server-card.js";

package/dist/bundle/limits.d.ts

@@ -1,7 +0,0 @@
-/**
- * Validate bundle size limits
- */
-export declare const BUNDLE_SIZE_LIMITS: {
-    module: number;
-    sourcemap: number;
-};

package/dist/bundle/limits.js

@@ -1,7 +0,0 @@
-/**
- * Validate bundle size limits
- */
-export const BUNDLE_SIZE_LIMITS = {
-    module: 5 * 1024 * 1024, // 5 MB
-    sourcemap: 10 * 1024 * 1024, // 10 MB
-};

package/dist/bundle/server-card.d.ts

@@ -1,108 +0,0 @@
-import { z } from "zod";
-export declare const ServerCardSchema: z.ZodObject<{
-    serverInfo: z.ZodObject<{
-        version: z.ZodString;
-        websiteUrl: z.ZodOptional<z.ZodString>;
-        description: z.ZodOptional<z.ZodString>;
-        icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            src: z.ZodString;
-            mimeType: z.ZodOptional<z.ZodString>;
-            sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            theme: z.ZodOptional<z.ZodEnum<{
-                light: "light";
-                dark: "dark";
-            }>>;
-        }, z.core.$strip>>>;
-        name: z.ZodString;
-        title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>;
-    authentication: z.ZodOptional<z.ZodObject<{
-        required: z.ZodBoolean;
-        schemes: z.ZodArray<z.ZodString>;
-    }, z.core.$strip>>;
-    tools: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        description: z.ZodOptional<z.ZodString>;
-        inputSchema: z.ZodObject<{
-            type: z.ZodLiteral<"object">;
-            properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<object, object>>>;
-            required: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$catchall<z.ZodUnknown>>;
-        outputSchema: z.ZodOptional<z.ZodObject<{
-            type: z.ZodLiteral<"object">;
-            properties: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodCustom<object, object>>>;
-            required: z.ZodOptional<z.ZodArray<z.ZodString>>;
-        }, z.core.$catchall<z.ZodUnknown>>>;
-        annotations: z.ZodOptional<z.ZodObject<{
-            title: z.ZodOptional<z.ZodString>;
-            readOnlyHint: z.ZodOptional<z.ZodBoolean>;
-            destructiveHint: z.ZodOptional<z.ZodBoolean>;
-            idempotentHint: z.ZodOptional<z.ZodBoolean>;
-            openWorldHint: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strip>>;
-        execution: z.ZodOptional<z.ZodObject<{
-            taskSupport: z.ZodOptional<z.ZodEnum<{
-                optional: "optional";
-                required: "required";
-                forbidden: "forbidden";
-            }>>;
-        }, z.core.$strip>>;
-        _meta: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodUnknown>>;
-        icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            src: z.ZodString;
-            mimeType: z.ZodOptional<z.ZodString>;
-            sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            theme: z.ZodOptional<z.ZodEnum<{
-                light: "light";
-                dark: "dark";
-            }>>;
-        }, z.core.$strip>>>;
-        name: z.ZodString;
-        title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-    resources: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        uri: z.ZodString;
-        description: z.ZodOptional<z.ZodString>;
-        mimeType: z.ZodOptional<z.ZodString>;
-        annotations: z.ZodOptional<z.ZodObject<{
-            audience: z.ZodOptional<z.ZodArray<z.ZodEnum<{
-                user: "user";
-                assistant: "assistant";
-            }>>>;
-            priority: z.ZodOptional<z.ZodNumber>;
-            lastModified: z.ZodOptional<z.ZodISODateTime>;
-        }, z.core.$strip>>;
-        _meta: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
-        icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            src: z.ZodString;
-            mimeType: z.ZodOptional<z.ZodString>;
-            sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            theme: z.ZodOptional<z.ZodEnum<{
-                light: "light";
-                dark: "dark";
-            }>>;
-        }, z.core.$strip>>>;
-        name: z.ZodString;
-        title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-    prompts: z.ZodOptional<z.ZodArray<z.ZodObject<{
-        description: z.ZodOptional<z.ZodString>;
-        arguments: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            name: z.ZodString;
-            description: z.ZodOptional<z.ZodString>;
-            required: z.ZodOptional<z.ZodBoolean>;
-        }, z.core.$strip>>>;
-        _meta: z.ZodOptional<z.ZodObject<{}, z.core.$loose>>;
-        icons: z.ZodOptional<z.ZodArray<z.ZodObject<{
-            src: z.ZodString;
-            mimeType: z.ZodOptional<z.ZodString>;
-            sizes: z.ZodOptional<z.ZodArray<z.ZodString>>;
-            theme: z.ZodOptional<z.ZodEnum<{
-                light: "light";
-                dark: "dark";
-            }>>;
-        }, z.core.$strip>>>;
-        name: z.ZodString;
-        title: z.ZodOptional<z.ZodString>;
-    }, z.core.$strip>>>;
-}, z.core.$loose>;
-export type ServerCard = z.infer<typeof ServerCardSchema>;

package/dist/bundle/server-card.js

@@ -1,16 +0,0 @@
-import { ImplementationSchema, PromptSchema, ResourceSchema, ToolSchema, } from "@modelcontextprotocol/sdk/types.js";
-import { z } from "zod";
-export const ServerCardSchema = z
-    .object({
-    serverInfo: ImplementationSchema,
-    authentication: z
-        .object({
-        required: z.boolean(),
-        schemes: z.array(z.string()),
-    })
-        .optional(),
-    tools: z.array(ToolSchema).optional(),
-    resources: z.array(ResourceSchema).optional(),
-    prompts: z.array(PromptSchema).optional(),
-})
-    .passthrough();