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
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 negotiationinitializednotificationping- 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/updatednotifications/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
cd chuk-mcp-server-reference
pip install -r requirements.txt
Run Examples
# 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:
# 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:
# 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:
# 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
# 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:
# 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 versionexamples/README.md- Guide to all examples- Each example file contains extensive inline documentation
Contributing
Contributions should:
- Map to specific MCP specification sections
- Include spec version and reference URLs
- Add tests
- Update documentation
Resources
License
MIT License
Built with chuk-mcp-server - The protocol implementation is already done, this repo just demonstrates all the features! 🚀