AI导哈

MCP服务器开发教程

一个详细的MCP服务器开发教程，包含工作示例和调试工具，帮助理解MCP服务器的工作原理、调试方法和常见问题诊断。

  • by DazzleML
  • Python
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 djdarcy/MCP-Server-Tutorial

使用说明

MCP服务器教程

一个详细的实践教程，用于学习MCP（模型上下文协议）服务器开发，包括工作示例和调试工具。

项目概述

本教程项目创建了一个最小、文档齐全的MCP服务器，旨在帮助您理解：

  • MCP服务器的工作原理
  • 如何使用VS代码调试MCP服务器
  • 如何诊断常见的MCP问题
  • 如何在Claude Desktop注册服务器
  • 如何构建自己的MCP工具和服务器

需求：Python 3.10+（MCP库要求）

快速开始

1.设置环境

# Run the setup script
scripts\setup.bat

# Or manually:
python -m venv venv
venv\Scripts\activate.bat
pip install mcp

2.测试服务器

# Activate virtual environment
venv\Scripts\activate.bat

# Run tests (basic test without Unicode issues)
python tests\test_simple.py

# Or run full test suite (may have Unicode display issues on Windows)
python tests\test_server.py

# Or use the safe test runner for Windows
scripts\test_safe.bat

Windows用户注意事项： 如果您看到Unicode编码错误，请使用 scripts\test_safe.bat 它将输出重定向到 test_output.log.

3.调试服务器

  1. 在VS Code中打开此文件夹
  2. 转到运行和调试（Ctrl+Shift+D）
  3. 选择“调试MCP服务器”
  4. 按F5开始调试

要设置的关键断点：

  • server.py:89 -工具发现
  • server.py:110 -工具执行
  • handlers.py:25 -个人工具操作员

4.用克劳德代码注册

  1. 从以下位置复制配置 config\claude_desktop.json
  2. 添加到您的Claude Desktop配置文件
  3. 重新启动克劳德桌面
  4. 服务器应显示为“简单mcp调试”

项目结构

MCPDebugTest/
├── CLAUDE.md                    # Detailed learning documentation
├── README.md                    # This file
├── setup.bat                    # Windows setup script
├── requirements.txt             # Python dependencies
├── simple_mcp_server/           # Main MCP server code
│   ├── server.py                # MCP server implementation
│   ├── tools.py                 # Tool definitions
│   ├── handlers.py              # Tool handlers
│   └── debug_utils.py           # Debugging utilities
├── tests/                       # Test scripts
│   └── test_server.py           # Server validation tests
├── config/                      # Configuration files
│   └── claude_desktop.json      # Claude Desktop config
├── .vscode/                     # VS Code configuration
│   └── launch.json              # Debug configurations
└── logs/                        # Debug logs (created on first run)

可用工具

MCP服务器公开这些工具进行测试：

1.你好_世界

简单的问候工具

  • 参数: name （可选）
  • 目的：基本功能测试

2.回声

回显带有可选前缀的消息

  • 参数: message （必填）， prefix （可选）
  • 目的：输入/输出测试

3.获取时间

以各种格式获取当前时间

  • 参数: format （iso/可读/时间戳）， timezone （可选）
  • 目的：系统交互测试

4.math_add

将两个数字相加

  • 参数: a （必填）， b （必填）
  • 目的：参数验证测试

5.调试信息

获取服务器调试信息

  • 参数: include_tools （布尔值）， include_stats （布尔值）
  • 目的：服务器自检

调试功能

日志记录

  • 详细的MCP协议消息记录
  • 性能指标
  • 使用堆栈跟踪进行错误跟踪
  • 不同方面的单独日志文件

VS代码集成

  • 预配置调试启动配置
  • 断点友好的代码结构
  • 可变检查能力
  • 逐步调试

测试套件

  • 自动化工具发现测试
  • 参数验证测试
  • 错误处理验证
  • 处理器功能测试

了解MCP协议

工具发现流程

  1. 客户端连接到服务器
  2. 客户电话 list_tools() 远程过程调用
  3. 服务器返回带有模式的可用工具
  4. 客户端现在可以调用单个工具

工具执行流程

  1. 客户电话 call_tool(name, arguments) 远程过程调用
  2. 服务器根据架构验证参数
  3. 服务器将路由到适当的处理程序
  4. 处理程序处理请求并返回结果
  5. 服务器格式化响应并发送回

调试要点

  • 工具注册：在中设置断点 get_all_tools()
  • 工具发现：在中设置断点 handle_list_tools()
  • 工具执行：在中设置断点 handle_call_tool()
  • 个人处理人员：在特定的工具处理程序中设置断点

常见问题及解决方法

问题：工具未出现在Claude代码中

调试步骤：

  1. 检查Claude桌面配置
  2. 验证服务器启动时没有错误
  3. 检查 list_tools() 日志中的响应
  4. 重新启动克劳德桌面

问题：工具执行失败

调试步骤：

  1. 检查日志中的参数验证
  2. 在工具处理程序中设置断点
  3. 验证处理程序返回格式
  4. 检查错误处理路径

问题：服务器无法启动

调试步骤：

  1. 检查Python环境
  2. 验证MCP库安装
  3. 检查导入路径
  4. 查看启动日志

问题：Windows控制台中的Unicode/表情符号字符

问题： Windows命令提示符可能无法正确显示Unicode字符 解决：

  1. 使用 scripts\test_safe.bat 它将输出重定向到文件
  2. 使用Windows终端或PowerShell而不是命令提示符
  3. 设置控制台代码页： chcp 65001 在运行测试之前
  4. 检查 test_output.log 查看完整的测试结果

问题：测试套件因UnicodeEncodeError而崩溃

问题： 尝试将Unicode字符输出到Windows控制台时，Python日志记录失败 解决：

  1. 使用运行测试 scripts\test_safe.bat 重定向输出
  2. 使用简化的测试流道： python tests\test_simple.py
  3. 检查中的日志文件 logs\ 详细输出目录
  4. 服务器功能正常工作；只有控制台输出有Unicode问题

后续步骤

一旦你理解了这个教程服务器：

  1. 构建自己的服务器：使用相同的模式创建自己的MCP服务器
  2. 探索高级功能：添加更复杂的工具和状态管理
  3. 部署到生产：遵循文档中的生产部署指南
  4. 回馈：与社区分享改进和其他示例

学习资源

有用的教程

本项目包括一个完整的分步教程，涵盖了MCP开发的各个方面：

📖 完整教程指南

教程章节：

  1. 了解MCP架构

    • MCP协议基础和客户端-服务器通信
    • 核心概念：工具、资源、提示和协议流
    • MCP如何融入AI助手生态系统

  2. 协议流

    • 消息交换模式和协议握手
    • 工具发现和执行生命周期
    • 错误处理和响应格式

  3. 工具注册

    • 使用JSON模式验证定义工具
    • 工具命名和参数设计的最佳实践
    • 高级工具特性和功能

  4. 错误处理

    • 不同的错误处理策略
    • 调试常见故障场景
    • 符合协议的错误响应

  5. 调试和测试

    • VS代码调试设置和断点策略
    • 测试套件开发和自动化验证
    • 协议级调试技术

  6. 身份验证和安全

    • MCP服务器的安全注意事项
    • 身份验证模式和访问控制
    • 生产部署的最佳实践

  7. 状态管理

    • 管理服务器状态和会话数据
    • 持久性策略和数据一致性
    • 高级状态管理模式

  8. 克劳德集成

    • Claude桌面配置和设置
    • 集成故障排除和优化
    • 跨平台部署注意事项

  9. 生产部署

    • 生产就绪服务器配置
    • 监控、记录和维护
    • 扩展和性能优化

其他文件

外部资源

贡献

这是一个学习项目。请随意：

  • 添加更多测试工具
  • 增强调试能力
  • 改进文档
  • 添加更广泛的测试

调试愉快！ 🐛🔍

相关 MCP