模型控制协议（Model Control Protocol, MCP）是一种专为实现AI代理与工具解耦而设计的通信协议，为AI驱动应用程序的开发提供了高度的灵活性和模块化架构。通过MCP服务器，AI代理能够动态发现并调用各种工具来响应用户请求。本文将详细介绍MCP服务器的构建过程，包括工具函数的注册、配置以及与Claude Desktop等AI代理的集成。我们将使用Python语言结合Anthropic的mcp库来构建一个功能完整的通用MCP服务器。
MCP协议概述
MCP协议建立了AI代理与MCP服务器上托管工具集之间的标准化通信机制。当用户向AI代理提交查询时，代理会从MCP服务器获取可用的工具列表，将这些工具转换为AI模型可理解的格式，并与用户请求一同发送给底层的AI模型。AI模型根据请求内容和可用工具，决定调用哪个工具并返回相应的执行指令。这种解耦架构确保了AI代理与工具之间的独立性，不仅提升了系统的灵活性，还显著增强了整体架构的可扩展性。
开发环境准备
在开始MCP服务器开发之前，需要确保开发环境满足以下要求：
系统需要安装Python 3.8或更高版本。对于包管理，建议使用pip、Poetry或UV等现代化工具，本文将采用UV作为主要的包管理工具。还需要准备一个支持MCP协议的AI代理应用程序（如Claude Desktop）用于后续的功能测试。开发者还应具备Python编程和JSON数据格式的基础知识。
创建项目的过程非常简单，通过UV命令即可快速初始化：
uv init McpAgent
cd McpAgent
该命令会生成一个针对Python开发优化的项目结构。项目根目录下包含Git仓库配置、gitignore文件用于忽略临时文件、python-version文件指定Python版本、main.py作为应用程序的入口点、pyproject.toml管理项目元数据和依赖关系、README.md提供项目文档，以及uv.lock文件确保依赖版本的一致性。
UV工具的优势在于其能够提供一致的依赖管理和虚拟环境创建功能，确保项目在不同系统环境中的可移植性。
工具函数的设计与实现
MCP服务器的核心功能依赖于工具函数的实现。我们首先创建一个用于获取系统信息的工具函数，该函数将作为MCP服务器托管的基础工具。
以下是一个完整的系统信息获取工具的实现示例：
tools.py
import platform
import json
def get_host_info() -> str:
"""
获取当前设备的系统信息。
Returns:
str: 包含操作系统、架构等系统信息的JSON格式字符串。
"""
system_info = {
"os": platform.system(),
"architecture": platform.machine(),
"platform": platform.platform()
}
return json.dumps(system_info)
if __name__ == "__main__":
print(get_host_info())
在设计工具函数时，需要遵循几个重要的原则。首先，函数命名应该具有明确的描述性，参数设计要清晰明了。例如，
get_host_info
这个函数名直接表达了其获取主机信息的功能。其次，完整的类型提示（如
-> str
）对于帮助AI模型理解函数的输入输出特征至关重要。
文档字符串的编写同样重要，特别是当函数功能不能从名称直接推断时，详细的文档字符串能够帮助AI模型更好地理解工具的用途和行为。在返回值设计方面，工具函数应该返回AI模型能够有效处理的字符串格式数据，通常采用JSON格式。在本例中，我们使用
json.dumps
方法将Python字典转换为JSON字符串。
工具函数的测试可以通过UV命令直接执行：
uv run tools.py
正常情况下，该命令会输出类似以下的系统信息：
{
"os": "Darwin",
"architecture": "arm64",
"platform": "macOS-15.4.1-arm64-arm-64bit"
}
MCP服务器的构建与配置
完成工具函数开发后，下一步是使用Anthropic的mcp库构建MCP服务器。该服务器将负责托管
get_host_info
工具并为AI代理提供访问接口。
首先需要安装mcp库。在使用UV的环境中，可以通过以下命令完成安装：
uv add mcp
安装完成后，pyproject.toml文件会自动更新相关配置：
[project]
name = "mcpagent"
version = "0.1.0"
description = "Add your description here"
readme = "README.md"
requires-python = ">=3.12"
dependencies = [
"mcp>=1.9.1",
]
接下来构建基础的MCP服务器代码：
main.py
from mcp.server.fastmcp import FastMCP
import tools
# 创建MCP服务器实例
mcp = FastMCP("System Info Service")
# 注册工具函数
mcp.add_tool(tools.get_host_info)
# 以stdio模式启动MCP服务器
def main() -> None:
mcp.run("stdio")
if __name__ == "__main__":
main()
代码的核心组件包括FastMCP类，它是mcp库的主要接口。构造函数接受一个服务名称参数，虽然名称选择相对自由，但建议使用具有描述性的名称。
add_tool
方法用于将工具函数注册到MCP服务器中，支持多次调用以注册多个工具。
run
方法负责启动MCP服务器，其中mode参数指定通信模式。
MCP协议支持两种主要的通信模式：stdio模式使用标准输入输出进行本地通信，实现简单但要求代理和服务器运行在同一设备上；SSE（Server-Sent Events）模式通过HTTP协议实现通信，适合云端部署场景，但需要处理身份验证和授权机制。考虑到教学目的，本文采用stdio模式以降低复杂性。
对于工具函数与MCP服务器定义在同一文件中的情况，可以采用装饰器模式进行注册：
main.py
from mcp.server.fastmcp import FastMCP
import platform
import json
mcp = FastMCP("System Info Service")
@mcp.tool
def get_host_info() -> str:
"""
获取当前设备的系统信息。
Returns:
str: 包含操作系统、架构等系统信息的JSON格式字符串。
"""
system_info = {
"os": platform.system(),
"architecture": platform.machine(),
"platform": platform.platform()
}
return json.dumps(system_info)
mcp.run(mode="stdio")
@mcp.tool
装饰器在功能上等同于
mcp.add_tool(get_host_info)
的调用，提供了更加简洁的代码组织方式。
AI代理的配置与集成
为了验证MCP服务器的功能，我们选择Claude Desktop作为测试平台。Claude Desktop是一个用户友好的AI代理应用程序，内置了对MCP协议的支持。需要注意的是，其他AI代理（如Cline）的配置过程基本相似。
Claude Desktop的配置过程包括以下步骤：
首先，在Claude Desktop中打开设置菜单，然后访问开发者设置选项。在开发者设置中，点击"编辑配置"按钮，系统会打开包含配置文件的目录。
在配置文件目录中，需要定位或创建MCP配置文件（通常命名为claude_desktop_config.json）。配置文件的核心内容是指定启动MCP服务器的命令和参数。由于我们使用UV作为包管理工具，配置文件的格式如下：
mcp_config.json
{
"mcpServers": {
"hostInfoMcp": {
"command": "/ABSOLUTE/PATH/TO/UV/uv",
"args": [
"--directory",
"/ABSOLUTE/PATH/TO/MCPAgent/FOLDER/",
"run",
"main.py"
]
}
}
}
配置文件中有几个关键点需要特别注意。command字段必须指向UV可执行文件的完整绝对路径，在macOS系统中通常是"/Users/username/.local/bin/uv"。同时，directory参数也必须使用项目的完整绝对路径，例如"/Users/username/projects/McpAgent"。
配置项的含义分别是：name字段应与FastMCP构造函数中提供的服务名称保持一致；command字段指定MCP服务器的启动命令；args字段包含命令执行所需的参数列表。
完成配置文件编辑后，需要保存文件并重启Claude Desktop使配置生效。
功能测试与验证
配置完成后，Claude Desktop应该能够自动检测到MCP服务器及其注册的工具。测试过程包括以下几个步骤：
启动Claude Desktop的聊天界面，在界面中应该能够看到已注册的"hostInfoMcp"工具。
在聊天界面中输入相关查询，例如"我的计算机的CPU架构是什么？"。Claude Desktop会显示一个对话框，提示AI模型希望调用get_host_info工具。用户需要点击"允许"按钮以授权工具的执行。
AI代理会执行工具函数，获取系统信息，并基于工具的返回结果生成响应。整个过程展示了MCP协议在AI代理与工具之间建立的有效通信机制。
AI生成的响应是基于
get_host_info
函数返回的JSON数据进行的智能解析和格式化输出。
开发最佳实践
在MCP服务器开发过程中，遵循最佳实践能够显著提升系统的可靠性和维护性。
在工具设计方面，应该将AI模型视为需要优质API和详细文档的开发者。因此，工具函数需要具备清晰的命名规范、完整的类型提示和详细的文档说明。函数的设计应该遵循单一职责原则，每个工具专注于完成特定的功能，这样不仅有利于代码维护，也便于AI模型的理解和调用。
通信模式的选择需要根据具体的部署场景来确定。对于本地开发和测试环境，stdio模式提供了简单直接的通信方式，能够快速验证功能的有效性。而在生产环境中，特别是需要远程访问的场景下，SSE模式提供了更强的灵活性和扩展性，但同时也需要考虑网络安全和访问控制的实现。
错误处理机制是系统稳定性的重要保障。工具函数应该能够优雅地处理各种异常情况，并返回格式化的错误信息字符串。这些错误信息不仅要便于AI模型理解，也要为用户提供有意义的错误提示。建议在工具函数中实现完整的异常捕获和处理逻辑，避免因为运行时错误导致整个MCP服务器崩溃。
模块化架构设计是MCP协议的核心优势之一。保持工具函数和MCP服务器的独立性，能够最大化系统的灵活性。这种设计允许开发者独立地开发、测试和部署不同的工具，也便于后期的功能扩展和维护。
总结
本文通过实际的代码示例和详细的配置步骤，展示了使用Python和Anthropic的mcp库构建MCP服务器的完整过程。我们从工具函数的设计开始，逐步介绍了MCP服务器的构建、AI代理的配置以及功能测试的验证方法。
MCP协议的核心价值在于实现了AI代理与工具之间的有效解耦。这种模块化架构不仅简化了工具的集成过程，还显著提升了系统的可扩展性。通过标准化的通信协议，开发者能够独立地开发AI代理和工具组件，为AI驱动应用程序的开发提供了更大的灵活性。
遵循本文介绍的最佳实践，包括清晰的工具函数设计、合适的通信模式选择以及完善的错误处理机制，开发者能够构建出可靠且高效的MCP应用系统。基于这个技术基础，可以进一步扩展MCP服务器的功能，集成更多类型的工具，或者尝试与不同的AI代理进行集成，从而充分发挥AI驱动工作流程的潜力。
MCP协议为AI应用开发领域带来了新的架构思路，其在提升系统模块化程度和开发效率方面的价值值得进一步探索和应用。
https://avoid.overfit.cn/post/42801ea56782426ea780152be00897b4
