Content
# 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)
MCP Store