---
title: 项目结构
description: 了解 MCP Server 模板仓库的结构及其各个部分的功能。
---
本文档介绍了 MCP Server 模板仓库的目录结构、各部分职责，以及开发命名与代码规范。
建议在实际开发前 **先阅读完本节并熟悉各目录职责**。
## 目录结构
| 目录 | 责任 | 规范 |
| ------------- | ------------------------------------------------------ | ------------------------------------------------------ |
| core/ | 核心业务逻辑 | 单功能模块化、支持异步、异常处理、无依赖工具文件 |
| tools/ | MCP Tool 实现 | 可供 client 调用的工具，文件名对应工具名、参数完全声明 |
| resources/ | MCP Resources 实现 | 可供 client 调用的资源 |
| prompts/ | MCP Prompts 实现 | 可供 client 调用的提示词 |
| config.yaml | 配置 & 元数据 | YAML 格式、只存储元数据 |
| server.py | MCP Server 启动 & 调度 | **无需修改** |
| YA_Common | 为 YA 项目其他仓库提供的通用工具函数，如日志、错误处理 | **无需修改**，如需实现专业工具函数，放在 core 目录中 |
| tests/ (可选) | 测试用例 | 单元测试 core 与 tools |
## core/
- 提供 MCP Tool 的具体业务逻辑和功能实现，如处理数据、调用数据库、执行计算等
- 不直接与 MCP 协议交互，保证逻辑独立、可复用
### 目录规范
```
core/
├── **init**.py
├── db.py # 数据库接口封装（如向量数据库、SQL）
├── processing.py # 数据处理、计算逻辑
├── utils.py # 通用工具函数
└── ... # 自行扩展模块
````
### 开发规范
- 每个模块功能单一，避免单个文件过于臃肿
- 代码风格规范
- 所有文件头部应有该文件的功能注释
- 在文件头部添加 `"""` 注释块
- 有多个函数时，列举所有函数的功能，一个函数一行
- 所有函数应具备完整的异常处理能力
- 尽量最小化 `try-except` 块
- 抛出的异常信息需清晰、易于 LLM 理解
- 所有函数应有完整的类型注解，**并使用 `pydantic` 的数据类型**
- 参数类型声明
- 返回值类型声明
- 所有函数应有完整的 `docstring`
- 函数功能
- 参数类型声明与含义（`Args`）
- 返回值类型声明与含义（`Returns`）
- 抛出的异常说明（`Raises`，可选）
- 返回值示例（`Example`）
- 异步方法优先使用 `async def`，以兼容 MCP Server 的异步调用
```python
"""
从 GitHub 获取用户贡献日历数据
"""
def get_data(username: str) -> Dict[str, Any]:
"""
获取 GitHub 用户的贡献日历数据
Args:
username (str): GitHub 用户名
Returns:
Dict[str, Any]: 包含总贡献数和按周分组的贡献数据
Raises:
RuntimeError: 如果请求或解析数据失败
Example:
{
"total": 1234,
"contributions": [
[{"date": "2023-01-01", "count": 5}, ...],
[{"date": "2023-01-08", "count": 3}, ...]
]
}
"""
url = f"https://proxy.cloudchewie.com/proxy/github.com/users/{username.replace('=', '')}/contributions"
print(f"请求 GitHub Proxy 数据，URL: {url}")
try:
response = requests.get(url)
response.raise_for_status()
except requests.RequestException as e:
raise RuntimeError(f"请求 GitHub 失败: {e}")
except Exception as e:
raise RuntimeError(f"发生未知错误: {e}")
try:
...
return {"total": total, "contributions": grouped}
except Exception as e:
raise RuntimeError(f"解析 GitHub 数据失败: {e}")
````
## tools/
* 描述 MCP Tool 的元数据（名称、描述、参数等）
* 定义 MCP Server 调用接口，**不实现具体业务逻辑**
* 具体业务逻辑必须通过调用 `core` 实现
* `prompts/` 与 `resources/` 的实现方式和规范与 `tools/` 一致
### 目录规范
```
tools/
├── __init__.py
├── weather_tool.py
├── math_tool.py
└── ... # 每种工具单独一个文件
```
### 开发规范
* 文件名必须以 `_tool.py` 结尾，并清晰表达工具功能
* 禁止在工具文件中直接访问网络或数据库，必须通过 `core`
* 每个工具必须使用 `@YA_MCPServer_Tool()` 注解进行注册
* 从 `core` 导入函数时遵循最小化原则
* 在函数体内 `import`
* 使用 `try-except` 捕获导入错误
* 其余代码风格规范与 `core` 保持一致
```python
"""
用于测试的工具函数，包括：
- 获取服务器的配置信息
"""
from typing import Any, Dict
@YA_MCPServer_Tool(
name="get_server_config",
title="Get Server Config",
description="获取服务器的配置信息",
)
async def get_server_config(key: str, default: Any = None) -> Dict[str, Any]:
"""获取服务器的配置信息。
Args:
key (str): 配置项的键，支持层级访问，例如 "server.name"
default (Any, optional): 配置不存在时返回的默认值
Returns:
Dict[str, Any]: 返回配置值，例如 {"value": ...}
Raises:
RuntimeError: 获取配置失败
"""
try:
from modules.YA_Common.utils.config import get_config
except ImportError as e:
raise RuntimeError(f"无法导入配置模块: {e}")
try:
res = get_config(key, default)
if res is Dict:
return res
return {"value": res}
except Exception as e:
raise RuntimeError(f"获取配置失败: {e}")
```
## config.yaml
* 包含 MCP Server 的基本信息与启动参数
* `server`：服务器元数据
* `logging`：日志配置
* `transport`：启动方式（`stdio` 或 `sse`）
### 开发规范
* 当 `core` 中涉及 API 调用或数据库访问时：
* 地址、连接参数等应统一维护在 `config.yaml`
* 使用 `utils/config.py` 中的 `get_config` 读取
* **禁止在 config 中存储 API Key、数据库密码等敏感信息**
* 必须通过环境变量读取
* 推荐使用 SOPS 进行加密管理
### 示例
```yaml
server:
name: hello_mcp
name_zh: 你好，MCP
author: YA Project
description: A simple hello mcp example for MCP Tool.
description_zh: MCP Tool 的一个简单示例。
version: 0.1.0
transport:
type: "sse"
host: "0.0.0.0"
port: 12345
logging:
console:
enabled: true
level: "DEBUG"
file:
enabled: true
level: "DEBUG"
path: "logs/mcp_server_{time:YYYYMMDD}.log"
rotation: "10 MB"
retention: "7 days"
compression: "zip"
email:
enable: true
host: smtp.qq.com
port: 465
secure: true
auth:
user: XXXXX@qq.com
chatglm:
chatglm_api_key_env: "CHATGLM_API_KEY_ENV"
max_length: 2048
chatglm_model: "glm-4-flash-250414"
```
## 可选扩展目录
* `tests/`：测试用例目录，用于对 `core` 与 `tools` 进行单元测试
