# hello-mcp

A minimal MCP server built as a learning exercise. Uses the Streamable HTTP transport and demonstrates the core MCP primitives: tools and resources.

## What is MCP?

The [Model Context Protocol](https://modelcontextprotocol.io) (MCP) is an open standard for connecting AI models to external data and capabilities. An MCP server exposes three types of primitives:

| Primitive | Purpose | Initiated by |
|---|---|---|
| **Tools** | Do things (side effects allowed) | The model |
| **Resources** | Expose data (read-only) | The client/user |
| **Prompts** | Reusable prompt templates | The client/user |

## Project Structure

```
src/
  server.js            # Entry point — HTTP transport
  stdio.js             # Entry point — stdio transport (Claude Desktop)
  mcp.js               # MCP server + tool/resource registration
  data/
    greetings.js       # Shared data (language → greeting mapping)
  tools/
    helloWorld.js      # No-input tool
    helloName.js       # Tool with a required string input
    greetName.js       # Tool with error handling and MCP logging
    listLanguages.js   # Tool that exposes the languages list to the model
  resources/
    languages.js       # Static resource exposing available languages
```

## Transport: Streamable HTTP

This server uses the `StreamableHTTPServerTransport` from `@modelcontextprotocol/sdk`. It runs as a plain Node.js HTTP server and handles MCP messages at `POST /mcp`.

Key details:
- Runs in **stateless mode** (`sessionIdGenerator: undefined`) — each request gets a fresh transport instance
- The client must send `Accept: application/json, text/event-stream` or the server will reject with 406
- The transport handles both JSON responses and SSE streams depending on the request

## Tools

Tools are registered with `server.registerTool(name, config, handler)`.

- `config.description` — shown to the model so it knows when to use the tool
- `config.inputSchema` — a plain object of Zod fields; the SDK wraps it in `z.object()` automatically
- Input is **validated at the transport layer** before the handler is called — invalid input returns `-32602` without ever reaching your code

### hello_world
No inputs. Always returns `"Hello, World!"`.

### hello_name
Takes a required `name` string. Returns `"Hello, {name}!"`.

### greet_name
Takes a `name` string and a `language` string. Returns a greeting in the specified language, or an `isError` response if the language isn't supported. Uses `sendLoggingMessage` to emit info, warning, and debug log messages through the MCP protocol — visible in the MCP Inspector notifications panel.

### list_languages
No inputs. Returns the list of supported languages. Useful for Claude Desktop where resources aren't surfaced to the model — the model can call this tool to discover valid options when `greet_name` returns an error.

## Resources

Resources are registered with `server.registerResource(name, uri, config, reader)`.

- Each resource has a **URI** (e.g. `languages://list`) that the client uses to fetch it
- The reader returns `{ contents: [{ uri, text }] }`
- Resources are read-only — no side effects

### languages://list
Returns a JSON array of supported language keys. Backed by the same `greetings.js` data used by the `greet_name` tool.

## Running the Server

### HTTP Streaming (MCP Inspector, remote clients)

```bash
npm install
npm start
```

The MCP endpoint will be available at `http://localhost:3000/mcp`.

To run on a different port:

```bash
PORT=3001 npm start
```

### stdio (Claude Desktop)

Claude Desktop spawns the process itself — no server needs to be running beforehand. Add the following to `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hello-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/hello-mcp/src/stdio.js"]
    }
  }
}
```

Quit and relaunch Claude Desktop after editing the config. Check **Claude menu → Settings → Developer** to confirm the server shows a green dot.

## Testing with MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```

Open the Inspector in **Chrome** (not Brave — its privacy settings block localhost requests), set the transport to **Streamable HTTP**, and enter `http://localhost:3000/mcp`.

You can also test with raw curl:

```bash
curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/list",
    "params": {}
  }'
```

## Key Lessons

- **Multiple transports, one server** — `mcp.js` is transport-agnostic; `server.js` (HTTP) and `stdio.js` (stdio) are separate entry points that both import the same server instance
- **Separation of concerns** — `server.js` owns the HTTP transport, `mcp.js` owns the MCP server, each tool/resource lives in its own file
- **Single source of truth** — shared data in `src/data/` is imported by both tools and resources; no duplication
- **Zod validation is free** — defining an `inputSchema` gives you automatic input validation before your handler runs
- **`registerTool` over `tool`** — the `tool()` method is deprecated; `registerTool()` uses a cleaner config object pattern
- **Stateless vs stateful** — stateless mode is simpler and sufficient for most use cases; stateful mode adds session tracking via `sessionIdGenerator`
- **Factory pattern for server-dependent handlers** — handlers that need to call `server.sendLoggingMessage()` can't import `server` directly (circular dependency). Instead, export a `createHandler(server)` factory that closes over the server instance and returns the handler function. `mcp.js` calls `createHandler(server)` at registration time.
- **`isError: true` vs throwing** — returning `isError: true` sends the error text back to the model as readable tool output it can reason about; throwing produces a protocol-level JSON-RPC error the model can't see
- **MCP logging** — `server.sendLoggingMessage({ level, message })` sends log messages through the MCP protocol to the client; visible in MCP Inspector's notifications panel
- **Resources vs tools in Claude Desktop** — Claude Desktop doesn't surface resources to the model; expose the same data as a tool if the model needs to access it