# 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