README.md•9.82 kB
# MCP Reference Server
A comprehensive reference implementation demonstrating **all features** of the Model Context Protocol (MCP) specification using `chuk-mcp-server`.
**🎉 Certified 100% MCP Specification Compliant** - See [COMPLIANCE.md](COMPLIANCE.md)
## Overview
This repository provides complete, working examples of every MCP feature defined in the official specification. It serves as:
- 📚 **Reference Documentation** - See how each MCP feature works
- ✅ **Spec Compliance Examples** - Validate MCP implementations
- 🎓 **Learning Resource** - Understand the MCP protocol
- 🧪 **Testing Tool** - Test MCP clients against spec features
## Specification Versions
| Version | Status | Features |
|---------|--------|----------|
| **2025-06-18** | ✅ **100% Implemented & Tested** | Core spec: Tools, Resources, Prompts, Sampling, Logging |
| **2025-11-25** | 📚 **Reference Examples Only** | Tasks (experimental), Enhanced Auth, Tool Calling in Sampling, Icons, Enhanced Elicitation |
| **2024-11-05** | 📚 **Documented** | Initial specification (superseded by 2025-06-18) |
**⚠️ Important**: MCP 2025-11-25 examples (12, 13, 14) are **reference implementations** showing how the spec SHOULD work. The features are not yet implemented in chuk-mcp-server. Icons are embedded as text/emojis, and elicitation features are documented in docstrings.
**Current Testing**: All compliance tests validate against **MCP 2025-06-18** (core specification)
## MCP Features Demonstrated
### ✅ Core Protocol (JSON-RPC 2.0)
All examples use proper JSON-RPC 2.0 message formatting implemented by chuk-mcp-server.
### ✅ Lifecycle
- `initialize` - Connection and capability negotiation
- `initialized` notification
- `ping` - Health check (bidirectional)
### ✅ Server Capabilities
#### Tools (`tools/list`, `tools/call`)
- Basic tools with various parameter types
- Tools with complex schemas
- Tools with progress reporting
- Tools with error handling
- Dynamic tool registration
- `notifications/tools/list_changed`
#### Resources (`resources/*`)
- Static resources
- Dynamic resources with URI templates
- Resource subscriptions
- Binary resources (images, audio)
- Text resources (markdown, JSON, code)
- `notifications/resources/updated`
- `notifications/resources/list_changed`
#### Prompts (`prompts/list`, `prompts/get`)
- Static prompts
- Prompts with arguments
- Multi-message prompts
- Prompt templates
- `notifications/prompts/list_changed`
### ✅ Client Capabilities
#### Sampling (`sampling/createMessage`)
- Server-initiated LLM requests
- Multi-turn conversations
- System prompts
- Model preferences
#### Roots (`roots/list`)
- Filesystem root queries
- `notifications/roots/list_changed`
### ✅ Utilities
#### Logging (`logging/setLevel`)
- Debug, info, warning, error levels
- `notifications/message` - Log output
#### Progress
- `notifications/progress` - Long-running operation updates
- Progress tokens
#### Completion (`completion/complete`)
- Argument autocompletion
- Context-aware suggestions
#### Cancellation
- `notifications/cancelled` - Request cancellation
## Project Structure
```
chuk-mcp-server-reference/
├── README.md
├── pyproject.toml
├── examples/
│ ├── 01_minimal.py # Simplest possible MCP server
│ ├── 02_tools_basic.py # Basic tool examples (all parameter types)
│ ├── 11_full_server.py # Complete 2025-06-18 reference
│ ├── 12_icons_metadata.py # Icons and metadata (2025-11-25)
│ ├── 13_enhanced_elicitation.py # Enhanced elicitation (2025-11-25)
│ ├── 14_spec_2025_11_25.py # Complete 2025-11-25 reference
│ └── README.md
├── specs/
│ ├── 2024-11-05/
│ │ ├── README.md # Spec version details
│ │ └── features.md # Feature checklist
│ ├── 2025-06-18/
│ │ ├── README.md
│ │ └── features.md
│ └── 2025-11-25/
│ ├── README.md
│ └── features.md
└── tests/
├── test_tools.py # Tool examples tests
├── test_resources.py # Resource examples tests
├── test_prompts.py # Prompt examples tests
└── test_integration.py # Full integration tests
```
## Quick Start
### Installation
```bash
cd chuk-mcp-server-reference
pip install -r requirements.txt
```
### Run Examples
```bash
# MCP 2025-06-18 (Core Specification - 100% Compliant)
python examples/01_minimal.py # Start here - simplest server
python examples/02_tools_basic.py # All tool parameter types
python examples/11_full_server.py # Complete 2025-06-18 reference
# MCP 2025-11-25 (Latest Specification - Reference Examples)
# ⚠️ These are reference examples only - features not yet in chuk-mcp-server
python examples/12_icons_metadata.py # Icons reference (emoji-based)
python examples/13_enhanced_elicitation.py # Enhanced elicitation reference
python examples/14_spec_2025_11_25.py # Complete 2025-11-25 reference
```
## Example Catalog
### 1. Minimal Server
The simplest possible MCP server with one tool.
### 2. Basic Tools
Demonstrates all tool parameter types:
- String, integer, number, boolean
- Arrays and objects
- Optional and required parameters
- Default values
### 3. Advanced Tools
- Complex nested schemas
- Progress reporting during execution
- Error handling patterns
- Tool result content types (text, images, embedded resources)
### 4. Basic Resources
- Static resources with various MIME types
- List resources
- Read resource content
- Text and binary resources
### 5. Advanced Resources
- URI templates (`file://logs/{date}`)
- Resource subscriptions
- Resource update notifications
- Dynamic resource generation
### 6. Basic Prompts
- Simple prompts
- Prompts with arguments
- Multi-message prompts
### 7. Advanced Prompts
- Parameterized prompt templates
- Dynamic prompt generation
- Prompt argument validation
### 8. Sampling
- Server requests LLM completion from client
- Multi-turn conversations
- System prompts and preferences
### 9. Logging & Progress
- Log level configuration
- Progress notifications for long operations
- Progress tokens
### 10. Completion
- Argument autocompletion
- Context-aware suggestions
### 11. Full Server
Complete server with ALL features enabled - the ultimate reference.
## Testing with MCP Inspector
All examples work with [MCP Inspector](https://github.com/modelcontextprotocol/inspector):
```bash
# Run any example
python examples/11_full_server.py
# In another terminal, use MCP Inspector
npx @modelcontextprotocol/inspector
```
Configure Inspector:
- **Transport**: HTTP or STDIO
- **URL**: `http://localhost:8000/mcp` (for HTTP)
- **Command**: `python examples/11_full_server.py` (for STDIO)
## Specification Mapping
Each example includes comments mapping features to the official MCP specification:
```python
# MCP Spec: tools/list
# Version: 2025-06-18
# Reference: https://modelcontextprotocol.io/specification/2025-06-18/server/tools
@mcp.tool
def example_tool(param: str) -> str:
"""Tool description per spec."""
return result
```
## Spec Compliance
This reference server aims for 100% compliance with the MCP specification:
- ✅ Proper JSON-RPC 2.0 formatting
- ✅ Capability negotiation
- ✅ Content type support (text, image, audio, embedded resources)
- ✅ Error codes and handling
- ✅ Notifications
- ✅ Pagination
- ✅ Progress reporting
- ✅ Cancellation
## Testing
### Run Compliance Demo
Interactive demo that tests full MCP spec compliance:
```bash
# Auto-start server and test
python examples/spec_compliance_demo.py --start-server
# Against a running server
python examples/spec_compliance_demo.py
# Against a different server
python examples/spec_compliance_demo.py --url http://localhost:3000/mcp
```
### Run Test Suite
```bash
# Run all tests
pytest
# Run protocol compliance tests (2025-06-18)
pytest tests/test_protocol_compliance.py -v
# Run example validation tests
pytest tests/test_examples.py -v
# Run 2025-11-25 feature tests (shows what's not implemented)
pytest tests/test_2025_11_25_features.py -v
# Run with coverage
pytest --cov=examples --cov-report=html
```
### MCP 2025-11-25 Feature Status
Test the implementation status of new features:
```bash
# Run feature tests - shows passing and expected failures
pytest tests/test_2025_11_25_features.py -v
# See summary of what works and what doesn't
pytest tests/test_2025_11_25_features.py::test_summary_report -v -s
```
**Results**: 3 passed (description, defaults), 5 xfailed (icons, elicitation modes)
## Documentation
- `specs/` - Detailed documentation for each spec version
- `examples/README.md` - Guide to all examples
- Each example file contains extensive inline documentation
## Contributing
Contributions should:
1. Map to specific MCP specification sections
2. Include spec version and reference URLs
3. Add tests
4. Update documentation
## Resources
- [MCP Specification](https://modelcontextprotocol.io/specification/)
- [MCP GitHub](https://github.com/modelcontextprotocol)
- [chuk-mcp-server](https://github.com/your-org/chuk-mcp-server)
- [JSON-RPC 2.0](https://www.jsonrpc.org/specification)
## License
MIT License
---
**Built with** [chuk-mcp-server](https://github.com/your-org/chuk-mcp-server) - The protocol implementation is already done, this repo just demonstrates all the features! 🚀