Improve all readmes (#188)
* Improve all readmes * Address some of the comments
This commit is contained in:
Alex Akimov
GitHub
parent
f26c52eab4
commit
9395583c49
11 changed files with 358 additions and 23 deletions
72
README.md
72
README.md
|
|
@ -1,9 +1,71 @@
|
|||
# Quickstart Resources
|
||||
# MCP Quickstart Resources
|
||||
|
||||
A repository of servers and clients from the following Model Context Protocol tutorials:
|
||||
- [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) – a simple MCP weather server
|
||||
- [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) – an LLM-powered chatbot MCP client
|
||||
Example servers and clients for the [Model Context Protocol](https://modelcontextprotocol.io) (MCP), in five languages. These are companion examples for two official tutorials:
|
||||
|
||||
## Security Note
|
||||
- [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) – a simple MCP weather server exposing two tools backed by the US National Weather Service API
|
||||
- [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) – an LLM-powered chatbot MCP client that connects to any stdio server and lets Claude call its tools
|
||||
|
||||
## What's in this repository
|
||||
|
||||
Each example lives in its own directory with its own README covering prerequisites, setup, and how to run it:
|
||||
|
||||
| Language | Weather server (MCP server) | Chatbot (MCP client) |
|
||||
|------------|------------------------------------------------------------|----------------------------------------------------|
|
||||
| Python | [`weather-server-python`](./weather-server-python) | [`mcp-client-python`](./mcp-client-python) |
|
||||
| TypeScript | [`weather-server-typescript`](./weather-server-typescript) | [`mcp-client-typescript`](./mcp-client-typescript) |
|
||||
| Go | [`weather-server-go`](./weather-server-go) | [`mcp-client-go`](./mcp-client-go) |
|
||||
| Rust | [`weather-server-rust`](./weather-server-rust) | [`mcp-client-rust`](./mcp-client-rust) |
|
||||
| Ruby | [`weather-server-ruby`](./weather-server-ruby) | [`mcp-client-ruby`](./mcp-client-ruby) |
|
||||
|
||||
All servers communicate over stdio and expose the same two tools: `get_forecast` and `get_alerts` (or `get-forecast` and `get-alerts` in TypeScript).
|
||||
|
||||
All clients accept a path to a server to launch, list its tools, and start an interactive chat loop in which Claude can call those tools.
|
||||
|
||||
Note: These example clients need an `ANTHROPIC_API_KEY` to operate. Without a key, each client still connects and lists the server's tools before exiting, so you can verify the MCP wiring without credentials.
|
||||
|
||||
You can mix and match across languages: for example, the Python client can drive the TypeScript server. Each client's README lists which server launch forms it supports.
|
||||
|
||||
The [`tests`](./tests) directory contains the smoke tests that run in CI against these examples. See [`tests/README.md`](./tests/README.md) for how they work.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
Each example only needs its own language toolchain. To work across the whole repository (for example, to run the smoke tests) you need:
|
||||
|
||||
- **Node.js** 24+ and **npm**
|
||||
- **Python** 3.10+ and **uv**
|
||||
- **Go** 1.25+
|
||||
- **Rust** stable and **Cargo**
|
||||
- **Ruby** 3.4+ and **Bundler**
|
||||
|
||||
## Running the tests
|
||||
|
||||
```bash
|
||||
./tests/smoke-test.sh
|
||||
```
|
||||
|
||||
The smoke tests verify that every server starts and answers MCP requests (including validating structured tool results against the schemas each tool advertises), and that the Python, TypeScript, and Ruby clients can connect to a mock server and list tools. They run automatically on every pull request via GitHub Actions.
|
||||
|
||||
## Contributing
|
||||
|
||||
Contributions are welcome. To submit a change:
|
||||
|
||||
1. Fork the repository and create a branch from `main`.
|
||||
2. Make your change. Keep the examples minimal - they exist to teach the protocol, not to be production services.
|
||||
3. If you change an example's behavior, setup, or dependencies, update that example's README to match.
|
||||
4. Run `./tests/smoke-test.sh` and make sure it passes.
|
||||
5. Open a pull request against `main` describing what changed and why.
|
||||
|
||||
A few conventions to follow, in line with the broader [Model Context Protocol contributing guidelines](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CONTRIBUTING.md):
|
||||
|
||||
- **Keep documentation clear, concise, and technically accurate.** Include code examples where appropriate, and test the commands and links you add.
|
||||
- **Disclose AI assistance.** If you used any kind of AI assistance to prepare your contribution, say so in the pull request.
|
||||
- **Keep commit messages about the change**, not the tooling used to make it.
|
||||
- **Be respectful.** This project follows the MCP community's [Code of Conduct](https://github.com/modelcontextprotocol/modelcontextprotocol/blob/main/CODE_OF_CONDUCT.md). Concerns can be reported to mcp-coc@anthropic.com.
|
||||
|
||||
## Security note
|
||||
|
||||
These examples are intentionally minimal. If you expose an MCP server over a network (HTTP/SSE/WebSocket), add authentication and basic hardening (CORS allowlist, request size limits, timeouts, rate limits, and log redaction). See [`SECURITY.md`](./SECURITY.md).
|
||||
|
||||
## License
|
||||
|
||||
This repository is licensed under the [MIT License](./LICENSE).
|
||||
|
|
|
|||
|
|
@ -1,6 +1,40 @@
|
|||
# An LLM-Powered Chatbot MCP Client written in Go
|
||||
|
||||
See the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial for more information.
|
||||
An interactive chatbot MCP client: it launches an MCP server over stdio, lists its tools, and hands them to Claude, which can call them while answering your questions.
|
||||
|
||||
This example accompanies the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Go 1.25+
|
||||
- An [Anthropic API key](https://console.anthropic.com/) (optional — see below)
|
||||
|
||||
## Setup
|
||||
|
||||
Put your API key in a `.env` file (or export `ANTHROPIC_API_KEY` in your shell — the `.env` file is optional):
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# then edit .env and add your key
|
||||
```
|
||||
|
||||
## Run the client
|
||||
|
||||
Pass the command that starts the server — a binary or an interpreter plus its arguments:
|
||||
|
||||
```bash
|
||||
go run main.go ../weather-server-go/weather
|
||||
```
|
||||
|
||||
(Build the server first with `go build -o weather` in its directory.) Any server command works, for example the Python server:
|
||||
|
||||
```bash
|
||||
go run main.go uv --directory ../weather-server-python run weather.py
|
||||
```
|
||||
|
||||
Type a question (for example, "What's the weather in Sacramento?") and Claude answers using the server's tools. Type `quit` to exit.
|
||||
|
||||
Without an `ANTHROPIC_API_KEY`, the client still connects, prints the server's tools, and exits — useful for verifying the MCP wiring without credentials.
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,41 @@
|
|||
# An LLM-Powered Chatbot MCP Client written in Python
|
||||
|
||||
See the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial for more information.
|
||||
An interactive chatbot MCP client: it launches an MCP server over stdio, lists its tools, and hands them to Claude, which can call them while answering your questions.
|
||||
|
||||
This example accompanies the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.10+
|
||||
- [uv](https://docs.astral.sh/uv/)
|
||||
- An [Anthropic API key](https://console.anthropic.com/) (optional — see below)
|
||||
|
||||
## Setup
|
||||
|
||||
Put your API key in a `.env` file (or export `ANTHROPIC_API_KEY` in your shell):
|
||||
|
||||
```bash
|
||||
cp .env.example .env
|
||||
# then edit .env and add your key
|
||||
```
|
||||
|
||||
## Run the client
|
||||
|
||||
Pass the path to a server script. `.py` servers are launched with `uv`, `.js` servers with `node`:
|
||||
|
||||
```bash
|
||||
uv run client.py ../weather-server-python/weather.py
|
||||
```
|
||||
|
||||
or, against the TypeScript server (build it first — see its README):
|
||||
|
||||
```bash
|
||||
uv run client.py ../weather-server-typescript/build/index.js
|
||||
```
|
||||
|
||||
Type a question (for example, "What's the weather in Sacramento?") and Claude answers using the server's tools. Type `quit` to exit.
|
||||
|
||||
Without an `ANTHROPIC_API_KEY`, the client still connects, prints the server's tools, and exits — useful for verifying the MCP wiring without credentials.
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,36 @@
|
|||
# An LLM-Powered Chatbot MCP Client written in Ruby
|
||||
|
||||
See the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial for more information.
|
||||
An interactive chatbot MCP client: it launches an MCP server over stdio, lists its tools, and hands them to Claude, which can call them while answering your questions.
|
||||
|
||||
This example accompanies the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Ruby 3.4+ (3.3 also satisfies the gems)
|
||||
- Bundler
|
||||
- An [Anthropic API key](https://console.anthropic.com/) (optional — see below)
|
||||
|
||||
## Setup
|
||||
|
||||
Install the gems, then put your API key in a `.env` file (or export `ANTHROPIC_API_KEY` in your shell):
|
||||
|
||||
```bash
|
||||
bundle install
|
||||
cp .env.example .env
|
||||
# then edit .env and add your key
|
||||
```
|
||||
|
||||
## Run the client
|
||||
|
||||
Pass the path to a server script. `.rb` servers are launched with `ruby`, `.py` with `python3`, and `.js` with `node`:
|
||||
|
||||
```bash
|
||||
bundle exec ruby client.rb ../weather-server-ruby/weather.rb
|
||||
```
|
||||
|
||||
Type a question (for example, "What's the weather in Sacramento?") and Claude answers using the server's tools. Type `quit` to exit.
|
||||
|
||||
Without an `ANTHROPIC_API_KEY`, the client still connects, prints the server's tools, and exits — useful for verifying the MCP wiring without credentials.
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,35 @@
|
|||
# An LLM-Powered Chatbot MCP Client written in Rust
|
||||
|
||||
See the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial for more information.
|
||||
An interactive chatbot MCP client: it launches an MCP server over stdio, lists its tools, and hands them to Claude, which can call them while answering your questions.
|
||||
|
||||
This example accompanies the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rust (stable) and Cargo
|
||||
- An [Anthropic API key](https://console.anthropic.com/) (optional — see below)
|
||||
|
||||
## Setup
|
||||
|
||||
Export your API key, or put it in a `.env` file in this directory (the `.env` file is optional):
|
||||
|
||||
```bash
|
||||
export ANTHROPIC_API_KEY=your-api-key-here
|
||||
```
|
||||
|
||||
## Run the client
|
||||
|
||||
Pass the command that starts the server — a binary or a script — after `--`:
|
||||
|
||||
```bash
|
||||
cargo run -- ../weather-server-rust/target/release/weather
|
||||
```
|
||||
|
||||
(Build the server first with `cargo build --release` in its directory.)
|
||||
|
||||
Type a question (for example, "What's the weather in Sacramento?") and Claude answers using the server's tools. Type `quit` to exit.
|
||||
|
||||
Without an `ANTHROPIC_API_KEY`, the client still connects, prints the server's tools, and exits — useful for verifying the MCP wiring without credentials.
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,39 @@
|
|||
# An LLM-Powered Chatbot MCP Client written in TypeScript
|
||||
|
||||
See the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial for more information.
|
||||
An interactive chatbot MCP client: it launches an MCP server over stdio, lists its tools, and hands them to Claude, which can call them while answering your questions.
|
||||
|
||||
This example accompanies the [Build an MCP client](https://modelcontextprotocol.io/docs/develop/build-client) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 24+
|
||||
- npm
|
||||
- An [Anthropic API key](https://console.anthropic.com/) (optional — see below)
|
||||
|
||||
## Setup
|
||||
|
||||
Install dependencies and build, then put your API key in a `.env` file (or export `ANTHROPIC_API_KEY` in your shell):
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
cp .env.example .env
|
||||
# then edit .env and add your key
|
||||
```
|
||||
|
||||
## Run the client
|
||||
|
||||
Pass the path to a server script — `.js` servers are launched with `node`, `.py` servers with `python` (or `python3`, depending on the platform):
|
||||
|
||||
```bash
|
||||
node build/index.js ../weather-server-typescript/build/index.js
|
||||
```
|
||||
|
||||
(Build the server first — see its README.)
|
||||
|
||||
Type a question (for example, "What's the weather in Sacramento?") and Claude answers using the server's tools. Type `quit` to exit.
|
||||
|
||||
Without an `ANTHROPIC_API_KEY`, the client still connects, prints the server's tools, and exits — useful for verifying the MCP wiring without credentials.
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,22 +1,29 @@
|
|||
# A Simple MCP Weather Server written in Go
|
||||
|
||||
See the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial for more information.
|
||||
A minimal MCP server that exposes US weather data from the [National Weather Service API](https://www.weather.gov/documentation/services-web-api) as two tools:
|
||||
|
||||
## Building
|
||||
- `get_forecast` – get the forecast for a location (takes `latitude` and `longitude`)
|
||||
- `get_alerts` – get active weather alerts for a US state (takes a two-letter state code)
|
||||
|
||||
This example accompanies the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Go 1.25+
|
||||
|
||||
## Build and run
|
||||
|
||||
```bash
|
||||
go build -o weather
|
||||
```
|
||||
|
||||
## Running
|
||||
|
||||
```bash
|
||||
./weather
|
||||
```
|
||||
|
||||
The server will communicate via stdio and expose two MCP tools:
|
||||
- `get_forecast` - Get weather forecast for a location (requires latitude and longitude)
|
||||
- `get_alerts` - Get weather alerts for a US state (requires two-letter state code)
|
||||
The server communicates over stdio, so running it directly just waits for a client on stdin. To see it in action, launch it from one of the client examples in this repository, for example:
|
||||
|
||||
```bash
|
||||
cd ../mcp-client-go
|
||||
go run main.go ../weather-server-go/weather
|
||||
```
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,31 @@
|
|||
# A Simple MCP Weather Server written in Python
|
||||
|
||||
See the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial for more information.
|
||||
A minimal MCP server that exposes US weather data from the [National Weather Service API](https://www.weather.gov/documentation/services-web-api) as two tools:
|
||||
|
||||
- `get_forecast` – get the forecast for a location (takes `latitude` and `longitude`)
|
||||
- `get_alerts` – get active weather alerts for a US state (takes a two-letter state code)
|
||||
|
||||
This example accompanies the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Python 3.10+
|
||||
- [uv](https://docs.astral.sh/uv/)
|
||||
|
||||
## Run the server
|
||||
|
||||
```bash
|
||||
uv run weather.py
|
||||
```
|
||||
|
||||
`uv run` creates the virtual environment and installs dependencies on first use.
|
||||
|
||||
The server communicates over stdio, so running it directly just waits for a client on stdin. To see it in action, launch it from one of the client examples in this repository, for example:
|
||||
|
||||
```bash
|
||||
cd ../mcp-client-python
|
||||
uv run client.py ../weather-server-python/weather.py
|
||||
```
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,31 @@
|
|||
# A Simple MCP Weather Server written in Ruby
|
||||
|
||||
See the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial for more information.
|
||||
A minimal MCP server that exposes US weather data from the [National Weather Service API](https://www.weather.gov/documentation/services-web-api) as two tools:
|
||||
|
||||
- `get_forecast` – get the forecast for a location (takes `latitude` and `longitude`)
|
||||
- `get_alerts` – get active weather alerts for a US state (takes a two-letter state code)
|
||||
|
||||
This example accompanies the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Ruby 3.4+ (3.3 also satisfies the gems)
|
||||
- Bundler
|
||||
|
||||
## Setup and run
|
||||
|
||||
```bash
|
||||
bundle install
|
||||
bundle exec ruby weather.rb
|
||||
```
|
||||
|
||||
The server communicates over stdio, so running it directly just waits for a client on stdin. To see it in action, launch it from the Ruby client example in this repository:
|
||||
|
||||
```bash
|
||||
cd ../mcp-client-ruby
|
||||
bundle install
|
||||
bundle exec ruby client.rb ../weather-server-ruby/weather.rb
|
||||
```
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,35 @@
|
|||
# A Simple MCP Weather Server written in Rust
|
||||
|
||||
See the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial for more information.
|
||||
A minimal MCP server that exposes US weather data from the [National Weather Service API](https://www.weather.gov/documentation/services-web-api) as two tools:
|
||||
|
||||
- `get_forecast` – get the forecast for a location (takes `latitude` and `longitude`)
|
||||
- `get_alerts` – get active weather alerts for a US state (takes a two-letter state code)
|
||||
|
||||
This example accompanies the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Rust (stable) and Cargo
|
||||
|
||||
## Build and run
|
||||
|
||||
```bash
|
||||
cargo build --release
|
||||
./target/release/weather
|
||||
```
|
||||
|
||||
Or, during development:
|
||||
|
||||
```bash
|
||||
cargo run
|
||||
```
|
||||
|
||||
The server communicates over stdio, so running it directly just waits for a client on stdin. To see it in action, launch it from one of the client examples in this repository, for example:
|
||||
|
||||
```bash
|
||||
cd ../mcp-client-rust
|
||||
cargo run -- ../weather-server-rust/target/release/weather
|
||||
```
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
|
|
@ -1,6 +1,32 @@
|
|||
# A Simple MCP weather Server written in TypeScript
|
||||
# A Simple MCP Weather Server written in TypeScript
|
||||
|
||||
See the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial for more information.
|
||||
A minimal MCP server that exposes US weather data from the [National Weather Service API](https://www.weather.gov/documentation/services-web-api) as two tools:
|
||||
|
||||
- `get-forecast` – get the forecast for a location (takes `latitude` and `longitude`)
|
||||
- `get-alerts` – get active weather alerts for a US state (takes a two-letter state code)
|
||||
|
||||
This example accompanies the [Build an MCP server](https://modelcontextprotocol.io/docs/develop/build-server) tutorial.
|
||||
|
||||
## Prerequisites
|
||||
|
||||
- Node.js 24+
|
||||
- npm
|
||||
|
||||
## Build and run
|
||||
|
||||
```bash
|
||||
npm install
|
||||
npm run build
|
||||
node build/index.js
|
||||
```
|
||||
|
||||
The server communicates over stdio, so running it directly just waits for a client on stdin. To see it in action, launch it from one of the client examples in this repository, for example:
|
||||
|
||||
```bash
|
||||
cd ../mcp-client-typescript
|
||||
npm install && npm run build
|
||||
node build/index.js ../weather-server-typescript/build/index.js
|
||||
```
|
||||
|
||||
## Structured content
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue