Toy MCP server implemented with the official MCP Python SDK.

## Overview

This project implements a **toy Model Context Protocol (MCP) server** using Anthropic's official Python SDK `mcp` ([PyPI](https://pypi.org/project/mcp/), [docs.claude.com](https://docs.claude.com/en/docs/mcp)).

It exposes two tools:

- **random_animal**: returns a random animal from a predefined list of 10 animals.
- **roll_d20**: returns a random integer simulating a roll of a 20-sided die (1–20).

The server is:

- **MCP-native** – built using `FastMCP` from the official SDK, implementing tools according to the MCP spec ([docs.claude.com](https://docs.claude.com/en/docs/mcp)).
- **Stateless and simple** – suitable as a toy reference server.
- **Flexible on transport** – can be run over stdio, streamable HTTP, or SSE using the `mcp` CLI.

## Installation

From the project root:

```bash
uv sync
```

If you are not using `uv`, you can install dependencies with:

```bash
pip install -e .
```

This will install the `mcp[cli]` SDK, which provides the MCP runtime and developer tooling.

You should also have **Claude Desktop** installed if you want to register this server as a Claude MCP connector, as described in the MCP docs ([docs.claude.com](https://docs.claude.com/en/docs/mcp)).

## Running the MCP server

The recommended way to run this server is via the `mcp` CLI, which understands MCP transports and discovers the `FastMCP` instance defined in `main.py`.

### Dev mode (MCP Inspector / stdio)

From the project root:

```bash
uv run mcp dev main.py
```

This runs the server in **development mode** (stdio transport) and opens the MCP Inspector, where you can:

- Inspect the server’s declared tools.
- Manually invoke `random_animal` and `roll_d20`.

Under the hood:

- `uv run` ensures the `mcp` CLI runs inside this project’s environment (with the right `mcp` version from [PyPI](https://pypi.org/project/mcp/)).
- `mcp dev main.py` starts your server as a subprocess over **stdio** and connects an MCP Inspector client to it.

### Direct execution

You can also run the server directly (for example, to integrate with a custom MCP client over stdio or another supported transport):

```bash
python main.py
```

This calls `mcp.run()` on the `FastMCP` instance defined in `main.py`, starting an MCP server loop using the SDK’s defaults.

This is useful for:

- Custom MCP clients that you write yourself.
- Simple testing of the server process and logging without the inspector.

Note that **direct execution does not automatically register** the server with Claude Desktop; it just runs the MCP server.

## Registering the server with Claude Desktop

Once Claude Desktop is installed, you can register this MCP server so Claude can discover and launch it automatically.

From the project root, run:

```bash
uv run mcp install main.py
```

What this does conceptually:

- Inspects `main.py` to find the `FastMCP` server.
- Prompts you (if needed) for details like the **server name** and **command**.
- Writes a **small manifest/config entry** into Claude Desktop’s MCP configuration directory (a per-user config location), telling Claude:
  - “This server exists and is named e.g. `Toy MCP Server`.”
  - “To start it, run: `python <path-to-your-project>/main.py` (with the proper environment).”

Importantly:

- **Your code is not copied or reinstalled**; it stays in your project folder.
- The “install” step only creates metadata so Claude Desktop knows how to launch the existing script as an MCP server.

After running `mcp install`:

1. Restart Claude Desktop (if it was open).
2. Open its settings/preferences and navigate to the **MCP / Tools / Servers** section.
3. You should see this server listed (with the name you chose); enable it if needed.
4. Claude will now spawn the server process on demand and call the tools (`random_animal`, `roll_d20`) via MCP.

## Example tool usage (conceptual)

The MCP client (e.g. Claude Desktop, MCP Inspector, or a custom MCP client) will discover and call tools using the MCP protocol rather than raw HTTP endpoints.

- **List tools** – the client inspects the server’s declared tools (`random_animal`, `roll_d20`) via MCP’s capabilities and tool metadata, similar to the examples in the MCP docs ([docs.claude.com](https://docs.claude.com/en/docs/mcp)).
- **Call `random_animal`** – the client sends an MCP tool invocation with no arguments and receives a string result like `"tiger"`.
- **Call `roll_d20`** – the client sends an MCP tool invocation with no arguments and receives an integer result between 1 and 20.

## Integrating with a local LLM (e.g. Claude Desktop, LM Studio)

Because this server is MCP-native, the **ideal** integration path is with MCP-aware clients (e.g. Claude Desktop, Claude Code, MCP Inspector) that speak the protocol directly as described in the MCP docs ([docs.claude.com](https://docs.claude.com/en/docs/mcp)).

For **LM Studio** or other local LLM runtimes that don’t yet natively support MCP, you can:

- Run this MCP server (via stdio or HTTP/SSE using the SDK’s transports).
- Write a **thin adapter** that acts as:
  - An MCP client on one side (talking to this server via the `mcp` Python SDK).
  - A tool/callout provider on the other side (using whatever HTTP or plugin mechanism LM Studio exposes; see e.g. [this overview of LM Studio](https://www.windowscentral.com/artificial-intelligence/ditch-ollama-and-use-lm-studio-for-local-ai-if-you-have-a-laptop-or-mini-pc)).

That way you keep this project focused purely on the MCP server, while still being able to integrate it into your local LLM workflow.

# License

GNU AFFERO GENERAL PUBLIC LICENSE
Version 3, 19 November 2007