# Task MCP Server — MCP 学習用サンプル

## このサンプルの目的

MCP (Model Context Protocol) の基本要素である **Resources / Tools / Prompts** を、
シンプルな ToDo 管理サーバーを通じて一通り体験するための学習用サンプルです。

## 何が学べるか

- **Resources**: AI クライアントがサーバーからデータを読み取る仕組み
- **Tools**: AI クライアントがサーバーに対して操作を実行する仕組み
- **Prompts**: AI に特定の視点や文脈を与えるテンプレートの仕組み
- MCP サーバーの基本的な構成と STDIO transport での通信

## MCP の仕組み

MCP は、AI アプリケーション（ホスト）が外部のデータやツールに統一的にアクセスするためのプロトコルです。

### 全体像

```mermaid
graph TB
  subgraph host[" "]
    HostLabel["🖥️ ホスト（Claude Desktop / VS Code など）"]
    LLM["LLM"]
    ClientA["MCP クライアント"]
    ClientB["MCP クライアント"]
    ClientC["MCP クライアント"]
    HostLabel ~~~ LLM
    LLM --- ClientA
    LLM --- ClientB
    LLM --- ClientC
  end

  ClientA -- "STDIO" --> ServerA["MCP サーバー A\n（本サンプル）"]
  ClientB -- "STDIO" --> ServerB["MCP サーバー B\n（別のサーバー）"]
  ClientC -- "SSE/HTTP" --> ServerC["MCP サーバー C\n（リモート）"]

  style host fill:#1a1a2e,stroke:#e0e0e0,stroke-width:2px,color:#ffffff
  style HostLabel fill:none,stroke:none,font-weight:bold,color:#ffffff
  style LLM fill:#ffffff,stroke:#333333,color:#000000
  style ClientA fill:#ffffff,stroke:#333333,color:#000000
  style ClientB fill:#ffffff,stroke:#333333,color:#000000
  style ClientC fill:#ffffff,stroke:#333333,color:#000000
```

- **ホスト**: AI アプリケーション本体。ユーザーとの対話や LLM の呼び出しを行う
- **MCP クライアント**: ホストに組み込まれ、各 MCP サーバーと 1:1 で通信する
- **MCP サーバー**: Resources / Tools / Prompts を提供する。本サンプルがこれにあたる

### MCP サーバーが提供する 3 つの要素

```mermaid
block-beta
  columns 1

  block:server["MCP サーバー"]
    R["📖 Resources（データ参照）\nタスク一覧 ・ 統計情報"]
    T["🔧 Tools（操作の実行）\nタスク追加 ・ タスク完了 ・ 検索"]
    P["💬 Prompts（テンプレート）\nデイリーレビュー ・ タスク分解"]
  end
```

| 要素      | 方向                     | 役割                                               | 例（本サンプル）                                          |
|-----------|--------------------------|----------------------------------------------------|---------------------------------------------------------|
| Resources | サーバー → クライアント   | データの読み取り。URI を指定して取得する               | `tasks://all` で全タスク一覧を返す                        |
| Tools     | クライアント → サーバー   | 操作の実行。引数を渡して処理を呼び出す                 | `add_task` でタスクを追加する                              |
| Prompts   | サーバー → クライアント   | AI への指示テンプレート。動的にデータを埋め込める       | `daily_review` で今日の状況に応じた Prompt を生成する       |

### 通信の流れ（本サンプルの場合）

```mermaid
sequenceDiagram
    participant U as ユーザー
    participant H as ホスト / LLM
    participant C as MCP クライアント
    participant S as MCP サーバー
    participant F as tasks.json

    U->>H: 「タスクを追加して」
    H->>C: add_task 呼び出し
    C->>S: JSON-RPC request
    S->>F: ファイル書き込み
    F-->>S: OK
    S-->>C: JSON-RPC response
    C-->>H: 結果を返す
    H-->>U: 「追加しました」
```

1. ユーザーが自然言語で依頼する
2. ホストの LLM が適切なツールを選び、MCP クライアント経由で呼び出す
3. MCP サーバーが処理を実行し（本サンプルでは tasks.json を読み書き）、結果を返す
4. LLM が結果をもとにユーザーへ応答する

> **ポイント**: MCP クライアントとサーバーの間は JSON-RPC 2.0 で通信します。本サンプルでは transport に STDIO（標準入出力）を使っているため、サーバーの `stdout` は MCP 通信専用です。ログ出力には `stderr` を使います。

## ファイル構成

```
├── server.py            # MCP サーバー本体（Resources / Tools / Prompts を登録）
├── task_store.py        # Task モデルと JSON 永続化
├── requirements.txt     # 依存パッケージ
├── tasks_sample.json    # サンプルデータ（動作確認用）
├── README.md
└── tests/
    └── test_task_store.py  # ストレージ層のテスト
```

## 前提条件

- Python 3.10 以上

## セットアップ

<details open>
<summary>Bash</summary>

```bash
# 仮想環境の作成（推奨）
python -m venv .venv
source .venv/bin/activate

# 依存パッケージのインストール
pip install -r requirements.txt

# テスト用パッケージ（テストを実行する場合）
pip install pytest
```

</details>

<details>
<summary>PowerShell</summary>

```powershell
# 仮想環境の作成（推奨）
python -m venv .venv
.venv\Scripts\Activate.ps1

# 依存パッケージのインストール
pip install -r requirements.txt

# テスト用パッケージ（テストを実行する場合）
pip install pytest
```

</details>

## 起動方法

<details open>
<summary>Bash</summary>

```bash
# サンプルデータを使う場合はコピー
cp tasks_sample.json tasks.json

# サーバー起動（STDIO transport）
python server.py
```

</details>

<details>
<summary>PowerShell</summary>

```powershell
# サンプルデータを使う場合はコピー
Copy-Item tasks_sample.json tasks.json

# サーバー起動（STDIO transport）
python server.py
```

</details>

サーバーは標準入出力で MCP プロトコルを話します。
直接実行しても人が読める出力は出ません。MCP クライアントから接続して使います。

## MCP クライアントからの使い方

### Claude Desktop の場合

1. Claude Desktop のメニューから **Settings** を開く
2. 左メニューの **Developer** を選択
3. **Edit Config** ボタンをクリックすると設定ファイルが開く
4. 設定ファイルに以下の内容を追加する（`cwd` はこのリポジトリを配置したディレクトリの絶対パスに置き換えてください）
5. ファイルを保存し、Claude Desktop を再起動する
6. チャット画面の入力欄にハンマーアイコンが表示されれば接続成功

> **注意**: Claude Desktop の再起動は、ウィンドウ右上の × ボタンではアプリが終了しません（バックグラウンドに残ります）。メニューバーの **File > Exit**（macOS では **Claude > Quit Claude**）から完全に終了したうえで、再度起動してください。

設定ファイルの場所:

| OS      | パス                                                              |
|---------|-------------------------------------------------------------------|
| macOS   | `~/Library/Application Support/Claude/claude_desktop_config.json` |
| Windows | `%APPDATA%\Claude\claude_desktop_config.json`                     |

設定内容（パスは環境に合わせて書き換えてください）:

```json
{
  "mcpServers": {
    "task-server": {
      "command": "python",
      "args": ["/path/to/mcp-sample/server.py"],
      "cwd": "/path/to/mcp-sample"
    }
  }
}
```

> **注意**: `args` の `server.py` は絶対パスで指定してください。相対パスにすると `cwd` が反映されず、意図しないディレクトリで実行される場合があります。

使用例 — チャット欄に以下のように入力します:

```text
add_task で「買い物リストを作る」というタスクを追加して
  → add_task ツールが呼ばれ、タスクが追加される

list_tasks でタスク一覧を表示して
  → list_tasks ツールが呼ばれ、一覧が表示される

daily_review プロンプトを使って、今日やることを整理して
  → daily_review Prompt をもとに提案が返る
```

> **ヒント**: MCP ツールは曖昧な自然言語では呼び出されないことがあります。ツール名やプロンプト名を含めて指示すると確実です。

### Claude Code (CLI) の場合

プロジェクトのルートディレクトリに `.mcp.json` を作成します:

```bash
# mcp-sample ディレクトリ内で実行
claude mcp add task-server -- python server.py
```

または、手動で `.mcp.json` を作成しても構いません:

```json
{
  "mcpServers": {
    "task-server": {
      "command": "python",
      "args": ["server.py"]
    }
  }
}
```

接続確認:

```bash
# Claude Code を起動して /mcp コマンドで確認
claude
> /mcp
```

ツール一覧に `add_task` や `list_tasks` が表示されれば接続成功です。

使用例 — Claude Code のプロンプトに直接入力します:

```text
> add_task で「レポート作成」というタスクを優先度 high で追加して
> list_tasks で高優先度のタスクだけ表示して
> search_tasks で「レポート」を検索して
> complete_task でタスク a1b2c3d4 を完了にして
> weekly_summary プロンプトを使って今週の振り返りをして
```

### VS Code (GitHub Copilot) の場合

VS Code では `.vscode/mcp.json` に設定を置きます:

```json
{
  "servers": {
    "task-server": {
      "command": "python",
      "args": ["server.py"],
      "cwd": "${workspaceFolder}"
    }
  }
}
```

1. `.vscode/mcp.json` を保存すると、ファイル上部に **Start** ボタンが表示される
2. **Start** をクリックしてサーバーを起動
3. Copilot Chat（Agent モード）からツールが利用可能になる

使用例 — Copilot Chat を Agent モードに切り替えてから入力します:

```text
add_task で期限 2026-04-10 の「設計レビュー」タスクを追加して
list_tasks で status が doing のタスクを表示して
break_down_task プロンプトでタスク a1b2c3d4 を小さく分解して
```

### Manus の場合

[Manus](https://manus.im/) は、ユーザーの指示をもとに自律的にタスクを遂行する AI エージェントプラットフォームです。MCP クライアントとしても動作し、外部の MCP サーバーに接続してツールやデータを利用できます。

Manus の設定画面から MCP サーバーを追加します:

1. Manus の **Settings**（設定）を開く
2. **MCP Servers** セクションで **Add Server** をクリック
3. 以下の内容を設定する:

| 項目 | 値 |
|------|-----|
| Name | `task-server` |
| Transport | `STDIO` |
| Command | `python` |
| Arguments | `/path/to/mcp-sample/server.py`（絶対パスに置き換え） |

> **注意**: Manus はクラウド上で動作するため、ローカルの MCP サーバーに接続するにはサーバーをリモートからアクセス可能にするか、Manus が提供するローカル接続機能を利用する必要があります。詳しくは Manus の公式ドキュメントを参照してください。

設定を保存すると、Manus のエージェントがタスク実行時に本サーバーのツールを自動的に選択・呼び出しできるようになります。

使用例 — Manus に以下のように指示します:

```text
タスク一覧を確認して、期限が近いものを優先度順に整理して
  → list_tasks ツールで一覧を取得し、整理した結果を返す

「企画書を書く」というタスクを追加して、さらに小さなステップに分解して
  → add_task でタスクを追加し、break_down_task で分解まで自動実行
```

> **ヒント**: Manus は自律的にツールを組み合わせて実行するため、複数のステップにまたがる指示もまとめて処理できます。

## 提供している MCP 機能一覧

### Resources（データ読み取り）

| URI | 説明 |
|-----|------|
| `tasks://all` | 全タスク一覧 |
| `tasks://incomplete` | 未完了タスク一覧（open / doing） |
| `tasks://stats` | 統計情報（total, open, doing, done, overdue） |
| `tasks://detail/{task_id}` | 特定タスクの詳細 |

### Tools（操作）

| ツール名 | 説明 |
|----------|------|
| `add_task` | タスクを追加 |
| `list_tasks` | タスク一覧（status / priority / tag / limit でフィルタ可） |
| `update_task` | タスクを更新（変更したいフィールドだけ指定） |
| `complete_task` | タスクを完了にする |
| `delete_task` | タスクを削除 |
| `search_tasks` | title / notes を部分一致検索 |

### Prompts（AI 向けテンプレート）

| Prompt 名 | 説明 | 引数 |
|------------|------|------|
| `daily_review` | 今日やるべきことを整理するデイリーレビュー | なし |
| `break_down_task` | 大きなタスクを小さく分解する | `task_id` |
| `weekly_summary` | 週次の振り返りと来週の計画 | なし |

## データ保存先

- `tasks.json`（サーバーと同じディレクトリに自動作成）
- JSON 形式で全タスクを保存

## テスト

```bash
python -m pytest tests/ -v
```

> テストの実行コマンドは Bash / PowerShell 共通です。

## 制約事項

- **単一ユーザー向け**: 同時アクセスやユーザー管理は非対応
- **ローカル専用**: ネットワーク公開は想定していない
- **学習用**: 本番運用向けの堅牢性・セキュリティは考慮していない
- **DB 未使用**: データは JSON ファイルに保存
- **認証なし**: 認証・認可の仕組みは含まない