npm package: @impv_npm/task-manager-mcp
Description: [![npm version](https://badge.fury.io/js/@impv_npm%2Ftask-manager-mcp.svg)](https://www.npmjs.com/package/@impv_npm/task-manager-mcp)
Latest version: 1.4.0

# Task Manager MCP Server

[![npm version](https://badge.fury.io/js/@impv_npm%2Ftask-manager-mcp.svg)](https://www.npmjs.com/package/@impv_npm/task-manager-mcp)

Task ManagerアプリをClaude CodeなどのMCPクライアントから操作するためのMCPサーバーです。

## クイックスタート

```bash
# ビルド不要。npxで直接実行可能
npx -y @impv_npm/task-manager-mcp
```

## 概要

このMCPサーバーを使用すると、以下の操作をAIアシスタントから直接実行できます：

- タスクの一覧取得、作成、開始、完了、クローズ、削除
- 次に取り組むべきタスクの提案
- 業務開始/終了の通知とSlackステータスの自動更新

## 前提条件

- Task Managerアプリが起動していること（ローカルまたは本番環境）
- 有効なMCP APIキーを持っていること

## セットアップ手順

### 1. APIキーの作成

1. Task Managerアプリにログイン
2. [設定ページ](https://task-manager-impressive.vercel.app/settings)に移動
3. **API設定** セクションの **MCP APIキー** カードを見つける
4. 「新しいAPIキーを作成」欄に名前を入力（例: "Claude Code"）
5. **+** ボタンをクリックしてキーを作成
6. 表示されたAPIキー（`tm_`で始まる文字列）をコピーして安全に保管

**重要**: APIキーは作成時に一度しか表示されません。必ずコピーして保存してください。

### 2. Claude Code での設定

`~/.claude/settings.local.json` の `mcpServers` セクションに以下を追加します：

```json
{
  "mcpServers": {
    "task-manager": {
      "command": "npx",
      "args": ["-y", "@impv_npm/task-manager-mcp"],
      "env": {
        "TASK_MANAGER_API_KEY": "tm_xxxxxxxxxxxxxxxxxxxx",
        "TASK_MANAGER_URL": "https://task-manager-impressive.vercel.app"
      }
    }
  }
}
```

**設定項目:**

| 環境変数 | 必須 | 説明 |
|---------|------|------|
| `TASK_MANAGER_API_KEY` | Yes | 設定画面で作成したAPIキー |
| `TASK_MANAGER_URL` | No | Task ManagerアプリのURL（デフォルト: `http://localhost:3000`）|

### 3. Claude Code の再起動

設定を反映するためにClaude Codeを再起動します。

## 使用可能なツール

### タスク管理

| ツール | 説明 | 主なパラメータ |
|--------|------|----------------|
| `task_list` | タスク一覧を取得 | `query`, `status`, `client`, `project`, `assignee`, `includeDone` |
| `task_add` | 新しいタスクを作成 | `title`, `body`, `client`, `project`, `taskBreakdown`, `dueDate`, `assignees` |
| `task_start` | タスクを開始（In Progress） | `taskNumber`, `sendSlackNotification` |
| `task_review` | レビュー待ちに変更（In Review） | `taskNumber` |
| `task_end` | タスクを完了（Done） | `taskNumber`, `sendSlackNotification` |
| `task_close` | タスクをクローズ | `taskNumber`, `reason` |
| `task_delete` | タスクを削除 | `taskNumber`, `confirm` |
| `task_advise` | 次のタスクを提案 | `assignee`, `includeAll` |

### 業務管理

| ツール | 説明 | 主なパラメータ |
|--------|------|----------------|
| `work_start` | 業務を開始 | `note` |
| `work_end` | 業務を終了 | `note` |

### その他

| ツール | 説明 | 主なパラメータ |
|--------|------|----------------|
| `open_board` | タスクボードをブラウザで開く | なし |

## ツール詳細

### task_list

タスク一覧を取得します。複数のフィルタを組み合わせて絞り込みができます。

**パラメータ:**
- `query` (string, optional): 検索キーワード
- `status` (string, optional): "Todo" | "In Progress" | "In Review" | "Done"
- `client` (string, optional): クライアント名でフィルタ
- `project` (string, optional): プロジェクト名でフィルタ
- `assignee` (string, optional): 担当者名でフィルタ
- `includeDone` (boolean, optional): 完了タスクを含めるか

### task_add

新しいタスクを作成します。クライアントやプロジェクトが存在しない場合は自動的に作成されます。

**パラメータ:**
- `title` (string, required): タスクのタイトル
- `body` (string, required): タスクの説明
- `client` (string, optional): クライアント名
- `project` (string, optional): プロジェクト名
- `taskBreakdown` (string[], optional): サブタスクのリスト
- `ticket` (string, optional): 関連チケットURL
- `requestSource` (string, optional): 依頼元URL
- `dueDate` (string, optional): 期日（YYYY-MM-DD形式）
- `assignees` (string[], optional): 担当者のログイン名リスト

### task_start

タスクを開始します。ステータスが「In Progress」に変更され、Slackステータスも更新されます。

**パラメータ:**
- `taskNumber` (number, required): タスク番号（#123の123部分）
- `sendSlackNotification` (boolean, optional): Slack通知を送信するか（デフォルト: true）

### task_review

タスクをレビュー待ちに変更します。

**パラメータ:**
- `taskNumber` (number, required): タスク番号

### task_end

タスクを完了します。ステータスが「Done」に変更され、Slackステータスも更新されます。

**パラメータ:**
- `taskNumber` (number, required): タスク番号
- `sendSlackNotification` (boolean, optional): Slack通知を送信するか（デフォルト: true）

### task_close

タスクをクローズします（キャンセル、重複などの理由で完了せずに閉じる場合）。

**パラメータ:**
- `taskNumber` (number, required): タスク番号
- `reason` (string, optional): クローズの理由

### task_delete

タスクを完全に削除します。この操作は取り消せません。

**パラメータ:**
- `taskNumber` (number, required): タスク番号
- `confirm` (boolean, required): 削除確認（trueを指定しないと削除されない）

### task_advise

優先度と期日に基づいて、次に取り組むべきタスクを提案します。

**パラメータ:**
- `assignee` (string, optional): 担当者名でフィルタ
- `includeAll` (boolean, optional): 全ての推奨タスクを表示するか（デフォルトは上位3件）

### work_start

業務を開始します。Slackに通知を送り、ステータスを業務中に変更します。

**パラメータ:**
- `note` (string, optional): 業務開始時のメモ

### work_end

業務を終了します。Slackに通知を送り、ステータスをクリアします。

**パラメータ:**
- `note` (string, optional): 業務終了時のメモ

### open_board

タスクボード（カンバン形式）をブラウザで開くためのURLを返します。

**パラメータ:** なし

**レスポンス:**
```json
{
  "success": true,
  "data": {
    "url": "https://task-manager-impressive.vercel.app/board",
    "message": "タスクボードを開いてください",
    "action": "open_url"
  }
}
```

## トラブルシューティング

### APIキーのエラー

```
Error: TASK_MANAGER_API_KEY environment variable is required
```

→ 環境変数 `TASK_MANAGER_API_KEY` が設定されているか確認してください。

```
Error: Invalid API key format. Key must start with 'tm_'
```

→ APIキーの形式が正しいか確認してください。キーは `tm_` で始まる必要があります。

### 認証エラー

```
Error: Unauthorized
```

→ APIキーが有効か確認してください。設定画面で新しいキーを発行し直すことをお勧めします。

**開発者向け**: `/api/mcp`エンドポイントはAPIキー認証を使用するため、`src/proxy.ts`の`publicPaths`に含まれている必要があります。Supabaseセッション認証をバイパスするためです。

### サーバーに接続できない

→ `TASK_MANAGER_URL` が正しいか、Task Managerアプリが起動しているか確認してください。

## セキュリティに関する注意

- APIキーは機密情報です。Git リポジトリにコミットしないでください。
- APIキーが漏洩した場合は、設定画面から即座に削除し、新しいキーを発行してください。
- 各APIキーは作成したユーザーの権限で操作を実行します。

### ユーザーに紐づいた操作

全ての操作（MCP経由およびアプリ内チャットインターフェース）は、認証されたユーザーのコンテキストで実行されます：

- **task_list / task_advise / get_today_progress**: `assignee`を指定しない場合、自動的に自分のタスクのみが表示されます
- **task_add**: 自分自身のみをassigneeとして設定できます。他人をassigneeに指定しようとするとエラーが返されます。`assignees`を指定しない場合は自動的に自分が設定されます。
- **task_start / task_review / task_end / task_close / task_delete / update_task / change_status**: 自分がassigneeまたは作成者のタスクのみ操作可能です。他人のタスクを操作しようとするとエラーが返されます。
- **業務管理（work_start / work_end / start_break / end_break）**: 常に認証ユーザー自身の業務として記録されます。
- **Slack通知**: 常に認証ユーザーの設定とチャンネルが使用されます。

## 開発

```bash
# 開発モードで起動
pnpm dev

# ビルド
pnpm build

# ビルド後のサーバーを起動
pnpm start
```

### ローカルでのClaude Code設定

ローカル開発時は以下の設定を使用します：

```json
{
  "mcpServers": {
    "task-manager": {
      "command": "node",
      "args": ["/path/to/task-manager/mcp-server/dist/index.js"],
      "env": {
        "TASK_MANAGER_API_KEY": "tm_xxxxxxxxxxxxxxxxxxxx",
        "TASK_MANAGER_URL": "http://localhost:3000"
      }
    }
  }
}
```

### npm公開

```bash
cd mcp-server

# npmにログイン（初回のみ）
npm login

# 公開
npm publish --access public
```

## アーキテクチャ

```
Claude Code / MCP Client
        │
        │ stdio (JSON-RPC)
        ▼
┌─────────────────────────┐
│   MCP Server (Node.js)  │
│   - src/index.ts        │  MCPサーバーのエントリポイント
│   - src/tools.ts        │  ツールの定義
│   - src/client.ts       │  API呼び出しクライアント
└─────────────────────────┘
        │
        │ HTTP (REST API)
        ▼
┌─────────────────────────┐
│   Task Manager API      │
│   - /api/mcp            │  MCPリクエストのエンドポイント
└─────────────────────────┘
        │
        ▼
┌─────────────────────────┐
│   Supabase (PostgreSQL) │
└─────────────────────────┘
```

## ライセンス

Private