MCP Hello World - MCP Server Mock for Testing

This is a minimal Model Context Protocol (MCP) server implemented in TypeScript, primarily intended to serve as a Test Double / Mock Server.

Core Purpose: To provide a lightweight, controllable, and predictable MCP server environment for unit testing or integration testing client code that needs to interact with an MCP server.

Note: This project is not suitable for production environments or deployment as a general-purpose MCP server.

Why Use mcp-hello-world in Tests?

When testing code related to MCP clients, you usually don't want to depend on a real, potentially complex, and unpredictably responsive AI backend service. Using mcp-hello-world as a test double offers several advantages:

1. Isolation: Focus your tests on client logic without worrying about network issues or the availability of the real server.
2. Predictability: The provided echo and debug tools have simple, fixed behaviors, making it easy to write assertions.
3. Speed: Fast startup and response times, suitable for frequent use in unit tests.
4. Lightweight: Few dependencies, easy to integrate into test environments.
5. Protocol Coverage: Supports both STDIO and HTTP/SSE MCP transport protocols, allowing you to test client behavior under different connection methods.

Installation

Add this package as a dev dependency to your project:

# Using pnpm
pnpm add --save-dev mcp-hello-world

# Or using bun
bun add --dev mcp-hello-world

Manual Execution (for Debugging Tests)

You might want to run the server manually sometimes to debug your tests or client behavior.

STDIO Mode

This is the simplest way to run, especially during local development and debugging.

# Ensure it's installed (globally or in the project)
# Using npx (universal)
npx mcp-hello-world

# Or using pnpm dlx
pnpm dlx mcp-hello-world

# Or using bunx
bunx mcp-hello-world

The server will listen on standard input and output MCP responses to standard output. You can use tools like MCP Inspector to connect to the process.

To configure this server in your MCP client, add the following to your configuration:

{
  "mcpServers": {
    "mcp-hello-world": {
      "command": "npx",
      "args": ["mcp-hello-world"]
    }
  }
}

HTTP/SSE Mode

If you need to debug via a network interface or test HTTP-based MCP clients.

# 1. Clone the repository (if not already installed in the project)
# git clone https://github.com/lobehub/mcp-hello-world.git
# cd mcp-hello-world
# pnpm install / bun install