README - Hello World MCP Server by madhukarkumar

Hello World MCP Server

A simple Model Context Protocol (MCP) server implementation built with TypeScript. This server demonstrates basic MCP functionality including resources, prompts, and tools.

Features

SSE and STDIO transport support
Resource handling with static and dynamic resources
Sample prompt implementation
Example tool that echoes messages
Debug tool for server introspection

Getting Started

Prerequisites

Node.js (v16 or higher)
npm or yarn

Installation

npm install

Build

npm run build

Running the Server

HTTP/SSE Transport (Web Browsers)

npm run start:http

This starts the server on http://localhost:3000 with:

SSE endpoint at /sse
Message endpoint at /messages

STDIO Transport (Command Line)

npm run start

This runs the server in stdio mode for command-line integrations.

Testing the Server

Testing with cURL

Start the HTTP server:
```
npm run start:http
```

In a terminal window, connect to the SSE endpoint:

curl -N http://localhost:3000/sse

You should see a response like:

event: endpoint
data: /messages?sessionId=YOUR_SESSION_ID

In another terminal window, send a request to invoke the echo tool:

curl -X POST \
  "http://localhost:3000/messages?sessionId=YOUR_SESSION_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "tools/invoke",
    "params": {
      "name": "echo",
      "parameters": {
        "message": "Testing the MCP server!"
      }
    }
  }'

You should see a response in the SSE terminal window:

event: message
data: {"jsonrpc":"2.0","id":1,"result":{"content":[{"type":"text","text":"Hello Testing the MCP server!"}]}}

Try the debug tool to see available server methods:

curl -X POST \
  "http://localhost:3000/messages?sessionId=YOUR_SESSION_ID" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 2,
    "method": "tools/invoke",
    "params": {
      "name": "debug",
      "parameters": {}
    }
  }'

Testing with MCP Inspector

For a visual interface, you can use the MCP Inspector tool:

Connect to http://localhost:3000/sse in the MCP Inspector
Browse available resources and tools
Invoke tools interactively

MCP Inspector HTTP Mode

MCP Inspector STDIO Mode

Server API

Resources

hello://world - A static hello world resource
greeting://{name} - A dynamic greeting with a name parameter

Tools

echo - Echoes back a message with "Hello" prefix
debug - Lists all available tools and methods

Prompts

helpful-assistant - A basic helpful assistant prompt

Troubleshooting

If you get "Headers already sent" errors, make sure you're not manually setting headers
Session ID handling is crucial for proper message routing
Check the server console for debugging information

License

MIT