A minimal MCP server mock in TypeScript for testing MCP clients, supporting both STDIO and HTTP/SSE protocols.
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.
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:
echo
and debug
tools have simple, fixed behaviors, making it easy to write assertions.STDIO
and HTTP/SSE
MCP transport protocols, allowing you to test client behavior under different connection methods.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
You might want to run the server manually sometimes to debug your tests or client behavior.
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"]
}
}
}
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
# 2. Build the project
# Using pnpm
pnpm build
# Or using bun
bun run build
# 3. Start the HTTP server
# Using pnpm
pnpm start:http
# Or using bun
bun run start:http
The server will start on http://localhost:3000
and provide:
/sse
/messages
You can programmatically start and stop the mcp-hello-world
server within your test framework (like Jest, Vitest, Mocha, etc.) for automated testing.
// test/my-mcp-client.test.ts (Example using Jest)
import { spawn } from 'child_process';
import { MCPClient } from '../src/my-mcp-client'; // Assuming this is your client code
describe('My MCP Client (STDIO)', () => {
let mcpServerProcess;
let client: MCPClient;
beforeAll(() => {
// Start the mcp-hello-world process before tests
// Using npx (or pnpm dlx / bunx) ensures the command is found and executed
mcpServerProcess = spawn('npx', ['mcp-hello-world']);
// Instantiate your client and connect to the subprocess's stdio
client = new MCPClient(mcpServerProcess.stdin, mcpServerProcess.stdout);
});
afterAll(() => {
// Shut down the mcp-hello-world process after tests
mcpServerProcess.kill();
});
it('should receive echo response', async () => {
const request = {
jsonrpc: '2.0',
id: 1,
method: 'tools/invoke',
params: { name: 'echo', parameters: { message: 'test message' } },
};
const response = await client.sendRequest(request); // Assuming your client has this method
expect(response).toEqual({
jsonrpc: '2.0',
id: 1,
result: { content: [{ type: 'text', text: 'Hello test message' }] },
});
});
it('should get greeting resource', async () => {
const request = {
jsonrpc: '2.0',
id: 2,
method: 'resources/get',
params: { uri: 'greeting://Alice' },
};
const response = await client.sendRequest(request);
expect(response).toEqual({
jsonrpc: '2.0',
id: 2,
result: { data: 'Hello Alice!' }, // Confirm return format based on actual implementation
});
});
// ... other test cases
});
For HTTP/SSE, you might need to:
exec
or spawn
in beforeAll
to start pnpm start:http
or bun run start:http
.axios
, node-fetch
, or your test framework's built-in client) to connect to http://localhost:3000/sse
and /messages
for testing.afterAll
.mcp-hello-world
provides the following fixed capabilities for interaction and assertion in your tests:
hello://world
resources/get
{ data: 'Hello World!' }
greeting://{name}
resources/get
name
included in the URI, e.g., greeting://Bob
.{ data: 'Hello {name}!' }
(e.g., { data: 'Hello Bob!' }
)echo
tools/invoke
{ name: 'echo', parameters: { message: string } }
{ content: [{ type: 'text', text: 'Hello {message}' }] }
(e.g., { content: [{ type: 'text', text: 'Hello test' }] }
)debug
tools/invoke
{ name: 'debug', parameters: {} }
helpful-assistant
prompts/get
system
and user
roles.MIT
Obtains latest dependency details for Clojure libraries.
MCP server empowers LLMs to interact with JSON files efficiently. With JSON MCP, you can split, merge, etc.
A secure command-line interface server for the Model Context Protocol (MCP) that allows AI models to interact with a user's terminal.
Converts OpenAPI/Swagger specifications to Model Context Protocol (MCP) format, providing a modern Web UI and a backend service.
Gentoro generates MCP Servers based on OpenAPI specifications.
An MCP server for the gget bioinformatics library, enabling standardized access to genomics tools and databases.
Integrates with the Stability AI API for image generation, editing, and upscaling.
A natural language interface for biological activities analysis using the decoupler tool.
Performs gene set enrichment analysis using the Enrichr API, supporting all available gene set libraries.
A demonstration tool showcasing potential security attack vectors against the Model Control Protocol (MCP).