MCP 学习笔记

MCP 学习笔记（基于 mcp-server-test 项目）

一、MCP 与 Python SDK 简介

• MCP（Model Context Protocol）：一种标准协议，用来把工具、数据源等"接到"LLM 上，让 LLM 通过统一的方式调用。
• Python SDK ：mcp 包（已在 PyPI 上发布），提供：
  • FastMCP：高层封装，快速写 MCP server；
  • 支持 tools / resources / prompts 三大能力；
  • 支持多种传输：stdio、SSE、Streamable HTTP。

---

二、当前示例项目结构

大致结构：

mcp_server_test/
├── server.py                # MCP 服务入口（FastMCP）
├── pyproject.toml           # 项目 & 依赖（给 uv/hatch 用）
├── requirements.txt         # pip 依赖（简单版）
├── uv.lock                  # uv 生成的锁文件
└── mcp_server_test/
    └── __init__.py          # 占位包（用于构建）

项目主要用途：演示一个 Python 实现的 MCP server，提供简单的 tools/resources/prompts。

---

三、依赖与环境管理

• 核心依赖行 （requirements.txt）：

  mcp[cli]>=1.0.0

  • mcp：MCP Python SDK。
  • [cli]：安装 CLI 相关 extra 依赖。
  • >=1.0.0：版本不低于 1.0.0（实际装到 1.26.0）。

• 推荐用 uv 管理依赖（已在项目里使用）：

  cd /Users/work/coding/tc/mcp_server_test
  uv sync

  作用：

  • 解析 pyproject.toml；
  • 创建/更新 .venv；
  • 安装 mcp 等依赖。

• pip install -r requirements.txt 报错：找不到 mcp[cli]

  报错类似：

  Could not find a version that satisfies the requirement mcp[cli]>=1.0.0 (from versions: none)

  原因：

  • 当前 pip 使用的源（比如公司内网镜像）没有同步 mcp 包，或者被防火墙阻断；
  • 不是写法问题，PyPI 上是存在 mcp 的。

  解决思路：

  • 用 uv sync（默认走 PyPI）；

  • 或用 pip 临时直连 PyPI：

    pip install "mcp[cli]>=1.0.0" -i https://pypi.org/simple

---

四、示例 MCP Server 设计（server.py）

使用：

from mcp.server.fastmcp import FastMCP

mcp = FastMCP("mcp-server-test", json_response=True)

1. Tools（工具）

• add(a: int, b: int) -> int

  • 说明：将两个整数相加。

  • FastMCP 装饰器：

    @mcp.tool()
    def add(a: int, b: int) -> int:
        return a + b

• greet(name: str, language: str = "zh") -> str

  • 说明：根据姓名和语言生成问候语。
  • 行为：
    • language == "en" → Hello, {name}!
    • 其他 → 你好，{name}！

• echo(text: str, repeat: int = 1) -> str

  • 说明：将文本重复若干次（简单回声）。

2. Resources（资源，类似只读 API）

• info://server

  • 返回当前 MCP server 的基本信息（名称、实现方式、能力列表等，Markdown 文本）。

• greeting://{name}

  • 根据 name 返回一条欢迎语，例如： Hello, {name}! Welcome to the MCP server.

3. Prompts（提示模板）

• summarize_prompt(topic: str, style: str = "brief")

  • style="brief"：简要总结；
  • style="detailed"：详细总结，包含背景、要点和结论。

• code_review_prompt(file_path: str, focus: str = "all")

  • 生成代码审查提示词：
    • focus="security"：强调安全问题；
    • focus="style"：强调风格和可读性；
    • focus="all"：全面审查。

---

五、运行方式（开发/调试）

1. stdio 模式（给 Cursor 等本地客户端）

命令：

cd /Users/work/coding/tc/mcp_server_test
uv run python server.py

特点：

• 通过 标准输入输出（stdio） 与客户端（如 Cursor）通信；
• 不要在这个终端里随便敲回车或输入文本 ，否则会产生"空行"被当成 JSON 解析，报错：
  • Invalid JSON: EOF while parsing a value at line 2 column 0
  • 原因：MCP 把一行 \n 当成 JSON 解析失败。

2. HTTP 模式（给浏览器/Inspector 调试）

命令：

cd /Users/work/coding/tc/mcp_server_test
uv run python server.py --http

特点：

• 使用 Streamable HTTP 传输；
• Uvicorn 日志类似：
  • Uvicorn running on http://127.0.0.1:8000 ...
• MCP 端点：http://127.0.0.1:8000/mcp。

用浏览器访问 http://127.0.0.1:8000//mcp：

• 能连上（哪怕显示 404/空内容），说明服务在监听端口，已启动成功；
• 连接被拒绝/打不开 → 服务没起来或已退出。

---

六、在 Cursor 里配置 MCP（让 AI 能用这些 tools）

1. MCP 配置文件位置

• 全局配置 （所有项目共享）：
  • ~/.cursor/mcp.json
• 项目级配置 （推荐；可被 Cloud Agents 使用）：
  • /Users/work/coding/tc/mcp_server_test/.cursor/mcp.json

最终是两个文件合并，项目级优先。

2. 使用 uv 作为 command（项目级推荐）

在项目根目录下的 .cursor/mcp.json（示例）：

{
  "mcpServers": {
    "mcp-server-test": {
      "command": "uv",
      "args": ["run", "python", "server.py"]
    }
  }
}

要点：

• 确保 Cursor 打开的是 mcp_server_test 这个目录作为工作区根；
• 这样执行 uv run python server.py 的 cwd 正好是项目目录 ，能找到 server.py 和 pyproject.toml。

3. 使用虚拟环境 Python（避免找不到 mcp）

曾遇到错误：

ModuleNotFoundError: No module named 'mcp'

原因：Cursor 用的是系统/conda 的 Python，而不是项目 .venv 里的 Python，因此没装 mcp。

解决：在 mcp.json 里显式写 .venv 解释器 + 绝对路径：

{
  "mcpServers": {
    "mcp-server-test": {
      "command": "/Users/work/coding/tc/mcp_server_test/.venv/bin/python",
      "args": ["/Users/work/coding/tc/mcp_server_test/server.py"]
    }
  }
}

• 保证：
  • .venv 中已经通过 uv sync 安装了 mcp；
  • server.py 路径是绝对路径，不依赖 cwd。

4. "No server info found" 的含义

日志：

[error] No server info found

含义：

• Cursor 启动 MCP server 失败（例如找不到 server.py、或 Python 报错退出）；
• 没有收到任何 MCP 能力信息（tools/resources/prompts）。

常见原因：

• 在 全局 ~/.cursor/mcp.json 用了：

  "command": "uv",
  "args": ["run", "python", "server.py"]

  但 Cursor 的当前工作目录不是项目根目录 → 找不到 server.py。

解决：

• 使用项目级 .cursor/mcp.json；
• 或在全局配置中使用绝对路径和 cwd（前提是 Cursor 版本支持）。

---

七、MCP Inspector 使用流程（验证 tools 是否可用）

1. 启动 HTTP 模式 MCP server

   cd /Users/work/coding/tc/mcp_server_test
   uv run python server.py --http

2. 启动 MCP Inspector

   npx -y @modelcontextprotocol/inspector

3. 在浏览器里操作

   • 打开 Inspector 页面（一般是 http://localhost:5173 一类地址）；
   • 选择传输类型为 Streamable HTTP；
   • URL 填入：http://localhost:8000/mcp；
   • 点击 Connect。

4. 在 Inspector 里调 add 工具

   • 切到 Tools 标签；
   • 找到并点开 add；
   • 输入参数：
     • a: 1
     • b: 1
   • 点击调用（Call/Invoke）；
   • 看到返回结果为 2，就说明：
     • MCP server 正常；
     • add 工具注册和调用都正常。

同理，能在 Inspector 里调用 greet、echo、info://server 等，也说明这些能力都可用。

---

八、常见错误与排查总结

• Invalid JSON: EOF while parsing a value

  • 触发场景：stdio 模式下，有客户端或你自己向 stdin 发送了空行 （\n）；
  • 原因：MCP 把每一行当 JSON-RPC 消息解析，空行不是合法 JSON；
  • 处理：终端里运行 MCP 时，不要乱按回车；只让 Cursor 等 MCP 客户端来写 stdin。

• Could not find a version that satisfies the requirement mcp[cli]>=1.0.0

  • 原因：当前 pip 源没有 mcp 这个包（常见于内网镜像或网络受限）；
  • 处理：用 uv sync，或临时换回 PyPI 源安装。

• ModuleNotFoundError: No module named 'mcp'

  • 原因：Cursor 启动 MCP 时用的是没有安装依赖的 Python；
  • 处理：在 mcp.json 里显式指定项目 .venv 的 Python 解释器。

• No server info found

  • 原因：Cursor 没法把 MCP server 成功跑起来，拿不到任何能力信息；
  • 排查：确认 command/args 路径正确、cwd 正确、依赖安装完整。

---

九、验证 MCP 工具可用的几种方式

• 方式一：MCP Inspector

  • uv run python server.py --http；
  • Inspector 连接 http://localhost:8000/mcp；
  • 在 Tools 中调用 add 等，查看返回值。

• 方式二：在 Cursor 中让 Agent 调

  • 配好 .cursor/mcp.json；
  • 重启 Cursor，在对话里说「用 add 工具算 1 加 1」；
  • 若返回 2，说明 MCP server 与 Cursor 集成成功。

• 方式三：自己写客户端（进阶）

  • 用 mcp SDK 的 client 或自己写 HTTP/stdio 客户端；
  • 发送 MCP 请求（如 tools/call）；
  • 观察返回的结果和错误，以验证协议行为。

---

这份笔记涵盖了：项目结构、依赖管理、MCP server 实现、运行方式、Cursor 集成方式、MCP Inspector 使用及常见报错排查。以后你可以在这个基础上继续扩展更多工具、资源和提示模板。