# TimeTracker RX MCP サーバー

TimeTracker RX（デンソークリエイト社）の REST API を MCP（Model Context Protocol）サーバーとして公開するツールです。
Claude Code / Claude Desktop / Cursor 等の AI ツールから工数管理・プロジェクト管理・分析を直接操作できます。

**セキュリティポリシー: 「人のものを壊さない」** — 自分が管理するリソースのみ書き込みを許可し、他者のプロジェクト・ワークアイテムの破壊を防ぎます。

## バージョン履歴

最新版: **Ver1.09** (2026-06-26)

| Ver | 日付 | 主要変更 |
|---|---|---|
| **Ver1.09** | 2026-06-26 | `update_work_item` を日付更新・`clearSchedule` 対応に拡張（`planned_start_date`/`planned_finish_date`/`fields`/`clear_schedule`/`move_schedule_days`/`field_calc_types`/`assignment_change`/`propagate_to_children` 追加）、`work_item_id`→`work_item_ids` リネームで複数ID一括更新・クリア対応 |
| **Ver1.08** | 2026-06-26 | `create_project`/`update_project` を公式API準拠に引数拡張（plannedStartDate/plannedFinishDate/managerId/members/projectCategories/memberChange 等）、`copy_project` 追加、`get_project` に `includes` 追加 |
| **Ver1.07** | 2026-05-08 | master 系: `skip→offset` 命名統一 + レスポンス `data[]` アンラップ。time_entries 一覧に日付・プロジェクト等のサーバ側フィルタ追加 |
| **Ver1.06** | 2026-05-08 | acl の引数を公式 `ace`/`aceChange` 構造に再設計、analytics の body を公式 `filterBy`/`groups` 構造に再設計 |
| Ver1.05 | 2026-05-07 | `update_work_item` の `status_id` → `status_type_id` リネーム + `actual_progress` 引数追加 |
| Ver1.04 | 2026-04-27 | write 系 body を `{fields:{...}}` ラッパに統一 |
| Ver1.01〜1.02 | 2026-04-27 | OwnershipChecker のレスポンス形式対応 |
| Ver1.00 | 2026-04-20 | Python + FastMCP 初版リリース |

> **互換性ポリシー**: 公式 API 仕様準拠を最優先するため、minor bump (Ver1.0X) でも引数 rename・必須化等の破壊変更を含みます。引数の差分は `tests/test_contract.py` で自動検知されます。

## 機能一覧

### 認証（1）

| ツール名 | 説明 |
|---------|------|
| `get_me` | 自分のユーザー情報取得 |

### ユーザー参照（2）

| ツール名 | 説明 |
|---------|------|
| `list_users` | ユーザー一覧取得（読み取り専用） |
| `get_user` | ユーザー取得（読み取り専用） |

### タイムシート — 自分の工数操作（5）

| ツール名 | 説明 |
|---------|------|
| `list_time_entries` | 自分の実績工数一覧取得 |
| `get_time_entry` | 自分の実績工数取得 |
| `add_time_entry` | 自分の実績工数追加（他人のプロジェクトへの工数登録も可） |
| `update_time_entry` | 自分の実績工数更新 |
| `delete_time_entry` | 自分の実績工数削除 |

### タイムシート — 任意ユーザー参照（2）

| ツール名 | 説明 |
|---------|------|
| `list_user_time_entries` | 任意ユーザーの実績工数一覧取得（読み取り専用） |
| `get_user_time_entry` | 任意ユーザーの実績工数取得（読み取り専用） |

### プロジェクト（7）

| ツール名 | 説明 |
|---------|------|
| `list_projects` | プロジェクト一覧取得（全プロジェクト閲覧可） |
| `get_project` | プロジェクト取得（includes で Members/UserGroups/WorkCalendar を指定可） |
| `create_project` | プロジェクト作成（plannedStartDate/plannedFinishDate 等の公式項目・メンバー対応、管理者は未指定で自分） |
| `update_project` | プロジェクト更新（日付・メンバー変更等の公式項目対応、自分が管理者のPJのみ） |
| `copy_project` | 既存プロジェクトの設定・メンバーをコピーして新規作成 |
| `get_project_calendar` | プロジェクトカレンダー取得 |
| `get_project_profile` | プロジェクトプロファイル取得 |

### ワークアイテム（6）

| ツール名 | 説明 |
|---------|------|
| `list_sub_items` | サブアイテム一覧取得 |
| `get_work_item` | ワークアイテム取得 |
| `create_work_item` | ワークアイテム追加（自分が管理者のプロジェクトのみ） |
| `update_work_item` | ワークアイテム更新（予定日更新・clearSchedule によるクリア・複数ID一括対応、自分が管理者のプロジェクトのみ） |
| `delete_work_item` | ワークアイテム削除（自分が管理者のプロジェクトのみ、アトミック拒否） |
| `duplicate_work_item` | ワークアイテム複製（自分が管理者のプロジェクトのみ） |

### ACL — プロジェクト権限（4）

| ツール名 | 説明 |
|---------|------|
| `get_project_acl` | プロジェクト権限取得（全プロジェクト閲覧可） |
| `add_project_acl` | プロジェクト権限追加（自分が管理者のプロジェクトのみ） |
| `update_project_acl` | プロジェクト権限更新（自分が管理者のプロジェクトのみ） |
| `delete_project_acl` | プロジェクト権限削除（自分が管理者のプロジェクトのみ） |

### マスタ参照（7）

| ツール名 | 説明 |
|---------|------|
| `list_item_types` | アイテムタイプ一覧 |
| `list_status_types` | ステータスタイプ一覧 |
| `list_process_categories` | 工程分類一覧 |
| `list_time_entry_categories` | 作業分類一覧 |
| `list_field_types` | フィールドタイプ一覧 |
| `list_organizations` | 組織一覧 |
| `list_profiles` | プロファイル一覧 |

### 分析（3）

| ツール名 | 説明 |
|---------|------|
| `analyze_time` | 工数分析（全ユーザー対象可） |
| `analyze_item_counts` | アイテム件数分析（全ユーザー対象可） |
| `export_time_entries` | 実績工数エクスポート |

## セットアップ

### 前提条件

- Python 3.12 以上
- [uv](https://docs.astral.sh/uv/)（`curl -LsSf https://astral.sh/uv/install.sh | sh` などでインストール）
- TimeTracker RX の API キー（管理画面のユーザー設定から発行）

### インストール

MCP クライアントごとに最適な方式を使い分けます。

| 環境 | 方式 | 理由 |
|------|------|------|
| Claude Code (WSL/Linux/macOS) | uvx (on-demand) | 事前インストール不要、タグ変更即反映 |
| Cursor (Windows / macOS) | uvx (on-demand) | 同上 |
| Claude Desktop / Cowork (Windows MSIX) | pre-install | MSIX sandbox が spawn 子プロセスからの git fetch を拒否するため |

**uvx 方式（Claude Code / Cursor）**:

```bash
# 動作確認
TIMETRACKER_BASE_URL=https://your-server/TimeTrackerRX/ \
TIMETRACKER_API_KEY=your-key \
uvx --from git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09 timetracker-rx-mcp
```

**pre-install 方式（Claude Desktop）**:

Windows PowerShell で事前にインストール:

```powershell
uv tool install git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09 --force
```

インストール先: `%USERPROFILE%\.local\bin\timetracker-rx-mcp.exe`。以降は `timetracker-rx-mcp` コマンドとして実行可能。

**バージョン指定:**
- 本番利用: `@Ver1.09` のようにタグ固定を推奨（破壊変更から保護される）
- 開発版: `@master` で常に最新を追う（破壊変更の可能性あり）

**更新:**
- uvx 方式: `uv cache clean` で再取得
- pre-install 方式: `uv tool upgrade timetracker-rx-mcp --force`

### 環境変数

MCP 設定ファイルの `env` セクションで環境変数を指定します。

| 変数名 | 必須 | 説明 | 例 |
|--------|:---:|------|-----|
| `TIMETRACKER_BASE_URL` | 必 | TimeTracker RX の API ベース URL | `https://your-server/TimeTrackerRX/` |
| `TIMETRACKER_API_KEY`  | 必 | ユーザーの API キー | `your-api-key` |
| `TIMETRACKER_TIMEOUT_MS` | 任 | リクエストタイムアウト（ミリ秒、既定 30000） | `60000` |
| `TIMETRACKER_SKIP_TLS_VERIFY` | 任 | 自己署名証明書向け TLS 検証スキップ（既定 false） | `true` |

### MCP 設定

全環境共通で `uvx --from git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09 timetracker-rx-mcp` を呼び出します。

#### Claude Code（WSL/Linux/macOS）

`~/.claude.json` の `mcpServers` に追記します。

```json
{
  "mcpServers": {
    "timetracker-rx": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09",
        "timetracker-rx-mcp"
      ],
      "env": {
        "TIMETRACKER_BASE_URL": "https://your-server/TimeTrackerRX/",
        "TIMETRACKER_API_KEY": "your-api-key"
      }
    }
  }
}
```

#### Claude Desktop / Cowork（Windows MSIX 環境）

MSIX sandbox で git fetch が失敗するため **pre-install 方式**を使います。事前に `uv tool install` を実行しておく必要があります（上記「インストール」参照）。

`%APPDATA%\Claude\claude_desktop_config.json` の `mcpServers` に追記:

```json
{
  "mcpServers": {
    "timetracker-rx": {
      "command": "timetracker-rx-mcp",
      "env": {
        "TIMETRACKER_BASE_URL": "https://your-server/TimeTrackerRX/",
        "TIMETRACKER_API_KEY": "your-api-key"
      }
    }
  }
}
```

> 新バージョン（Ver1.01 等）リリース時は `uv tool upgrade timetracker-rx-mcp --force` を PowerShell で別途実行してください（Claude Desktop は自動更新されません）。

#### Cursor（Windows / macOS）

```json
{
  "mcpServers": {
    "timetracker-rx": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/nori1173-ops/timetracker-rx-mcp@Ver1.09",
        "timetracker-rx-mcp"
      ],
      "env": {
        "TIMETRACKER_BASE_URL": "https://your-server/TimeTrackerRX/",
        "TIMETRACKER_API_KEY": "your-api-key"
      }
    }
  }
}
```

> 自己署名証明書の環境では `env` に `"TIMETRACKER_SKIP_TLS_VERIFY": "true"` を追加してください。

## セキュリティポリシー

**「人のものを壊さない」** — このルールはすべての実装に優先します。

| 操作 | 制限 |
|------|------|
| 閲覧（GET） | 全て許可。他者のリソースも読み取り可 |
| プロジェクト作成 | 管理者（managerId）は自分に自動設定 |
| プロジェクト更新 | 自分が管理者のプロジェクトのみ |
| ワークアイテム CRUD | 自分が管理者のプロジェクトのみ |
| ACL 変更 | 自分が管理者のプロジェクトのみ |
| タイムシート操作 | 自分のユーザー ID のみ（他者分は閲覧のみ可） |
| 分析（読み取り） | 全ユーザーのデータを含めて許可 |
| ユーザー管理 | 一覧・取得のみ実装（作成・更新・削除は除外） |

複数 ID の一括操作では、1 つでも権限のない対象が含まれる場合は操作全体を拒否します（アトミック拒否）。

## 開発

### セットアップ

```bash
uv sync --extra dev
```

### テスト

```bash
uv run pytest                    # 全テスト
uv run pytest --cov              # カバレッジ付き
uv run pytest tests/test_ownership.py -v  # 単一ファイル
```

### lint / format

```bash
uv run ruff check src/ tests/
uv run ruff format src/ tests/
```

### ローカル実行

```bash
export TIMETRACKER_BASE_URL=https://your-server/TimeTrackerRX/
export TIMETRACKER_API_KEY=your-key
uv run timetracker-rx-mcp
```

## 技術スタック

- Python 3.12+
- [mcp](https://github.com/modelcontextprotocol/python-sdk)（FastMCP）
- [httpx](https://www.python-httpx.org/)（HTTP クライアント、コネクションプール）
- [pydantic](https://docs.pydantic.dev/)（バリデーション）
- [uv](https://docs.astral.sh/uv/)（パッケージ管理）
- [ruff](https://docs.astral.sh/ruff/)（lint + format）
- pytest / pytest-asyncio / respx（テスト）

## アーキテクチャ

詳細は [Documents/DESIGN.md](Documents/DESIGN.md) を参照してください。

## ライセンス

MIT

## 免責事項

- 本プロジェクトはデンソークリエイト社とは無関係の非公式ツールです。
- TimeTracker RX の正規ライセンスが別途必要です。
- API の仕様変更により動作しなくなる可能性があります。
- 本ツールの使用により発生した損害について開発者は責任を負いません。

## 商標

「TimeTracker」はデンソークリエイト株式会社の登録商標です。