Skip to main content
Glama
yunosuke-github

Task API MCP

by yunosuke-github
OverviewSchemaRelated ServersScoreDiscussions
Python
Local

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各層を自動テストする

Related MCP server: MCP API Server

アーキテクチャ

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

Available Tools

1 tool
create_taskB

Create one task in the task management service.

ParametersJSON Schema
NameRequiredDescriptionDefault
titleYesShort task title.
due_dateNoOptional due date in YYYY-MM-DD format.
priorityNoTask priority: low, medium, or high.medium
descriptionNoOptional details about the task.

Output Schema

ParametersJSON Schema
NameRequiredDescription
idYes
titleYes
statusYes
due_dateNo
priorityYes
created_atYes
descriptionNo

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are present, so the description must carry the full burden. It only states the basic action (create), without disclosing side effects, auth requirements, rate limits, or idempotency. For a mutation tool, this is insufficient.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single concise sentence with no waste. However, it is perhaps too terse for a create tool; additional context could be beneficial without sacrificing conciseness.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's simplicity (4 parameters, output schema exists), the description is adequate for basic understanding. However, it lacks behavioral and usage context, which diminishes completeness for an agent deciding to invoke it.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the baseline is 3. The description adds no parameter-specific information beyond what the schema already provides, hence no extra value.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states the action (create), resource (task), and scope (one task). With no sibling tools listed, differentiation is not needed. It is specific and unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance provided on when to use the tool or when not to. There are no siblings or alternatives mentioned, and no prerequisites or use-case hints. The description is purely operational.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections. Dates show when Glama detected each change.

  1. 1 tool updatev0.1.0
    • First observedcreate_task
Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

B3.3/5.0
Disambiguation5/5

Only one tool exists, so there is no possibility of confusion or overlap.

Naming Consistency5/5

With a single tool, naming is trivially consistent; no pattern violations occur.

Tool Count2/5

A task management service with only one creation tool is too thin; typical requires at least list, read, update, and delete operations.

Completeness2/5

The tool surface lacks critical operations like listing, retrieving, updating, and deleting tasks, leaving significant gaps for agents.

Maintenance

ActivitySlowing
ResponsivenessSyncing

Resources

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Related MCP Servers

  • OpenAPI MCP Server

    rahgadda
    A
    license
    Not graded
    quality
    D
    maintenance
    A Model Context Protocol Server that enables LLMs to interact with and execute REST API calls through natural language prompts, supporting GET/PUT/POST/PATCH operations on configured APIs.
    6
    Apache 2.0

  • MCP API Server

    fikri2992
    A
    license
    A
    quality
    D
    maintenance
    A Model Context Protocol server that enables AI assistants to make HTTP requests (GET, POST, PUT, DELETE) to external APIs through standardized MCP tools.
    4
    2
    MIT

  • Task Manager MCP Server

    cjmontgom
    A
    license
    C
    quality
    D
    maintenance
    Enables local task management through the Model Context Protocol with tools for creating, updating, and deleting tasks. It also provides read-only resources for viewing task summaries and full task lists.
    4
    18
    ISC

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/yunosuke-github/task-api-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server