FastMCP教程

一、FastMCP简介

1.1 定义

FastMCP是一个用于构建MCP（Model Context Protocol，模型上下文协议）服务器和客户端的Python框架。MCP是一种全新的、标准化的为大语言模型（LLMs）提供上下文和工具的方式，而FastMCP使得构建MCP服务器和客户端变得简单直观，让开发者能够用简洁的、符合Python风格的代码来创建工具、公开资源、定义提示等。

1.2 用途

FastMCP主要用于为大语言模型提供上下文和工具，使得大语言模型能够与外部系统进行交互，获取实时信息，执行特定任务。具体应用场景包括但不限于：

• 开发AI助手工具集：为Claude等AI助手提供本地功能扩展，构建特定领域的工具链。

• 数据库交互：安全地暴露数据库查询功能，提供schema信息给AI参考。

• 文件处理：读取和处理本地文件，处理图片等多媒体内容。

• API集成：包装现有API为AI可用的工具，提供统一的访问接口。

1.3 特点

• 快速：高级接口意味着更少的代码和更快的开发速度。

• 简单：用最少的模板代码构建MCP服务器。

• Pythonic：对Python开发者来说使用自然，代码结构清晰、语义明确，符合Python所倡导的简洁明了的编程理念。

• 完整：FastMCP旨在提供核心MCP规范的完整实现，能够支持MCP协议所规定的各种功能，包括资源、工具和提示的定义。

二、安装步骤

2.1 安装uv（可选）

在macOS上，可能需要先通过Homebrew安装uv：

brew install uv

2.2 安装FastMCP

可以使用以下命令安装FastMCP：

uv pip install fastmcp

也可以直接使用pip安装：

pip install fastmcp

2.3 验证安装

安装完成后，可以使用以下命令查看版本，验证是否安装成功：

fastmcp version

2.4 安装用于开发（可选）

如果需要进行开发，可以从源码安装：

git clone https://github.com/jlowin/fastmcp.git
cd fastmcp
# Install with dev dependencies
uv sync

安装完成后，可以运行测试：

pytest

三、核心概念

3.1 FastMCP服务器

FastMCP服务器是代表MCP应用程序的核心对象，它处理连接、协议细节和路由。以下是创建一个基本的FastMCP服务器的示例：

from fastmcp import FastMCP

# 创建一个FastMCP服务器实例
mcp = FastMCP(name="MyServer")

# 启动服务器
if __name__ == "__main__":
    mcp.run()

你还可以添加更多元数据来描述服务器：

from fastmcp import FastMCP

# 创建带有元数据的服务器
mcp = FastMCP(
    name="WeatherServer",
    description="提供天气预报和历史天气数据",
    version="1.0.0",
    contact={"name": "开发团队", "email": "[email protected]"}
)

if __name__ == "__main__":
    mcp.run()

3.2 工具（Tools）

工具允许LLMs通过执行Python函数来执行操作，类似于API的POST端点，非常适合涉及计算、外部API调用或副作用的任务。使用@mcp.tool()装饰同步或异步函数，FastMCP会根据类型提示和文档字符串自动生成必要的MCP模式。以下是一个简单的工具示例：

from fastmcp import FastMCP

mcp = FastMCP(name="CalculatorServer")

@mcp.tool()
def add(a: float, b: float) -> float:
    """将两个数字相加。
    
    Args:
        a: 第一个数字
        b: 第二个数字
        
    Returns:
        两个数字的和
    """
    return a + b

@mcp.tool()
def multiply(a: float, b: float) -> float:
    """将两个数字相乘。
    
    Args:
        a: 第一个数字
        b: 第二个数字
        
    Returns:
        两个数字的乘积
    """
    return a * b

if __name__ == "__main__":
    mcp.run()

FastMCP还支持异步工具函数，对于需要I/O操作的任务特别有用：

import asyncio
from fastmcp import FastMCP

mcp = FastMCP(name="AsyncServer")

@mcp.tool()
async def fetch_data(url: str) -> dict:
    """从指定URL异步获取数据。
    
    Args:
        url: 要获取数据的URL
        
    Returns:
        获取的数据字典
    """
    # 模拟异步网络请求
    await asyncio.sleep(1)
    return {"url": url, "status": "success", "data": "示例数据"}

工具函数还可以使用上下文对象来访问额外功能：

from fastmcp import FastMCP
from fastmcp.server import Context

mcp = FastMCP(name="ContextServer")

@mcp.tool()
async def log_message(ctx: Context, message: str) -> bool:
    """记录消息并返回成功状态。
    
    Args:
        ctx: FastMCP上下文对象
        message: 要记录的消息
        
    Returns:
        操作是否成功
    """
    # 使用上下文发送日志
    ctx.info(f"收到消息: {message}")
    return True

3.3 资源（Resources）

资源用于向LLMs提供数据和上下文信息，类似于API的GET端点，主要用于读取数据而非执行操作。在URI中使用占位符可创建接受参数的动态模板，从而允许客户端请求特定数据子集。以下是一个静态资源和动态资源模板的示例：

# 静态资源
@mcp.resource("config://version")
def get_version():
    return "2.0.1"

# 动态资源模板
@mcp.resource("users://{user_id}/profile")
def get_profile(user_id: int):
    # Fetch profile for user_id...
    return {"name": f"User {user_id}", "status": "active"}

3.4 提示（Prompts）

提示定义可重用的消息模板以指导LLM交互，使用@mcp.prompt()装饰函数，返回字符串或对象。以下是一个提示示例：

@mcp.prompt()
def summarize_request(text: str) -> str:
    """Generate a prompt asking for a summary."""
    return f"Please summarize the following text: \n\n {text}"

3.5 上下文（Context）

通过添加参数来访问工具、资源或提示中的MCP会话功能。Context提供了以下方法：

• 日志记录：使用ctx.info()、ctx.error()等将消息记录到MCP客户端。

• LLM采样：用于从客户端的LLM请求完成，ctx.sample()。

• HTTP请求：用于向其他服务器发出HTTP请求，ctx.http_request()。

• 资源访问：用于访问服务器上的资源，ctx.read_resource()。

• 进度报告：用于向客户端报告进度，ctx.report_progress()。 以下是一个使用上下文的工具函数示例：

from fastmcp import FastMCP, Context

mcp = FastMCP("My MCP Server")

@mcp.tool()
async def process_data(uri: str, ctx: Context):
    # Log a message to the client
    await ctx.info(f"Processing {uri}...")
    # Read a resource from the server
    data = await ctx.read_resource(uri)
    # Ask client LLM to summarize the data
    summary = await ctx.sample(f"Summarize: {data.content[:500]}")
    # Return the summary
    return summary.text

3.6 MCP客户端

使用FastMCP客户端可以以编程方式与任何MCP服务器进行交互，它支持各种传输方式（Stdio、SSE、In - Memory），并且经常自动检测正确的传输方式。以下是一个客户端使用示例：

from fastmcp import Client

async def main():
    # Connect via stdio to a local script
    async with Client("my_server.py") as client:
        tools = await client.list_tools()
        print(f"Available tools: {tools}")
        result = await client.call_tool("add", {"a": 5, "b": 3})
        print(f"Result: {result.text}")
    # Connect via SSE
    async with Client("http://localhost:8000/sse") as client:
        # ... use the client
        pass

四、代码示例及详细解释

4.1 简单加法工具服务器示例

from fastmcp import FastMCP

mcp = FastMCP("Demo 🚀")

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

if __name__ == "__main__":
    mcp.run()

解释：

• from fastmcp import FastMCP：导入FastMCP类。

• mcp = FastMCP("Demo 🚀")：创建一个名为Demo 🚀的FastMCP服务器实例。

• @mcp.tool()：使用装饰器将add函数注册为一个工具。

• def add(a: int, b: int) -> int：定义一个名为add的函数，接受两个整数参数a和b，并返回它们的和。

• if __name__ == "__main__": mcp.run()：如果该脚本作为主程序运行，则启动服务器。

4.2 包含多个工具和资源的服务器示例

from fastmcp import FastMCP

mcp = FastMCP(name="MyApp")

@mcp.tool()
def add(a: float, b: float) -> float:
    """将两个数字相加。
    
    Args:
        a: 第一个数字
        b: 第二个数字
        
    Returns:
        两个数字的和
    """
    return a + b

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

if __name__ == "__main__":
    mcp.run()

解释：

• 除了定义了add工具外，还定义了一个动态资源get_greeting。

• @mcp.resource("greeting://{name}")：将get_greeting函数注册为一个资源，使用占位符{name}创建动态资源模板。

4.3 客户端使用示例

from fastmcp import Client

async def main():
    async with Client("path/to/server") as client:
        # Call a tool
        result = await client.call_tool("add", {"a": 5, "b": 3})
        print(result)
        
        # Read a resource
        res = await client.read_resource("db://users/123/profile")
        print(res)

解释：

• from fastmcp import Client：导入Client类。

• async with Client("path/to/server") as client：创建一个客户端实例，并连接到指定的服务器。

• result = await client.call_tool("add", {"a": 5, "b": 3})：调用服务器上的add工具，并传入参数a = 5和b = 3。

• res = await client.read_resource("db://users/123/profile")：读取服务器上的指定资源。

五、运行服务器

5.1 开发模式（推荐用于构建和测试）

fastmcp dev fastmcp - test.py

这将启动一个互动式测试环境，包括MCP Inspector，方便你测试工具和资源的功能。

5.2 Claude Desktop集成（常规使用）

使用install命令将你的服务器设置为在Claude Desktop应用程序中持久使用：

fastmcp install server.py

你还可以自定义安装名称：

fastmcp install server.py --name "我的工具"

添加额外依赖项和环境变量：

fastmcp install server.py --with requests - v API_KEY = 123 - f.env

5.3 直接执行（高级用例）

直接运行你的服务器脚本，你需要自己管理环境和依赖项：

python server.py

或

uv run python server.py

六、总结

FastMCP是一个强大的Python框架，它为开发者提供了一种简单、高效的方式来构建MCP服务器和客户端，使得大语言模型能够更好地与外部系统进行交互。通过本文的教程，你应该对FastMCP有了一个基本的了解，并且能够使用它来创建自己的MCP应用程序。在实际开发中，你可以根据具体需求进一步扩展和优化你的应用程序。