# 📋 Trae Rules Generator MCP

一个用于自动生成和管理 Trae AI 项目规则文件的 MCP (Model Context Protocol) 服务。

## ✨ 功能特性

- 🔍 **读取现有规则**: 扫描和分析现有的规则文件结构
- 🎯 **智能生成规则**: 根据项目类型和功能特性生成定制化规则
- 💾 **规则文件管理**: 保存、更新和备份规则文件
- 🌐 **多语言支持**: 支持中文和英文规则生成
- 🔧 **灵活配置**: 支持自定义规则路径和文件名

## 🚀 快速开始

### 方式一：使用已发布的包 (推荐)

#### 1. 安装包

```bash
pip3 install trae-rules-mcp
```

#### 2. 在 Trae AI 中配置 MCP

在 Trae AI 的 MCP 配置中添加以下配置：

```json
{
  "mcpServers": {
    "trae-rules-mcp": {
      "command": "python3",
      "args": ["-m", "trae_rules_mcp.main"],
      "env": {
        "PYTHONPATH": "."
      }
    }
  }
}
```

### 方式二：从源码运行

#### 1. 环境要求

- Python 3.8+
- pip 或 uv 包管理器

#### 2. 克隆项目

```bash
git clone https://github.com/trae-ai/trae-rules-mcp.git
cd trae-rules-mcp
```

#### 3. 安装依赖

```bash
# 使用 uv (推荐)
uv sync

# 或使用 pip
pip install -e .
```

#### 4. 在 Trae AI 中配置 MCP

```json
{
  "mcpServers": {
    "trae-rules-generator": {
      "command": "uv",
      "args": ["run", "python", "main.py"],
      "cwd": "/path/to/trae-rules-mcp",
      "env": {
        "PYTHONPATH": "/path/to/trae-rules-mcp"
      }
    }
  }
}
```

> 💡 **注意**: 请将 `/path/to/trae-rules-mcp` 替换为实际的项目路径。

#### 5. 重启 Trae AI

配置完成后，重启 Trae AI 以加载新的 MCP 服务器。

## 🛠️ MCP 工具

### 1. read_existing_rules

读取现有的规则文件内容和结构信息。

**参数:**
- `rules_path` (str, 可选): 规则文件目录路径，默认为 `.trae/rules`

**返回:**
- 规则文件的详细信息，包括文件列表、内容预览等

### 2. generate_project_rules

根据项目类型和功能特性生成新的项目规则文件。

**参数:**
- `project_type` (str): 项目类型 (如: web, mobile, ai, backend, frontend)
- `features` (List[str]): 项目功能特性列表 (如: ["authentication", "database", "api"])
- `language` (str, 可选): 规则文件语言，默认为中文

**返回:**
- 生成的规则文件内容 (Markdown 格式)

### 3. save_rules_file

保存规则文件到指定目录。

**参数:**
- `content` (str): 规则文件内容
- `filename` (str, 可选): 文件名，默认为 `project_rules.md`
- `rules_path` (str, 可选): 规则文件目录路径，默认为 `.trae/rules`

**返回:**
- 保存操作的结果信息

### 4. update_existing_rules

更新现有的规则文件内容。

**参数:**
- `file_path` (str): 要更新的规则文件路径
- `updates` (Dict[str, Any]): 更新内容的字典

**返回:**
- 更新操作的结果信息

## 📖 使用示例

### 示例 1: 生成 Web 项目规则

```
用户: 帮我生成一个包含用户认证和数据库功能的 Web 项目规则文件

AI 助手会调用:
generate_project_rules(
  project_type="web",
  features=["authentication", "database"],
  language="中文"
)
```

### 示例 2: 读取现有规则

```
用户: 查看我当前项目的规则文件

AI 助手会调用:
read_existing_rules(rules_path=".trae/rules")
```

### 示例 3: 保存生成的规则

```
用户: 将刚才生成的规则保存为 web_project_rules.md

AI 助手会调用:
save_rules_file(
  content="生成的规则内容",
  filename="web_project_rules.md",
  rules_path=".trae/rules"
)
```

### 生成的规则文件示例

```markdown
---
description: web 项目规则
globs: 
alwaysApply: true
---

### 📋 WEB 项目开发规则

#### 🔧 通用开发规则

1. **代码质量**
   * 保持代码简洁、可读性强
   * 添加必要的注释和文档
   * 遵循项目的编码规范

#### 🎯 功能特性规则

1. **Authentication**
   * 实现安全的用户认证
   * 使用强密码策略
   * 实现会话管理

2. **Database**
   * 设计合理的数据库结构
   * 实现数据备份策略
   * 优化查询性能
```

## 📁 项目结构

```
trae-rules-mcp/
├── trae_rules_mcp/      # 主要包目录
│   ├── __init__.py     # 包初始化文件
│   └── main.py         # MCP 服务主文件
├── main.py             # 兼容性入口文件
├── pyproject.toml      # 项目配置文件
├── README.md           # 项目说明文档
├── example_rules.md    # 示例规则文件
├── mcp_config_example.json # MCP 配置示例
├── CHANGELOG.md        # 更新日志
├── LICENSE             # 许可证文件
└── .gitignore          # Git 忽略文件
```

## 🔧 配置说明

### 默认规则路径

服务默认在 `.trae/rules` 目录下查找和保存规则文件。你可以通过工具参数自定义路径。

### 支持的项目类型

- `web` / `frontend`: 前端 Web 项目
- `backend` / `api`: 后端 API 项目
- `ai`: AI/机器学习项目
- `mobile`: 移动应用项目
- 其他自定义类型

### 支持的功能特性

- `authentication`: 用户认证
- `database`: 数据库操作
- `api`: API 接口
- `ui`: 用户界面
- `testing`: 测试相关
- `deployment`: 部署配置
- `security`: 安全相关
- `performance`: 性能优化
- 其他自定义特性

## 🔧 故障排除

### 常见问题

#### 1. "找不到命令: python" 错误

**问题**: 在 MCP 配置中遇到 "spawn python ENOENT" 错误。

**解决方案**:
- 使用完整的 Python 路径：`"command": "/usr/bin/python3"`
- 或者确保 Python 在系统 PATH 中：`"command": "python3"`

#### 2. 模块导入失败

**问题**: "No module named 'trae_rules_mcp'" 错误。

**解决方案**:
```bash
# 重新安装包
pip3 uninstall trae-rules-mcp -y
pip3 install trae-rules-mcp

# 验证安装
python3 -c "import trae_rules_mcp; print('安装成功!')"
```

#### 3. MCP 服务器无法启动

**问题**: Trae AI 无法连接到 MCP 服务器。

**解决方案**:
1. 检查配置文件格式是否正确
2. 确认路径设置正确
3. 重启 Trae AI
4. 查看 Trae AI 的错误日志

#### 4. 权限问题

**问题**: 无法创建或写入规则文件。

**解决方案**:
```bash
# 确保目录存在且有写入权限
mkdir -p .trae/rules
chmod 755 .trae/rules
```

### 调试技巧

1. **测试 MCP 连接**:
   ```bash
   # 手动启动服务器测试
   python3 -m trae_rules_mcp.main
   ```

2. **检查包安装**:
   ```bash
   pip3 show trae-rules-mcp
   pip3 list | grep trae
   ```

3. **验证配置**:
   - 确保 JSON 格式正确
   - 检查路径是否存在
   - 验证环境变量设置

## 🤝 贡献指南

1. Fork 本仓库
2. 创建功能分支 (`git checkout -b feature/AmazingFeature`)
3. 提交更改 (`git commit -m 'Add some AmazingFeature'`)
4. 推送到分支 (`git push origin feature/AmazingFeature`)
5. 打开 Pull Request

## 📄 许可证

本项目采用 MIT 许可证 - 查看 [LICENSE](LICENSE) 文件了解详情。

## 🆘 支持

### 获取帮助

- 📖 **文档**: 查看本 README 和项目 Wiki
- 🐛 **问题报告**: [GitHub Issues](https://github.com/trae-ai/trae-rules-mcp/issues)
- 💡 **功能建议**: [GitHub Discussions](https://github.com/trae-ai/trae-rules-mcp/discussions)
- 📦 **PyPI 包**: [trae-rules-mcp](https://pypi.org/project/trae-rules-mcp/)

### 版本信息

- **当前版本**: 1.0.1
- **Python 支持**: 3.8+
- **MCP 协议**: 兼容最新版本

### 更新日志

查看 [CHANGELOG.md](CHANGELOG.md) 了解详细的版本更新信息。

---

**🎉 感谢使用 Trae Rules Generator MCP！**

如果这个项目对你有帮助，请考虑给我们一个 ⭐ Star！