快速手搓一个MCP服务指南（一）：FastMCP 快速入门指南详解

FastMCP 快速入门指南详解

一、FastMCP 简介与指南目的

FastMCP 是一个用于搭建工具型服务器的框架，可通过简单的代码快速创建支持工具调用的服务。本指南旨在帮助用户从零开始搭建首个 FastMCP 服务器，涵盖服务器创建、工具添加、测试及运行的全流程。

二、创建 FastMCP 服务器

1. 核心步骤：初始化服务器实例

• 操作目的：创建 FastMCP 服务的基础框架

• 代码实现 ：

  # my_server.py
  from fastmcp import FastMCP
  
  mcp = FastMCP("My MCP Server")

• 关键说明 ：

  • 导入 FastMCP 类后，通过实例化该类创建服务器对象
  • 实例化时传入的字符串（如 "My MCP Server"）为服务器名称，用于标识服务

三、添加工具（Tool）到服务器

1. 工具的作用与注册方式

• 工具本质：服务器中可被客户端调用的功能函数

• 代码示例 ：

  from fastmcp import FastMCP
  
  mcp = FastMCP("My MCP Server")
  
  @mcp.tool  # 装饰器注册工具
  def greet(name: str) -> str:
      return f"Hello, {name}!"

• 核心逻辑 ：

  • 使用 @mcp.tool 装饰器将普通函数注册为服务器可识别的工具
  • 函数需定义明确的参数类型和返回类型（如 name: str），便于客户端调用

四、测试服务器功能

1. 异步客户端的使用方式

• 测试目的：验证服务器工具是否可被正确调用

• 完整测试代码 ：

  import asyncio
  from fastmcp import FastMCP, Client
  
  mcp = FastMCP("My MCP Server")
  
  @mcp.tool
  def greet(name: str) -> str:
      return f"Hello, {name}!"
  
  client = Client(mcp)  # 客户端指向服务器对象
  
  async def call_tool(name: str):
      async with client:  # 进入客户端上下文
          result = await client.call_tool("greet", {"name": name})
          print(result)
  
  asyncio.run(call_tool("Ford"))  # 执行异步调用

• 关键要点 ：

  • FastMCP 基于异步编程（asyncio），需使用 async/await 语法
  • Client(mcp) 直接关联服务器对象，无需网络配置
  • async with client 用于管理客户端连接上下文，确保资源正确释放
  • call_tool 方法接收工具名称和参数，返回异步执行结果

五、运行服务器

1. 直接通过 Python 运行

• 代码修改 ：在服务器文件中添加运行逻辑

  from fastmcp import FastMCP
  
  mcp = FastMCP("My MCP Server")
  
  @mcp.tool
  def greet(name: str) -> str:
      return f"Hello, {name}!"
  
  if __name__ == "__main__":
      mcp.run()  # 启动服务器

• 执行命令 ：

  python my_server.py

• if __name__ == "__main__": 的作用 ：

  • 确保服务器仅在直接运行脚本时启动，避免被其他模块导入时意外运行
  • 是 Python 开发中的标准最佳实践，保证跨环境运行的一致性

2. 服务器传输协议（默认 stdio）

• stdio 传输：基于标准输入输出的文本协议，适合本地测试和简单场景
• 其他传输方式可在服务器配置指南中查看

六、使用 FastMCP CLI 工具

1. CLI 运行方式

• 命令格式 ：

  fastmcp run my_server.py:mcp

• 参数说明 ：

  • my_server.py：服务器脚本文件名
  • :mcp：指定服务器对象名称（若省略，默认搜索 mcp/app/server）

• 优势 ：

  • 无需在代码中添加 if __name__ == "__main__": 块
  • CLI 会自动管理服务器生命周期，直至手动停止

2. 客户端与 CLI 配合使用

• 客户端代码示例 ：

  # my_client.py
  import asyncio
  from fastmcp import Client
  
  client = Client("my_server.py")  # 直接指向服务器脚本
  
  async def call_tool(name: str):
      async with client:
          result = await client.call_tool("greet", {"name": name})
          print(result)
  
  asyncio.run(call_tool("Ford"))

• 执行逻辑 ：

  • 客户端通过文件名识别服务器，底层会自动调用 python my_server.py
  • 适用于本地开发环境的快速交互

七、核心概念总结

模块/概念	作用描述
FastMCP 类	服务器核心类，管理工具注册和客户端连接
@mcp.tool 装饰器	将函数注册为可被客户端调用的工具
Client 类	异步客户端，用于连接服务器并调用工具
asyncio	Python 异步编程框架，支撑 FastMCP 的非阻塞式通信
stdio 传输	基于文本的简单通信协议，适用于本地测试场景

八、延伸学习建议

1. 查看 服务器配置指南，了解更多传输协议（如网络端口配置）和高级参数
2. 探索工具参数验证、异步工具定义等进阶功能
3. 尝试在分布式系统中部署 FastMCP 服务器，实现跨节点工具调用

通过以上步骤，可快速搭建一个功能完整的 FastMCP 服务器，并通过客户端实现工具的远程调用。该框架适合需要轻量化工具服务的场景，如自动化任务调度、微服务工具组件等。