mcp-hello-world

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

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

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:

{
  "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):

{
  "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 to inject secrets:

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 - LangChain basics
• 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/