Task MCP Server — пример для изучения MCP

Цель этого примера

Это учебный пример для ознакомления с основными элементами MCP (Model Context Protocol) — Resources / Tools / Prompts — через простой сервер управления задачами (ToDo).

Что можно изучить

Resources: механизм, с помощью которого AI-клиент считывает данные с сервера.
Tools: механизм, с помощью которого AI-клиент выполняет операции на сервере.
Prompts: механизм шаблонов, задающих AI определенную перспективу или контекст.
Базовая структура MCP-сервера и обмен данными через транспорт STDIO.

Как работает 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-сервером

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` в зависимости от ситуации

Поток обмена данными (в данном примере)

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: 「追加しました」

Пользователь делает запрос на естественном языке.
LLM хоста выбирает подходящий инструмент и вызывает его через MCP-клиент.
MCP-сервер выполняет операцию (в данном примере чтение/запись tasks.json) и возвращает результат.
LLM на основе результата формирует ответ пользователю.

Важно: Обмен данными между MCP-клиентом и сервером происходит через JSON-RPC 2.0. В этом примере используется транспорт 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 или выше

Установка

# 仮想環境の作成（推奨）
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

Запуск

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

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

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

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

Сервер общается по протоколу MCP через стандартный ввод-вывод. При прямом запуске вы не увидите понятного человеку вывода. Используйте его через подключение MCP-клиента.

Использование через MCP-клиент

Для Claude Desktop

Откройте Settings в меню Claude Desktop.
Выберите Developer в левом меню.
Нажмите кнопку Edit Config, чтобы открыть файл конфигурации.
Добавьте в файл следующее содержимое (замените cwd на абсолютный путь к директории, где находится этот репозиторий):
Сохраните файл и перезапустите Claude Desktop.
Если в поле ввода чата появился значок молотка, подключение прошло успешно.

Внимание: Перезапуск Claude Desktop через кнопку × в углу окна не завершает приложение (оно остается в фоне). Полностью завершите его через меню File > Exit (в macOS Claude > Quit Claude), а затем запустите снова.

Расположение файла конфигурации:

ОС	Путь
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"
    }
  }
}

Внимание: Указывайте server.py в args абсолютным путем. Использование относительного пути может привести к тому, что 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}"
    }
  }
}

После сохранения .vscode/mcp.json в верхней части файла появится кнопка Start.
Нажмите Start для запуска сервера.
Инструменты станут доступны в Copilot Chat (в режиме Agent).

Пример использования — переключите Copilot Chat в режим Agent и введите:

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

Для Manus

Manus — это платформа AI-агентов, которые автономно выполняют задачи на основе инструкций пользователя. Она также работает как MCP-клиент и может подключаться к внешним MCP-серверам для использования инструментов и данных.

Добавьте MCP-сервер в настройках Manus:

Откройте Settings в Manus.
В разделе MCP Servers нажмите Add Server.
Укажите следующие данные:

Поле	Значение
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)

Название промпта	Описание	Аргументы
`daily_review`	Ежедневный обзор для планирования дел	Нет
`break_down_task`	Декомпозиция большой задачи	`task_id`
`weekly_summary`	Еженедельный отчет и планирование следующей недели	Нет

Место хранения данных

tasks.json (создается автоматически в той же директории, что и сервер)
Все задачи сохраняются в формате JSON

Тестирование

python -m pytest tests/ -v

Команда запуска тестов одинакова для Bash и PowerShell.

Ограничения

Для одного пользователя: одновременный доступ и управление пользователями не поддерживаются.
Только локально: сетевой доступ не предусмотрен.
Для обучения: надежность и безопасность для промышленной эксплуатации не учитывались.
Без БД: данные сохраняются в JSON-файл.
Без аутентификации: механизмы аутентификации и авторизации отсутствуют.

Task MCP Server