mcp-server-hello-world

# MCP Server Hello World A lightweight NodeJS implementation of a Model Context Protocol (MCP) Hello World server for testing and development purposes. Inspired by [mcp-hello-world](https://github.com/lobehub/mcp-hello-world/), but much more lightweight (~17MB vs 1GB+). ## MCP Spec Compliance This server exists as a spec-exact test target for MCP **client** authors. It speaks both protocol generations: - **Complies with the [`2026-07-28`](https://modelcontextprotocol.io/specification/2026-07-28) spec revision** — the stateless generation — via per-request `_meta` versioning, `server/discover`, `resultType` on results, cacheable list/read results, and the Streamable HTTP transport. - Also speaks the **legacy handshake generation** (`2024-11-05` through `2025-11-25`): `initialize` negotiates `protocolVersion`, falling back to `2025-11-25`. Dual-stack during the deprecation window (legacy removal ~July 2027, 3.0.0). - Optional server features are deliberately **not** implemented or advertised: elicitation, sampling, roots, logging, tasks. Omitting optional capabilities is spec-conformant — the server advertises exactly what it supports. - Transports: **stdio** (all revisions), **Streamable HTTP** (`POST /mcp`, `2026-07-28`), and **HTTP+SSE** (`/sse` + `/messages`, the `2025-03-26` transport; deprecated by the spec, kept during the transition window). ## Features Resources, tools, and prompts — the full set of server primitives a client needs to exercise: - **Resources**: Static and dynamic data sources - `hello://world` - Returns "Hello World!" - `greeting://{name}` - Returns personalized greeting - **Tools**: Invokable functions - `echo` - Echoes input with "Hello " prefix - `debug` - Lists all available MCP capabilities - **Prompts**: Predefined conversation templates - `helpful-assistant` - Basic assistant prompt **Communication Modes**: - **STDIO**: Direct process communication for MCP clients - **Streamable HTTP** (`2026-07-28`): stateless `POST /mcp` with required `MCP-Method`/`MCP-Name`/`MCP-Protocol-Version` headers (starts at `http://localhost:3000`) - **HTTP+SSE**: Legacy transport (`2025-03-26`) — POST requests to a session-scoped `/messages` URL, responses delivered as SSE events on the `/sse` stream - `/health` - Health check endpoint - `/mcp` - Streamable HTTP MCP endpoint (POST; GET/DELETE return 405) - `/messages?sessionId=...` - HTTP POST endpoint for MCP messages (URL issued per session by the `/sse` `endpoint` event) - `/sse` - Server-Sent Events endpoint (legacy transport) Browser origins are rejected by default (DNS-rebinding protection). Set `MCP_ALLOWED_ORIGINS` (comma-separated) or `--allowed-origins` to allow browser clients; non-browser clients are unaffected. ## Installation ### As Development Dependency (Recommended) ```bash npm install --save-dev @trippnology/mcp-server-hello-world ``` ### Global Installation ```bash npm install -g @trippnology/mcp-server-hello-world ``` ## Quick Start ### Using npx (Easiest) ```bash # STDIO mode (default) npx @trippnology/mcp-server-hello-world # HTTP/SSE mode npx @trippnology/mcp-server-hello-world --mode http --port 3000 ``` ### As Dev Dependency ```bash # Via package.json scripts npm run mcp:stdio npm run mcp:http # Or directly ./node_modules/.bin/mcp-hello-world --mode stdio ./node_modules/.bin/mcp-hello-world --mode http --port 8080 ``` ### Global Installation ```bash mcp-hello-world --mode stdio mcp-hello-world --mode http --port 3000 ``` ### CLI Options - `--mode <stdio|http>` - Communication mode (default: stdio) - `--port <number>` - HTTP server port (default: 3000) - `--host <string>` - HTTP server host (default: localhost) - `--allowed-origins <origins>` - Comma-separated browser origins allowed via CORS / Origin validation (default: none) - `--verbose` - Enable verbose logging - `--version` - Show version - `--help` - Show help ### Package.json Integration Add these scripts to your `package.json` for easy testing: ```json { "scripts": { "mcp:stdio": "mcp-hello-world --mode stdio", "mcp:http": "mcp-hello-world --mode http --port 3001" } } ``` ## Testing ```bash npm test ``` ## Documentation For detailed API documentation, request/response examples, and implementation details, see [API.md](API.md). ## Contributing 1. Fork it! 2. Create your feature branch: `git checkout -b my-new-feature develop` 3. Commit your changes: `git commit -am 'Add some feature'` 4. Push to the branch: `git push origin my-new-feature` 5. Submit a pull request :D ## License MIT Copyright (c) 2025 Rikki Tripp - [Trippnology](https://trippnology.com)