mcp python-sdk使用记录

1 前言

MCP（Model Context Protocol）是连接 AI 模型与外部工具、数据源的"标准适配器"。它让模型不再只是"大脑"，而是变成了能调用真实世界工具的"操盘手"。

1.1 MCP 解决了什么痛点？

在没有 MCP 之前，AI 的能力边界被锁死在训练数据里。它知道"怎么查天气"的语法，但无法真正调用天气 API；它懂代码，但无法直接操作你的文件系统。

MCP 的出现，就是为了拆掉这堵墙。它定义了一套标准协议，让任何外部资源（数据库、API、本地工具）都能被安全、规范地挂载到模型上。

1.2 MCP 的三大核心作用

1. 能力扩展（Breaking Limits）

   这是最直观的作用。MCP 允许模型突破纯文本交互的限制，获得"动手能力"。

   操作现实工具：通过 MCP Server，模型可以执行终端命令、读取数据库、发送邮件、管理日历。

   实时数据获取：接入新闻源、股票行情、天气 API，让回答基于最新信息而非陈旧训练数据。

2. 上下文管理（Context Management）

   MCP 是模型的高效"外置记忆库"。

   突破 Token 限制：将庞大的代码库、文档库通过 MCP 挂载，模型无需将全部内容塞入对话上下文，即可按需检索。

   持久化记忆：MCP 可以连接向量数据库，帮模型记住跨会话的对话历史或用户偏好。

3. 安全与管控（Safety & Control）

   这是 MCP 在架构设计上的关键优势。

   权限沙箱：MCP Server 运行在独立进程中，模型只能通过定义好的"工具（Tools）"进行交互。你可以放心让模型查数据库，但绝不允许它执行 rm -rf /。

   环境隔离：开发和生产环境可以配置不同的 MCP Server，避免模型在测试时误操作线上数据。

1.3 一个形象的比喻

如果把大语言模型（LLM）比作"大脑"，那么 MCP 就是"神经末梢和感觉器官"。

没有 MCP：大脑很聪明，但被关在黑屋子里，只能靠回忆（训练数据）回答问题。

有了 MCP：大脑长出了手（操作工具）、眼睛（读取数据）、耳朵（监听事件），能真正感知并改变外部世界。

安装uv

uv作为新的python主流包管理工具，构建快于pip。

安装官网指令: https://docs.astral.sh/uv/

win:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

mac & Linux

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

构建项目

新建一个文件夹，在该文件夹根目录构建python版本为3.13的python项目

uv init -p 3.13

安装依赖, 把mcp的开发依赖安装上

uv add "mcp[cli]"

python-sdk

https://github.com/modelcontextprotocol/python-sdk

main.py的内容

"""
FastMCP quickstart example.

Run from the repository root:
    uv run examples/snippets/servers/fastmcp_quickstart.py
"""

from mcp.server.fastmcp import FastMCP

# Create an MCP server
mcp = FastMCP("Demo", json_response=True)


# Add an addition tool
@mcp.tool()
def add(a: int, b: int) -> int:
    """Add two numbers, ex  124 + 11 = 135"""
    return a + b


# Add an addition tool
@mcp.tool()
def chen_cal_add(a: int, b: int) -> int:
    """chen cal add, ex 100 chen 100 = 500"""
    return a + b * 2


# Add a dynamic greeting resource
@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """Get a personalized greeting"""
    return f"Hello, {name}!"


# Add a prompt
@mcp.prompt()
def greet_user(name: str, style: str = "friendly") -> str:
    """Generate a greeting prompt"""
    styles = {
        "friendly": "Please write a warm, friendly greeting",
        "formal": "Please write a formal, professional greeting",
        "casual": "Please write a casual, relaxed greeting",
    }

    return f"{styles.get(style, styles['friendly'])} for someone named {name}."


# Run with streamable HTTP transport
if __name__ == "__main__":
    mcp.run(transport="streamable-http")
    # mcp.run(transport="sse")

将这个mcp server运行起来

cherryStudio

还需要一个ai客户端来交互。cherrystudio下载官网: https://www.cherry-ai.com/

mcp配置:

我们可以看见会调用后端的mcp服务:

后台能看到调用记录

StreamableHTTP和Server-Sent Events（SSE）都是用于实现实时数据传输的技术，但它们之间有一些关键的区别：

1. 用途和场景：

   • StreamableHTTP：通常用于客户端和服务端之间建立一个持久的HTTP连接，通过这个连接可以持续发送数据流。它适用于需要双向通信的场景，比如实时聊天，或者需要在客户端和服务器之间进行数据交换的应用。
   • SSE（Server-Sent Events）：是一种用于从服务器向客户端推送实时更新的协议。它允许服务器在客户端打开连接后持续发送数据流，而客户端只需要接收这些数据，而不必主动请求。SSE非常适合单向数据流（即从服务器到客户端）的应用场景，比如实时新闻更新、股票行情推送等。

2. 通信方向：

   • StreamableHTTP：可以支持双向通信，即客户端和服务器都可以通过同一个连接发送和接收数据。
   • SSE：只支持从服务器到客户端的单向通信，客户端无法通过SSE向服务器发送数据。

3. 数据格式：

   • StreamableHTTP：数据可以是任意的格式，比如JSON、XML、文本等，具体取决于实现。
   • SSE ：数据格式通常是纯文本，使用text/event-stream MIME类型，且数据以事件的形式发送，每个事件包含一个事件类型和数据内容。

4. 连接管理：

   • StreamableHTTP：需要客户端和服务器都维护连接状态，通常需要使用HTTP/1.1的持久连接（keep-alive）或HTTP/2。
   • SSE：连接一经建立，服务器可以一直保持该连接以推送数据，直到客户端关闭连接或服务器主动关闭连接。

5. 兼容性：

   • SSE：是基于标准的HTTP协议，兼容性较好，大多数现代浏览器都支持。
   • StreamableHTTP：通常指的是使用HTTP流的方式，可能需要更复杂的实现，兼容性可能取决于具体的实现方式。

总结来说，SSE 是一个更轻量级、适用于单向数据流的协议，而StreamableHTTP更广泛，适用于需要双向通信的实现实时数据流的场景。