# mcp-hello-world

A learning-focused MCP server that demonstrates how the Model Context Protocol works.

## What is MCP?

MCP (Model Context Protocol) is a standard that lets AI assistants like Claude use external tools. Think of it like a plugin system:

1. You build a **server** that offers tools
2. Claude connects to your server
3. Claude can now call your tools during conversations

This project is a minimal example with two tools that show a learning progression.

## What Does This Server Do?

It has two tools:

| Tool | Input | Output | Purpose |
|------|-------|--------|---------|
| `hello` | (none) | `world` | Minimal static example |
| `polyglot` | A greeting in any language | Structured JSON with language info | Shows LangChain + structured output |

The `hello` tool is intentionally simple - it's about understanding *how* MCP works. The `polyglot` tool builds on that by calling an external LLM.

## Project Structure

```text
mcp-hello-world/
├── src/
│   └── index.ts                      # The MCP server
├── docs/
│   ├── langchain-polyglot-tool.md    # LangChain basics
│   └── structured-output.md          # Structured output with Zod
├── dist/                             # Compiled JavaScript (generated by build)
├── package.json                      # Project dependencies
└── tsconfig.json                     # TypeScript configuration
```

## How to Build

```bash
npm install    # Install dependencies
npm run build  # Compile TypeScript to JavaScript
```

## How to Use With Claude

To connect this server to Claude, add it to your MCP configuration.

**For Claude Code (CLI):**

Add to `~/.claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "hello-world": {
      "command": "node",
      "args": ["/full/path/to/mcp-hello-world/dist/index.js"]
    }
  }
}
```

**For Claude Desktop App:**

Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):

```json
{
  "mcpServers": {
    "hello-world": {
      "command": "node",
      "args": ["/full/path/to/mcp-hello-world/dist/index.js"]
    }
  }
}
```

After adding the configuration, restart Claude. The `hello` tool will be available.

## How MCP Communication Works

```
┌─────────────────┐         ┌─────────────────┐
│                 │  stdin  │                 │
│     Claude      │────────▶│   MCP Server    │
│                 │◀────────│                 │
│                 │ stdout  │                 │
└─────────────────┘         └─────────────────┘
```

1. Claude launches the server as a subprocess
2. Claude sends JSON messages to the server via stdin
3. The server processes requests and sends responses via stdout
4. This back-and-forth follows the MCP protocol specification

## Key Concepts

### Server
The main object that manages everything. It:
- Registers available tools
- Handles incoming requests
- Routes tool calls to handler functions

### Tool
A function that Claude can call. Each tool has:
- **Name**: How Claude identifies it (e.g., "hello")
- **Description**: Helps Claude know when to use it
- **Parameters**: What inputs it accepts (our tool has none)
- **Handler**: The code that runs when called

### Transport
How the server communicates. We use `StdioServerTransport` which means:
- Input comes from stdin
- Output goes to stdout
- Claude runs the server as a subprocess

This is the standard approach for local MCP servers.

## The Polyglot Tool

The `polyglot` tool demonstrates LangChain's structured output feature. Send a greeting in any language, get back validated JSON with language details.

**Input:**
```text
"bonjour"
```

**Output:**
```json
{
  "detectedLanguage": "French",
  "greeting": "bonjour",
  "worldTranslation": "monde",
  "languageFamily": "Romance"
}
```

**Requirements:** The polyglot tool needs an `ANTHROPIC_API_KEY` environment variable. This project uses [Teller](https://github.com/tellerops/teller) to inject secrets:

```bash
teller run -- npm start
```

### Greetings for Testing

The `worldTranslation` field in the response:

| Language | Greeting | worldTranslation |
|----------|----------|-----------------|
| English | hello | world |
| Spanish | hola | mundo |
| French | bonjour | monde |
| German | hallo | Welt |
| Italian | ciao | mondo |
| Portuguese | olá | mundo |
| Japanese | こんにちは | 世界 |
| Korean | 안녕하세요 | 세계 |
| Chinese | 你好 | 世界 |
| Russian | привет | мир |
| Arabic | مرحبا | عالم |
| Hindi | नमस्ते | दुनिया |
| Dutch | hallo | wereld |
| Swedish | hej | värld |
| Greek | γεια | κόσμος |

For a deeper dive into how this tool works:
- [docs/langchain-polyglot-tool.md](docs/langchain-polyglot-tool.md) - LangChain basics
- [docs/structured-output.md](docs/structured-output.md) - Structured output with Zod validation

## Learning More

The `src/index.ts` file is heavily documented with explanations of each piece. Start there to understand the code.

For the full MCP specification: https://modelcontextprotocol.io/