# toy-mcp-server

A minimal [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server built from scratch to learn how MCP actually works — no boilerplate generators, no templates, just the SDK.

Built as a first hands-on MCP project: two tools and one resource, wired into Claude Desktop over stdio.

## What it does

MCP lets an LLM client (like Claude Desktop) call functions running on your own machine, instead of only generating text from its training data. This server exposes:

**Tools** (functions Claude can call):
- `roll_dice` — rolls N dice with a configurable number of sides
- `flip_coin` — flips a coin N times

**Resources** (read-only data Claude can fetch):
- `server-info` — basic metadata about the server (name, purpose, start time)

## Why this exists

LLMs can't access anything outside their own training data, and can't *do* anything by default — they only generate text. MCP is a standard way to give a model:
- **capability** it doesn't have on its own (e.g. true randomness — LLMs are notoriously bad at picking random numbers themselves)
- **access** to live or private data it has no way of knowing

This project is a small, safe sandbox for that idea before pointing an MCP server at something real (a database, an API with auth, etc.).

## Tech stack

- TypeScript
- [`@modelcontextprotocol/sdk`](https://www.npmjs.com/package/@modelcontextprotocol/sdk) — official MCP SDK
- [`zod`](https://www.npmjs.com/package/zod) — runtime schema validation for tool arguments
- stdio transport (local subprocess communication with Claude Desktop)

## Project structure

```
toy-mcp-server/
├── src/
│   └── index.ts       # server setup, tools, and resource
├── build/              # compiled output (git-ignored)
├── package.json
├── tsconfig.json
└── README.md
```

## Setup

### 1. Install dependencies

```bash
npm install
```

### 2. Build

```bash
npm run build
```

### 3. Connect to Claude Desktop

Find your Claude Desktop config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: usually under `%LOCALAPPDATA%\Packages\<Claude package folder>\LocalCache\Roaming\Claude\claude_desktop_config.json` — the exact path can vary by install method (Microsoft Store vs. direct installer). The reliable way to find it: open Claude Desktop → **Settings → Developer → Local MCP servers → Edit Config**, which opens the exact file the app reads.

Add this server under `mcpServers` (merge into the existing file rather than overwriting it):

```json
{
  "mcpServers": {
    "toy-mcp-server": {
      "command": "node",
      "args": ["/absolute/path/to/toy-mcp-server/build/index.js"]
    }
  }
}
```

Replace the path with the actual absolute path to `build/index.js` on your machine. On Windows, escape backslashes (`\\`) in the JSON string.

### 4. Restart Claude Desktop

Fully quit (not just close the window) and reopen. Check **Settings → Developer → Local MCP servers** to confirm `toy-mcp-server` shows as connected.

### 5. Try it

In a chat, ask:
- "Roll 3 six-sided dice"
- "Flip a coin 10 times"

You should see a small tool-call indicator (e.g. "Roll Dice") above the response, confirming Claude actually invoked the function rather than guessing an answer.

## How it works, briefly

- `McpServer` — the object that declares the server's capabilities to any connecting client
- `registerTool(name, config, handler)` — registers a callable function. `config.inputSchema` uses Zod to validate whatever arguments the model sends before the handler runs
- `registerResource(name, uri, config, handler)` — registers read-only data addressable by a URI, fetched without arguments
- `StdioServerTransport` — the wire format: Claude Desktop spawns this file as a subprocess and communicates over stdin/stdout using JSON-RPC. `console.log` is never used for logging here, since stdout is the actual protocol channel — `console.error` (stderr) is used instead

## Next steps

- Swap the toy tools for real ones hitting an actual database (Postgres via Prisma)
- Add a GitHub-backed tool (e.g. `list_open_prs`) to practice token-based auth
- Explore Streamable HTTP transport to host this remotely instead of running it locally

## License

MIT