MCP Test Server

A comprehensive Model Context Protocol (MCP) server designed specifically for testing MCP scanners and validating MCP implementations. This server provides a rich set of tools, resources, and prompts to exercise various aspects of the MCP specification.

🔍 Scanner Compatible: This repository is fully configured to be detected by the APIsec MCP Audit Scanner.

⚡ Quick Start: Want to test scanner detection immediately? See QUICK_START.md

Scanner Detection Documentation

• QUICK_START.md - Get scanned in 10 minutes

• SCANNER_GUIDE.md - Detailed detection guide

• SCANNER_CHECKLIST.md - Verification checklist

Features

🛠️ Tools

The server exposes multiple tools with varying complexity levels:

• echo - Basic string echo for testing simple parameter handling

• add_numbers - Numeric operations testing

• format_json - JSON object handling and formatting

• list_operations - Array/list manipulation (sort, reverse, count, join)

• complex_schema - Nested object schemas with various types

• timestamp - Tools with optional parameters only

📦 Resources

Multiple resource types for testing resource discovery and reading:

• static-text - Plain text resource

• json-data - Structured JSON data

• markdown-doc - Formatted markdown documentation

• config - Configuration file example

💬 Prompts

Sample prompts to test prompt capabilities:

• test-prompt - Basic prompt with required argument

• debug-prompt - Multi-argument prompt with optional parameters

Installation

From Source

# Clone the repository
git clone <repository-url>
cd mcp-test

# Install the package
pip install .

Development Installation

# Install with development dependencies
pip install -e ".[dev]"

Usage

Running the Server

Command Line

After installation, run the server directly:

mcp-test-server

Python Module

Alternatively, run as a Python module:

python server.py

Testing with MCP Client

The server uses stdio transport, so you can test it with any MCP-compatible client:

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def test_mcp_server():
    server_params = StdioServerParameters(
        command="mcp-test-server",
        args=[],
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()
            
            # List available tools
            tools = await session.list_tools()
            print(f"Available tools: {[t.name for t in tools.tools]}")
            
            # Call a tool
            result = await session.call_tool("echo", {"message": "Hello MCP!"})
            print(f"Result: {result}")

if __name__ == "__main__":
    asyncio.run(test_mcp_server())

Configuration for MCP Clients

Add to your MCP client configuration (e.g., Claude Desktop config):

{
  "mcpServers": {
    "mcp-test": {
      "command": "mcp-test-server"
    }
  }
}

Or with explicit Python path:

{
  "mcpServers": {
    "mcp-test": {
      "command": "python",
      "args": ["-m", "server"]
    }
  }
}

Testing MCP Scanners

This server is ideal for testing MCP scanner tools because it provides:

1. Diverse Tool Schemas - From simple strings to complex nested objects

2. Multiple Resource Types - Different MIME types and content structures

3. Edge Cases - Tools with no required parameters, optional fields, enums

4. Standard Compliance - Follows MCP specification strictly

5. Scanner Detection - Multiple configuration files for detection testing

Scanner Detection

This repository is configured to be detected by MCP scanner tools like the APIsec MCP Audit Scanner.

Detection files included:

• mcp.json - Claude Desktop style configuration

• mcp.yaml - YAML format configuration

• .mcp/config.json - Hidden directory config

• package.json - npm dependencies with @modelcontextprotocol/sdk

• requirements.txt - Python dependencies with modelcontextprotocol

📖 See SCANNER_GUIDE.md for detailed scanner testing instructions.

Scanner Test Checklist

• Discovers all 6 tools

• Parses complex nested schemas correctly

• Identifies all 4 resources with correct URIs

• Handles tools with optional-only parameters

• Recognizes prompt capabilities

• Correctly interprets enum constraints

• Handles array and object types

Project Structure

mcp-test/
├── server.py              # Main MCP server implementation
├── pyproject.toml         # Package configuration
├── package.json           # npm metadata (for scanner detection)
├── requirements.txt       # Python dependencies
├── README.md             # This file
├── SCANNER_GUIDE.md      # Scanner detection guide
├── .gitignore            # Git ignore rules
├── LICENSE               # MIT License
├── mcp.json              # MCP configuration (Claude Desktop style)
├── mcp.yaml              # MCP configuration (YAML format)
├── mcp-config.json       # Example client configuration
├── .mcp/                 # MCP metadata directory
│   ├── config.json       # Scanner-detectable config
│   └── mcp.json          # MCP metadata
├── examples/             # Example usage scripts
│   ├── README.md
│   ├── test_client.py
│   └── scanner_test.py
└── tests/                # Unit tests
    ├── __init__.py
    └── test_server.py

Requirements

• Python 3.10 or higher

• mcp >= 0.9.0

Development

Running Tests

pytest tests/

Code Style

This project follows PEP 8 guidelines. Format code with:

black server.py

API Reference

Tools

echo

• Input: message (string, required)

• Output: Echoes the input message

• Purpose: Test basic string parameter handling

add_numbers

• Input: a (number), b (number)

• Output: Sum of the two numbers

• Purpose: Test numeric parameter handling

format_json

• Input: data (object), indent (number, default: 2)

• Output: Formatted JSON string

• Purpose: Test object parameter handling

list_operations

• Input: items (array), operation (enum), separator (string, optional)

• Output: Result of list operation

• Purpose: Test array handling and enum constraints

complex_schema

• Input: Nested object with user info and options

• Output: Processed data structure

• Purpose: Test complex nested schema parsing

timestamp

• Input: format (enum, optional)

• Output: Current timestamp in specified format

• Purpose: Test tools with all-optional parameters

Resources

All resources use URIs in the format mcp://test/{resource-name}:

• mcp://test/static-text - Plain text content

• mcp://test/json-data - Structured JSON

• mcp://test/markdown-doc - Markdown documentation

• mcp://test/config - Configuration data

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch

3. Make your changes

4. Add tests if applicable

5. Submit a pull request

License

MIT License - see LICENSE file for details

Support

For issues, questions, or contributions, please open an issue on the repository.

Changelog

v0.1.0 (Initial Release)

• Basic MCP server implementation

• 6 diverse tools for testing

• 4 resource types

• 2 sample prompts

• Complete documentation

Related Projects

• Model Context Protocol Specification

• MCP Python SDK

Note: This is a testing server. Do not use in production environments.