Task MCP Server — Sample for MCP Learning

Purpose of this sample

This is a learning sample to experience the basic elements of MCP (Model Context Protocol) — Resources / Tools / Prompts — through a simple ToDo management server.

Related MCP server: Obsidian Todos MCP Server

What you can learn

• Resources: How AI clients read data from the server

• Tools: How AI clients execute operations on the server

• Prompts: How templates provide specific perspectives or context to the AI

• Basic structure of an MCP server and communication via STDIO transport

How MCP works

MCP is a protocol that allows AI applications (hosts) to access external data and tools in a unified manner.

Overview

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

• Host: The AI application itself. Handles user interaction and LLM calls.

• MCP Client: Embedded in the host, communicates 1:1 with each MCP server.

• MCP Server: Provides Resources / Tools / Prompts. This sample falls into this category.

Three elements provided by the MCP server

block-beta
  columns 1

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

Communication flow (in this sample)

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. User makes a request in natural language.

2. The host's LLM selects the appropriate tool and calls it via the MCP client.

3. The MCP server executes the process (reads/writes tasks.json in this sample) and returns the result.

4. The LLM responds to the user based on the result.

Point: Communication between the MCP client and server uses JSON-RPC 2.0. Since this sample uses STDIO (standard input/output) as the transport, the server's stdout is dedicated to MCP communication. Use stderr for log output.

File structure

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

Prerequisites

• Python 3.10 or higher

Setup

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

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

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

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

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

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

How to start

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

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

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

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

The server speaks the MCP protocol via standard input/output. It does not produce human-readable output if run directly. Use it by connecting from an MCP client.

How to use from an MCP client

For Claude Desktop

1. Open Settings from the Claude Desktop menu.

2. Select Developer from the left menu.

3. Click the Edit Config button to open the configuration file.

4. Add the following content to the configuration file (replace cwd with the absolute path to the directory where you placed this repository).

5. Save the file and restart Claude Desktop.

6. If the hammer icon appears in the chat input field, the connection is successful.

Note: Restarting Claude Desktop by clicking the × button in the top right corner does not terminate the app (it remains in the background). Please exit completely via File > Exit (or Claude > Quit Claude on macOS) before restarting.

Configuration file location:

Configuration content (please adjust paths to your environment):

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

Note: Specify server.py in args with an absolute path. Using a relative path may cause cwd to be ignored, leading to execution in an unintended directory.

Usage example — Enter the following in the chat field:

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

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

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

Tip: MCP tools may not be called if the natural language is ambiguous. Including the tool name or prompt name in your instructions ensures success.

For Claude Code (CLI)

Create .mcp.json in the project root directory:

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

Alternatively, you can create .mcp.json manually:

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

Verify connection:

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

If add_task or list_tasks appear in the tool list, the connection is successful.

Usage example — Enter directly into the Claude Code prompt:

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

For VS Code (GitHub Copilot)

In VS Code, place the configuration in .vscode/mcp.json:

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

1. Saving .vscode/mcp.json will display a Start button at the top of the file.

2. Click Start to launch the server.

3. Tools become available from Copilot Chat (Agent mode).

Usage example — Switch Copilot Chat to Agent mode and enter:

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

For Manus

Manus is an AI agent platform that autonomously executes tasks based on user instructions. It can also act as an MCP client, connecting to external MCP servers to use tools and data.

Add an MCP server from the Manus settings screen:

1. Open Manus Settings.

2. Click Add Server in the MCP Servers section.

3. Configure the following:

Note: Since Manus runs in the cloud, connecting to a local MCP server requires making the server accessible remotely or using the local connection feature provided by Manus. Refer to the official Manus documentation for details.

Once saved, the Manus agent will be able to automatically select and call this server's tools when executing tasks.

Usage example — Instruct Manus as follows:

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

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

Tip: Since Manus autonomously combines and executes tools, it can handle instructions spanning multiple steps at once.

List of provided MCP features

Resources (Data reading)

Tools (Operations)

Prompts (Templates for AI)

Data storage

• tasks.json (automatically created in the same directory as the server)

• Saves all tasks in JSON format

Testing

python -m pytest tests/ -v

The test execution command is the same for both Bash and PowerShell.

Constraints

• Single-user only: Concurrent access and user management are not supported.

• Local only: Not intended for network exposure.

• For learning: Robustness and security for production use are not considered.

• No DB: Data is saved in a JSON file.

• No authentication: No authentication or authorization mechanisms included.