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:
- Diverse Tool Schemas - From simple strings to complex nested objects
- Multiple Resource Types - Different MIME types and content structures
- Edge Cases - Tools with no required parameters, optional fields, enums
- Standard Compliance - Follows MCP specification strictly
- 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 configurationmcp.yaml- YAML format configuration.mcp/config.json- Hidden directory configpackage.json- npm dependencies with@modelcontextprotocol/sdkrequirements.txt- Python dependencies withmodelcontextprotocol
📖 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 contentmcp://test/json-data- Structured JSONmcp://test/markdown-doc- Markdown documentationmcp://test/config- Configuration data
Contributing
Contributions are welcome! Please:
- Fork the repository
- Create a feature branch
- Make your changes
- Add tests if applicable
- 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
Note: This is a testing server. Do not use in production environments.
