diff --git a/packages/sdk/README.md b/packages/sdk/README.md index 06bc3b3..4dbd076 100644 --- a/packages/sdk/README.md +++ b/packages/sdk/README.md @@ -179,6 +179,8 @@ await client.close(); ### `StitchProxy` +For a more advanced example of building a custom MCP server with compound tools, see the [MCP Server Example](./examples/mcp-server/README.md). + An MCP proxy server that forwards requests to Stitch. Use this to expose Stitch tools through your own MCP server. ```ts @@ -297,4 +299,4 @@ Program](https://bughunters.google.com/open-source-security). ## License -Apache 2.0 — see [LICENSE](LICENSE) for details. \ No newline at end of file +Apache 2.0 — see [LICENSE](LICENSE) for details. diff --git a/packages/sdk/examples/mcp-server/README.md b/packages/sdk/examples/mcp-server/README.md new file mode 100644 index 0000000..52da61d --- /dev/null +++ b/packages/sdk/examples/mcp-server/README.md @@ -0,0 +1,44 @@ +# MCP Server Example + +This example demonstrates how to wrap the Stitch SDK (`@google/stitch-sdk`) into an MCP server that exposes compound tools. + +## Why Compound Tools? + +The raw Stitch MCP tools are granular (e.g., generate a screen, fetch HTML). Agents often need to perform multiple steps to get a usable result. Compound tools reduce round-trips by combining these steps on the server side. + +For example, `generate_and_extract` generates a screen, fetches the HTML, extracts the Tailwind theme and body, and returns them in one call. + +## Prerequisites + +- `STITCH_API_KEY` environment variable must be set. +- Install dependencies: `bun install` + +## Running the Server + +Since this is an MCP server, it communicates over stdio. You can run it directly: + +```bash +bun index.ts +``` + +Then type a JSON-RPC request like: + +```json +{"jsonrpc": "2.0", "id": 1, "method": "tools/list"} +``` + +Or configure it in an MCP client (like Claude Desktop) with the command: + +```json +{ + "mcpServers": { + "stitch-design": { + "command": "bun", + "args": ["run", "/path/to/packages/sdk/examples/mcp-server/index.ts"], + "env": { + "STITCH_API_KEY": "your-api-key" + } + } + } +} +``` diff --git a/packages/sdk/examples/mcp-server/SKILL.md b/packages/sdk/examples/mcp-server/SKILL.md new file mode 100644 index 0000000..0c81d19 --- /dev/null +++ b/packages/sdk/examples/mcp-server/SKILL.md @@ -0,0 +1,30 @@ +# Skill: Using the Stitch Design MCP Server + +This skill demonstrates how to expose the Stitch SDK as an MCP server with compound tools that combine multiple Stitch operations into single calls. + +## Overview + +The Stitch SDK provides granular tools (e.g., generate a screen, fetch HTML, edit a screen). While powerful, agents often need compound tools to reduce round-trips. + +This MCP server exposes compound tools like: +- `generate_and_extract`: Generates a screen and returns the extracted Tailwind theme, HTML body, and screenshot URL in a single call. +- `compare_themes`: Generates variants and diffs their configs. +- `scaffold_project`: Generates multiple screens and returns them as a page manifest. + +## Usage + +This is a standard MCP server running over stdio. + +1. Ensure `STITCH_API_KEY` is set in your environment. +2. Run the server using an MCP client (e.g., Claude Desktop, Cursor, or another agent): +```bash +bun run packages/sdk/examples/mcp-server/index.ts +``` + +## Example: `generate_and_extract` + +When you call `generate_and_extract` with `{ "projectId": "...", "prompt": "..." }`, the server will: +1. Call `project.generate(prompt)` to create the screen. +2. Fetch the HTML content. +3. Parse the HTML to extract the Tailwind `