@wallacewen/tapd-mcp-server

# TAPD MCP Server - 本周工作数据获取助手一个专为AI助手设计的Model Context Protocol (MCP) 服务器，集成TAPD工时系统，获取本周项目、人员、工作事项、工时和花费等综合工作数据。 ## 概述 TAPD MCP Server 让AI助手能够通过Model Context Protocol协议访问TAPD工时数据，获取完整的本周工作信息。主要功能包括： * **项目信息获取** - 获取员工参与的各个项目详情 * **人员工作分配** - 查看人员在不同项目中的工作分布 * **工作事项详情** - 获取具体的任务和工作内容描述 * **工时统计分析** - 统计各项目和任务的时间投入 * **资源花费情况** - 分析工作成本和资源利用情况 ## 最新更新 ### 🔄 POST请求适配 (v1.0.0) 已完全适配实际的TAPD API POST请求格式： - ✅ 请求方式：`POST http://porsche-tapd-inc.chinahuanong.com.cn/ai/queryTimeSheets` - ✅ 内容类型：`application/x-www-form-urlencoded` - ✅ 参数顺序：`name`, `endDate`, `startDate` (与实际API保持一致) - ✅ 编码方式：URL编码格式 (`name=潘明哲&endDate=2025-05-23&startDate=2025-05-23`) - ✅ 错误处理：详细的请求和响应日志 - ✅ 连接测试：使用实际API端点进行连接验证 ### 🧪 测试功能新增测试脚本，可以快速验证TAPD连接和数据查询： ```bash # 安装依赖 pnpm install # 运行TAPD连接测试 pnpm run test:tapd # 或者直接运行 ts-node --esm src/test-tapd.ts ``` ## 核心功能 - **本周工作数据查询** - 基于员工姓名和日期范围获取完整工作数据 - **多维度信息整合** - 项目、人员、任务、工时、成本一体化查询 - **结构化数据输出** - 支持结构化JSON数据输出，便于AI分析 - **参数严格验证** - 使用Zod进行参数验证确保数据准确性 - **完整TypeScript支持** - 提供类型安全保障 ## Claude Desktop 使用配置 1. 编辑 `claude_desktop_config.json`: - 打开 Claude Desktop - 进入 `Settings` -> `Developer` -> `Edit Config` - 添加以下配置到 `mcpServers` 部分 2. 重启 Claude Desktop 使配置生效 ### Docker 部署 ```json { "mcpServers": { "tapd-weekly-data": { "command": "docker", "args": [ "run", "-i", "--rm", "-e", "TAPD_BASE_URL", "your-username/tapd-mcp-server" ], "env": { "TAPD_BASE_URL": "http://your-tapd-server.com" } } } } ``` ### NPX 部署 ```json { "mcpServers": { "tapd-weekly-data": { "command": "npx", "args": [ "-y", "tapd-mcp-server@1.0.0" ], "env": { "TAPD_BASE_URL": "http://your-tapd-server.com" } } } } ``` ### 本地开发配置 ```json { "mcpServers": { "tapd-weekly-data": { "command": "node", "args": [ "/path/to/tapd-mcp-server/dist/index.js" ], "env": { "TAPD_BASE_URL": "http://your-tapd-server.com" } } } } ``` ## 可用工具 ### 本周工作数据获取 `get_weekly_work_summary`: 获取员工本周综合工作数据 * 参数: * `employee_name` (必需) - 员工姓名 * `week_start_date` (必需) - 周开始日期 (YYYY-MM-DD格式，通常为周一) * `week_end_date` (必需) - 周结束日期 (YYYY-MM-DD格式，通常为周日) * 返回数据包含: * **项目信息** - 员工参与的项目列表和详情 * **工作事项** - 具体任务和工作内容 * **工时分配** - 各项目和任务的时间投入 * **成本花费** - 人力资源成本统计 ## 🎯 可用提示词 TAPD MCP服务器提供了多个智能提示词，帮助AI更好地分析和使用工作数据： ### 1. `weekly_report_analysis` - 周报分析 **功能**: 生成全面的周工作报告分析 **参数**: - `employee_name` (必需) - 要分析的员工姓名 - `week_start_date` (必需) - 周开始日期 (YYYY-MM-DD格式) - `week_end_date` (必需) - 周结束日期 (YYYY-MM-DD格式) - `analysis_focus` (可选) - 分析重点 (如：生产力、项目分布、时间分配) **输出**: 详细的周报分析框架，包含工作量分析、项目分布、任务类型统计等维度 ### 2. `project_team_analysis` - 项目团队协作分析 **功能**: 分析团队工作分布和协作模式 **参数**: - `project_name` (必需) - 要分析的项目名称 - `team_members` (必需) - 团队成员名单 (逗号分隔) - `week_start_date` (必需) - 分析期间开始日期 - `week_end_date` (必需) - 分析期间结束日期 **输出**: 团队协作分析框架，包含人员投入、任务分工、协作效率等 ### 3. `personal_productivity_insights` - 个人效率洞察 **功能**: 基于工作模式生成个人效率洞察和建议 **参数**: - `employee_name` (必需) - 要分析的员工姓名 - `analysis_period_weeks` (可选) - 分析周数 (默认: 4) - `current_date` (可选) - 当前日期参考 (YYYY-MM-DD格式) **输出**: 个人效率分析框架，包含工作模式识别、效率评估、成长建议等 ### 4. `tapd_data_query_guide` - 数据查询指南 **功能**: TAPD MCP服务器使用指南和最佳实践 **参数**: 无 **输出**: 完整的使用指南，包含工具说明、查询模式、分析技巧等 ## 🚀 提示词使用示例 ### 生成员工周报 ``` 使用 weekly_report_analysis 提示词: - employee_name: "张三" - week_start_date: "2025-05-20" - week_end_date: "2025-05-26" - analysis_focus: "生产力分析" ``` ### 团队协作分析 ``` 使用 project_team_analysis 提示词: - project_name: "CRM系统" - team_members: "张三,李四,王五" - week_start_date: "2025-05-20" - week_end_date: "2025-05-26" ``` ## 环境变量 * `TAPD_BASE_URL` - TAPD系统地址 (默认: http://porsche-tapd-inc.chinahuanong.com.cn) ## 本周工作数据获取示例 ### 获取个人本周工作概况 ``` 请获取张三本周(2025年1月6日到2025年1月12日)的完整工作数据，包括参与的项目、具体工作事项、工时分配和资源花费情况。 ``` ### 分析项目人员投入 ``` 请获取张三、李四、王五三人本周的工作数据，分析CRM项目的人员投入、工作进展和成本花费情况。 ``` ### 工作量和成本统计 ``` 请分析张三本周的工作分布，统计各项目的工时占比、主要工作事项和相应的资源成本。 ``` ## 返回数据格式 ### 本周工作数据响应 ```json { "success": true, "message": "Success", "total": 15, "data": [ { "id": "12345", "name": "张三", "date": "2025-01-08", "hours": 8.0, "project": "CRM客户管理系统", "task": "用户权限模块开发", "description": "完成角色权限分配功能，包括前端界面设计和后端权限验证逻辑实现", "cost_rate": "500/天", "project_phase": "开发阶段" }, { "id": "12346", "name": "张三", "date": "2025-01-09", "hours": 6.5, "project": "数据分析平台", "task": "销售报表优化", "description": "优化销售数据查询性能，重构报表生成逻辑，添加数据缓存机制", "cost_rate": "500/天", "project_phase": "优化阶段" }, { "id": "12347", "name": "张三", "date": "2025-01-10", "hours": 7.5, "project": "CRM客户管理系统", "task": "API接口联调", "description": "与前端团队联调用户管理API，修复数据格式问题，完成集成测试", "cost_rate": "500/天", "project_phase": "测试阶段" } ] } ``` ### 数据分析维度 #### 项目维度 - 项目名称和阶段 - 项目投入总工时 - 项目成本统计 - 项目进展情况 #### 人员维度 - 员工工作分配 - 每日工作强度 - 技能应用情况 - 工作效率分析 #### 工作事项维度 - 任务类型分布 - 任务完成进度 - 工作内容详情 - 任务优先级 #### 工时维度 - 总工时统计 - 项目时间分配 - 每日工时分布 - 加班情况分析 #### 成本维度 - 人力成本计算 - 项目预算使用 - 资源利用率 - 成本效益分析 ## 开发指南 1. 克隆仓库: ```bash git clone https://github.com/yourusername/tapd-mcp-server.git cd tapd-mcp-server ``` 2. 安装依赖: ```bash pnpm install ``` 3. 构建项目: ```bash pnpm run build ``` 4. 配置 Claude Desktop ```json { "mcpServers": { "tapd-weekly-data": { "command": "node", "args": [ "/path/to/tapd-mcp-server/dist/index.js" ], "env": { "TAPD_BASE_URL": "http://your-tapd-server.com" } } } } ``` ### 开发环境要求 * Node.js 20 或更高版本 * pnpm 10.7.0 或更高版本 * Docker (用于容器化构建) ### 开发脚本 * `pnpm run build` - 构建TypeScript代码 * `pnpm run start` - 启动服务器 * `pnpm run dev` - 开发模式启动 * `pnpm run test` - 运行测试 * `pnpm run lint` - 代码检查 * `pnpm run format` - 代码格式化 ## 许可证 MIT