Registry / testing / mcp-hello-world

mcp-hello-world

JSON →
library1.1.2jsnpmunverified

mcp-hello-world is a minimalist Model Context Protocol (MCP) server simulation, primarily designed as a test double or mock server for client-side unit and integration testing. Implemented in TypeScript, it offers a lightweight, predictable, and isolated environment for verifying MCP client logic without relying on real, complex, or potentially slow AI backend services. It currently stands at version 1.1.2 (released April 2025) with a recent cadence of small patches. Key differentiators include its support for both STDIO and HTTP/SSE MCP transport protocols, enabling comprehensive client testing across different connection methods. It provides simple `echo` and `debug` tools for predictable behavior, ensuring fast and reliable test execution. This package is explicitly *not* intended for production deployments or as a general-purpose MCP server.

npm install mcp-hello-world
INSTALL
IMPORT
SIG · MCP-HELLO-WORLD
M
mcp-hello-world
testingjavascriptv1.1.2
Install
Import
Disk
Pass rate
0/ 6
Env Coverage0 / 6
glibc
1822
musl
1822
Install & Compatibility
Where this runs
tested against v? · npm install
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
musl
node 18226 runs
build_error
glibc
node 18226 runs
build_error
Code
Verified usage

Verified import paths — ran on the pinned version, not inferred.

MCPHelloWorld
import * as MCPHelloWorld from 'mcp-hello-world'
While this package ships TypeScript types, its primary usage pattern is as a command-line executable spawned as a child process (e.g., via `npx mcp-hello-world` or `child_process.spawn`). Direct programmatic import of a server instance is not explicitly documented, but this illustrates a general module import.
spawn
import { spawn } from 'child_process'
The `spawn` function from Node.js's `child_process` module is essential for programmatically starting `mcp-hello-world` as a separate process in test environments, as demonstrated in the official documentation examples for testing.
ChildProcess
import type { ChildProcess } from 'child_process'
TypeScript type for the object returned by `child_process.spawn`, useful for managing the lifecycle (e.g., `kill()`) of the `mcp-hello-world` server process within your test setup.

Demonstrates how to programmatically start `mcp-hello-world` as a child process in STDIO mode within a test suite (e.g., Jest) and interact with it to verify a custom MCP client implementation.

import { spawn } from 'child_process'; // Assume './my-mcp-client' is your custom client implementation // that connects to stdin/stdout streams. import { MCPClient } from './my-mcp-client'; describe('My MCP Client (STDIO mode)', () => { let mcpServerProcess: ReturnType<typeof spawn>; let client: MCPClient; // Assume MCPClient accepts Readable/Writable streams beforeAll(() => { // Start mcp-hello-world as a child process in STDIO mode mcpServerProcess = spawn('npx', ['mcp-hello-world']); // Instantiate your client and connect it to the spawned process's stdio streams client = new MCPClient(mcpServerProcess.stdin, mcpServerProcess.stdout); // Optional: Log server output for debugging purposes mcpServerProcess.stdout.on('data', (data) => console.log(`MCP Server STDOUT: ${data}`)); mcpServerProcess.stderr.on('data', (data) => console.error(`MCP Server STDERR: ${data}`)); }); afterAll(() => { // Ensure the server process is terminated after all tests are done if (mcpServerProcess) { mcpServerProcess.kill(); } }); it('should receive an echo response from the mock server', async () => { const request = { jsonrpc: '2.0', id: 1, method: 'tools/invoke', params: { name: 'echo', parameters: { message: 'hello test' } } }; // Assuming client.sendRequest handles JSON-RPC messaging over streams const response = await client.sendRequest(request); expect(response).toEqual({ jsonrpc: '2.0', id: 1, result: { content: [{ type: 'text', text: 'Hello hello test' }] } }); }); });
Debug
Known issues
gotchaThis package is explicitly designed as a 'test double' or 'mock server' and is not suitable for production deployments or as a general-purpose Model Context Protocol (MCP) server. Using it outside of a controlled testing environment is unsupported and may lead to unexpected behavior or security issues.
fix
Always use a robust, production-ready MCP server for live applications. Limit `mcp-hello-world` to development and testing environments only.
affects: >=1.0.0
gotchaThe primary method of interacting with `mcp-hello-world` programmatically is by spawning it as a child process (e.g., using `child_process.spawn('npx', ['mcp-hello-world'])`) rather than direct JavaScript module imports. Developers expecting a programmatic API with `import { Server } from 'mcp-hello-world'` might find this unconventional.
fix
Follow the documentation's examples for using `child_process.spawn` to manage the server's lifecycle within your test setup. Be mindful of process management (killing the child process) in `afterAll` hooks to prevent resource leaks.
affects: >=1.0.0
gotchaThe package lists `react` and `react-dom` as peer dependencies. This is unusual for a server-side test utility and might cause unnecessary dependency warnings or conflicts in projects that don't use React, or use different versions.
fix
Ensure your project satisfies the `react` and `react-dom` peer dependency range, or be prepared to address npm/yarn warnings. For test environments where these are not strictly needed by `mcp-hello-world` itself, you might choose to ignore these warnings or install compatible versions.
affects: >=1.0.0
Errors
Common errors & fixes
Error: spawn npx ENOENT
The `npx` command (or `pnpm dlx`/`bunx`) is not found in the system's PATH, or the Node.js environment is not correctly configured or accessible.
fix
Ensure Node.js and npm/pnpm/bun are correctly installed and their executables are available in your system's PATH. For CI/CD environments, verify the Node.js environment setup steps.
ERR_STREAM_WRITE_AFTER_END
Attempting to write data to the `mcp-hello-world` child process's `stdin` stream after the stream has been closed, often because the server process exited prematurely or was explicitly killed.
fix
Before sending data to the server, ensure the `mcp-hello-world` child process is still alive and its `stdin` stream is writable. Review your test lifecycle hooks to confirm processes are started before and terminated correctly after interaction.
Error: connect ECONNREFUSED 127.0.0.1:3000
An attempt was made to connect to the HTTP/SSE server (which defaults to port 3000) when it was not running, was running in STDIO mode, or was listening on a different port.
fix
Verify that `mcp-hello-world` is started in HTTP/SSE mode (e.g., using `pnpm start:http`) and that your client is configured to connect to the correct `localhost:3000` endpoint. Check for potential port conflicts with other applications.
Upgrade
Version history
1.1.2latest on npm
Audit
Dependencies
reactrequiredPeer dependency for projects using React, although not directly consumed by the server simulator itself. Likely due to its ecosystem context.
react-domrequiredPeer dependency for projects using React, although not directly consumed by the server simulator itself. Likely due to its ecosystem context.
Agent activity
4 hits · last 30 days
node
4
Resources
mcp-hello-world — npm install mcp-hello-world · libregistry