Gitea MCP Tool

# 迁移方案决策指南 基于新旧架构对比，以下是针对不同场景的建议。 ## 核心问题：剩余 65 个工具有必要迁移吗？ ### ❌ 不建议全部迁移的理由 1. **新架构的核心价值在于简洁性** - 从 3044 行减少到 489 行是巨大优势 - 如果迁移所有 86 个工具，会失去这个优势 - 即使用模块化方式，总代码量也会增加 60%+ 2. **边际收益递减** ``` 已迁移 21 个工具 → 覆盖 90% 日常场景 再迁移 7 个 (Milestone + Org) → 覆盖 95% 场景 再迁移 38 个 (Label + Team 等) → 覆盖 98% 场景 再迁移 20 个 (Webhook 等) → 覆盖 99% 场景 ``` 投入产出比：21 工具 (最高) > 28 工具 (高) > 65 工具 (低) 3. **很多工具更适合在 UI 中操作** - Webhook 配置：一次性设置，可视化更直观 - Team 权限管理：复杂权限模型，UI 操作更安全 - Label 批量操作：拖拽式操作更高效 4. **新架构的独特功能只在高频工具中体现价值** - **Elicitation**：适合 `gitea_init` 这种初始化工具 - **Prompts**：适合 create-issue/create-pr 这种常用操作 - 低频工具 (如 webhook_test) 不需要这些功能 ## 推荐方案对比 ### 方案 0：维持现状（21 个工具）⭐⭐⭐ **适用场景：** - 个人开发者或小团队 - 主要使用 Git 基础功能 - 不需要复杂的项目管理 **优势：** - ✅ 代码最简洁（489 行主文件 + 3 个小模块） - ✅ 维护成本最低 - ✅ 启动速度最快 - ✅ 已覆盖核心开发流程： - 仓库管理（创建、查看、搜索） - Issue 完整生命周期 - PR 完整流程（包括审查） - 配置和上下文管理 **缺点：** - ❌ 缺少 Milestone（需要在 UI 中操作） - ❌ 缺少 Organization 信息查询 **结论：** 如果你的团队主要使用 Issue + PR 工作流，这已经足够。 --- ### 方案 A：精简版（28 个工具）⭐⭐⭐⭐⭐ 推荐 **新增 7 个工具：** - Milestone: create, get, list, update, delete (5个) - Organization: get, list (2个) **适用场景：** - 中小型团队协作 - 使用 Milestone 管理版本迭代 - 需要查看组织信息 **工作量估算：** ```typescript // 创建 2 个新的 registry 文件 src/tools-registry/milestone-registry.ts (~200 行) src/tools-registry/org-registry.ts (~100 行) // 在 src/index.ts 中添加 2 行注册调用 registerMilestoneTools(mcpServer, toolContext); registerOrganizationTools(mcpServer, toolContext); ``` 预计工作量：1-2 小时 **优势：** - ✅ 完善项目管理能力（Issue + Milestone） - ✅ 支持多人协作场景（Organization） - ✅ 仍然保持代码简洁 - ✅ 覆盖 95% 的实际使用场景 **结论：** 性价比最高的方案，强烈推荐。 --- ### 方案 B：标准版（37 个工具）⭐⭐⭐ **在方案 A 基础上新增：** - User: get, list (2个) - Token: create, list, delete (3个) - Label 核心: create, list, add_to_issue, remove_from_issue (4个，剩余 10 个不迁移) **适用场景：** - 需要用户管理功能 - 需要自动化创建 API Token - 经常使用 Label 管理 Issue **工作量估算：** - 额外创建 3 个 registry 文件 (~400 行) - 预计工作量：3-4 小时 **优势：** - ✅ 更完整的用户管理 - ✅ 支持自动化场景（Token 管理） - ✅ Label 基本操作 **缺点：** - ⚠️ 代码量增加 50% - ⚠️ Label 功能不完整（剩余 10 个工具未迁移） - ⚠️ Token 管理通常是一次性操作 **结论：** 如果团队规模较大且有自动化需求，可以考虑。 --- ### 方案 C：完整版（86 个工具）❌ 不推荐 **全部迁移包括：** - Project (8个) - Wiki (8个) - Team (11个) - Webhook (11个) - Label 完整 (10个额外) **工作量估算：** - 创建 6 个额外 registry 文件 (~1500 行) - 预计工作量：8-12 小时 **不推荐的理由：** 1. ❌ **代码量激增** - 主文件可能需要增加到 600+ 行 - 总代码量接近旧架构 - 失去重构的核心价值 2. ❌ **维护成本高** - 更多模块需要维护 - 更新 SDK 时需要修改更多地方 3. ❌ **很多功能使用频率极低** ``` Webhook 工具使用频率：1-2 次/项目生命周期 Team 工具使用频率：取决于组织规模，中小团队几乎不用 Wiki 工具使用频率：很多团队使用外部文档系统 ``` 4. ❌ **与新架构理念相悖** - 新架构强调"简洁"和"高频功能优先" - 全量迁移回到了"大而全"的旧思路 **结论：** 违背重构初衷，不推荐。 --- ## 决策树 ``` 你的团队是否使用 Milestone 管理版本？ │ ├─ 是 → 方案 A（28 工具） │ └─ 否 → 是否需要 Organization 信息查询？ │ ├─ 是 → 方案 A（28 工具） │ └─ 否 → 是否需要 Token 自动化管理？ │ ├─ 是 → 方案 B（37 工具） │ └─ 否 → 方案 0（21 工具）保持现状 ``` ## 最终建议 ### 立即执行：方案 A（28 工具） **理由：** 1. Milestone 是 Issue/PR 的自然延伸 2. Organization 是多人协作的基础信息 3. 工作量小（1-2 小时） 4. 性价比极高（7 个工具覆盖额外 5% 场景） ### 按需执行：方案 B 中的部分工具 - 如果未来用户明确需要某个功能（如 Token 管理） - 可以按照现有模式快速添加对应模块 - 不需要预先实现所有功能 ### 永久保留：src/index.old.ts - 作为功能完整的备份 - 如果用户需要低频功能（如 Webhook），可以： 1. 临时使用旧版本 2. 或从旧代码中提取特定工具迁移到新架构 ## 投入产出比分析 | 方案 | 新增工具 | 工作量 | 场景覆盖 | 代码增加 | 推荐度 | |------|---------|--------|----------|----------|--------| | 方案 0 | 0 | 0 | 90% | 0% | ⭐⭐⭐ | | **方案 A** | **7** | **1-2h** | **95%** | **+15%** | **⭐⭐⭐⭐⭐** | | 方案 B | 16 | 4-5h | 97% | +45% | ⭐⭐⭐ | | 方案 C | 65 | 10-12h | 100% | +150% | ❌ | **最佳选择：方案 A** - 投入 1-2 小时换来 5% 场景覆盖提升 - 保持代码简洁性 - 满足绝大多数团队需求