ZenTao MCP Server

## ADDED Requirements

### Requirement: ZenTao API Connector
MCP 服务器 SHALL 提供完整的禅道 API 连接器，支持与禅道 REST API 的所有交互。

#### Scenario: 连接配置
- **GIVEN** 用户提供了正确的禅道 baseUrl 和 token
- **WHEN** MCP 服务器启动
- **THEN** 建立与禅道 API 的连接并验证认证信息

#### Scenario: 连接失败处理
- **GIVEN** 用户提供了错误的认证信息或无效的 baseUrl
- **WHEN** MCP 服务器尝试连接禅道 API
- **THEN** 返回详细的错误信息，包括错误原因和修复建议

### Requirement: Project Management Tools
MCP 服务器 SHALL 提供项目管理相关的工具，包括项目查询、创建、更新等操作。

#### Scenario: 获取项目列表
- **GIVEN** 用户已配置禅道连接
- **WHEN** 调用 get_projects 工具
- **THEN** 返回项目列表，包含每个项目的 id、name、code、status、begin、end 等字段

#### Scenario: 创建项目
- **GIVEN** 用户提供了项目名称和代码
- **WHEN** 调用 create_project 工具
- **THEN** 创建新项目并返回项目详情，包括自动分配的 ID

#### Scenario: 按 ID 获取项目
- **GIVEN** 用户提供了有效的项目 ID
- **WHEN** 调用 get_project_by_id 工具
- **THEN** 返回该项目的完整详细信息

#### Scenario: 项目不存在处理
- **GIVEN** 用户提供了不存在的项目 ID
- **WHEN** 调用 get_project_by_id 工具
- **THEN** 返回错误信息，明确说明项目不存在

### Requirement: Task Management Tools
MCP 服务器 SHALL 提供任务管理相关的工具，支持任务的全生命周期管理。

#### Scenario: 获取任务列表
- **GIVEN** 用户已配置禅道连接
- **WHEN** 调用 get_tasks 工具，可选择按项目 ID 过滤
- **THEN** 返回任务列表，包含每个任务的 id、name、project、status、assignedTo、deadline 等字段

#### Scenario: 创建任务
- **GIVEN** 用户提供了任务名称、项目 ID、负责人等信息
- **WHEN** 调用 create_task 工具
- **THEN** 创建新任务并返回任务详情，包括自动分配的 ID

#### Scenario: 更新任务状态
- **GIVEN** 用户提供了任务 ID 和新状态
- **WHEN** 调用 update_task_status 工具
- **THEN** 更新任务状态并返回更新后的任务信息

#### Scenario: 无效状态处理
- **GIVEN** 用户提供了不被禅道支持的状态值
- **WHEN** 调用 update_task_status 工具
- **THEN** 返回错误信息，列出所有有效的状态值

### Requirement: Product Management Tools
MCP 服务器 SHALL 提供产品管理相关的工具，支持产品的创建、查询和管理。

#### Scenario: 获取产品列表
- **GIVEN** 用户已配置禅道连接
- **WHEN** 调用 get_products 工具
- **THEN** 返回产品列表，包含每个产品的 id、name、code、status、createdDate 等字段

#### Scenario: 创建产品
- **GIVEN** 用户提供了产品名称和代码
- **WHEN** 调用 create_product 工具
- **THEN** 创建新产品并返回产品详情，包括自动分配的 ID

### Requirement: Story Management Tools
MCP 服务器 SHALL 提供需求（Story）管理相关的工具，支持需求的创建、查询和状态管理。

#### Scenario: 获取需求列表
- **GIVEN** 用户已配置禅道连接
- **WHEN** 调用 get_stories 工具，可选择按产品 ID 过滤
- **THEN** 返回需求列表，包含每个需求的 id、title、product、status、pri、estimate 等字段

#### Scenario: 创建需求
- **GIVEN** 用户提供了需求标题、产品 ID、优先级等信息
- **WHEN** 调用 create_story 工具
- **THEN** 创建新需求并返回需求详情，包括自动分配的 ID

### Requirement: User Management Tools
MCP 服务器 SHALL 提供用户管理相关的工具，支持用户查询和权限验证。

#### Scenario: 获取用户列表
- **GIVEN** 用户已配置禅道连接
- **WHEN** 调用 get_users 工具
- **THEN** 返回用户列表，包含每个用户的 id、account、realname、dept、role 等字段

#### Scenario: 验证用户权限
- **GIVEN** 用户提供了用户名和权限类型
- **WHEN** 调用验证用户权限的工具
- **THEN** 返回用户的权限状态和角色信息

### Requirement: Generic API Request Tool
MCP 服务器 SHALL 提供通用 API 请求工具，允许用户直接调用禅道的任何 API 端点。

#### Scenario: 自定义 API 调用
- **GIVEN** 用户提供了 API 端点、HTTP 方法和参数
- **WHEN** 调用 zendao_request 工具
- **THEN** 执行 API 请求并返回响应数据

#### Scenario: 错误处理
- **GIVEN** 用户提供了不存在的 API 端点或无效参数
- **WHEN** 调用 zendao_request 工具
- **THEN** 返回详细的错误信息，包括 HTTP 状态码和错误消息

### Requirement: Batch Operations
MCP 服务器 SHALL 提供批量操作工具，支持一次处理多个对象，提高操作效率。

#### Scenario: 批量创建任务
- **GIVEN** 用户提供了任务列表，包含名称、项目 ID、负责人等信息
- **WHEN** 调用 batch_create_tasks 工具
- **THEN** 批量创建所有任务，返回成功/失败统计和详细报告

#### Scenario: 批量更新任务状态
- **GIVEN** 用户提供了任务 ID 列表和新状态
- **WHEN** 调用 batch_update_task_status 工具
- **THEN** 批量更新所有任务状态，返回更新结果

#### Scenario: 部分成功处理
- **GIVEN** 批量操作中有部分任务失败（权限不足、重复名称等）
- **WHEN** 设置 continueOnError: true
- **THEN** 继续处理剩余任务，返回每个任务的成功/失败状态

#### Scenario: 批量操作进度报告
- **GIVEN** 用户执行大批量操作（100+ 项目）
- **WHEN** 操作进行中
- **THEN** 实时报告处理进度，包括已处理数量和预计剩余时间

#### Scenario: 并发控制
- **GIVEN** 用户执行大量并发请求
- **WHEN** 并发数超过限制（默认 10 个并发）
- **THEN** 自动排队处理，避免对禅道 API 造成压力

#### Scenario: 批量创建项目
- **GIVEN** 用户提供了项目信息列表
- **WHEN** 调用 batch_create_projects 工具
- **THEN** 批量创建所有项目，支持模板和自动生成代码

#### Scenario: 批量创建需求
- **GIVEN** 用户提供了需求列表，包含标题、产品 ID、优先级等
- **WHEN** 调用 batch_create_stories 工具
- **THEN** 批量创建所有需求，返回创建结果和 ID 映射

#### Scenario: 批量操作回滚
- **GIVEN** 批量操作出现严重错误
- **WHEN** 用户需要回滚已成功创建的对象
- **THEN** 提供批量删除功能，清理已创建的对象

### Requirement: Caching Mechanism
MCP 服务器 SHALL 提供智能缓存机制，提高查询性能，减少不必要的 API 调用。

#### Scenario: 缓存查询结果
- **GIVEN** 用户连续查询项目列表
- **WHEN** 缓存中存在有效的项目列表数据
- **THEN** 直接从缓存返回数据，无需重新请求 API

#### Scenario: 缓存失效
- **GIVEN** 缓存中的数据超过 TTL 时间
- **WHEN** 用户再次查询该项目列表
- **THEN** 自动清除过期缓存，重新请求 API 获取最新数据

#### Scenario: 缓存更新
- **GIVEN** 用户执行了修改操作（如创建项目）
- **WHEN** 后续查询相关数据
- **THEN** 自动更新缓存，确保数据一致性

#### Scenario: LRU 缓存管理
- **GIVEN** 缓存已满（达到最大项数）
- **WHEN** 需要缓存新数据
- **THEN** 自动移除最久未使用的数据，腾出空间

#### Scenario: 不同数据类型的缓存策略
- **GIVEN** 查询不同类型的数据
- **WHEN** 缓存时
- **THEN** 根据数据类型设置不同的 TTL（静态数据 30分钟，动态数据 5分钟）

#### Scenario: 手动缓存清理
- **GIVEN** 用户需要清理所有缓存
- **WHEN** 调用 clear_cache 工具
- **THEN** 清理所有缓存数据，下次查询将从 API 重新获取

#### Scenario: 缓存性能统计
- **GIVEN** 用户查询缓存性能
- **WHEN** 调用 get_cache_stats 工具
- **THEN** 返回缓存命中率、缓存项数、内存使用等统计信息

### Requirement: API Version Compatibility
MCP 服务器 SHALL 兼容禅道开源版 18.0+ 的所有 API 版本。

#### Scenario: 低版本 API 调用
- **GIVEN** 用户连接到禅道 18.x 版本
- **WHEN** 调用 API 工具
- **THEN** 使用兼容低版本的 API 格式和参数

#### Scenario: 版本特性检测
- **GIVEN** 不知道连接的禅道版本
- **WHEN** 启动时
- **THEN** 自动检测禅道版本并调整 API 调用方式

#### Scenario: 向后兼容
- **GIVEN** 禅道升级到新版本
- **WHEN** MCP 服务器继续运行
- **THEN** 自动适配新版本 API，保持向后兼容

### Requirement: Type Safety
MCP 服务器 SHALL 为所有工具提供完整的 TypeScript 类型定义，确保类型安全。

#### Scenario: 参数类型验证
- **GIVEN** 用户调用任意工具并提供参数
- **WHEN** 参数类型不匹配时
- **THEN** MCP 工具在调用前进行类型检查，拒绝无效参数

#### Scenario: 返回值类型定义
- **GIVEN** 用户调用任意工具
- **WHEN** 工具返回数据时
- **THEN** 返回值有明确的 TypeScript 类型注解，便于 IDE 提示和类型检查

### Requirement: Error Handling
MCP 服务器 SHALL 提供完善的错误处理机制，向用户返回清晰、详细的错误信息。

#### Scenario: 网络错误处理
- **GIVEN** 网络连接中断或 API 服务器不可用
- **WHEN** 调用任意工具
- **THEN** 返回网络错误信息，包括错误类型和重试建议

#### Scenario: 认证错误处理
- **GIVEN** token 过期、无效或权限不足
- **WHEN** 调用需要认证的工具
- **THEN** 返回认证错误信息，指导用户如何修复认证问题

#### Scenario: 业务逻辑错误处理
- **GIVEN** 业务规则验证失败（如重复名称、无效引用等）
- **WHEN** 调用相关工具
- **THEN** 返回业务错误信息，明确说明失败原因和修正方法

### Requirement: Configuration Management
MCP 服务器 SHALL 支持通过环境变量或配置文件管理禅道连接信息。

#### Scenario: 环境变量配置
- **GIVEN** 用户设置了 ZENDTAO_BASE_URL 和 ZENDTAO_TOKEN 环境变量
- **WHEN** MCP 服务器启动
- **THEN** 自动使用环境变量中的配置连接禅道

#### Scenario: 配置文件支持
- **GIVEN** 用户提供了配置文件（如 config.json）
- **WHEN** MCP 服务器启动
- **THEN** 从配置文件读取连接信息并建立连接

### Requirement: Logging and Debugging
MCP 服务器 SHALL 提供详细的日志记录和调试信息，便于问题诊断。

#### Scenario: 操作日志记录
- **GIVEN** 用户调用任意工具
- **WHEN** 工具执行时
- **THEN** 记录操作日志，包括请求参数、执行时间、响应状态等

#### Scenario: 调试模式
- **GIVEN** 用户启用调试模式
- **WHEN** 工具执行失败
- **THEN** 返回详细的调试信息，包括完整错误堆栈和请求/响应详情

### Requirement: Documentation
MCP 服务器 SHALL 提供完整的文档，包括工具说明、使用示例和最佳实践。

#### Scenario: 工具文档
- **GIVEN** 用户查看工具文档
- **WHEN** 查看任意工具的说明
- **THEN** 提供清晰的功能描述、参数说明、返回值格式和使用示例

#### Scenario: 快速开始指南
- **GIVEN** 新用户需要快速上手
- **WHEN** 阅读快速开始指南
- **THEN** 能够完成安装、配置和基本使用的完整流程