交互式MCP与FastMCP指南

奠定基石：理解模型上下文协议 (MCP)

本部分旨在建立 MCP 的基本概念。通过阐释 MCP 旨在解决的问题，并定义其核心架构组件与基本要素，为后续深入探讨实现细节提供必要的理论基础。

1.1 “为何需要”：破解大语言模型集成难题

在 MCP 出现之前，将大语言模型 (LLM) 与外部工具和数据源连接是一个充满临时解决方案的混乱过程。每个集成都需要定制的 API、复杂的 JSON 格式和艰巨的状态管理。

MCP 如同一个“为 AI 设计的 USB-C 端口”，创建了一个通用的、可互操作的标准，让不同的 AI 应用和服务能够无缝连接，从根本上改变了集成模式。

它将复杂的 “N 对 M” 网状连接，转变为一个更易于管理的 “N 对 1 对 M” 模式：多个应用通过一个标准协议 (MCP) 与多个工具交互。

之前：点对点混乱

LLM App 1

Tool A

LLM App 2

Tool B

每个连接都需要定制开发

之后：MCP 标准化

LLM App 1

LLM App 2

→

MCP

→

Tool A

Tool B

1.2 MCP 架构：主机、服务器与客户端

整个工作流程确保了功能执行与语言生成之间的清晰分离和高效协作。将鼠标悬停在下面的组件上以了解更多信息。

🖥️

MCP 主机 (Host)

用户直接交互的应用 (如 IDE)，是工作流的“指挥中心”。

主机负责协调用户、LLM 和 MCP 服务器之间的通信。

⚙️

MCP 服务器 (Server)

暴露能力的轻量级程序，是开发者构建的核心。

FastMCP 就是用于构建这类服务器的框架。

🔌

MCP 客户端 (Client)

嵌入在主机内，负责与服务器直接通信。

客户端管理底层的通信协议，并建立一对一连接。

1.3 “包含什么”：MCP 的核心要素

一个 MCP 服务器可以提供三种主要类型的功能，类似于 REST API 的不同端点。

资源 (Resources)

类似 GET

用于暴露只读数据（如文件内容、数据库记录）到 LLM 上下文。其核心职责是“提供信息”。

工具 (Tools)

类似 POST / PUT

代表可由 LLM 调用的函数，用于执行操作、运行代码或产生副作用。其核心职责是“执行动作”。

提示 (Prompts)

AI 的"脚本"

可复用的模板，用于指导 LLM 的交互模式和构建其响应，规范 AI 的行为。

付诸实践：使用 FastMCP 框架构建

本部分将从理论转向实践，通过一个分步指南，带你构建第一个 FastMCP 服务器，并重点阐述该框架的特性和设计哲学。

2.1 你的第一个 FastMCP 服务器：分步指南

1安装

强烈推荐使用 `uv` 来安装 FastMCP。

uv pip install fastmcp

2实例化服务器

创建一个 `FastMCP` 对象实例，并为你的服务器命名。

# server.py
from fastmcp import FastMCP

mcp = FastMCP("我的第一个应用")

3定义一个工具

使用 `@mcp.tool()` 装饰器。FastMCP 会自动从函数的类型提示和文档字符串中生成符合规范的模式。

# server.py
from fastmcp import FastMCP

mcp = FastMCP("演示 🚀")

@mcp.tool()
def add(a: int, b: int) -> int:
    """将两个数字相加"""
    return a + b

4运行服务器

在文件末尾添加启动代码，并使用命令行工具运行。

# 在 server.py 文件末尾添加
if __name__ == "__main__":
    mcp.run()

# 在终端中运行:
# fastmcp run server.py

2.2 深入探索 FastMCP 组件

定义资源

与工具类似，但使用 `@mcp.resource()`。可以使用 `{}` 创建动态 URI。

@mcp.resource("greeting://{name}")
def get_greeting(name: str) -> str:
    """获取个性化问候语"""
    return f"你好, {name}!"

处理复杂输入

可以直接使用 Pydantic 模型作为类型提示，FastMCP 会自动处理转换。

from pydantic import BaseModel

class UserProfile(BaseModel):
    name: str
    age: int

@mcp.tool()
def create_user(profile: UserProfile):
    ...

`Context` 对象

自动作为第一个参数传递，提供日志记录、进度报告、访问其他资源等强大功能。

处理图像和文件

`Image` 类可以自动处理图像数据的转换和 MIME 类型。

调试、测试与运行模式

本部分将聚焦于开发流程中的关键环节：如何高效地测试、调试你的 MCP 服务器，以及如何处理不同的运行方式。

4.1 测试你的 MCP 服务

测试是确保服务质量的基石。FastMCP 提供了两种主要的测试方式。

方法一：交互式测试 (使用 MCP Inspector)

这是开发和调试过程中的首选方式。FastMCP 自带了一个名为 MCP Inspector 的强大 Web 调试工具。

使用 `dev` 命令启动，它会自动打开一个浏览器窗口，你可以在其中直观地看到所有工具和资源，并直接填写参数进行调用。执行结果、日志和错误都会清晰地显示出来。

fastmcp dev your_server_file.py

方法二：程序化测试 (使用 `fastmcp.Client`)

对于自动化测试（如 CI/CD），你可以使用 `fastmcp.Client` 编写测试脚本来调用服务器。

# test_client.py
import asyncio
from fastmcp import Client
from fastmcp.transport import StdioTransport

async def main():
    # 假设服务器文件是 basic_server.py
    transport = StdioTransport.create_process(["python", "basic_server.py"])
    client = Client(transport)
    await client.connect()
    try:
        result = await client.tools.greet(name="测试者")
        assert result == "你好, 测试者! 欢迎使用 MCP。"
        print("✅ 测试通过")
    finally:
        await client.disconnect()

if __name__ == "__main__":
    asyncio.run(main())

4.2 在 PyCharm 中调试

在 PyCharm 中调试 MCP 服务非常直接。关键在于正确设置“运行/调试配置”，而不是依赖 `fastmcp` 命令行工具。

步骤 1: 在 PyCharm 右上角，点击 "Add Configuration..."。

步骤 2: 点击 `+` 号，选择 "Python"。

步骤 3: 填写配置，如下图所示：

Name: Debug MCP Server

Script path: /path/to/your/server.py

Parameters: (留空)

步骤 4: 在你的代码中（例如工具函数内部）设置断点。

步骤 5: 点击 PyCharm 右上角的**绿色小虫子 (Debug) 图标**启动调试会话。

步骤 6: 使用任意一种测试方法（如 MCP Inspector 或测试脚本）从外部调用你的工具，即可触发断点并开始调试。

4.3 解决模块化项目中的 `fastmcp dev` 路径问题

从模块化运行 (`python -m my_package.server`) 切换到脚本化开发 (`fastmcp dev ...`) 是一个常见的痛点，其根源在于 Python 的导入路径机制。

问题根源：执行上下文的差异

当使用 python -m my_package.server 运行时，Python 会将你的**项目根目录**添加到搜索路径中。因此，在 `server.py` 内部的 `from . import utils` 或 `from my_package import models` 这样的导入能够成功。
当直接运行 fastmcp dev my_package/server.py 时，Python 的执行上下文是 `my_package/` 目录。它不知道上层目录的存在，导致所有基于包的导入（无论是相对的还是绝对的）都会因找不到模块而失败 (`ImportError`)。

解决方案：创建开发入口文件

最佳实践是在你的**项目根目录**下创建一个专门用于开发和调试的入口文件，例如 `dev_server.py`。这个文件不会用于生产环境，只为了给 `fastmcp dev` 提供一个正确的启动点。

步骤 1: 在你的项目根目录（与 `src` 或你的主包目录同级）下，创建新文件 `dev_server.py`。

步骤 2: 将以下代码粘贴到 `dev_server.py` 中，并确保导入路径与你的项目结构匹配。

# dev_server.py
# 该文件为 `fastmcp dev` 提供一个正确的项目根入口点。

# 假设你的 mcp 实例在 src/github_stars_mcp/server.py 中定义
from src.github_stars_mcp.server import mcp

# `fastmcp dev` 会自动发现这个名为 `mcp` 的实例并用它来启动开发服务器。
# 无需添加 if __name__ == "__main__" 代码块。

步骤 3: 现在，你可以从项目根目录运行以下命令来启动开发服务器：

fastmcp dev dev_server.py

这个方法通过从根目录启动，确保了 Python 的导入系统能够像 `python -m` 那样正常工作，从而解决了所有路径问题，且无需修改任何项目源代码。

总结与快速上手参考

本部分将综合关键要点，并为希望开始使用 MCP 和 FastMCP 的开发者提供一份实用的、精炼的参考指南。

5.1 核心 FastMCP 组件 (Python)

组件	用途	示例语法
`FastMCP(...)`	初始化 MCP 服务器实例，是所有应用的起点。	`mcp = FastMCP(name="我的应用")`
`@mcp.tool()`	装饰器，将一个 Python 函数暴露为可执行的工具。	`@mcp.tool()`
`@mcp.resource(...)`	装饰器，将一个函数暴露为可供读取的数据资源。	`@mcp.resource("data://items/{id}")`
`Context`	作为参数传递，提供日志、进度报告等服务器端功能。	`def my_tool(ctx, ...):`

5.2 基础服务器模板

这是一个完整的、可直接复制粘贴的“Hello, World”服务器示例，整合了所有基本要素。

# basic_server.py
from fastmcp import FastMCP, Context

# 1. 实例化服务器
mcp = FastMCP(name="基础模板服务器")

# 2. 定义一个工具
@mcp.tool()
def greet(name: str) -> str:
    """生成一个简单的问候语。"""
    return f"你好, {name}! 欢迎使用 MCP。"

# 3. 定义一个资源
@mcp.resource("server://status")
def get_status(ctx: Context) -> dict:
    """返回服务器的当前状态。"""
    ctx.info("正在请求服务器状态...")
    return {"status": "ok", "server_name": mcp.name}

# 4. 运行服务器
if __name__ == "__main__":
    mcp.run()