AI导哈

MCP服务器教程

一个演示如何使用FastMCP构建模型上下文协议（MCP）服务器的教程项目，包含密码工具、员工API工具和Petstore OpenAPI工具的示例。

  • by ameykelkar
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 ameykelkar/mcp-server-tutorial

使用说明

MCP服务器教程🚀

演示如何使用FastMCP构建模型上下文协议（MCP）服务器的教程项目。此仓库包含三个示例服务器：

  • 演示密码工具(server.py)
  • 通过REST后端的员工API工具(server_api.py)
  • OpenAPI为Petstore API生成的工具(server_openapi.py)

什么是MCP？

模型上下文协议（MCP）是一种标准，使AI助手能够安全地连接到外部数据源和工具。这些示例展示了构建助手可以使用的MCP服务器的不同方法。

先决条件

  • Python 3.13或更高版本
  • uv 包管理器（推荐）或pip

安装

使用紫外线（推荐）

  1. 克隆存储库：
git clone <repository-url>
cd mcp-server-tutorial
  1. 安装依赖项：
uv sync

使用pip

  1. 克隆存储库：
git clone <repository-url>
cd mcp-server-tutorial
  1. 创建虚拟环境并安装deps：
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install 'fastmcp>=2.10.5' 'httpx>=0.25.0'

用法

1） 演示密码工具-- server.py

运行服务器：

uv run server.py
# or
python server.py

可用工具：

  • generate_password(length: int = 12, include_symbols: bool = True) -> str
    • 生成随机密码。最小长度为4。
  • score_password(password: str) -> dict
    • 退货 score (0–10), strength, feedback 列表， length，以及 character_types 细节。

示例：

generate_password(length=16, include_symbols=True)
score_password("MySecureP@ssw0rd!")

2） 员工API工具- server_api.py

支持 https://dummy.restapiexample.com/api/v1.

运行服务器：

uv run server_api.py
# or
python server_api.py

可用工具：

  • get_all_employees() -> Dict[str, Any]
  • get_employee_by_id(employee_id: int) -> Dict[str, Any]
  • filter_employees_by_age(min_age: Optional[int] = None, max_age: Optional[int] = None) -> Dict[str, Any]
  • filter_employees_by_salary(min_salary: Optional[int] = None, max_salary: Optional[int] = None) -> Dict[str, Any]
  • search_employees_by_name(name_query: str) -> Dict[str, Any]
  • get_employee_statistics() -> Dict[str, Any]

笔记：

  • 外部API可以是有等级限制的或片状的；错误返回为 { "error": "..." }.

3） Petstore OpenAPI工具-- server_openapi.py

根据Petstore OpenAPI规范动态生成工具。

环境变量（可选）：

  • PETSTORE_OPENAPI_URL （默认值： https://petstore3.swagger.io/api/v3/openapi.json)
  • PETSTORE_BASE_URL （默认值： https://petstore3.swagger.io/api/v3)

OpenAPI规范： https://petstore3.swagger.io/api/v3/openapi.json

运行服务器：

uv run server_openapi.py
# or
python server_openapi.py

关于工具：

  • 工具直接从OpenAPI规范生成，并镜像API操作 （例如，Petstore API中的宠物、商店和用户端点）。
  • 需要访问互联网才能获取OpenAPI规范并调用API。

连接到AI助手

配置您的MCP兼容客户端（例如Claude Desktop）以连接到您正在运行的服务器。有关如何注册MCP服务器，请参阅客户的文档。

发展

项目结构

mcp-server-tutorial/
├── server.py            # Demo password tools
├── server_api.py        # Employee API tools (dummy.restapiexample.com)
├── server_openapi.py    # OpenAPI-generated tools (Petstore)
├── README.md            # This file
├── pyproject.toml       # Project configuration
└── uv.lock              # Dependency lock file

添加新工具

对于手写工具（例如 server.py 或 server_api.py):

  1. 定义一个函数 @mcp.tool 装饰器
  2. 添加适当的类型提示和简洁的文档字符串
  3. 执行你的逻辑；工具自动暴露给MCP客户端
@mcp.tool
def my_new_tool(param: str) -> str:
    return "result"

对于基于OpenAPI的服务器，调整OpenAPI源URL和基本URL，然后使用以下命令重建服务器 FastMCP.from_openapi 如图所示 server_openapi.py.

依赖项

  • fastmcp>=2.10.5
  • httpx>=0.25.0

故障排除

  • 服务器无法启动：验证Python 3.13+、已安装的依赖项和网络可用性（适用于API/OpenAPI服务器）。
  • 外部API错误：Employee和Petstore服务器依赖于公共API，这些API可能会限制速率或返回间歇性错误。检查退回的 { "error": "..." } 消息。
  • 客户端无法连接：确认服务器进程正在运行，MCP客户端配置正确。

编码愉快！ 🎉

相关 MCP