{"id":11274,"library":"mcp-hello-world","title":"MCP Hello World Server Simulator","description":"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.","status":"active","version":"1.1.2","language":"javascript","source_language":"en","source_url":"https://github.com/lobehub/mcp-hello-world","tags":["javascript","lobehub","model-context-protocol","sdk","typescript"],"install":[{"cmd":"npm install mcp-hello-world","lang":"bash","label":"npm"},{"cmd":"yarn add mcp-hello-world","lang":"bash","label":"yarn"},{"cmd":"pnpm add mcp-hello-world","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Peer dependency for projects using React, although not directly consumed by the server simulator itself. Likely due to its ecosystem context.","package":"react","optional":false},{"reason":"Peer dependency for projects using React, although not directly consumed by the server simulator itself. Likely due to its ecosystem context.","package":"react-dom","optional":false}],"imports":[{"note":"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.","symbol":"MCPHelloWorld","correct":"import * as MCPHelloWorld from 'mcp-hello-world'"},{"note":"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.","symbol":"spawn","correct":"import { spawn } from 'child_process'"},{"note":"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.","symbol":"ChildProcess","correct":"import type { ChildProcess } from 'child_process'"}],"quickstart":{"code":"import { spawn } from 'child_process';\n// Assume './my-mcp-client' is your custom client implementation\n// that connects to stdin/stdout streams.\nimport { MCPClient } from './my-mcp-client'; \n\ndescribe('My MCP Client (STDIO mode)', () => {\n  let mcpServerProcess: ReturnType<typeof spawn>;\n  let client: MCPClient; // Assume MCPClient accepts Readable/Writable streams\n\n  beforeAll(() => {\n    // Start mcp-hello-world as a child process in STDIO mode\n    mcpServerProcess = spawn('npx', ['mcp-hello-world']);\n\n    // Instantiate your client and connect it to the spawned process's stdio streams\n    client = new MCPClient(mcpServerProcess.stdin, mcpServerProcess.stdout);\n\n    // Optional: Log server output for debugging purposes\n    mcpServerProcess.stdout.on('data', (data) => console.log(`MCP Server STDOUT: ${data}`));\n    mcpServerProcess.stderr.on('data', (data) => console.error(`MCP Server STDERR: ${data}`));\n  });\n\n  afterAll(() => {\n    // Ensure the server process is terminated after all tests are done\n    if (mcpServerProcess) {\n      mcpServerProcess.kill();\n    }\n  });\n\n  it('should receive an echo response from the mock server', async () => {\n    const request = {\n      jsonrpc: '2.0',\n      id: 1,\n      method: 'tools/invoke',\n      params: { name: 'echo', parameters: { message: 'hello test' } }\n    };\n\n    // Assuming client.sendRequest handles JSON-RPC messaging over streams\n    const response = await client.sendRequest(request);\n\n    expect(response).toEqual({\n      jsonrpc: '2.0',\n      id: 1,\n      result: { content: [{ type: 'text', text: 'Hello hello test' }] }\n    });\n  });\n});","lang":"typescript","description":"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."},"warnings":[{"fix":"Always use a robust, production-ready MCP server for live applications. Limit `mcp-hello-world` to development and testing environments only.","message":"This 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"},{"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.","message":"The 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.","severity":"gotcha","affected_versions":">=1.0.0"}],"env_vars":null,"last_verified":"2026-04-19T00:00:00.000Z","next_check":"2026-07-18T00:00:00.000Z","problems":[{"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.","cause":"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.","error":"Error: spawn npx ENOENT"},{"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.","cause":"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.","error":"ERR_STREAM_WRITE_AFTER_END"},{"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.","cause":"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.","error":"Error: connect ECONNREFUSED 127.0.0.1:3000"}],"ecosystem":"npm"}