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

このサンプルの目的

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

何が学べるか

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

MCP の仕組み

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

全体像

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 つの要素

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 を生成する

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

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>

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

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

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

</details>

<details> <summary>PowerShell</summary>

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

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

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

</details>

起動方法

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

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

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

</details>

<details> <summary>PowerShell</summary>

# サンプルデータを使う場合はコピー
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

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

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

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

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

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

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

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

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

Claude Code (CLI) の場合

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

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

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

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

接続確認:

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

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

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

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

VS Code (GitHub Copilot) の場合

VS Code では .vscode/mcp.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 モードに切り替えてから入力します:

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

Manus の場合

Manus は、ユーザーの指示をもとに自律的にタスクを遂行する 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 に以下のように指示します:

タスク一覧を確認して、期限が近いものを優先度順に整理して
  → 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 形式で全タスクを保存

テスト

python -m pytest tests/ -v

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

制約事項

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