Task API MCP

English

既存REST APIをAIクライアントから利用するための、ローカル実行可能なPythonサンプルです。FastAPIで作られたタスク管理APIを正規の入り口として残し、stdio MCPサーバーは create_task ToolとHTTPの間を変換する薄いアダプターとして動作します。

このリポジトリは学習・ローカル検証用です。認証、複数プロセス対応、冪等性など、実運用で必要になる機能は意図的に含めていません。

最終更新: 2026-07-15

できること

• POST /tasks でタスクを作成し、data/tasks.json へ保存する
• GET /tasks と GET /tasks/{task_id} でタスクを確認する
• MCPの create_task Toolから同じREST APIを呼び出す
• 入力エラー、一時障害、想定外レスポンスを安全なMCPエラーへ変換する
• 実サーバーを使わず、API・HTTP・MCP各層を自動テストする

アーキテクチャ

flowchart LR
    User[ユーザー] -->|自然言語| AI[AIクライアント]
    AI -->|MCP / stdio| MCP[task_mcp]
    MCP -->|HTTP POST /tasks| API[task_api]
    API --> JSON[(data/tasks.json)]

コンポーネント	責務
AIクライアント	自然言語をTool引数へ変換する
task_mcp	Tool Schemaを公開し、MCPとHTTPを変換する
task_api	入力・業務ルールを検証し、タスクを作成する
data/tasks.json	ローカル環境でタスクを永続化する

MCPサーバーはJSONファイルを直接変更しません。保存処理と過去日付の禁止はREST API側にだけ実装されています。

クイックスタート

必要なもの

• Python 3.10以上
• uv
• Node.js 18以上（MCP Inspectorを使う場合のみ）
• Codex CLI（Codexから試す場合のみ）

1. 依存関係をインストールする

リポジトリをcloneしたディレクトリで実行します。

cd task-api-mcp
uv sync --dev

uv.lock が含まれているため、記事と同じ mcp[cli]==1.28.1 を含む検証済みの依存関係がインストールされます。

2. REST APIを起動する

uv run task-api

開発中に自動リロードを使う場合は、代わりに次を実行します。

uv run uvicorn task_api.app:app --reload --port 8000

APIは http://localhost:8000 で起動します。Swagger UIは http://localhost:8000/docs です。

3. タスクを作成する

別のターミナルで実行します。

curl -X POST http://localhost:8000/tasks \
  -H "Content-Type: application/json" \
  -d '{
    "title": "MCPの記事を公開する",
    "description": "図とコードを最終確認する",
    "priority": "high"
  }'

201 Created と、次のようなタスクが返れば成功です。

{
  "id": "b48b8da3-f80b-40e3-a78d-8d70b11e58c4",
  "title": "MCPの記事を公開する",
  "description": "図とコードを最終確認する",
  "priority": "high",
  "due_date": null,
  "status": "todo",
  "created_at": "2026-07-15T21:30:00+09:00"
}

作成結果は data/tasks.json に保存されます。

MCP Inspectorで試す

REST APIを起動したまま、別のターミナルで実行します。

TASK_API_BASE_URL=http://localhost:8000 \
npx -y @modelcontextprotocol/inspector \
uv run python -m task_mcp.server

Inspectorで次を確認できます。

1. Tools から create_task を選ぶ
2. title が必須であることを確認する
3. priority が low / medium / high のenumであることを確認する
4. due_date に今日以降の日付を入力して実行する

Codex CLIへ登録する

リポジトリのルートで次を実行します。

codex mcp add task-manager \
  --env TASK_API_BASE_URL=http://localhost:8000 \
  --env TASK_API_TIMEOUT_SECONDS=10 \
  -- uv run python -m task_mcp.server

登録結果を確認します。

codex mcp list

その後、Codexへ次のように依頼できます。

明日までに「MCPの記事を公開する」というタスクを作成してください。
優先度はhighにしてください。

Codexの設定方法は公式MCPドキュメントも参照してください。

REST APIリファレンス

ベースURL: http://localhost:8000

認証: なし（ローカルデモのみ）

メソッド	パス	成功時	説明
POST	/tasks	201	タスクを作成する
GET	/tasks	200	全タスクを作成順で返す
GET	/tasks/{task_id}	200	IDでタスクを1件取得する

POST /tasks の入力

フィールド	型	必須	デフォルト	制約
title	string	はい	—	空白除去後1〜100文字
description	string / null	いいえ	null	最大1000文字
priority	string	いいえ	medium	low, medium, high
due_date	string / null	いいえ	null	YYYY-MM-DD、今日以降

未知のフィールドは受け付けません。時刻は保存しないため、「明日の17時」の17時部分は due_date には入りません。

主なエラー

状態	HTTP	MCPでの扱い
必須・型・文字数・enum・日付形式の不正	422	通常はTool Schemaで先に検出
過去の due_date	422	修正可能な ToolError
存在しないタスク	404	GET APIのみ
JSON保存障害	500	一時的な利用不能
APIタイムアウト・接続失敗	—	一時的な利用不能
不正JSON・未知のHTTP状態	—	詳細を隠した想定外エラー

設定

環境変数	デフォルト	使用箇所	説明
TASK_API_BASE_URL	http://localhost:8000	MCP	接続先REST API
TASK_API_TIMEOUT_SECONDS	10	MCP	HTTPタイムアウト秒数。0より大きい数値
TASK_API_DATA_FILE	data/tasks.json	REST API	JSON保存先

.env.example を使う場合、uvへ明示的に渡します。

cp .env.example .env
uv run --env-file .env task-api

MCPサーバーにも同じ方法を使えます。

uv run --env-file .env task-mcp

プロジェクト構成

task-api-mcp/
├── data/tasks.json              # ローカルのタスクデータ
├── docs/plans/                  # 設計判断
├── src/
│   ├── task_api/
│   │   ├── app.py               # FastAPIのルートと起動処理
│   │   ├── models.py            # REST APIの入出力モデル
│   │   └── repository.py        # JSON永続化
│   └── task_mcp/
│       ├── api_client.py        # 非同期REST APIクライアント
│       ├── errors.py            # HTTP結果の意味的なエラー分類
│       ├── models.py            # MCP境界の構造化モデル
│       └── server.py            # create_task Toolとstdio起動処理
├── tests/                       # API、HTTP、MCPのテスト
├── .env.example                 # 環境変数の例
├── pyproject.toml               # パッケージと依存関係
└── uv.lock                      # 解決済み依存関係

テスト

uv run pytest

テストでは一時ディレクトリと httpx.MockTransport を使うため、起動中のAPIや既存の data/tasks.json は変更しません。

トラブルシューティング

Address already in use と表示される

ポート8000を使用中のプロセスを停止するか、別ポートでAPIを起動し、MCP側のURLも合わせます。

uv run uvicorn task_api.app:app --port 8001
TASK_API_BASE_URL=http://localhost:8001 uv run task-mcp

MCPから temporarily unavailable が返る

REST APIが起動していることと、TASK_API_BASE_URL が正しいことを確認してください。コンテナ内から接続する場合、localhost はコンテナ自身を指します。

due_date must be today or later が返る

due_date をAPIが動作している環境の今日以降へ変更してください。

Task storage is unavailable が返る

TASK_API_DATA_FILE の親ディレクトリへ書き込めることと、既存ファイルがJSON配列であることを確認してください。デモデータを破棄してよければ、API停止後に data/tasks.json を削除できます。次回作成時に再生成されます。

実運用へ進む前に

• JSONファイルをトランザクションと複数プロセスに対応したデータベースへ置き換える
• API認証情報をTool引数ではなく、環境変数またはシークレットストアから取得する
• REST API側へ冪等性キー、重複検出、監査ログ、レート制限を追加する
• リモート利用ではstdioではなく、認証とOrigin検証を備えたStreamable HTTPを検討する

ライセンス

MIT License