本文翻译自 MCP 官方文档。

使用 LLM 构建 MCP

本指南将帮助您使用 LLM（大型语言模型）来构建自定义的模型上下文协议 (MCP) 服务器和客户端。本教程将重点介绍 Claude，但您可以使用任何前沿的大型语言模型来完成此操作。

准备文档

在开始之前，请收集必要的文档以帮助 Claude 理解 MCP：

访问 https://modelcontextprotocol.io/llms-full.txt 并复制完整的文档文本
导航至 MCP TypeScript SDK 或 Python SDK 代码库
复制 README 文件和其他相关文档
将这些文档粘贴到您与 Claude 的对话中

描述您的服务器

提供文档后，清晰地向 Claude 描述您想要构建什么样的服务器。具体说明：

您的服务器将公开哪些资源
它将提供哪些工具
它应提供哪些提示
它需要与哪些外部系统交互

例如：

构建一个 MCP 服务器，该服务器需具备以下功能：

- 连接到我公司的 PostgreSQL 数据库
- 将表结构（table schemas）作为资源进行公开/暴露
- 提供用于运行只读 SQL 查询的工具
- 包含用于常见数据分析任务的提示（prompts）

与 Claude 协作

在与 Claude 合作开发 MCP 服务器时：

首先从核心功能开始，然后迭代添加更多功能
请 Claude 解释您不理解的代码部分
根据需要请求修改或改进
让 Claude 帮助您测试服务器并处理边缘情况

Claude 可以帮助实现所有关键的 MCP 功能：

资源管理和公开
工具定义和实现
提示模板和处理程序
错误处理和日志记录
连接和传输设置

最佳实践

使用 Claude 构建 MCP 服务器时：

将复杂的服务器分解成更小的部分
在继续之前彻底测试每个组件
牢记安全 - 验证输入并适当限制访问
为将来的维护做好代码文档记录
仔细遵循 MCP 协议规范

后续步骤

在 Claude 帮助您构建服务器之后：

仔细审查生成的代码
使用 MCP Inspector 工具测试服务器
将其连接到 Claude.app 或其他 MCP 客户端
根据实际使用情况和反馈进行迭代

请记住，随着需求的不断变化，Claude 可以帮助您修改和改进服务器。

需要更多指导？只需向 Claude 询问有关实现 MCP 功能或解决出现的问题的具体问题即可。

调试

有效的调试对于开发 MCP 服务器或将其与应用程序集成至关重要。本指南涵盖了 MCP 生态系统中可用的调试工具和方法。

MCP 提供了几种用于不同级别调试的工具：

MCP 检查器 (MCP Inspector)
- 交互式调试界面
- 直接服务器测试
- 详情请参阅检查器指南
Claude 桌面开发者工具 (Claude Desktop Developer Tools)
- 集成测试
- 日志收集
- Chrome DevTools 集成
服务器日志记录 (Server Logging)
- 自定义日志记录实现
- 错误跟踪
- 性能监控

在 Claude 桌面版中调试 (Debugging in Claude Desktop)

检查服务器状态 (Checking server status)

Claude.app 界面提供了基本的服务器状态信息：

点击图标查看：
- 已连接的服务器
- 可用的提示 (prompts) 和资源
点击图标查看：
- 提供给模型的工具

查看日志 (Viewing logs)

从 Claude 桌面版查看详细的 MCP 日志：

日志捕获：

服务器连接事件
配置问题
运行时错误
消息交换

使用 Chrome DevTools (Using Chrome DevTools)

在 Claude 桌面版内部访问 Chrome 的开发者工具以调查客户端错误：

创建一个 developer_settings.json 文件，并将 allowDevTools 设置为 true：
```
{
  "allowDevTools": true
}
```
打开 DevTools：Command-Option-Shift-i

注意：您会看到两个 DevTools 窗口：

主内容窗口
应用程序标题栏窗口

使用 Console (控制台) 面板检查客户端错误。

使用 Network (网络) 面板检查：

消息负载 (payloads)
连接计时

常见问题 (Common issues)

工作目录 (Working directory)

将 MCP 服务器与 Claude 桌面版一起使用时：

通过 claude_desktop_config.json 启动的服务器的工作目录可能未定义（例如在 macOS 上是 /），因为 Claude 桌面版可以从任何地方启动。
请始终在您的配置和 .env 文件中使用绝对路径，以确保可靠运行。
对于直接通过命令行测试服务器，工作目录将是您运行命令的位置。

例如，在 claude_desktop_config.json 中，使用：

{
  "command": ["/path/to/your/server/executable"],
  "workingDirectory": "/path/to/your/server/data"
}

而不是相对路径，如 ./data

环境变量 (Environment variables)

MCP 服务器仅自动继承一部分环境变量，例如 USER、HOME 和 PATH。

要覆盖默认变量或提供您自己的变量，您可以在 claude_desktop_config.json 中指定一个 env 键：

{
  "command": ["/path/to/your/server/executable"],
  "env": {
    "API_KEY": "your_api_key",
    "CUSTOM_SETTING": "value"
  }
}

服务器初始化 (Server initialization)

常见的初始化问题：

路径问题 (Path Issues)
- 服务器可执行文件路径不正确
- 缺少必需文件
- 权限问题
- 尝试为 command 使用绝对路径
配置错误 (Configuration Errors)
- 无效的 JSON 语法
- 缺少必需字段
- 类型不匹配
环境问题 (Environment Problems)
- 缺少环境变量
- 变量值不正确
- 权限限制

连接问题 (Connection problems)

当服务器无法连接时：

检查 Claude 桌面版日志
验证服务器进程是否正在运行
使用检查器进行独立测试
验证协议兼容性

实现日志记录 (Implementing logging)

服务器端日志记录 (Server-side logging)

构建使用本地 stdio 传输方式的服务器时，所有记录到 stderr (标准错误) 的消息将自动被主机应用程序（例如 Claude 桌面版）捕获。

import sys
print("This is a log message", file=sys.stderr)

对于所有传输方式，您还可以通过发送日志消息通知来向客户端提供日志记录：

{
  "type": "notification",
  "event": "logMessage",
  "params": {
    "level": "info",
    "message": "Server initialized successfully."
  }
}

需要记录的重要事件：

初始化步骤
资源访问
工具执行
错误状况
性能指标

客户端日志记录 (Client-side logging)

在客户端应用程序中：

启用调试日志记录
监控网络流量
跟踪消息交换
记录错误状态

调试工作流 (Debugging workflow)

开发周期 (Development cycle)

初始开发 (Initial Development)
- 使用检查器进行基本测试
- 实现核心功能
- 添加日志记录点
集成测试 (Integration Testing)
- 在 Claude 桌面版中测试
- 监控日志
- 检查错误处理

测试更改 (Testing changes)

为了高效地测试更改：

配置更改：重新启动 Claude 桌面版
服务器代码更改：使用 Command-R 重新加载
快速迭代：在开发过程中使用检查器

最佳实践 (Best practices)

日志记录策略 (Logging strategy)

结构化日志记录 (Structured Logging)
- 使用一致的格式
- 包含上下文
- 添加时间戳
- 跟踪请求 ID
错误处理 (Error Handling)
- 记录堆栈跟踪 (stack traces)
- 包含错误上下文
- 跟踪错误模式
- 监控恢复情况
性能跟踪 (Performance Tracking)
- 记录操作计时
- 监控资源使用情况
- 跟踪消息大小
- 测量延迟 (latency)

安全注意事项 (Security considerations)

调试时：

敏感数据 (Sensitive Data)
- 清理日志 (Sanitize logs)
- 保护凭证
- 掩盖个人信息
访问控制 (Access Control)
- 验证权限
- 检查身份验证
- 监控访问模式

获取帮助 (Getting help)

遇到问题时：

第一步 (First Steps)
- 检查服务器日志
- 使用检查器进行测试
- 审查配置
- 验证环境
支持渠道 (Support Channels)
- GitHub issues (问题)
- GitHub discussions (讨论)
提供信息 (Providing Information)
- 日志摘录
- 配置文件
- 重现步骤
- 环境详情

好的，这是将上面提供的 HTML 内容转换为 Markdown 格式的结果：

检查器 (Inspector)

MCP 检查器 (MCP Inspector) 是一个用于测试和调试 MCP 服务器的交互式开发者工具。虽然调试指南将检查器作为整体调试工具包的一部分进行了介绍，但本文档将详细探讨检查器的各项功能与能力。

入门指南

安装与基本用法

检查器可以通过 npx 直接运行，无需安装：

检查来自 NPM 或 PyPi 的服务器

这是从 NPM 或 PyPi 启动服务器包的常用方法。

检查本地开发的服务器

要检查本地开发或作为仓库下载的服务器，最常用的方法是：

请仔细阅读任何附加的 README 文件以获取最准确的说明。

功能概览

检查器提供了多种与您的 MCP 服务器交互的功能：

服务器连接窗格

允许选择用于连接服务器的传输方式
对于本地服务器，支持自定义命令行参数和环境（变量）

资源选项卡

列出所有可用资源
显示资源元数据（MIME 类型、描述）
允许检查资源内容
支持订阅测试

提示选项卡

显示可用的提示模板
显示提示参数和描述
支持使用自定义参数进行提示测试
预览生成的消息

工具选项卡

列出可用工具
显示工具模式（schema）和描述
支持使用自定义输入进行工具测试
显示工具执行结果

通知窗格

展示从服务器记录的所有日志
显示从服务器接收到的通知

最佳实践

开发工作流

开始开发
- 使用您的服务器启动检查器
- 验证基本连接性
- 检查能力协商
迭代测试
- 进行服务器更改
- 重新构建服务器
- 重新连接检查器
- 测试受影响的功能
- 监控消息
测试边界情况
- 无效输入
- 缺失的提示参数
- 并发操作
- 验证错误处理和错误响应

使用 LLM 构建 MCP#

准备文档#

描述您的服务器#

与 Claude 协作#

最佳实践#

后续步骤#

调试#

在 Claude 桌面版中调试 (Debugging in Claude Desktop)#

检查服务器状态 (Checking server status)#

查看日志 (Viewing logs)#

使用 Chrome DevTools (Using Chrome DevTools)#

常见问题 (Common issues)#

工作目录 (Working directory)#

环境变量 (Environment variables)#

服务器初始化 (Server initialization)#

连接问题 (Connection problems)#

实现日志记录 (Implementing logging)#

服务器端日志记录 (Server-side logging)#

客户端日志记录 (Client-side logging)#

调试工作流 (Debugging workflow)#

开发周期 (Development cycle)#

测试更改 (Testing changes)#

最佳实践 (Best practices)#

日志记录策略 (Logging strategy)#

安全注意事项 (Security considerations)#

获取帮助 (Getting help)#

检查器 (Inspector)#

入门指南#

安装与基本用法#

检查来自 NPM 或 PyPi 的服务器#

检查本地开发的服务器#

功能概览#

服务器连接窗格#

资源选项卡#

提示选项卡#

工具选项卡#

通知窗格#

最佳实践#

开发工作流#

使用 LLM 构建 MCP

准备文档

描述您的服务器

与 Claude 协作

最佳实践

后续步骤

调试

在 Claude 桌面版中调试 (Debugging in Claude Desktop)

检查服务器状态 (Checking server status)

查看日志 (Viewing logs)

使用 Chrome DevTools (Using Chrome DevTools)

常见问题 (Common issues)

工作目录 (Working directory)

环境变量 (Environment variables)

服务器初始化 (Server initialization)

连接问题 (Connection problems)

实现日志记录 (Implementing logging)

服务器端日志记录 (Server-side logging)

客户端日志记录 (Client-side logging)

调试工作流 (Debugging workflow)

开发周期 (Development cycle)

测试更改 (Testing changes)

最佳实践 (Best practices)

日志记录策略 (Logging strategy)

安全注意事项 (Security considerations)

获取帮助 (Getting help)

检查器 (Inspector)

入门指南

安装与基本用法

检查来自 NPM 或 PyPi 的服务器

检查本地开发的服务器

功能概览

服务器连接窗格

资源选项卡

提示选项卡

工具选项卡

通知窗格

最佳实践

开发工作流