MCP Hello World Server Simulator

Common errors

• Error: spawn npx ENOENT

  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.
  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

  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.
  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

  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.
  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.

Warnings

• gotcha 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.
  Fix: Always use a robust, production-ready MCP server for live applications. Limit `mcp-hello-world` to development and testing environments only.
• gotcha 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.
  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.
• gotcha 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.
  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.

Install

• npm install mcp-hello-world npm
• yarn add mcp-hello-world yarn
• pnpm add mcp-hello-world pnpm

Imports

• 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.

Quickstart

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' }] }
    });
  });
});