PROJECT_STRUCTURE.md•3.99 kB
# MCP Recommender 项目结构
## 📁 核心文件说明
### 必需的源代码文件
```
mcp-recommender-clean/
├── mcp_recommender/ # 主包目录
│ ├── __init__.py # 包初始化文件
│ ├── __main__.py # CLI入口点，支持 python -m mcp_recommender
│ ├── server.py # MCP服务器核心实现
│ └── data/ # 数据文件目录
│ ├── mcp_database.json # 874个MCP服务器数据库
│ └── functional_keywords.json # 功能关键词映射
├── scripts/ # 构建和工具脚本
│ ├── build.py # uv构建脚本
│ └── prepare_release.py # 发布准备检查脚本
├── pyproject.toml # 项目配置和依赖管理
├── LICENSE # MIT许可证
├── README.md # 英文文档
├── README-zh.md # 中文文档
├── MANIFEST.in # 包含文件规则
├── .gitignore # Git忽略文件
└── PROJECT_STRUCTURE.md # 本文件
```
## 🎯 包含的核心文件类型
### 1. 源代码文件 (.py)
- `__init__.py` - 包初始化和版本信息
- `__main__.py` - 命令行入口，处理asyncio冲突
- `server.py` - FastMCP服务器实现，智能推荐算法
### 2. 数据文件 (.json)
- `mcp_database.json` - 874个MCP服务器的完整数据库
- `functional_keywords.json` - 15个功能分类的关键词映射
### 3. 配置文件
- `pyproject.toml` - Python包配置，uv兼容，MIT许可证
- `MANIFEST.in` - 包构建时的文件包含规则
- `.gitignore` - Git版本控制忽略规则
### 4. 文档文件 (.md)
- `README.md` - 英文项目文档
- `README-zh.md` - 中文项目文档
- `PROJECT_STRUCTURE.md` - 项目结构说明
### 5. 许可证文件
- `LICENSE` - MIT开源许可证
### 6. 工具脚本
- `scripts/build.py` - 自动化构建脚本
- `scripts/prepare_release.py` - 发布前检查脚本
## ❌ 已排除的文件类型
### 1. 编译产物
- `__pycache__/` - Python字节码缓存
- `*.pyc`, `*.pyo` - 编译的Python文件
- `build/`, `dist/` - 构建输出目录
- `*.egg-info/` - 包信息目录
### 2. 虚拟环境
- `.venv/`, `venv/` - Python虚拟环境
- `.uv/` - uv缓存目录
- `uv.lock` - uv锁定文件
### 3. IDE和编辑器文件
- `.vscode/` - VS Code配置
- `.idea/` - PyCharm配置
- `*.swp`, `*.swo` - Vim临时文件
### 4. 系统文件
- `.DS_Store` - macOS系统文件
- `Thumbs.db` - Windows缩略图缓存
- `*.tmp`, `*.temp` - 临时文件
### 5. 日志和缓存
- `*.log` - 日志文件
- `.cache/` - 各种缓存目录
- `.pytest_cache/` - pytest缓存
### 6. 测试和覆盖率
- `.coverage` - 覆盖率数据
- `htmlcov/` - 覆盖率报告
- `.pytest_cache/` - pytest缓存
## 🚀 使用方法
### 1. 克隆到本地
```bash
git clone <repository-url>
cd mcp-recommender-clean
```
### 2. 安装依赖
```bash
# 使用uv（推荐）
uv sync
# 或使用pip
pip install -e .
```
### 3. 测试运行
```bash
# 测试模式
uv run -m mcp_recommender --test
# 服务器模式
uv run -m mcp_recommender --server
```
### 4. 构建包
```bash
# 使用构建脚本
python scripts/build.py
# 或直接使用uv
uv build
```
## ✅ 完整性验证
这个干净的项目文件夹包含了实现完整功能所需的所有文件：
- ✅ 核心MCP服务器功能
- ✅ 874个MCP服务器数据库
- ✅ 智能推荐算法
- ✅ CLI和MCP客户端支持
- ✅ uv工作流支持
- ✅ AsyncIO冲突修复
- ✅ 完整的文档和示例
- ✅ MIT开源许可证
- ✅ 构建和发布工具
## 📋 GitHub仓库要求
此项目结构完全符合GitHub仓库的最佳实践：
- 清晰的目录结构
- 完整的README文档（中英文）
- 适当的.gitignore文件
- 开源许可证
- 项目配置文件
- 无临时或生成文件
可以直接上传到GitHub并立即使用！