什么是 MCP

MCP，Model Context Protocol，模型上下文协议。

通过 MCP 协议，AI 应用（比如 Claude、ChatGPT、Qwen）可以访问指定的数据源（比如数据库、Markdown 文档）、运行指定的工具（比如搜索引擎、计算器）、执行指定的工作流等。

img

MCP 架构

服务器

服务器提供三种功能：

  • 资源（Resources）
  • 工具（Tools）
  • 提示（Prompts）

分层

MCP 由两层组成：数据层（Data Layer）、传输层（Transport Layer）。

数据层

数据层实现了一个基于 JSON-RPC 2.0 的交互协议，定义了消息结构和语义。

传输层

支持两种传输机制：

  • Stdio
  • Streamable HTTP

有些旧的还支持 SSE（Server-Sent Events）。

搭建 MCP 服务器

当前环境

  • python 版本

    1
2

    $ python3 --version
Python 3.12.5

操作命令

  • 创建目录

    1
2
3

    $ mkdir my_mcp_server

$ cd my_mcp_server

  • 创建并激活虚拟环境

    1
2
3

    $ python3 -m venv .venv

$ source .venv/Scripts/activate

    激活后，可以输入 deactivate 取消激活。

  • 更新 pip 工具

    1

    $ python3 -m pip install --upgrade pip

  • 安装 mcp 库

    1

    $ pip3 install "mcp[cli]"

代码

新建一个 main.py 文件。

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48

import logging
import mcp
import json

from functools import wraps
from mcp.server.fastmcp import FastMCP

logging.basicConfig(level=logging.DEBUG)
logger = logging.getLogger("my-mcp-server")

mcp_server = FastMCP("my-mcp-server", host="127.0.0.1", port=8080)

def log_mcp_request(func):
    @wraps(func)
    def wrapper(*args, **kwargs):
        payload = {
            "tool_name": func.__name__,
            "arguments": kwargs
        }
        logger.info(f"[MCP Request]: {json.dumps(payload, ensure_ascii=False)}")

        result = func(*args, **kwargs)
        return result
    return wrapper

# 定义 mcp server 工具
@mcp_server.tool()
@log_mcp_request
def calculate_sum(a: int, b: int) -> int:
    return a + b

# 定义 mcp server 资源
@mcp_server.resource("config://server/info")
@log_mcp_request
def get_server_info() -> str:
    return "Theme: Dark, Language: zh-CN, AutoSave: true"

# 定义 mcp server 提示
@mcp_server.prompt()
@log_mcp_request
def translate_role(text: str) -> str:
    return f"你是一个专业翻译。请将以下文本翻译成英语，要求信达雅：\n\n{text}"

def main():
    mcp_server.run(transport="streamable-http")

if __name__ == "__main__":
    main()

测试

当前环境：

  • CodeBuddy CN（4.9.14）

  • Node.js

    1
2

    $ node --version
v24.18.0

MCP 配置如下:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11

{
  "mcpServers": {
    "my-mcp-server": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "http://127.0.0.1:8080/mcp"
      ]
    }
  }
}

等效于执行以下命令：

1

$ npx mcp-remote "http://127.0.0.1:8080/mcp"
  1. npx 是 Node.js 的命令
  2. npx 会自动下载依赖

运行服务器：

1

$ python3 main.py

测试：

  • 连接成功后可以看到 MCP 服务器提供的能力

    image-20260625180219559

  • 对话运行在 Craft 模式

    image-20260625183532518

    image-20260625183619430

    image-20260625183729401

注意事项

  1. 需要小心处理 MCP 服务器中的调试信息、日志记录。

    • 如果是类型是 sdtio 的服务器，禁止将信息输出到标准输出 stdout。

      1. 这是因为写入 stdout 会破坏 JSON-RPC 消息并导致服务器崩溃。
      2. 对于 python 来说，禁止使用 print() 语句（print() 默认使用 stdout），可以使用 logging 模块代替。

版权声明

本文为「Zeepunt 日常随笔」的原创文章，遵循 CC BY-NC-ND 4.0 许可协议。允许在署名作者、注明原文链接且不作任何更改的前提下非商业性地分享本文。

原文链接：https://zeepunt.github.io/article/ai/ai%E6%90%AD%E5%BB%BA%E4%B8%80%E4%B8%AA-mcp-%E6%9C%8D%E5%8A%A1%E5%99%A8/