MCP Reference Server

MCP参考服务器

一个全面的参考实施演示 所有功能 使用模型上下文协议（MCP）规范 chuk-mcp-server.

🎉 经认证100%符合MCP规范 -请参阅 合规.md

概述

此存储库提供了官方规范中定义的每个MCP功能的完整工作示例。它的作用是：

• 📚 参考文档 -了解每个MCP功能的工作原理
• ✅ 规范合规示例 -验证MCP实施
• 🎓 学习资源 -了解MCP协议
• 🧪 测试工具 -根据规范功能测试MCP客户端

规范版本

⚠️ 重要：MCP 2025-11-25示例（12、13、14）为 实施参考 展示了规范应该如何工作。这些功能尚未在chuk-mcp服务器中实现。图标以文本/表情符号的形式嵌入，启发功能记录在文档字符串中。

电流测试：所有合规性测试均根据 MCP 2025-06-18 （核心规格）

MCP功能演示

✅ 核心协议（JSON-RPC 2.0）

所有示例都使用chuk-mcp服务器实现的正确JSON-RPC 2.0消息格式。

✅ 生命周期

• initialize -连接和能力协商
• initialized 通知
• ping -健康检查（双向）

✅ 服务器功能

工具(tools/list, tools/call)

• 具有各种参数类型的基本工具
• 具有复杂模式的工具
• 带有进度报告的工具
• 具有错误处理功能的工具
• 动态刀具注册
• notifications/tools/list_changed

资源(resources/*)

• 静态资源
• 具有URI模板的动态资源
• 资源订阅
• 二进制资源（图像、音频）
• 文本资源（markdown、JSON、代码）
• notifications/resources/updated
• notifications/resources/list_changed

提示(prompts/list, prompts/get)

• 静态提示
• 用论据提示
• 多消息提示
• 提示模板
• notifications/prompts/list_changed

✅ 客户能力

取样(sampling/createMessage)

• 服务器发起LLM请求
• 多回合对话
• 系统提示
• 模型首选项

根(roots/list)

• 文件系统根查询
• notifications/roots/list_changed

✅ 公用事业

日志记录(logging/setLevel)

• 调试、信息、警告、错误级别
• notifications/message -日志输出

进展

• notifications/progress -长时间运行的操作更新
• 进度令牌

竣工(completion/complete)

• 参数自动补全
• 情境感知建议

取消

• notifications/cancelled -请求取消

项目结构

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

快速开始

安装

cd chuk-mcp-server-reference
pip install -r requirements.txt

运行示例

# 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

示例目录

1.最小服务器

使用一个工具的最简单的MCP服务器。

2.基本工具

演示所有工具参数类型：

• 字符串、整数、数字、布尔值
• 数组和对象
• 可选和必需参数
• 默认值

3.高级工具

• 复杂的嵌套模式
• 执行过程中的进度报告
• 错误处理模式
• 工具结果内容类型（文本、图像、嵌入式资源）

4.基础资源

• 具有各种MIME类型的静态资源
• 列出资源
• 读取资源内容
• 文本和二进制资源

5.高级资源

• URI模板(file://logs/{date})
• 资源订阅
• 资源更新通知
• 动态资源生成

6.基本提示

• 简单提示
• 用论据提示
• 多消息提示

7.高级提示

• 参数化提示模板
• 动态提示生成
• 提示参数验证

8.取样

• 服务器请求客户端完成LLM
• 多回合对话
• 系统提示和偏好

9.记录和进度

• 日志级别配置
• 长期操作的进度通知
• 进度令牌

10.竣工

• 参数自动补全
• 情境感知建议

11.完整服务器

启用所有功能的完整服务器-终极参考。

MCP检验员测试

所有示例均适用于 MCP检查员:

# Run any example
python examples/11_full_server.py

# In another terminal, use MCP Inspector
npx @modelcontextprotocol/inspector

配置检查器：

• 运输：HTTP或STDIO
• 统一资源定位符: http://localhost:8000/mcp （适用于HTTP）
• 命令: python examples/11_full_server.py （适用于STDIO）

规格映射

每个示例都包括将功能映射到官方MCP规范的注释：

# 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

规范合规性

此参考服务器旨在100%符合MCP规范：

• ✅ 正确的JSON-RPC 2.0格式
• ✅ 能力协商
• ✅ 内容类型支持（文本、图像、音频、嵌入式资源）
• ✅ 错误代码和处理
• ✅ 通知
• ✅ 分页
• ✅ 进度报告
• ✅ 取消

测试

运行合规性演示

测试完全符合MCP规范的交互式演示：

# 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 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功能状态

测试新功能的实施状态：

# 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

结果：3个通过（描述、默认值），5个失败（图标、启发模式）

文档

• specs/ -每个规范版本的详细文档
• examples/README.md -所有示例指南
• 每个示例文件都包含大量的内联文档

贡献

捐款应：

1. 映射到特定的MCP规范部分
2. 包括规范版本和参考URL
3. 添加测试
4. 更新文档

资源

• MCP规范
• chuk mcp服务器
• JSON-RPC 2.0

许可证

MIT许可证

______________________________________________________________________

内置于 chuk mcp服务器 -协议实现已经完成，这个仓库只是演示了所有的功能！ 🚀