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 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

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 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
• MCP GitHub
• chuk-mcp-server
• JSON-RPC 2.0

License

MIT License

---

Built with chuk-mcp-server - The protocol implementation is already done, this repo just demonstrates all the features! 🚀