MCP Server 开发实战

1. MCP 是什么

MCP（Model Context Protocol，模型上下文协议） 是一种由 Anthropic 提出的开放协议，旨在通过标准化接口连接大型语言模型与外部数据源（如文件、数据库、API）和工具，解决AI模型与数据孤岛之间的整合难题。其核心目标是让大语言模型不仅能生成文本，还能安全、动态地访问和操作本地及远程资源，从而实现更复杂的任务执行能力。

2. 为什么大模型应用需要工具支持

想象你开发了一个"个人助手"AI应用，它能通过对话回答你的问题。其核心功能是将你的提问通过API传递给大语言模型（LLM），并将模型的回复返回给你。

然而，当问题涉及实时或未知信息时，比如"明天天气怎么样？"，大模型可能无法回答------因为它是基于历史数据训练的，不具备预测未来的能力。

这时，工具的作用就显现了。例如，你可以为"个人助手"集成一个天气查询工具，该工具能根据地区编码返回未来天气数据（尽管原始数据可能不够直观）。

具体流程如下：

工具集成：当用户提问时，"个人助手"会先检查可用工具（如天气查询），并将工具的功能和用法告知大模型。
智能决策：大模型判断是否需要调用工具。若需要，则驱动"个人助手"执行工具（如获取天气数据）。
优化输出：工具返回原始数据后，大模型会整合信息，生成清晰、自然的回答，最终呈现给用户。

通过工具扩展，大模型不仅能弥补自身局限（如实时数据缺失），还能将原始数据转化为用户友好的结果，显著提升实用性。

3. MCP 架构

总共分为了下面五个部分：

MCP Hosts: Hosts 是指大模型应用程序，像 Cursor, Claude Desktop、Cline 这样的应用程序。
MCP Clients: 客户端是用来在 Hosts 应用程序内维护与 Server 之间连接。
MCP Servers: 通过标准化的协议，为 Client 端提供上下文、工具和提示。
Local Data Sources: 本地的文件、数据库和 API。
Remote Services: 外部的文件、数据库和 API。

4. MCP 通信机制

MCP 目前定义了两种标准传输机制用于客户端和服务器通信：

stdio, 通过标准输入和标准输出通信
HTTP with Server-Sent Events (SSE)。在协议版本 2024-11-05 中，Streamable HTTP 取代了 HTTP+SSE 传输。

MCP 协议中，HTTP with SSE ****与 Streamable HTTP 的核心区别在于：前者依赖长连接（需独立端点如/sse），强制服务器维持状态化会话且无法恢复中断，导致高资源消耗和单向通信限制；而后者通过统一端点（如/message）按需升级为流式传输（支持会话恢复），兼容标准 HTTP 协议，允许服务器无状态运行，降低连接压力并实现灵活双向交互（通过普通请求或 SSE 动态切换），同时天然适配防火墙和代理环境，兼顾性能与扩展性，是更高效、灵活且兼容性强的现代协议设计。

4.1 stdio

在 stdio 传输中：客户端将 MCP 服务器作为子进程启动。服务器从标准输入（stdin）读取消息，并将消息发送到标准输出（stdout）。消息由换行符分隔。

4.2 HTTP with SSE

在 SSE 传输中，服务器作为一个独立的进程运行，可以处理多个客户端连接。

服务器必须提供两个端点：

SSE 端点，供客户端建立连接并从服务器接收消息
客户端向服务器发送消息的常规 HTTP POST 端点

当客户端连接时，服务器必须发送一个端点事件，其中包含客户端用于发送消息的 URI。所有后续客户端消息都必须以 HTTP POST 请求的形式发送到此端点。

服务器消息作为 SSE 消息事件发送。

4.3 Streamable HTTP

在流式 HTTP 传输中，服务器作为一个独立进程运行，可以处理多个客户端连接。此传输使用 HTTP POST 和 GET 请求。服务器可以选择使用服务器发送事件（SSE）来流式传输多个服务器消息。

向 服务器 发送消息

每个从客户端发送的 JSON-RPC 消息都必须是一个新的 HTTP POST 请求，发送到 MCP 端点。
客户端必须使用 HTTP POST 向 MCP 端点发送 JSON-RPC 消息。
客户端必须包含一个Accept 头，列出支持的内容类型为 application/json 和 text/event-stream。

监听来自 服务器 的消息

客户端可以发出一个 HTTP GET 请求到 MCP 端点。这可以用来打开一个 SSE 流，允许服务器与客户端通信，而无需客户端首先通过 HTTP POST 发送数据。
客户端必须包含一个 Accept 头，列出 text/event-stream 作为支持的内容类型。
服务器必须对此 HTTP GET 请求返回 Content-Type: text/event-stream，或者返回 HTTP 405 Method Not Allowed，表示服务器在此端点不提供 SSE 流。

5. MCP Server 核心能力组件

提示模板 (Prompts)： 指导和语言模型交互的预定义模板或指令
资源库 (Resources)： 结构化的数据或内容，为模型提供额外上下文
工具集 (Tools)： 允许模型执行或检索信息的函数

6. MCP Server 开发

安装工具和依赖：

bash 复制代码

curl -LsSf https://astral.sh/uv/install.sh | sh

# Create a new directory for our project
uv init weather
cd weather

# Create virtual environment and activate it
uv venv
source .venv/bin/activate

# Install dependencies
uv add "mcp[cli]" httpx

# Create our server file
touch weather.py

开发一个 MCP Server 示例，通信机制为 stdio，包含两个工具：

python 复制代码

from typing import Any
import httpx
from mcp.server.fastmcp import FastMCP

# Initialize FastMCP server
mcp = FastMCP("weather")

# Constants
API_BASE = "https://restapi.amap.com"

async def make_request(url: str) -> dict[str, Any] | None:
    """Make a request to the API with proper error handling."""
    async with httpx.AsyncClient() as client:
        try:
            response = await client.get(url, timeout=30.0)
            response.raise_for_status()
            return response.json()
        except Exception:
            return None


@mcp.tool()
async def get_adcode(address: str) -> str:
    """通过地址信息获取区域编码

    Args:
        address: 地址信息
    """
    geo_url = f"{API_BASE}/v3/geocode/geo?address={address}&output=JSON&key=ccafce2c43c45*****e708f06be57ac"
    geo_data = await make_request(geo_url)
    if geo_data and geo_data["status"] == "1":
        return geo_data["geocodes"][0]["adcode"]
    else:
        return "Unable to fetch adcode for this location."



@mcp.tool()
async def get_weather_info(adcode: str) -> str:
    """根据区域编码获取天气信息

    Args:
        adcode: 区域编码
    """
    # First get the forecast grid endpoint
    weather_info_url = f"{API_BASE}/v3/weather/weatherInfo?city={adcode}&extensions=all&key=ccafce2c43c45*****e708f06be57ac"
    weather_info_data = await make_request(weather_info_url)
    if weather_info_data and weather_info_data["status"] == "1":
        return weather_info_data
    else:
        return "Unable to fetch weather information for this location."

if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='stdio')

HTTP with SSE 通信方式启动

ini 复制代码

if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='sse')

Streamable HTTP 通信方式启动

ini 复制代码

if __name__ == "__main__":
    # Initialize and run the server
    mcp.run(transport='streamable-http')

7. 调试 MCP Server

MCP Inspector 是一个交互式开发工具，可用于测试和调试MCP服务器。

Inspector 直接通过 npx 运行，无需安装：

bash 复制代码

npx @modelcontextprotocol/inspector <command>

运行 Inspector，调试上面的 weather 示例：

访问调试页面

连接后，点击 List Tools，可以看到，weather mcp server 提供的两个工具

可以直接在页面选择并调用工具

8. 集成和测试 MCP Server

通过上面 MCP 架构可知，要使用 MCP Server，还需要有一个 Host，也就是应用，而且这个应用必须集成了MCP Client。常见的集成了MCP Client 的应用有 Claude Desktop、Cursor、Cline、CherryStudio 等。

这里我们使用 CherryStudio 进行集成和测试刚才开发的天气查询 MCP Server。

8.1 集成 MCP Server

与 MCP 三种通信机制相对应，MCP Server 的集成方式也有三种：

stdio

HTTP with SSE

Streamable HTTP

8.2 测试 MCP Server

未启用 MCP

启用 MCP后

从以上测试可以看出，当没有集成天气的 MCP Server 时，AI 应用没有办法给出具体准确的天气信息，只能给出一些查询方法。当集成了天气的 MCP Server 后，AI 应用可以给出具体准确的天气信息。

9. References

modelcontextprotocol.io/introductio...

10. 团队介绍

「三翼鸟数字化技术平台-ToC服务平台」以用户行为数据为基础，利用推荐引擎为用户提供"千人千面"的个性化推荐服务，改善用户体验，持续提升核心业务指标。通过构建高效、智能的线上运营系统，全面整合数据资产，实现数据分析-人群圈选-用户触达-后效分析-策略优化的运营闭环，并提供可视化报表，一站式操作提升数字化运营效率。