# TimeCard MCP

透過 HTTP 直接操作 TimeCard 工時系統的 Model Context Protocol (MCP) 伺服器。

## 功能特色

- **無狀態工具**：每次工具呼叫完全獨立，不依賴跨呼叫的共享狀態
- **原子性儲存**：單一 `timecard_save` 即可同時處理項目、工時與備註
- **自動驗證**：首次請求時自動登入，無需手動處理
- **Session 持久化**：HTTP session cookie 可跨重啟重複使用

---

## 快速開始

**建議方式：** 使用 `npx` 自動取得最新版本（需 Node.js v18+）。

```bash
export TIMECARD_USERNAME="你的帳號"
export TIMECARD_PASSWORD="你的密碼"
export TIMECARD_BASE_URL="http://your-timecard-server/app/"

npx git+https://github.com/keith-hung/timecard-mcp.git
```

### Claude Desktop / Claude Code 整合

```json
{
  "mcpServers": {
    "timecard": {
      "command": "npx",
      "args": ["git+https://github.com/keith-hung/timecard-mcp.git"],
      "env": {
        "TIMECARD_USERNAME": "你的帳號",
        "TIMECARD_PASSWORD": "你的密碼",
        "TIMECARD_BASE_URL": "http://your-timecard-server/app/"
      }
    }
  }
}
```

**注意：** `TIMECARD_BASE_URL` 必須包含完整的應用程式路徑（例如 `http://your-server/app/`）。

---

## 可用工具（6 個）

### 資料查詢
| 工具 | 說明 |
|------|------|
| `timecard_get_projects` | 取得可用專案（回傳 `id` 供其他工具使用） |
| `timecard_get_activities(project_id)` | 取得專案下的活動（回傳 `value` 供 `save` 使用） |
| `timecard_get_timesheet(date)` | 取得某週工時表資料（工時、狀態、備註） |
| `timecard_get_summary(date)` | 取得每週摘要統計 |

### 寫入
| 工具 | 說明 |
|------|------|
| `timecard_save(date, entries?, hours?, notes?)` | 原子性儲存 — 一次 POST 套用所有變更 |

### 工具資訊
| 工具 | 說明 |
|------|------|
| `timecard_version` | 取得 MCP 版本資訊（commit、branch、build date） |

---

## 使用流程

```
1. get_timesheet("2026-03-02")          — 查看目前儲存的資料
2. get_activities("17647")              — 取得 activity_value
3. save({
     date: "2026-03-02",
     entries: [
       { entry_index: 0, project_id: "17647", activity_value: "true$9$17647$100" }
     ],
     hours: [
       { entry_index: 0, date: "2026-03-02", hours: 8.0 },
       { entry_index: 0, date: "2026-03-03", hours: 8.0 }
     ],
     notes: [
       { entry_index: 0, date: "2026-03-02", note: "Development" }
     ]
   })                                   — 原子性儲存
4. get_timesheet("2026-03-02")          — 驗證結果（選用）
```

### 重點說明

- **日期格式統一使用 YYYY-MM-DD** — hours 和 notes 的日期必須與頂層 `date` 同一週
- **`entries` 為選填** — 若該列已有正確的 project/activity，可省略
- **項目不可變性** — 變更既有項目的 project/activity 會清除其工時，請改用不同的 `entry_index`
- **備註限制** — 不可包含：`#$%^&*=+{}[]|?'"`

### 增量更新

若週一至週三已有工時，僅需補填週四、週五：

```
save({
  date: "2026-03-02",
  hours: [
    { entry_index: 0, date: "2026-03-05", hours: 8.0 },
    { entry_index: 0, date: "2026-03-06", hours: 8.0 }
  ]
})
```

無需重新指定 entries 或既有工時。save 工具會自動從伺服器重建完整表單，僅覆蓋你指定的變更。

---

## 本地開發

```bash
git clone https://github.com/keith-hung/timecard-mcp.git
cd timecard-mcp
npm install
npm run build
```

指向本地 build：

```json
{
  "mcpServers": {
    "timecard": {
      "command": "node",
      "args": ["/path/to/timecard-mcp/dist/index.js"],
      "env": {
        "TIMECARD_USERNAME": "你的帳號",
        "TIMECARD_PASSWORD": "你的密碼",
        "TIMECARD_BASE_URL": "http://your-timecard-server/app/"
      }
    }
  }
}
```

## 授權

MIT