# MCP Todoist

Todoist API互換のMCPサーバー実装

## 技術スタック

- **MCPサーバー**: Node.js + TypeScript
- **プロトコル**: MCP (Model Context Protocol) stdio transport
- **外部API**: Todoist REST API
- **言語**: TypeScript
- **ランタイム**: tsx

## アーキテクチャ

```
├── フロントエンド (Next.js 14)
│   ├── React Server Components
│   ├── Client Components
│   └── API Routes
├── MCP Server Layer
│   ├── Protocol Handler
│   ├── Todoist API Adapter
│   └── Tool Registry
├── バックエンド (Convex)
│   ├── Database Functions
│   ├── Mutations
│   ├── Queries
│   └── Actions
└── 外部API
    └── Todoist API
```

## 主要機能

### 実装済み

- [x] MCP Protocol Handler (stdio transport)
- [x] Todoist APIクライアント
- [x] MCPツール実装
  - [x] `todoist_get_tasks` - タスク一覧取得
  - [x] `todoist_create_task` - タスク作成
  - [x] `todoist_update_task` - タスク更新
  - [x] `todoist_close_task` - タスク完了
  - [x] `todoist_get_projects` - プロジェクト一覧取得
  - [x] `todoist_create_project` - プロジェクト作成
  - [x] `todoist_update_project` - プロジェクト更新
  - [x] `todoist_delete_project` - プロジェクト削除
- [x] ツール可視性制御システム

### ツール可視性設定

セキュリティと用途に応じて、各ツールの公開・非公開を設定できます。

**現在の設定:**
- **公開ツール**: `todoist_get_tasks`, `todoist_create_task`, `todoist_update_task`, `todoist_close_task`, `todoist_get_projects`, `todoist_move_task`
- **非公開ツール**: `todoist_create_project`, `todoist_update_project`, `todoist_delete_project`

> 📖 **詳細**: ツールの可視性設定の詳細については [TOOL_VISIBILITY.md](./TOOL_VISIBILITY.md) を参照してください。

## クイックスタート

### 1. 依存関係のインストール

```bash
npm install
```

### 2. MCPサーバーのビルド

```bash
cd packages/mcp-server
npm run build
cd ../..
```

### 3. MCPサーバーのテスト

```bash
# タスクリスト取得のテスト
echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"todoist_get_tasks","arguments":{}}}' | TODOIST_API_TOKEN=your-api-token npx tsx script/run-mcp-server.ts
```

## 🚀 Cursor AI 自動セットアップガイド

### 前提条件
- Node.js 18+ がインストールされている
- npm または yarn がインストールされている
- Cursor AI がインストールされている
- Todoist アカウントを持っている

### Step 1: プロジェクトのセットアップ

```bash
# リポジトリをクローン（または既存プロジェクトの場合はスキップ）
git clone <repository-url>
cd mcp-todoist

# 依存関係のインストール
npm install

# MCPサーバーのビルド
cd packages/mcp-server
npm run build
cd ../..
```

### Step 2: Todoist API トークンの取得

1. [Todoist App Console](https://todoist.com/app_console) にアクセス
2. 「Create a new app」をクリック
3. アプリ名を入力（例：「MCP Todoist Integration」）
4. 「Create app」をクリック
5. 表示されたAPI tokenをコピー（例：`61dae250699e84eb85b9c2ab9461c0581873566d`）

### Step 3: プロジェクトパスの確認

```bash
# 現在のプロジェクトの絶対パスを取得
pwd
```

**出力例**: `/Users/username/projects/mcp-todoist`

### Step 4: Cursor AI MCP設定の自動セットアップ

**方法A: 自動設定スクリプト実行**

以下のコマンドを実行して、Cursor AI設定を自動生成：

```bash
# 現在のディレクトリパスを取得
CURRENT_DIR=$(pwd)

# Cursor AI設定ディレクトリを作成
mkdir -p ~/.cursor

# MCP設定ファイルを自動生成
cat > ~/.cursor/mcp.json << EOF
{
  "mcpServers": {
    "mcp-todoist": {
      "command": "tsx",
      "args": ["$CURRENT_DIR/script/run-mcp-server.ts"],
      "env": {
        "TODOIST_API_TOKEN": "YOUR_TODOIST_API_TOKEN_HERE"
      }
    }
  }
}
EOF

echo "✅ MCP設定ファイルを作成しました: ~/.cursor/mcp.json"
echo "⚠️  次のステップ: YOUR_TODOIST_API_TOKEN_HERE を実際のAPIトークンに置き換えてください"
```

**方法B: 手動設定**

1. **設定ファイルの場所を確認**:
```bash
# macOS/Linux
ls -la ~/.cursor/
# Windowsの場合: %USERPROFILE%\.cursor\
```

2. **設定ファイルを作成/編集**:
```bash
# macOS/Linux
nano ~/.cursor/mcp.json
# または
code ~/.cursor/mcp.json
```

3. **以下の内容をコピー&ペースト**:
```json
{
  "mcpServers": {
    "mcp-todoist": {
      "command": "tsx",
      "args": ["/REPLACE_WITH_YOUR_PROJECT_PATH/script/run-mcp-server.ts"],
      "env": {
        "TODOIST_API_TOKEN": "REPLACE_WITH_YOUR_API_TOKEN"
      }
    }
  }
}
```

4. **プレースホルダーを置き換え**:
   - `/REPLACE_WITH_YOUR_PROJECT_PATH` → 実際のプロジェクトパス
   - `REPLACE_WITH_YOUR_API_TOKEN` → 実際のTodoist APIトークン

### Step 5: 設定の検証

```bash
# 設定ファイルの内容を確認
cat ~/.cursor/mcp.json

# MCPサーバーが正常に動作するかテスト
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | TODOIST_API_TOKEN=your-actual-token tsx script/run-mcp-server.ts
```

正常な場合の出力例：
```json
{"jsonrpc":"2.0","id":1,"result":{"protocolVersion":"2024-11-05","capabilities":{"tools":{"listChanged":true},"resources":{"subscribe":true,"listChanged":true},"prompts":{"listChanged":true}},"serverInfo":{"name":"mcp-todoist","version":"1.0.0"}}}
```

### Step 6: Cursor AI での確認

1. **Cursor AI を完全に再起動**
2. **設定確認**:
   - `⌘+,` (Mac) または `Ctrl+,` (Windows) で設定を開く
   - "MCP" を検索
   - `mcp-todoist` サーバーが表示され、緑のインジケーターが点灯していることを確認

3. **動作テスト**:
   - `⌘+L` でチャットを開く
   - 「Todoistからタスクリストを取得して」と入力
   - MCPツールが自動実行され、タスクリストが表示されることを確認

## 🔧 AI アシスタント向け自動セットアップ手順

**AIアシスタントがこのREADMEを読んで自動セットアップを実行する場合の手順:**

1. **環境確認**:
```bash
node --version  # 18+ であることを確認
npm --version   # インストールされていることを確認
```

2. **プロジェクト準備**:
```bash
# プロジェクトディレクトリに移動していることを確認
pwd
# 依存関係インストール
npm install
# MCPサーバービルド
cd packages/mcp-server && npm run build && cd ../..
```

3. **パス取得**:
```bash
CURRENT_DIR=$(pwd)
echo "プロジェクトパス: $CURRENT_DIR"
```

4. **Cursor AI設定作成**:
```bash
mkdir -p ~/.cursor
cat > ~/.cursor/mcp.json << EOF
{
  "mcpServers": {
    "mcp-todoist": {
      "command": "tsx",
      "args": ["$CURRENT_DIR/script/run-mcp-server.ts"],
      "env": {
        "TODOIST_API_TOKEN": "PLACEHOLDER_FOR_USER_TOKEN"
      }
    }
  }
}
EOF
```

5. **ユーザーに指示**:
```
✅ MCP設定ファイルを作成しました！
📝 次の手順を完了してください：

1. Todoist API トークンを取得: https://todoist.com/app_console
2. 以下のコマンドで設定ファイルを編集:
   
   nano ~/.cursor/mcp.json
   
3. "PLACEHOLDER_FOR_USER_TOKEN" を実際のAPIトークンに置き換え
4. Cursor AI を再起動
5. チャットで「Todoistからタスクリストを取得して」とテスト
```

6. **設定検証**:
```bash
echo "設定ファイルの内容:"
cat ~/.cursor/mcp.json
echo ""
echo "APIトークンを設定後、以下でテスト:"
echo 'echo \'{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"todoist_get_tasks","arguments":{}}}\' | TODOIST_API_TOKEN=your-token tsx script/run-mcp-server.ts'
```

## 利用可能なMCPツール

| ツール名 | 説明 | パラメータ |
|---------|------|-----------|
| `todoist_get_tasks` | タスク一覧取得 | `project_id`, `filter`, `limit` (すべて任意) |
| `todoist_create_task` | タスク作成 | `content` (必須), `description`, `project_id`, `priority`, `due_string`, `labels` |
| `todoist_update_task` | タスク更新 | `task_id` (必須), `content`, `description`, `priority`, `due_string`, `labels` |
| `todoist_close_task` | タスク完了 | `task_id` (必須) |
| `todoist_get_projects` | プロジェクト一覧取得 | なし |
| `todoist_create_project` | プロジェクト作成 | `name` (必須), `color`, `parent_id`, `is_favorite` |
| `todoist_update_project` | プロジェクト更新 | `project_id` (必須), `name`, `color`, `is_favorite` |
| `todoist_delete_project` | プロジェクト削除 | `project_id` (必須) |

## 使用例

### Cursor AIでの基本操作

```
「Todoistからタスクリストを取得して」
「新しいタスク『プロジェクト資料作成』を優先度2で作成して」
「プロジェクト一覧を表示して」
「タスクID 123456789 を完了にして」
```

### コマンドラインでの直接テスト

```bash
# 初期化
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | TODOIST_API_TOKEN=your-token tsx script/run-mcp-server.ts

# ツール一覧
echo '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' | TODOIST_API_TOKEN=your-token tsx script/run-mcp-server.ts

# タスク作成
echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"todoist_create_task","arguments":{"content":"テストタスク","priority":2}}}' | TODOIST_API_TOKEN=your-token tsx script/run-mcp-server.ts
```

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

### よくある問題

1. **「Module not found」エラー**
   - `cd packages/mcp-server && npm run build` でビルドを実行

2. **Cursor AIでMCPサーバーが認識されない**
   - Cursor AIを完全に再起動
   - `~/.cursor/mcp.json` のパスが正しいか確認
   - 環境変数 `TODOIST_API_TOKEN` が設定されているか確認

3. **Todoist API エラー**
   - APIトークンが有効か確認
   - [Todoist API ドキュメント](https://developer.todoist.com/rest/v2/) で制限事項を確認

## 他の環境での使用

このMCPサーバーはCursor AI以外の環境でも使用できます：

- **Claude Desktop**: 設定ファイル `~/.config/claude/claude_desktop_config.json`
- **その他のMCPクライアント**: stdio transportをサポートするクライアント

設定方法は基本的に同じで、コマンドとパスを適切に指定するだけです。

## 🌟 主な特徴

- **🤖 AI統合**: Cursor AI、Claude Desktopなど複数のAIツールからTodoistを操作
- **🚀 簡単セットアップ**: 3ステップで導入完了
- **📋 高度なタスク管理**: AIアシスタントでGTD、タスク整理、プロジェクト管理が効率化
- **🔄 リアルタイム同期**: Todoist APIと直接連携
- **🛠️ 拡張可能**: オープンソースで自由にカスタマイズ
- **💾 stdio transport**: 標準的なMCPプロトコル準拠

## 📖 ライセンス

MIT License - 詳細は [LICENSE](LICENSE) ファイルを参照

## 🔗 リンク

- **GitHub**: [https://github.com/kentaroh7777/mcp-todoist](https://github.com/kentaroh7777/mcp-todoist)
- **MCP Protocol**: [https://modelcontextprotocol.io](https://modelcontextprotocol.io)
- **Todoist API**: [https://developer.todoist.com](https://developer.todoist.com)

## 🤝 コントリビューション

プルリクエスト、イシュー報告、機能提案を歓迎します！

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/AmazingFeature`)
3. Commit your changes (`git commit -m 'Add some AmazingFeature'`)
4. Push to the branch (`git push origin feature/AmazingFeature`)
5. Open a Pull Request

---

**🎯 AIでタスク管理を革新しよう！**