@msfeldstein/mcp-test-servers

MCP Test Servers

A collection of test servers implementing the Model Context Protocol (MCP).

Development Setup

Node.js Version Management

This project includes an .nvmrc file that specifies the recommended Node.js version. To automatically use the correct Node.js version:

1. Make sure you have nvm (Node Version Manager) installed
2. Run nvm use manually when entering the project directory, or
3. Set up automatic version switching by sourcing the included auto-nvm.sh script in your shell profile:

# Add to your ~/.zshrc or ~/.bashrc
source /path/to/mcp-test-servers/auto-nvm.sh

This will automatically run nvm use whenever you change directories to a folder with an .nvmrc file.

Package Management

This project requires pnpm for package management. Always use pnpm instead of npm or yarn when working with this project.

# Install dependencies
pnpm install

# Run a script
pnpm run ping

# Add a dependency
pnpm add package-name

# Use a package without installing
pnpm dlx package-name

The .npmrc file in this project is configured to enforce pnpm for package management. Additionally, the auto-nvm.sh script automatically creates aliases that redirect npm and yarn commands to use pnpm instead when you're in this project directory.

Available Servers

• ping: A simple server that responds with 'pong'
• resource: Resource server implementation
• combined: Combined server implementation
• broken-tool: Server with intentionally broken tool
• crash-on-startup: Server that crashes on startup
• env-check: Server for environment checking
• env-echo: Server that echoes environment variables
• many-resources: Server with multiple resources
• duplicate-names: Server with duplicate name implementations
• image: Server for image handling
• big-response: Server that returns large responses
• date: Server for date operations
• time: Server that returns the current time in ISO format
• many-tools: Server with 100 tools that each return 'ack'
• named: Server with configurable name via MCP_SERVER_NAME environment variable
• bad-param: Server with an intentionally malformed parameter name
• stderr: Server that logs to stderr
• optional-param: Server with optional parameters
• all-types: Server that demonstrates various parameter types supported by MCP

Usage

To run a server, use:

pnpm dlx @msfeldstein/mcp-test-servers <server-type>

Example:

pnpm dlx @msfeldstein/mcp-test-servers time

For the named server, you can set a custom name using the MCP_SERVER_NAME environment variable:

MCP_SERVER_NAME="my-custom-server" pnpm dlx @msfeldstein/mcp-test-servers named

Server Details

Ping Server

The ping server provides a simple ping-pong interaction:

• Tool: ping
• Returns: "pong"
• No parameters required

Resource Server

The resource server provides a single text resource:

• Resource name: "Hello World Text"
• URI: "test://hello.txt"
• Content: "Hello, world"
• MIME type: "text/plain"

Combined Server

The combined server implements both tool and resource capabilities:

• Tool: ping - Returns "pong"
• Tool: fizzbuzz - Generates a FIZZY sequence up to the specified number
• Resource: "Hello World Text" - Same as resource server

Broken Tool Server

The broken tool server intentionally throws an error when the tool is called:

• Tool: crash
• Behavior: Throws an error with message "This tool is intentionally broken!"

Crash on Startup Server

This server crashes during initialization, useful for testing error handling.

Environment Check Server

The env-check server requires an environment variable to run:

• Environment variable: SHOULD_RUN=true (required)
• Tool: status
• Returns: "Server is running with SHOULD_RUN=true"

Environment Echo Server

The env-echo server returns all environment variables:

• Tool: echo_env
• Returns: A formatted list of all environment variables

Many Resources Server

The many-resources server provides multiple resources (600):

• Resources: "Resource 1" through "Resource 600"
• Each has unique content and URI

Duplicate Names Server

The duplicate-names server provides resources with duplicate names:

• Three sets of resources with names "Common Resource", "Duplicate File", and "Same Name Different Content"
• Each name has 3 versions with different content and URIs

Image Server

The image server provides an image resource:

• Tool: generate_image
• Returns: A red circle image in base64 format

Big Response Server

The big-response server can generate large responses:

• Tool: generate_big_response
• Parameter: stringLength - The length of the random string to generate
• Returns: A random string of the specified length

Date Server

The date server provides date operations:

• Tool: Provides date operations (details may vary)

Time Server

The time server provides a simple tool to get the current time:

• Tool: get-time
• Returns: Current time in ISO format
• No parameters required

Many Tools Server

The many tools server provides 100 simple tools:

• Tools: tool_1 through tool_100
• Each tool returns: 'ack'
• No parameters required

Named Server

The named server allows testing with custom server names:

• Tool: <server-name>_get_name (e.g., "my-custom-server_get_name")
• Returns: The server's configured name
• No parameters required
• Name can be set via MCP_SERVER_NAME environment variable
• Defaults to 'unnamed-server' if no name is provided

Bad Param Server

The bad-param server includes a tool with an incorrectly formed parameter name:

• Tool: bad-param
• Parameter: Has an invalid parameter name with special characters
• Useful for testing how clients handle malformed parameter definitions

Stderr Server

The stderr server demonstrates stderr logging:

• Tool: log-to-stderr
• Behavior: Logs a message to stderr while responding
• Returns: "Should have logged to stderr"
• No parameters required

Optional Param Server

The optional-param server demonstrates parameter optionality:

• Tool: echo
• Parameters:
  • name (required): The name of the caller
  • text (optional): The text to echo
• Returns: The provided text or "No message sent" if no text was provided

All Types Server

The all-types server demonstrates various parameter types supported by MCP:

• Tool: all_types_tool
• Parameters: Includes required and optional parameters covering string, integer, number (float), boolean, array (string, number), object (with nested types), and enum.
• Returns: A JSON string representation of the received parameters.
• Useful for testing client-side handling of different parameter types.