From e4646dccdef68656ff1a7d06663463d5ffc4420d Mon Sep 17 00:00:00 2001 From: Jonathan Hefner Date: Wed, 18 Feb 2026 14:42:04 -0600 Subject: [PATCH] Update `README.md` and `docs/faq.md` to link full quickstart guides Now that the server and client quickstart tutorials have been imported, update the README and FAQ to funnel newcomers to them. The README "Quick Start" section is replaced with a "Getting Started" section that shows an inline code snippet, links the two quickstart tutorials, and demotes the advanced examples to a secondary mention. The "Documentation" section is flattened into a single list with updated URLs. The FAQ answer for "Where can I find runnable server examples?" now points to `server-quickstart.md` first. Co-Authored-By: Claude Opus 4.6 (1M context) --- README.md | 74 ++++++++++++++++++++++++----------------------------- docs/faq.md | 2 +- 2 files changed, 35 insertions(+), 41 deletions(-) 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?