diff --git a/README.md b/README.md index f108c30ea..d9abb4610 100644 --- a/README.md +++ b/README.md @@ -14,7 +14,7 @@ - [Overview](#overview) - [Packages](#packages) - [Installation](#installation) -- [Quick Start (runnable examples)](#quick-start-runnable-examples) +- [Getting Started](#getting-started) - [Documentation](#documentation) - [Contributing](#contributing) - [License](#license) @@ -90,59 +90,53 @@ npm install @modelcontextprotocol/express express npm install @modelcontextprotocol/hono hono ``` -## Quick Start (runnable examples) +## Getting Started -The runnable examples live under `examples/` and are kept in sync with the docs. +Here is what an MCP server looks like. This minimal example exposes a single `greet` tool over stdio: -1. **Install dependencies** (from repo root): +```typescript +import { McpServer, StdioServerTransport } from '@modelcontextprotocol/server'; +import * as z from 'zod/v4'; -```bash -pnpm install -``` - -2. **Run a Streamable HTTP example server**: - -```bash -pnpm --filter @modelcontextprotocol/examples-server exec tsx src/simpleStreamableHttp.ts -``` +const server = new McpServer({ name: 'greeting-server', version: '1.0.0' }); -Alternatively, from within the example package: +server.registerTool( + 'greet', + { + description: 'Greet someone by name', + inputSchema: z.object({ name: z.string() }), + }, + async ({ name }) => ({ + content: [{ type: 'text', text: `Hello, ${name}!` }], + }), +); -```bash -cd examples/server -pnpm tsx src/simpleStreamableHttp.ts -``` - -3. **Run the interactive client in another terminal**: +async function main() { + const transport = new StdioServerTransport(); + await server.connect(transport); +} -```bash -pnpm --filter @modelcontextprotocol/examples-client exec tsx src/simpleStreamableHttp.ts +main(); ``` -Alternatively, from within the example package: +Ready to build something real? Follow the step-by-step quickstart tutorials: -```bash -cd examples/client -pnpm tsx src/simpleStreamableHttp.ts -``` +- [Build a weather server](docs/server-quickstart.md) — server quickstart +- [Build an LLM-powered chatbot](docs/client-quickstart.md) — client quickstart -Next steps: +The complete code for each tutorial is in [`examples/server-quickstart/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/server-quickstart/) and [`examples/client-quickstart/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/client-quickstart/). For more advanced runnable examples, see: -- Server examples index: [`examples/server/README.md`](examples/server/README.md) -- Client examples index: [`examples/client/README.md`](examples/client/README.md) -- Guided walkthroughs: [`docs/server.md`](docs/server.md) and [`docs/client.md`](docs/client.md) +- [`examples/server/README.md`](examples/server/README.md) — server examples index +- [`examples/client/README.md`](examples/client/README.md) — client examples index ## Documentation -- Local SDK docs: - - [docs/server.md](docs/server.md) – building MCP servers: transports, tools, resources, prompts, server-initiated requests, and deployment - - [docs/client.md](docs/client.md) – building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling - - [docs/faq.md](docs/faq.md) – frequently asked questions and troubleshooting -- External references: - - [SDK API documentation](https://ts.sdk.modelcontextprotocol.io/) - - [Model Context Protocol documentation](https://modelcontextprotocol.io) - - [MCP Specification](https://spec.modelcontextprotocol.io) - - [Example Servers](https://github.com/modelcontextprotocol/servers) +- [Server Guide](docs/server.md) — building MCP servers: transports, tools, resources, prompts, server-initiated requests, and deployment +- [Client Guide](docs/client.md) — building MCP clients: connecting, tools, resources, prompts, server-initiated requests, and error handling +- [FAQ](docs/faq.md) — frequently asked questions and troubleshooting +- [API docs](https://modelcontextprotocol.github.io/typescript-sdk/) +- [MCP documentation](https://modelcontextprotocol.io/docs) +- [MCP specification](https://modelcontextprotocol.io/specification/latest) ### Building docs locally diff --git a/docs/faq.md b/docs/faq.md index e0a898c9a..7755b9606 100644 --- a/docs/faq.md +++ b/docs/faq.md @@ -67,7 +67,7 @@ For production use, you can either: ### Where can I find runnable server examples? -The SDK ships several runnable server examples under `examples/server/src`. Start from the server examples index in [`examples/server/README.md`](../examples/server/README.md) and the entry-point quick start in the root [`README.md`](../README.md). +The [server quickstart](./server-quickstart.md) walks you through building a weather server from scratch. Its complete source lives in [`examples/server-quickstart/`](https://github.com/modelcontextprotocol/typescript-sdk/tree/main/examples/server-quickstart/). For more advanced examples (OAuth, streaming, sessions, etc.), see the server examples index in [`examples/server/README.md`](../examples/server/README.md). ### Why did we remove `server` auth exports?