在 AI 智能体开发中，工具调用的标准化是提升效率的关键。MCP（Model Context Protocol，模型上下文协议）作为连接大模型与外部工具的通用标准，让开发者能快速构建可复用、跨平台的 AI 工具。本文将从协议原理、环境搭建、工具开发、调试部署到生态扩展，全方位拆解 MCP 的开发流程，补充详细的技术细节、错误处理和进阶技巧，帮你轻松打造自己的第一个 MCP 工具。
MCP 是一套规范大模型与外部工具交互的协议，核心作用是作为“中间层”，让大模型通过统一格式调用各类工具（API、本地程序、硬件设备等）。其核心价值在于：
| 传输方式 | 核心原理 | 优势 | 劣势 | 适用场景 |
|---|---|---|---|---|
| STDIO | 大模型通过标准输入/输出与 MCP 工具通信 | 无需网络、延迟低、配置简单 | 仅支持本地调用、不支持多客户端共享 | 本地开发调试、单机工具调用 |
| SSE | 基于 HTTP 协议的服务器推送，大模型通过网络调用 MCP 服务 | 支持远程调用、多客户端共享 | 需部署服务器、有网络依赖 | 团队协作、云端工具服务 |
一个完整的 MCP 工具包含三部分：
uv 是 Rust 编写的 Python 环境管理工具，具有依赖解析快、安装高效的优势，是 MCP 开发的首选工具：
# macOS/Linux 安装 uv
curl -LsSf https://astral.sh/uv/install.sh | sh
# Windows 安装（PowerShell）
powershell -c "irm https://astral.sh/uv/install.ps1 | iex"
# 验证安装
uv --version # 输出 uv x.y.z 即成功MCP 协议推荐使用 Python 3.10+，本文以 Python 3.13.7 为例：
# 安装指定版本 Python
uv python install 3.13.7
# 查看已安装 Python 版本
uv python list# 初始化 MCP 项目（指定 Python 版本）
uv init mcp-web-search -p 3.13
cd mcp-web-search
# 创建并激活虚拟环境
uv venv
# Windows 激活
.venv\Scripts\activate.bat
# macOS/Linux 激活
source .venv/bin/activate
# 安装核心依赖
uv add "mcp[cli]" # MCP 核心 SDK
uv add httpx # HTTP 请求库（用于调用外部 API）
uv add python-dotenv # 环境变量管理
uv add openai # 可选，用于大模型交互测试
uv add logging # 日志管理初始化后项目核心文件：
mcp-web-search/
├── .env # 环境变量配置（存储 API Key 等敏感信息）
├── pyproject.toml # 项目依赖与配置
├── .venv/ # 虚拟环境
└── web_search.py # MCP 工具核心代码为提升开发效率，推荐安装以下插件：
.env 文件语法高亮；本文将开发一个包含“网页搜索”“数值计算”“主机信息查询”三大功能的 MCP 工具，覆盖 API 调用、本地系统交互、错误处理等核心场景。
创建 .env 文件，存储 API Key 等敏感信息（避免硬编码）：
# .env 文件内容
ZHI_PU_AI_API_KEY=你的智谱 AI API Key # 用于网页搜索功能import httpx
import json
import os
import logging
import platform
from dotenv import load_dotenv
from mcp.server import FastMCP
# 1. 初始化配置
# 加载环境变量
load_dotenv()
# 配置日志（便于调试）
logging.basicConfig(
level=logging.INFO,
format="%(asctime)s - %(name)s - %(levelname)s - %(message)s"
)
logger = logging.getLogger("mcp-web-search")
# 2. 初始化 MCP 服务器（服务名称：web-search）
app = FastMCP("web-search")
# 3. 验证敏感配置
ZHI_PU_API_KEY = os.getenv("ZHI_PU_AI_API_KEY")
if not ZHI_PU_API_KEY:
logger.error("未配置 ZHI_PU_AI_API_KEY 环境变量")
raise ValueError("请在 .env 文件中配置 ZHI_PU_AI_API_KEY")
# 4. 工具函数 1：网页搜索（调用智谱 AI 网页搜索 API）
@app.tool()
async def web_search(query: str) -> str:
"""
搜索互联网最新信息，支持各类公开内容查询（如新闻、知识、数据）
:param query: 搜索关键词（如"2025 年 AI 发展趋势"）
:return: 搜索结果的结构化总结（多个结果用三个换行分隔）
"""
async with httpx.AsyncClient(timeout=30.0) as client:
try:
# 构建请求参数
request_data = {
"tool": "web-search-pro",
"messages": [{"role": "user", "content": query}],
"stream": False
}
# 发送请求
response = await client.post(
url="https://open.bigmodel.cn/api/paas/v4/tools",
headers={"Authorization": ZHI_PU_API_KEY},
json=request_data
)
# 处理 HTTP 错误（非 200 状态码抛出异常）
response.raise_for_status()
response_json = response.json()
# 解析搜索结果
search_results = []
for choice in response_json.get("choices", []):
tool_calls = choice.get("message", {}).get("tool_calls", [])
for tool_call in tool_calls:
result_list = tool_call.get("search_result", [])
for result in result_list:
content = result.get("content", "")
if content.strip():
search_results.append(content)
# 无结果处理
if not search_results:
return "未找到相关搜索结果，请尝试调整关键词"
return "\n\n\n".join(search_results)
except httpx.HTTPStatusError as e:
error_msg = f"HTTP 错误：状态码 {e.response.status_code}，内容：{e.response.text[:200]}"
logger.error(error_msg)
return f"网页搜索失败：{error_msg}"
except httpx.RequestError as e:
error_msg = f"网络请求失败：{str(e)}"
logger.error(error_msg)
return f"网页搜索失败：{error_msg}"
except json.JSONDecodeError as e:
error_msg = f"响应解析失败：{str(e)}"
logger.error(error_msg)
return f"网页搜索失败：{error_msg}"
except Exception as e:
logger.exception("网页搜索发生未知错误")
return f"网页搜索失败：未知错误 - {str(e)}"
# 5. 工具函数 2：数值加法（本地计算工具）
@app.tool()
def add(a: int, b: int) -> int:
"""
计算两个整数的和，支持正负整数运算
:param a: 第一个整数
:param b: 第二个整数
:return: 两个整数的和
"""
try:
result = a + b
logger.info(f"加法运算：{a} + {b} = {result}")
return result
except Exception as e:
logger.error(f"加法运算失败：{str(e)}")
raise ValueError(f"计算失败：{str(e)}")
# 6. 工具函数 3：获取主机信息（本地系统工具）
@app.tool()
def get_host_info() -> str:
"""
获取当前主机的系统信息，包括操作系统、硬件架构等
:return: 结构化的主机信息（JSON 字符串格式）
"""
try:
host_info = {
"操作系统": platform.system(),
"主机名": platform.node(),
"系统版本": platform.release(),
"内核版本": platform.version(),
"硬件架构": platform.machine(),
"处理器": platform.processor() or "未知"
}
# 格式化 JSON 输出（便于大模型解析）
return json.dumps(host_info, ensure_ascii=False, indent=4)
except Exception as e:
logger.error(f"获取主机信息失败：{str(e)}")
return f"获取主机信息失败：{str(e)}"
# 7. 启动 MCP 服务（默认 STDIO 传输）
if __name__ == "__main__":
logger.info("MCP 工具服务启动中...")
# 支持通过命令行参数指定传输方式（如 --transport sse）
app.run(transport="stdio")query: str），帮助大模型精准传参；@app.tool()：用于有副作用的工具（如 API 调用、数据修改）；@app.resource()：用于只读工具（如数据查询），类比 HTTP 的 GET 方法（本文暂未使用）。python-dotenv 加载环境变量，避免硬编码 API Key；~/.zshrc），提升安全性。# 启动 MCP 工具（STDIO 模式）
uv run web_search.py启动后，工具会等待大模型的输入，可通过 MCP 调试工具发送测试请求。
MCP 官方提供调试工具，可快速验证工具功能：
# 安装 MCP Inspector（需 Node.js 20+）
npm install -g @modelcontextprotocol/inspector
# 启动调试
mcp-inspector uv run web_search.pyweb_search），输入参数并执行，查看返回结果；mcp-web-search 项目根目录；uv run web_search.py；在 Cherry Studio 中输入自然语言指令，测试工具调用：
add 工具）；web_search 工具）；get_host_info 工具）。若需让团队共享 MCP 工具，可部署为 SSE 服务，支持远程调用：
修改 web_search.py 的启动代码，支持指定传输方式和端口：
if __name__ == "__main__":
import argparse
parser = argparse.ArgumentParser(description="MCP 工具服务（支持 STDIO/SSE）")
parser.add_argument("--transport", default="stdio", choices=["stdio", "sse"], help="传输方式")
parser.add_argument("--host", default="0.0.0.0", help="SSE 服务绑定地址")
parser.add_argument("--port", default=8000, type=int, help="SSE 服务端口")
args = parser.parse_args()
logger.info(f"MCP 服务启动：传输方式={args.transport}，端口={args.port}")
if args.transport == "sse":
app.run(transport="sse", host=args.host, port=args.port)
else:
app.run(transport="stdio")# 启动 SSE 服务（绑定 8000 端口）
uv run web_search.py --transport sse --port 8000AI 客户端需通过 HTTP 地址连接 SSE 服务：
http://你的服务器IP:8000/mcp；nohup 或 systemd 确保服务后台运行；pip install 安装后直接运行；npx 快速调用。lru_cache），减少重复计算或 API 调用；.env 文件路径错误、变量名称拼写错误；.env 文件在项目根目录；print(os.getenv("ZHI_PU_AI_API_KEY")) 验证变量是否加载。uv install；--port 8001）。MCP 协议的核心优势在于“标准化”与“复用性”——一次开发，可在所有支持 MCP 的 AI 客户端中使用，无需重复适配。本文开发的 MCP 工具覆盖了 API 调用、本地计算、系统交互三大典型场景，可直接用于日常开发、智能体搭建等场景。
未来，MCP 生态将进一步完善，支持更多传输方式（如 gRPC）、多模态工具（如语音、图像处理）和权限控制机制。作为开发者，掌握 MCP 协议能让你在 AI 工具开发中抢占先机，打造可复用、高兼容的工具产品。
如果你想进一步扩展工具功能（如添加文件处理、数据库查询），或需要部署为高可用的云端服务，不妨尝试本文的进阶技巧，或探索 MCP 官方 SDK 的更多高级特性。
除非注明，否则均为李锋镝的博客原创文章，转载必须以链接形式标明本文链接
此内容由惯性聚合(RSS阅读器)自动聚合整理，仅供阅读参考。 原文来自 — 版权归原作者所有。