software

模型上下文协议 (MCP)：全面技术报告

发布: (2025年12月3日 GMT+8 12:43)
8 min read
原文: Dev.to

Source: Dev.to

执行摘要

大型语言模型（LLMs）快速集成到生产软件中，暴露出一个关键的互操作性瓶颈。开发者在尝试将推理引擎（如 Claude 3.5 Sonnet、GPT‑4o）与专有数据源（PostgreSQL、Slack、GitHub）对接时，行业面临 “N×M” 集成问题：每个新模型都需要为每个数据源编写独立的连接器，导致生态系统碎片化且脆弱。Anthropic 于 2024 年底推出的模型上下文协议（Model Context Protocol，MCP）成为 AI 领域的 “USB‑C”，它提供了一套标准化、开源的规范，将智能与数据解耦。

本报告是一份详尽的技术资源，旨在帮助开发团队实现、部署并传播 MCP 方案。内容覆盖 MCP 服务器开发的全生命周期——从 JSON‑RPC 消息层的理论架构到 Python 与 TypeScript 的实际实现；详细阐述在 Cloudflare Workers、Google Cloud Run 等云原生基础设施上的部署策略，并提供严格的安全框架以实现代理访问。此外，文档还分析了技术写作平台（Dev.to、Medium、Hashnode）并提供了结构化的高影响力视频演示制作指南，帮助团队成员实现出版目标。

1. 模型上下文协议的架构范式

模型上下文协议代表了 AI 系统与外部世界交互方式的根本转变。不同于过去将 “工具” 直接注入提示或通过专有函数调用 API 处理的做法，MCP 对连接进行标准化。

1.1 互操作性危机：N×M 问题

在 MCP 出现之前，集成格局被供应商锁定所主导。开发者为 OpenAI 的 Assistant API 构建的 “Chat with PDF” 工具，难以迁移到 Anthropic 的 Claude 或本地运行在 Ollama 上的 Llama 3 模型。

  • “N” 模型： 每个模型提供商（OpenAI、Google、Anthropic、Meta）都有自己的工具模式。
  • “M” 数据源： 每个数据源（Salesforce、Zendesk、本地文件）都需要为每个模型定制适配器。

这种组合爆炸式的维护工作通过 MCP 的标准化接口得以解决。单一 MCP 服务器充当通用适配器，以统一格式暴露资源（数据）和工具（函数），任何符合 MCP 标准的客户端（Host）都可以发现并使用它们。

1.2 核心原语：资源、提示与工具

协议定义了三类主要原语，以映射代理工作流的多样需求。

原语功能类比代理使用场景
Resources（资源）暴露可读取的数据。HTTP GET 或文件读取让 LLM 访问日志、代码文件或数据库行，而无需执行代码。
Prompts（提示）可复用的交互模板。斜杠命令（/fix）预包装复杂系统指令（例如 “审查此代码的安全漏洞”）。
Tools（工具）可执行函数。HTTP POST 或 RPC 调用让 LLM 执行操作：修改数据库、发送邮件或进行计算。

1.3 传输层：JSON‑RPC 2.0

在网络层面，MCP 基于 JSON‑RPC 2.0，这是一种语言无关、可读性强的协议。

  • 无状态性： 每个请求都包含所有必要上下文（method、params、ID）。
  • 异步性： 支持异步消息传递，适用于模型推理或工具执行可能耗时较长的 AI 场景。

MCP 支持两种传输机制：

  • Stdio（标准输入/输出）： 用于本地连接。Host 将 Server 作为子进程启动，提供高安全性（进程隔离）和零网络延迟。这是 Claude Desktop 等桌面客户端的默认方式。
  • SSE（服务器发送事件）/ HTTP： 用于远程连接。Client 建立 HTTP 连接以接收事件（服务器→客户端），并使用 HTTP POST 发送请求（客户端→服务器）。这使得模型与工具可以部署在不同的基础设施上。

2. 实施指南：使用 Python 构建 MCP 服务器

本节为负责 Python 实现的团队成员提供技术基础，亦可作为 “使用 FastMCP 构建高性能 MCP 服务器” 文章的内容框架。

2.1 Python 生态与 FastMCP

Python 生态使用 mcp SDK，特别是 FastMCP 类，它抽象了底层协议的复杂性。FastMCP 利用 Python 类型提示自动生成协议所需的 JSON Schema，使用体验类似 FastAPI。

2.2 环境搭建

为确保可复现的环境，我们使用 uv——一种现代的 Python 包管理器，取代 pip 与 venv，提供统一工作流。

步骤式搭建

mkdir mcp-calculator-py
cd mcp-calculator-py
uv init
uv add "mcp[cli]"

上述命令会安装核心 MCP 库以及用于调试的命令行界面工具。

2.3 开发一个计算器服务器

下面的代码演示了一个实现数学运算的稳健 MCP 服务器，重点展示 @mcp.tool() 装饰器和文档字符串的解析。

文件: server.py

from mcp.server.fastmcp import FastMCP
import math

# Initialize the FastMCP server with a descriptive name
mcp = FastMCP("Advanced-Calculator")

@mcp.tool()
def add(a: int, b: int) -> int:
    """
    Add two integers together.

    Args:
        a: The first integer.
        b: The second integer.
    """
    return a + b

@mcp.tool()
def calculate_bmi(weight_kg: float, height_m: float) -> float:
    """
    Calculate Body Mass Index (BMI).

    Args:
        weight_kg: Weight in kilograms.
        height_m: Height in meters.
    """
    if height_m  str:
    """
    Retrieve the calculation history (Static Resource Example).
    """
    return "No history available in this session."

if __name__ == "__main__":
    # The run method automatically selects the transport (stdio/sse)
    mcp.run()

代码分析

  • 装饰器魔法： @mcp.tool() 会检查函数签名，生成描述必需参数的 JSON Schema，并将工具注册到服务器。
  • 文档字符串： 描述（如 “Calculate Body Mass Index”）会随同发送给 LLM，使模型能够理解何时调用该工具。
  • 错误处理： 抛出的 ValueError 会被 SDK 捕获并以标准化的 JSON‑RPC 错误返回给客户端，防止服务器崩溃。

2.4 使用 MCP Inspector 进行测试

在连接 Claude 等客户端之前，开发者应使用 MCP Inspector 验证功能。

mcp dev server.py

该命令启动服务器并打开一个网页界面（通常是 http://localhost:5173）。在此界面中，开发者可以：

  • 查看已加载的工具列表。
  • 手动输入参数（例如 weight_kg=70, height_m=1.75）并执行工具。
  • 检查原始 JSON 日志，确保 schema 与响应符合预期。
Back to Blog

相关文章

阅读更多 »