smithery-ai · glassBead-tc · Aug 7, 2025
diff --git a/sdk/getting-started.mdx b/sdk/getting-started.mdx
@@ -0,0 +1,212 @@
+---
+title: "Getting Started with Smithery SDK"
+description: "Build your first MCP client and server with the Smithery SDK"
+---
+
+This guide walks you through creating both an MCP client and server using the Smithery SDK.
+
+## Prerequisites
+
+- Node.js 18 or higher
+- npm or yarn
+- A Smithery account (for deployment)
+
+## Project Setup
+
+Create a new directory and initialize your project:
+
+```bash
+mkdir my-mcp-project
+cd my-mcp-project
+npm init -y
+npm install @smithery/sdk @modelcontextprotocol/sdk express zod
+npm install -D @types/node typescript tsx
+```
+
+## Building an MCP Server
+
+### 1. Basic Server Structure
+
+Create `src/server.ts`:
+
+```typescript
+import { createStatefulServer } from "@smithery/sdk"
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js"
+import { z } from "zod"
+
+// Optional: Define configuration schema
+export const configSchema = z.object({
+  apiKey: z.string().describe("API key for external service"),
+  maxRetries: z.number().default(3).describe("Maximum retry attempts"),
+})
+
+// Server factory function - called for each new session
+function createMcpServer({ sessionId, config }: { 
+  sessionId: string
+  config: z.infer<typeof configSchema> 
+}) {
+  console.log(`Creating server for session: ${sessionId}`)
+
+  const server = new Server({
+    name: "my-mcp-server",
+    version: "1.0.0"
+  }, {
+    capabilities: {
+      tools: {}
+    }
+  })
+
+  // List available tools
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "add_numbers",
+        description: "Add two numbers together",
+        inputSchema: {
+          type: "object",
+          properties: {
+            a: { type: "number", description: "First number" },
+            b: { type: "number", description: "Second number" }
+          },
+          required: ["a", "b"]
+        }
+      }
+    ]
+  }))
+
+  // Handle tool calls
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (request.params.name === "add_numbers") {
+      const { a, b } = request.params.arguments as { a: number; b: number }
+      const result = a + b
+
+      return {
+        content: [
+          {
+            type: "text",
+            text: `${a} + ${b} = ${result}`
+          }
+        ]
+      }
+    }
+
+    throw new Error(`Unknown tool: ${request.params.name}`)
+  })
+
+  return server
+}
+
+// Create and start the stateful server
+const { app } = createStatefulServer(createMcpServer, {
+  schema: configSchema // Optional: validates config on each request
+})
+
+const PORT = process.env.PORT || 3000
+app.listen(PORT, () => {
+  console.log(`MCP server running on port ${PORT}`)
+})
+```
+
+### 2. Run the Server
+
+```bash
+npx tsx src/server.ts
+```
+
+Your server is now running at `http://localhost:3000/mcp`
+
+## Building an MCP Client
+
+### 1. Create the Client
+
+Create `src/client.ts`:
+
+```typescript
+import { createTransport } from "@smithery/sdk"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+
+async function main() {
+  // Create transport with configuration
+  const transport = createTransport("http://localhost:3000", {
+    config: {
+      apiKey: "test-key",
+      maxRetries: 5
+    }
+  })
+
+  // Initialize client
+  const client = new Client({
+    name: "my-mcp-client",
+    version: "1.0.0"
+  }, {
+    capabilities: {}
+  })
+
+  try {
+    // Connect to server
+    await client.connect(transport)
+    console.log("Connected to server!")
+
+    // List available tools
+    const tools = await client.listTools()
+    console.log("Available tools:", tools)
+
+    // Call a tool
+    const result = await client.callTool("add_numbers", {
+      a: 5,
+      b: 3
+    })
+    console.log("Result:", result)
+  } catch (error) {
+    console.error("Error:", error)
+  } finally {
+    await client.close()
+  }
+}
+
+main().catch(console.error)
+```
+
+### 2. Run the Client
+
+```bash
+# In another terminal
+npx tsx src/client.ts
+```
+
+## Next Steps
+
+Now that you have a basic client and server running:
+
+1. **Add More Tools**: Extend your server with additional capabilities
+2. **Use AI SDK Integration**: Connect your MCP tools to LLMs
+3. **Deploy to Smithery**: Share your server with others
+4. **Add Authentication**: Secure your server with API keys
+
+<CardGroup>
+  <Card
+    title="Server Patterns"
+    icon="server"
+    href="/sdk/server"
+  >
+    Learn about stateful vs stateless servers
+  </Card>
+  <Card
+    title="Configuration"
+    icon="cog"
+    href="/sdk/configuration"
+  >
+    Add configuration validation
+  </Card>
+  <Card
+    title="AI Integration"
+    icon="robot"
+    href="/sdk/integrations/ai-sdk"
+  >
+    Connect to Vercel AI SDK
+  </Card>
+</CardGroup>
diff --git a/sdk/index.mdx b/sdk/index.mdx
@@ -0,0 +1,148 @@
+---
+title: "Smithery SDK"
+description: "Official TypeScript SDK for building and using MCP servers with Smithery"
+---
+
+## Installation
+
+```bash
+npm install @smithery/sdk @modelcontextprotocol/sdk
+```
+
+## Quick Start
+
+The Smithery SDK provides utilities for both MCP clients and servers, with built-in support for configuration, validation, and integrations.
+
+### Creating a Client
+
+```typescript
+import { createTransport } from "@smithery/sdk"
+import { Client } from "@modelcontextprotocol/sdk/client/index.js"
+
+// Create a transport to connect to a Smithery server
+const transport = createTransport("https://your-server.smithery.ai", {
+  apiKey: process.env.SMITHERY_API_KEY,
+  config: {
+    // Your server configuration
+    debug: true
+  }
+})
+
+// Initialize the MCP client
+const client = new Client({
+  name: "my-client",
+  version: "1.0.0"
+}, {
+  capabilities: {}
+})
+
+// Connect to the server
+await client.connect(transport)
+```
+
+### Creating a Server
+
+```typescript
+import { createStatefulServer } from "@smithery/sdk"
+import { Server } from "@modelcontextprotocol/sdk/server/index.js"
+
+// Define your server factory function
+function createMcpServer({ sessionId, config }) {
+  const server = new Server({
+    name: "my-server",
+    version: "1.0.0"
+  }, {
+    capabilities: {
+      tools: {}
+    }
+  })
+
+  // Add your tools, resources, etc.
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+      {
+        name: "hello",
+        description: "Say hello",
+        inputSchema: {
+          type: "object",
+          properties: {
+            name: { type: "string" }
+          }
+        }
+      }
+    ]
+  }))
+
+  return server
+}
+
+// Create the stateful server
+const app = createStatefulServer(createMcpServer)
+
+// Start listening
+app.listen(process.env.PORT || 3000)
+```
+
+## Core Concepts
+
+<CardGroup>
+  <Card
+    title="Client"
+    icon="plug"
+    href="/sdk/client"
+  >
+    Connect to MCP servers and use their capabilities
+  </Card>
+  <Card
+    title="Server"
+    icon="server"
+    href="/sdk/server"
+  >
+    Build stateful or stateless MCP servers
+  </Card>
+  <Card
+    title="Configuration"
+    icon="cog"
+    href="/sdk/configuration"
+  >
+    Validate and manage server configuration
+  </Card>
+  <Card
+    title="Integrations"
+    icon="puzzle-piece"
+    href="/sdk/integrations"
+  >
+    Integrate with AI SDKs and LLM providers
+  </Card>
+</CardGroup>
+
+## Key Features
+
+- **TypeScript-first**: Full type safety and IntelliSense support
+- **Session Management**: Built-in session stores for stateful servers
+- **Configuration Validation**: Zod schema validation for configs
+- **AI SDK Integration**: Works with Vercel AI SDK out of the box
+- **Express Compatible**: Built on Express for familiar patterns
+
+## API Reference
+
+### Client Utilities
+- [`createTransport`](/sdk/client/transport) - Create HTTP transports for MCP clients
+- [`createSmitheryUrl`](/sdk/client/connections) - Build properly formatted Smithery URLs (pass full URL with protocol)
+
+### Server Utilities  
+- [`createStatefulServer`](/sdk/server/stateful) - Stateful server with session management
+- [Stateless server patterns](/sdk/server/stateless) - Simple stateless server approach
+- [`createLRUStore`](/sdk/server/sessions) - LRU session store implementation
+
+### Configuration
+- [`parseAndValidateConfig`](/sdk/configuration/validation) - Validate configs with Zod
+- [`parseExpressRequestConfig`](/sdk/configuration/schemas) - Parse base64 configs
+
+### Integrations
+- [`watchTools`](/sdk/integrations/ai-sdk) - Vercel AI SDK tool integration
+- [`listTools`](/sdk/integrations/ai-sdk) - Convert MCP tools to AI SDK format
+- [`wrapError`](/sdk/integrations/ai-sdk#error-handling) - Wrap tool calls with error handling
+
+### Utilities
+- [`patch`](/sdk/utilities/patch) - Safely patch object methods with custom behavior