# McpServerFramework **Repository Path**: shaoleixp/mcp-server-framework ## Basic Information - **Project Name**: McpServerFramework - **Description**: McpServerFramework - **Primary Language**: Unknown - **License**: Apache-2.0 - **Default Branch**: main - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-04-04 - **Last Updated**: 2026-04-04 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # FastMCP 项目模板 - 新手完整指南 ## 📚 目录 1. [项目简介](#项目简介) 2. [前置知识](#前置知识) 3. [快速开始](#快速开始) 4. [项目结构详解](#项目结构详解) 5. [核心概念解释](#核心概念解释) 6. [如何添加新功能](#如何添加新功能) 7. [常见问题解答](#常见问题解答) 8. [进阶学习](#进阶学习) --- ## 项目简介 ### 这是什么项目？ 这是一个 **FastMCP 项目模板**，帮助你快速构建 MCP (Model Context Protocol) 服务器。 ### 什么是 MCP？ **MCP** 是一个协议（规则），让 AI 助手（如 Claude）能够： - 调用你编写的工具函数 - 访问你提供的资源 - 使用你定义的提示词 **简单比喻**：MCP 就像一个"翻译官"，让 AI 助手能够理解和使用你的代码。 ### 这个模板能做什么？ 这个模板提供了： - ✅ 完整的项目结构 - ✅ 基础代码框架 - ✅ 配置管理系统 - ✅ 日志记录功能 - ✅ 测试框架 - ✅ Docker 部署支持 **你只需要**：专注于编写业务逻辑，其他都已经准备好了！ --- ## 前置知识 ### 需要了解的基础知识 在开始之前，你需要了解： #### 1. Python 基础 - 变量、函数、类 - 异步编程（async/await） - 模块导入 #### 2. 命令行基础 - 如何打开终端/命令行 - 基本命令：cd, ls, python #### 3. 开发工具 - Python 3.10 或更高版本 - 代码编辑器（推荐 VS Code） ### 如果你是完全的新手 **不用担心！** 本指南会详细解释每一步。遇到不懂的术语，可以： 1. 查看本文档的"核心概念解释"部分 2. 在网上搜索相关教程 3. 向 AI 助手提问 --- ## 快速开始 ### 第一步：准备项目文件 #### 方法一：使用 data 文件夹中的模板 ```bash # 1. 进入 data 文件夹 cd data # 2. 复制所有文件到你的新项目文件夹 # Windows: xcopy /E /I . ..\my-new-project # Mac/Linux: cp -r . ../my-new-project # 3. 进入新项目 cd ..\my-new-project ``` #### 方法二：手动创建 参考 `data` 文件夹中的结构，手动创建相同的目录和文件。 ### 第二步：配置环境 #### 1. 创建虚拟环境（推荐） **什么是虚拟环境？** 虚拟环境是一个独立的 Python 环境，避免不同项目之间的依赖冲突。 ```bash # 创建虚拟环境 python -m venv venv # 激活虚拟环境 # Windows: venv\Scripts\activate # Mac/Linux: source venv/bin/activate ``` **如何确认虚拟环境已激活？** 命令行前面会显示 `(venv)`，例如： ``` (venv) E:\Dev\my-project> ``` #### 2. 安装依赖 ```bash # 安装生产依赖 pip install -e . # 安装开发依赖（包含测试工具） pip install -e ".[dev]" ``` **安装了什么？** - `fastmcp`: MCP 框架核心 - `pydantic`: 数据验证工具 - `python-dotenv`: 环境变量管理 - `pytest`: 测试框架（开发依赖） #### 3. 配置环境变量 ```bash # 复制环境变量示例文件 # Windows: copy .env.example .env # Mac/Linux: cp .env.example .env # 编辑 .env 文件，修改配置 # 可以使用记事本或代码编辑器打开 ``` ### 第三步：运行项目 #### 1. 运行服务器 ```bash python main.py ``` **看到以下输出表示成功：** ``` 2026-04-04 13:11:14 - server.app - INFO - FastMCP server 'fastmcp-template' initialized 2026-04-04 13:11:14 - __main__ - INFO - Starting FastMCP server... ``` #### 2. 运行测试 ```bash # 运行所有测试 pytest tests/ # 查看详细输出 pytest tests/ -v ``` **看到以下输出表示测试通过：** ``` tests\test_example.py ... [100%] 3 passed in 0.05s ``` --- ## 项目结构详解 ### 完整目录结构 ``` fastmcp-template/ ├── common/ # 公共组件（基础设施） │ ├── __init__.py │ ├── config.py # 配置管理 │ ├── logger.py # 日志记录 │ ├── exceptions.py # 异常定义 │ └── utils.py # 工具函数 ├── services/ # 业务服务层（核心逻辑） │ ├── __init__.py │ └── .example_service.py # 示例服务模板 ├── tools/ # 工具接口层（AI调用入口） │ ├── __init__.py │ └── .example_tools.py # 示例工具模板 ├── resources/ # 只读资源层 │ ├── __init__.py │ └── .example_resources.py ├── prompts/ # 提示词模板层 │ ├── __init__.py │ └── .example_prompts.py ├── server/ # MCP 协议层 │ ├── __init__.py │ └── app.py # FastMCP 核心实例 ├── tests/ # 测试套件 │ ├── __init__.py │ ├── conftest.py # 测试配置 │ └── test_example.py # 示例测试 ├── deploy/ # Docker 部署 │ ├── .dockerignore │ ├── Dockerfile │ └── docker-compose.yml ├── main.py # 程序入口 ├── pyproject.toml # 项目配置 ├── .env.example # 环境变量示例 └── .gitignore # Git 忽略文件 ``` ### 各部分作用详解 #### 1. `common/` - 公共组件层 **作用**：提供基础设施功能，被所有其他层使用。 **包含内容**： - `config.py`: 管理应用配置（如应用名称、日志级别） - `logger.py`: 提供日志记录功能 - `exceptions.py`: 定义自定义异常 - `utils.py`: 通用工具函数 **使用示例**： ```python # 在任何地方使用配置 from common.config import config print(config.app_name) # 输出: fastmcp-template # 在任何地方记录日志 from common.logger import get_logger logger = get_logger(__name__) logger.info("这是一条日志") ``` #### 2. `services/` - 业务服务层 **作用**：编写核心业务逻辑，与 MCP 完全解耦。 **为什么要分离？** - 业务逻辑独立，便于测试 - 可以被多个工具共享 - 不依赖特定框架 **如何使用**： 1. 创建服务文件，如 `user_service.py` 2. 定义服务类和业务方法 3. 导出服务实例 **示例**： ```python # services/user_service.py from common.logger import get_logger logger = get_logger(__name__) class UserService: async def get_user(self, user_id: str) -> dict: """获取用户信息""" logger.info(f"获取用户: {user_id}") # 这里写业务逻辑 return {"id": user_id, "name": "张三"} # 导出实例 user_service = UserService() ``` #### 3. `tools/` - 工具接口层 **作用**：定义 AI 可以调用的工具函数。 **工作原理**： 1. AI 助手看到工具的文档字符串 2. AI 决定调用哪个工具 3. 工具调用服务层完成实际工作 4. 返回结果给 AI **如何使用**： ```python # tools/user_tools.py from server.app import mcp from services.user_service import user_service @mcp.tool() async def get_user_info(user_id: str) -> str: """ 获取用户信息 Args: user_id: 用户ID Returns: str: 用户信息 """ user = await user_service.get_user(user_id) return f"用户: {user['name']}" ``` **重要**：工具函数的文档字符串会被 AI 看到，所以要写清楚！ #### 4. `resources/` - 只读资源层 **作用**：提供只读数据，如配置、状态等。 **与工具的区别**： - 工具：执行操作，可能有副作用 - 资源：只读访问，无副作用 **如何使用**： ```python # resources/config_resources.py from server.app import mcp from common.config import config @mcp.resource("config://app") async def get_app_config() -> str: """应用配置资源""" return f""" 应用名称: {config.app_name} 版本: {config.app_version} """ ``` #### 5. `prompts/` - 提示词模板层 **作用**：管理 LLM 提示词，帮助 AI 更好地使用工具。 **如何使用**： ```python # prompts/user_prompts.py USER_TOOL_PROMPT = """ 使用用户工具时请注意： 1. 确保用户ID格式正确 2. 处理用户不存在的情况 """ ``` #### 6. `server/` - MCP 协议层 **作用**：创建和配置 FastMCP 实例。 **核心文件**：`app.py` ```python from fastmcp import FastMCP # 创建 MCP 实例 mcp = FastMCP("my-app") ``` #### 7. `tests/` - 测试套件 **作用**：编写单元测试，确保代码质量。 **如何使用**： ```python # tests/test_user_service.py import pytest from services.user_service import user_service @pytest.mark.anyio async def test_get_user(): user = await user_service.get_user("123") assert user["id"] == "123" ``` #### 8. `main.py` - 程序入口 **作用**：启动 MCP 服务器。 **执行流程**： 1. 加载环境变量 2. 创建 MCP 实例 3. 注册工具和资源 4. 启动服务器 --- ## 核心概念解释 ### 1. 什么是异步编程（async/await）？ **简单理解**：异步编程让程序可以同时处理多个任务，提高效率。 **对比**： ```python # 同步（一个一个执行） def get_data(): data1 = fetch_data1() # 等待 1 秒 data2 = fetch_data2() # 等待 1 秒 # 总共等待 2 秒 # 异步（同时执行） async def get_data(): data1 = await fetch_data1() # 同时执行 data2 = await fetch_data2() # 同时执行 # 总共等待 1 秒 ``` **在项目中的使用**： - 服务层方法：`async def method()` - 工具函数：`async def tool()` - 资源函数：`async def resource()` ### 2. 什么是装饰器？ **简单理解**：装饰器是一个函数，用来"装饰"另一个函数，给它添加额外功能。 **示例**： ```python # @mcp.tool() 是装饰器 @mcp.tool() async def my_tool(): pass # 等价于 async def my_tool(): pass my_tool = mcp.tool()(my_tool) ``` **在项目中的使用**： - `@mcp.tool()`: 将函数注册为工具 - `@mcp.resource()`: 将函数注册为资源 ### 3. 什么是环境变量？ **简单理解**：环境变量是操作系统级别的配置，可以在不修改代码的情况下改变程序行为。 **使用场景**： - 不同环境（开发/测试/生产）使用不同配置 - 存储敏感信息（密码、密钥） **在项目中的使用**： ```bash # .env 文件 APP_NAME=my-app LOG_LEVEL=DEBUG ``` ```python # 代码中使用 import os app_name = os.getenv("APP_NAME") ``` ### 4. 什么是依赖管理？ **简单理解**：依赖是项目需要的外部库，依赖管理是安装和跟踪这些库的过程。 **pyproject.toml**： ```toml [project] dependencies = [ "fastmcp>=2.0.0", # 项目需要 fastmcp 库 ] ``` **安装依赖**： ```bash pip install -e . ``` --- ## 如何添加新功能 ### 完整示例：添加用户管理功能 #### 步骤 1：创建服务层 ```python # services/user_service.py """ 用户服务 处理用户相关的业务逻辑 """ from common.logger import get_logger from common.exceptions import ServiceError logger = get_logger(__name__) class UserService: """用户服务类""" # 模拟数据库 _users = { "1": {"id": "1", "name": "张三", "email": "zhangsan@example.com"}, "2": {"id": "2", "name": "李四", "email": "lisi@example.com"}, } async def get_user(self, user_id: str) -> dict: """ 获取用户信息 Args: user_id: 用户ID Returns: dict: 用户信息 Raises: ServiceError: 用户不存在 """ logger.info(f"获取用户: {user_id}") if user_id not in self._users: raise ServiceError(f"用户 {user_id} 不存在") return self._users[user_id] async def list_users(self) -> list: """获取所有用户""" logger.info("获取用户列表") return list(self._users.values()) async def create_user(self, name: str, email: str) -> dict: """ 创建用户 Args: name: 用户名 email: 邮箱 Returns: dict: 新创建的用户 """ logger.info(f"创建用户: {name}") # 生成新ID new_id = str(len(self._users) + 1) # 创建用户 user = { "id": new_id, "name": name, "email": email } # 保存用户 self._users[new_id] = user logger.info(f"用户创建成功: {user}") return user # 导出服务实例 user_service = UserService() ``` #### 步骤 2：创建工具接口 ```python # tools/user_tools.py """ 用户工具接口 提供用户相关的工具函数 """ from server.app import mcp from services.user_service import user_service from common.logger import get_logger logger = get_logger(__name__) @mcp.tool() async def get_user(user_id: str) -> str: """ 获取用户信息 Args: user_id: 用户ID Returns: str: 用户信息 """ logger.info(f"工具调用: get_user({user_id})") user = await user_service.get_user(user_id) return f""" 用户信息: - ID: {user['id']} - 姓名: {user['name']} - 邮箱: {user['email']} """ @mcp.tool() async def list_users() -> str: """ 获取所有用户列表 Returns: str: 用户列表 """ logger.info("工具调用: list_users()") users = await user_service.list_users() result = "用户列表:\n" for user in users: result += f"- {user['id']}: {user['name']} ({user['email']})\n" return result @mcp.tool() async def create_user(name: str, email: str) -> str: """ 创建新用户 Args: name: 用户名 email: 邮箱地址 Returns: str: 创建结果 """ logger.info(f"工具调用: create_user({name}, {email})") user = await user_service.create_user(name, email) return f"用户创建成功: {user['name']} (ID: {user['id']})" ``` #### 步骤 3：注册工具 在 `main.py` 中添加导入： ```python # main.py # ... 其他导入 ... # 导入工具（添加这一行） from tools import user_tools # ... 其他代码 ... ``` #### 步骤 4：编写测试 ```python # tests/test_user_service.py """ 用户服务测试 """ import pytest from services.user_service import user_service from common.exceptions import ServiceError @pytest.mark.anyio async def test_get_user(): """测试获取用户""" user = await user_service.get_user("1") assert user["id"] == "1" assert user["name"] == "张三" @pytest.mark.anyio async def test_get_user_not_found(): """测试获取不存在的用户""" with pytest.raises(ServiceError): await user_service.get_user("999") @pytest.mark.anyio async def test_list_users(): """测试获取用户列表""" users = await user_service.list_users() assert len(users) == 2 @pytest.mark.anyio async def test_create_user(): """测试创建用户""" user = await user_service.create_user("王五", "wangwu@example.com") assert user["name"] == "王五" assert user["email"] == "wangwu@example.com" ``` #### 步骤 5：运行测试 ```bash # 运行所有测试 pytest tests/ # 只运行用户服务测试 pytest tests/test_user_service.py ``` #### 步骤 6：启动服务器 ```bash python main.py ``` --- ## 常见问题解答 ### Q1: 如何调试代码？ **方法一：使用 print** ```python print(f"调试信息: {variable}") ``` **方法二：使用日志** ```python from common.logger import get_logger logger = get_logger(__name__) logger.debug(f"调试信息: {variable}") ``` **方法三：使用调试器** 在 VS Code 中： 1. 设置断点（点击行号左侧） 2. 按 F5 启动调试 3. 查看变量值 ### Q2: 如何处理错误？ **使用异常**： ```python from common.exceptions import ServiceError async def my_function(): if something_wrong: raise ServiceError("出错了") ``` **在工具中捕获**： ```python @mcp.tool() async def my_tool(): try: result = await my_service.do_something() return f"成功: {result}" except ServiceError as e: return f"失败: {str(e)}" ``` ### Q3: 如何添加配置项？ **步骤 1：在 .env 文件中添加** ```bash MY_CONFIG=my-value ``` **步骤 2：在 config.py 中添加** ```python @dataclass(frozen=True) class Config: # ... 其他配置 ... my_config: str = "default-value" @classmethod def from_env(cls) -> "Config": return cls( # ... 其他配置 ... my_config=os.getenv("MY_CONFIG", "default-value"), ) ``` **步骤 3：使用配置** ```python from common.config import config print(config.my_config) ``` ### Q4: 如何部署到生产环境？ **方法一：直接运行** ```bash python main.py ``` **方法二：使用 Docker** ```bash # 构建镜像 docker-compose -f deploy/docker-compose.yml build # 启动容器 docker-compose -f deploy/docker-compose.yml up -d # 查看日志 docker-compose -f deploy/docker-compose.yml logs -f ``` ### Q5: 如何查看日志？ **运行时查看**： 日志会直接输出到控制台。 **调整日志级别**： ```bash # 在 .env 文件中 LOG_LEVEL=DEBUG # 显示所有日志 LOG_LEVEL=INFO # 只显示重要日志 LOG_LEVEL=ERROR # 只显示错误日志 ``` --- ## 进阶学习 ### 推荐学习路径 1. **Python 基础** → 掌握基本语法 2. **异步编程** → 理解 async/await 3. **FastMCP 文档** → 了解框架细节 4. **实际项目** → 动手实践 ### 有用的资源 - [Python 官方教程](https://docs.python.org/zh-cn/3/tutorial/) - [FastMCP 文档](https://github.com/anthropics/fastmcp) - [MCP 协议规范](https://modelcontextprotocol.io/) ### 下一步建议 1. **实践项目**：尝试添加更多功能 2. **阅读源码**：理解模板的工作原理 3. **优化改进**：根据需求调整架构 4. **分享交流**：与他人讨论学习 --- ## 总结 这个模板提供了完整的 MCP 服务器开发框架： - ✅ **清晰的结构**：分层设计，职责明确 - ✅ **完整的文档**：详细解释每个部分 - ✅ **示例代码**：提供可参考的模板 - ✅ **测试支持**：确保代码质量 - ✅ **部署方案**：支持 Docker 部署 **开始你的 MCP 开发之旅吧！** 🚀 如有问题，欢迎： - 查看本文档 - 阅读代码注释 - 向 AI 助手提问 - 搜索相关资料 祝你学习顺利！