# tocaro-mcp

Tocaro Web API (`https://api.tocaro.im`) を MCP ツールとして公開するローカル MCP サーバ。
トランスポートは stdio（既定）と Streamable HTTP（`--http`）に対応する。

実装仕様の詳細は [CLAUD.md](./CLAUD.md) を参照。

## セットアップ

```bash
uv sync
cp .env.example .env
# .env を編集して TOCARO_API_TOKEN を設定する
```

## 起動確認

```bash
# stdio で起動（Ctrl-C で終了）
uv run tocaro-mcp

# Streamable HTTP で起動
uv run tocaro-mcp --http --host 127.0.0.1 --port 8000

# MCP Inspector で対話的に確認
uv run fastmcp dev src/tocaro_mcp/server.py

# ツール一覧の確認
uv run fastmcp list src/tocaro_mcp/server.py
```

## 環境変数

`.env` に設定する（`.env.example` 参照）。

| 変数名 | 必須 | 既定値 | 説明 |
|---|---|---|---|
| `TOCARO_API_TOKEN` | ✅（read/write 個別設定時は不要） | — | Bot ユーザーの Bearer トークン |
| `TOCARO_API_TOKEN_READ` | | — | read スコープ専用トークン（未設定なら `TOCARO_API_TOKEN` にフォールバック） |
| `TOCARO_API_TOKEN_WRITE` | | — | write スコープ専用トークン（未設定なら `TOCARO_API_TOKEN` にフォールバック） |
| `TOCARO_BASE_URL` | | `https://api.tocaro.im` | API のベース URL |
| `TOCARO_TIMEOUT` | | `30.0` | リクエストタイムアウト（秒） |
| `TOCARO_READ_ONLY` | | `false` | `true` のとき書き込み系ツールを登録しない |
| `TOCARO_DRY_RUN` | | `false` | `true` のとき書き込み系ツールは送信内容を返すだけで実際に POST しない |
| `TOCARO_LOG_LEVEL` | | `INFO` | ログレベル（`DEBUG` で仕様書とのフィールド差分を stderr に警告出力） |

## Claude Code への登録

```bash
claude mcp add tocaro \
  --env TOCARO_API_TOKEN=xxxxxxxx \
  -- uv --directory /absolute/path/to/tocaro-mcp run tocaro-mcp
```

`--directory` は必ず絶対パスで指定する。登録後 `/mcp` で接続状態を確認できる。

## Claude Desktop への登録

`claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "tocaro": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/tocaro-mcp", "run", "tocaro-mcp"],
      "env": { "TOCARO_API_TOKEN": "xxxxxxxx" }
    }
  }
}
```

## 開発

```bash
uv run pytest
uv run ruff check .
uv run ruff format --check .
```

## 提供ツール

`tocaro_` プレフィックスの MCP ツールを10個提供する（`TOCARO_READ_ONLY=true` の場合は
read 系5個のみ）。

| ツール名 | 種別 |
|---|---|
| `tocaro_search_users` | read |
| `tocaro_list_groups` | read |
| `tocaro_get_group_members` | read |
| `tocaro_list_todo_lists` | read |
| `tocaro_search_tasks` | read |
| `tocaro_create_group` | write |
| `tocaro_invite_to_group` | write |
| `tocaro_post_message` | write |
| `tocaro_create_todo_list` | write |
| `tocaro_create_task` | write |

## 既知の未確認事項

`docs/api-responses.md` を参照。有効な `TOCARO_API_TOKEN` がない環境で実装したため、
`GET /groups/{group}/members` と `GET /projects` のレスポンス形状、および日時文字列の
実際のフォーマットは未検証。実トークンが用意でき次第、確認して記録すること。