Agent---MCP (Model Context Protocol) 协议开发

Ronin-Lotus

593人浏览 · 2026-03-06 23:13:39

Ronin-Lotus · 2026-03-06 23:13:39 发布

一、MCP 协议核心概念解析

Model Context Protocol (MCP) 是由 Anthropic 主导推出的开放标准协议，旨在解决大语言模型（LLM）与外部数据源、工具及服务之间的标准化连接问题。它类似于 AI 领域的 "USB-C 接口"，让任何应用都能以统一的方式接入各类能力。

🧩 三大核心原语

Resources (资源)：只读数据源（如文件、数据库记录、API 响应），模型可读取但不能修改。
Tools (工具)：可执行的操作（如搜索、计算、写入数据库），模型可调用并获取结果。
Prompts (提示词)：预定义的交互模板，用于引导模型完成特定任务（如代码审查、周报生成）。

🏗️ 架构角色

MCP Host (宿主)：运行 LLM 的应用程序（如 Claude Desktop, Dify, LangChain），负责发起请求。
MCP Client (客户端)：Host 内部的组件，负责与 Server 建立连接并转发消息。
MCP Server (服务端)：暴露具体能力（资源/工具/提示词）的轻量级服务，通常由开发者编写。

二、MCP 开发全流程详解

阶段 1：环境准备与选型

在开始编码前，需确定技术栈和通信方式。

步骤	关键决策	推荐方案
语言选择	根据团队技能栈选择	TypeScript/Node.js (生态最成熟), Python (AI 领域首选), Go/Rust (高性能场景)
通信传输	决定 Host 与 Server 如何对话	Stdio (本地进程间通信，最常用), SSE (远程 HTTP 流式，适合云部署)
SDK 选择	避免重复造轮子	`@modelcontextprotocol/sdk` (官方 TS), `mcp` (官方 Python)

阶段 2：构建 MCP Server (核心开发)

这是开发者的主要工作区，目标是封装业务逻辑为标准接口。

1. 初始化项目

# TypeScript 示例
npm init -y
npm install @modelcontextprotocol/sdk zod

2. 定义能力 (Capabilities)

在 Server 代码中注册三类原语：

注册 Resources：定义 URI 模板（如 file://docs/{filename}），实现 readResource 回调。
注册 Tools：定义输入 Schema (JSON Schema)，实现 callTool 回调（执行具体逻辑）。
注册 Prompts：定义参数和返回的 Message 模板。

3. 实现业务逻辑

在回调函数中编写真实代码。例如，一个 "天气查询工具"：

接收参数：{ location: string }
逻辑：调用 OpenWeatherMap API
返回：结构化文本或 JSON

4. 启动服务

配置 Server 监听 Stdio 或 HTTP 端口，并处理生命周期事件（初始化、关闭）。

阶段 3：配置 MCP Host (集成对接)

让 LLM 应用发现并连接你的 Server。

1. 配置文件编辑

大多数 Host 使用 JSON 配置文件（如 Claude Desktop 的 claude_desktop_config.json）。

{
  "mcpServers": {
    "my-weather-tool": {
      "command": "node",
      "args": ["/path/to/server.js"],
      "env": { "API_KEY": "secret_key" }
    }
  }
}

2. 连接测试

重启 Host 应用，检查是否自动加载了新工具。通常在 UI 上会显示新发现的 "Tools" 列表。

阶段 4：调试与验证

日志分析：MCP 基于 JSON-RPC 2.0，所有消息均为 JSON 格式，易于抓包分析。
Inspector 工具：使用官方提供的 MCP Inspector (Web 界面) 手动发送请求测试 Server 响应，无需启动完整的 LLM。
权限控制：验证 Host 是否正确传递了用户上下文，确保工具不会越权访问。

阶段 5：部署与分发

本地开发：直接通过文件路径引用。
远程部署：将 Server 容器化 (Docker)，通过 SSE 模式暴露 HTTPS 端点，Host 配置 URL 即可连接。
市场发布：提交至 MCP Servers 仓库或 Dify/Coze 等平台的插件市场。

三、Mermaid 总结框图：MCP 开发与运行全景

这张图展示了从开发者构建 Server 到 Host 运行时调用 的完整数据流。

四、代码实战示例 (Python)

以下是一个极简的 Python MCP Server 示例，提供一个 "Hello World" 工具：

# server.py
from mcp.server import Server
from mcp.server.stdio import stdio_server
from mcp.types import Tool, TextContent

# 1. 初始化 Server
app = Server("demo-server")

# 2. 定义工具列表
@app.list_tools()
async def list_tools():
    return [
        Tool(
            name="say_hello",
            description="向指定用户说你好",
            inputSchema={
                "type": "object",
                "properties": {
                    "name": {"type": "string", "description": "用户名字"}
                },
                "required": ["name"]
            }
        )
    ]

# 3. 实现工具调用逻辑
@app.call_tool()
async def call_tool(name: str, arguments: dict):
    if name == "say_hello":
        user = arguments.get("name", "World")
        return [TextContent(type="text", text=f"Hello, {user}! Welcome to MCP.")]
    raise ValueError(f"Unknown tool: {name}")

# 4. 启动服务 (Stdio 模式)
if __name__ == "__main__":
    import asyncio
    async def main():
        async with stdio_server() as (read_stream, write_stream):
            await app.run(read_stream, write_stream, app.create_session())
    
    asyncio.run(main())

配置 Host (claude_desktop_config.json):

{
  "mcpServers": {
    "demo": {
      "command": "python",
      "args": ["/path/to/server.py"]
    }
  }
}

五、开发最佳实践与避坑指南

✅ 最佳实践

Schema 严谨性：工具的 inputSchema 必须严格符合 JSON Schema 标准，否则 LLM 无法正确生成参数。
错误处理友好：Tool 执行失败时，返回清晰的错误信息（而非堆栈跟踪），帮助 LLM 自我修正。
无状态设计：Server 应尽量保持无状态，依赖 Host 传递上下文，便于横向扩展。
安全性优先：
- 不要硬编码敏感密钥（使用 Host 传递的环境变量）。
- 对 Tool 的写操作（Delete/Update）增加二次确认机制或在 Prompt 层限制。