# 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](https://apisec-inc.github.io/mcp-audit/).

**⚡ Quick Start:** Want to test scanner detection immediately? See [QUICK_START.md](QUICK_START.md)

## Scanner Detection Documentation

- **[QUICK_START.md](QUICK_START.md)** - Get scanned in 10 minutes
- **[SCANNER_GUIDE.md](SCANNER_GUIDE.md)** - Detailed detection guide
- **[SCANNER_CHECKLIST.md](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

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

# Install the package
pip install .
```

### Development Installation

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

## Usage

### Running the Server

#### Command Line
After installation, run the server directly:

```bash
mcp-test-server
```

#### Python Module
Alternatively, run as a Python module:

```bash
python server.py
```

### Testing with MCP Client

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

```python
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):

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

Or with explicit Python path:

```json
{
  "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](https://apisec-inc.github.io/mcp-audit/).

**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](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

```bash
pytest tests/
```

### Code Style

This project follows PEP 8 guidelines. Format code with:

```bash
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](https://spec.modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)

---

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