@impv_npm/task-manager-mcp 1.0.0

package/README.md

@@ -0,0 +1,330 @@
+# Task Manager MCP Server
+
+Task ManagerアプリをClaude CodeなどのMCPクライアントから操作するためのMCPサーバーです。
+
+## 概要
+
+このMCPサーバーを使用すると、以下の操作をAIアシスタントから直接実行できます：
+
+- タスクの一覧取得、作成、開始、完了、クローズ、削除
+- 次に取り組むべきタスクの提案
+- 業務開始/終了の通知とSlackステータスの自動更新
+
+## 前提条件
+
+- Task Managerアプリが起動していること（ローカルまたは本番環境）
+- 有効なMCP APIキーを持っていること
+
+## セットアップ手順
+
+### 1. APIキーの作成
+
+1. Task Managerアプリにログイン
+2. **設定** ページに移動
+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/task-manager-mcp"],
+      "env": {
+        "TASK_MANAGER_API_KEY": "tm_xxxxxxxxxxxxxxxxxxxx",
+        "TASK_MANAGER_URL": "https://your-app.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` |
+
+## ツール詳細
+
+### 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): 業務終了時のメモ
+
+## 活用例
+
+### 1. 朝の業務開始
+
+```
+「業務を開始して」
+→ work_start が呼ばれ、Slackステータスが業務中に更新される
+```
+
+### 2. タスクの確認と着手
+
+```
+「今日やるべきタスクを教えて」
+→ task_advise が呼ばれ、優先度の高いタスクが提案される
+
+「タスク#123を開始する」
+→ task_start が呼ばれ、ステータスがIn Progressに変更される
+```
+
+### 3. タスクの作成
+
+```
+「Acme社のダッシュボードにグラフ追加するタスクを作成して」
+→ task_add が呼ばれ、新しいタスクが作成される
+```
+
+### 4. タスク一覧の確認
+
+```
+「進行中のタスク一覧を見せて」
+→ task_list が status: "In Progress" で呼ばれる
+
+「Acme社のタスクを教えて」
+→ task_list が client: "Acme" で呼ばれる
+```
+
+### 5. タスクの完了
+
+```
+「タスク#123を完了した」
+→ task_end が呼ばれ、ステータスがDoneに変更される
+```
+
+### 6. 業務終了
+
+```
+「業務終了」
+→ work_end が呼ばれ、Slackステータスがクリアされる
+```
+
+## トラブルシューティング
+
+### 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キーが有効か確認してください。設定画面で新しいキーを発行し直すことをお勧めします。
+
+### サーバーに接続できない
+
+→ `TASK_MANAGER_URL` が正しいか、Task Managerアプリが起動しているか確認してください。
+
+## セキュリティに関する注意
+
+- APIキーは機密情報です。Git リポジトリにコミットしないでください。
+- APIキーが漏洩した場合は、設定画面から即座に削除し、新しいキーを発行してください。
+- 各APIキーは作成したユーザーの権限で操作を実行します。
+
+## 開発
+
+```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

package/dist/client.d.ts

@@ -0,0 +1,12 @@
+interface McpApiResponse<T = unknown> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+export declare class TaskManagerClient {
+    private baseUrl;
+    private apiKey;
+    constructor(baseUrl: string, apiKey: string);
+    call<T = unknown>(tool: string, params?: Record<string, unknown>): Promise<McpApiResponse<T>>;
+}
+export {};

package/dist/client.js

@@ -0,0 +1,23 @@
+export class TaskManagerClient {
+    baseUrl;
+    apiKey;
+    constructor(baseUrl, apiKey) {
+        this.baseUrl = baseUrl.replace(/\/$/, "");
+        this.apiKey = apiKey;
+    }
+    async call(tool, params = {}) {
+        const response = await fetch(`${this.baseUrl}/api/mcp`, {
+            method: "POST",
+            headers: {
+                "Content-Type": "application/json",
+                "Authorization": `Bearer ${this.apiKey}`,
+            },
+            body: JSON.stringify({ tool, params }),
+        });
+        if (!response.ok) {
+            const data = await response.json().catch(() => ({ error: "Unknown error" }));
+            return { success: false, error: data.error || `HTTP ${response.status}` };
+        }
+        return await response.json();
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,34 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { TaskManagerClient } from "./client.js";
+import { registerTools } from "./tools.js";
+async function main() {
+    // Environment variable validation
+    const apiKey = process.env.TASK_MANAGER_API_KEY;
+    const appUrl = process.env.TASK_MANAGER_URL || "http://localhost:3000";
+    if (!apiKey) {
+        console.error("Error: TASK_MANAGER_API_KEY environment variable is required");
+        process.exit(1);
+    }
+    if (!apiKey.startsWith("tm_")) {
+        console.error("Error: Invalid API key format. Key must start with 'tm_'");
+        process.exit(1);
+    }
+    // Create API client
+    const client = new TaskManagerClient(appUrl, apiKey);
+    // Create MCP server
+    const server = new McpServer({
+        name: "task-manager",
+        version: "1.0.0",
+    });
+    // Register tools
+    registerTools(server, client);
+    // Create transport and connect
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/dist/tools.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { TaskManagerClient } from "./client.js";
+export declare function registerTools(server: McpServer, client: TaskManagerClient): void;

package/dist/tools.js

@@ -0,0 +1,111 @@
+import { z } from "zod";
+export function registerTools(server, client) {
+    // task_list - タスク一覧取得
+    server.tool("task_list", "タスク一覧を取得します。フィルタリング可能。", {
+        query: z.string().optional().describe("検索キーワード"),
+        status: z.enum(["Todo", "In Progress", "In Review", "Done"]).optional().describe("ステータスでフィルタ"),
+        client: z.string().optional().describe("クライアント名でフィルタ"),
+        project: z.string().optional().describe("プロジェクト名でフィルタ"),
+        assignee: z.string().optional().describe("担当者名でフィルタ"),
+        includeDone: z.boolean().optional().describe("完了タスクを含めるか"),
+    }, async (params) => {
+        const result = await client.call("task_list", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // task_add - タスク作成
+    server.tool("task_add", "新しいタスクを作成します。", {
+        title: z.string().describe("タスクのタイトル"),
+        body: z.string().describe("タスクの説明"),
+        client: z.string().optional().describe("クライアント名（存在しない場合は作成）"),
+        project: z.string().optional().describe("プロジェクト名（存在しない場合は作成）"),
+        taskBreakdown: z.array(z.string()).optional().describe("サブタスクのリスト"),
+        ticket: z.string().optional().describe("関連チケットURL"),
+        requestSource: z.string().optional().describe("依頼元URL"),
+        dueDate: z.string().optional().describe("期日（YYYY-MM-DD形式）"),
+        assignees: z.array(z.string()).optional().describe("担当者のログイン名リスト"),
+    }, async (params) => {
+        const result = await client.call("task_add", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // task_start - タスク開始
+    server.tool("task_start", "タスクを開始します（In Progressに変更）。Slackステータスも更新されます。", {
+        taskNumber: z.number().describe("タスク番号（#123の123部分）"),
+        sendSlackNotification: z.boolean().optional().default(true).describe("Slack通知を送信するか"),
+    }, async (params) => {
+        const result = await client.call("task_start", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // task_review - レビュー提出
+    server.tool("task_review", "タスクをレビュー待ちに変更します（In Reviewに変更）。", {
+        taskNumber: z.number().describe("タスク番号（#123の123部分）"),
+    }, async (params) => {
+        const result = await client.call("task_review", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // task_end - タスク完了
+    server.tool("task_end", "タスクを完了します（Doneに変更）。Slackステータスも更新されます。", {
+        taskNumber: z.number().describe("タスク番号（#123の123部分）"),
+        sendSlackNotification: z.boolean().optional().default(true).describe("Slack通知を送信するか"),
+    }, async (params) => {
+        const result = await client.call("task_end", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // task_close - タスククローズ
+    server.tool("task_close", "タスクをクローズします（キャンセル、重複などの理由で完了せずに閉じる）。", {
+        taskNumber: z.number().describe("タスク番号（#123の123部分）"),
+        reason: z.string().optional().describe("クローズの理由"),
+    }, async (params) => {
+        const result = await client.call("task_close", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // task_delete - タスク削除
+    server.tool("task_delete", "タスクを完全に削除します。この操作は取り消せません。", {
+        taskNumber: z.number().describe("タスク番号（#123の123部分）"),
+        confirm: z.boolean().describe("削除を確認する（trueを指定しないと削除されない）"),
+    }, async (params) => {
+        const result = await client.call("task_delete", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // task_advise - 次のタスク提案
+    server.tool("task_advise", "優先度と期日に基づいて、次に取り組むべきタスクを提案します。", {
+        assignee: z.string().optional().describe("担当者名でフィルタ"),
+        includeAll: z.boolean().optional().describe("全ての推奨タスクを表示するか（デフォルトは上位3件）"),
+    }, async (params) => {
+        const result = await client.call("task_advise", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // work_start - 業務開始
+    server.tool("work_start", "業務を開始します。Slackに通知を送り、ステータスを業務中に変更します。", {
+        note: z.string().optional().describe("業務開始時のメモ"),
+    }, async (params) => {
+        const result = await client.call("work_start", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+    // work_end - 業務終了
+    server.tool("work_end", "業務を終了します。Slackに通知を送り、ステータスをクリアします。", {
+        note: z.string().optional().describe("業務終了時のメモ"),
+    }, async (params) => {
+        const result = await client.call("work_end", params);
+        return {
+            content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+        };
+    });
+}

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@impv_npm/task-manager-mcp",
+  "version": "1.0.0",
+  "type": "module",
+  "main": "dist/index.js",
+  "bin": {
+    "task-manager-mcp": "./dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "prepublishOnly": "pnpm build"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@types/node": "^20",
+    "tsx": "^4.7.0",
+    "typescript": "^5"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}