docs: improve main README with better quick start, include examples of stateless HTTP, explain tools v resources v prompts #980
Conversation
- Wrap TOC in collapsible details/summary tags to reduce initial scroll - Update quick start example to use streamable HTTP instead of stdio - Reorder overview to emphasize servers over clients - Move resources section after tools since tools are more commonly used - Add structured output examples to tool responses - Improve code examples with better formatting and comments - Add direct links to MCP clients (Inspector, Claude Code, VS Code, Cursor) - Clarify tool vs resource use cases - Remove redundant 'What is MCP?' section - Simplify stateless HTTP example with clearer comments
- Replace .tool() with .registerTool() in all example servers - Add outputSchema to all tool definitions - Add structuredContent to all tool responses - Align text content with structured output using JSON.stringify - Add title fields to all tools for better UI presentation
domdomegg
force-pushed
the
adamj/collapsible-toc
branch
from
0098151 to
996fc0b
Compare
domdomegg
changed the title
|
NB: failing CI is unrelated, see #981 |
README.md
Outdated
| ## Quick Start | ||
|
|
||
| Let's create a simple MCP server that exposes a calculator tool and some data: | ||
| Let's create a simple MCP server that exposes a calculator tool and some data. Save the following as `server.mjs`: |
There was a problem hiding this comment.
Why .mjs and not .ts? Shouldn't we be giving TypeScript based examples in our Readme?
There was a problem hiding this comment.
The SDK is written in TypeScript but works whether your underlying source code is standard JS or TypeScript.
For the sake of being able to get started very quickly (e.g. not have to set up a typescript toolchain) I suggested this. Happy to change and provide instructions for/link to getting set up with tsx or similar.
This is also valid TypeScript anyway, so people can copy paste from this directly into TypeScript anyway. It just doesn't use any type annotations as they're not needed here.
There was a problem hiding this comment.
Imo given it's a typescript SDK and people who'd want to work with it likely want to get up and running in a TS environment, I'd argue we should have the quickstart reflect that. Is it that much more complicated to provide a quick start with tsx?
We could optionally provide somewhere in the readme to set up with javascript, but I wouldn't make that the very first example here.
Change the quickstart example from JavaScript (.mjs) to TypeScript (.ts) and use npx tsx to run it directly without requiring a build step. 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude <[email protected]>
domdomegg
force-pushed
the
adamj/collapsible-toc
branch
from
1638750 to
220c6f8
Compare
Resolved conflicts by: - Keeping collapsible TOC from this branch - Keeping TypeScript/tsx approach from this branch (npx -y tsx) - Adopting main's stdio transport instead of HTTP for quickstart - Adopting main's content organization and improvements - Accepting all example server changes from main
domdomegg
force-pushed
the
adamj/collapsible-toc
branch
from
220c6f8 to
4be7ee0
Compare
This PR improves the README documentation:
<details>tags to reduce initial scroll lengthstructuredContentfieldThese changes make it easier for new users to get started with MCP and understand the key concepts.