mcp-task-manager

Локальный менеджер задач, который подключается к Claude Desktop через Model Context Protocol от Anthropic. Никакого UI, никакой серверной части — только процесс Python и файл SQLite. Вы управляете задачами, общаясь с Claude.

"Создай задачу с высоким приоритетом: исправить баг авторизации, срок до пятницы, добавь тег backend." → задача создана. "На чем мне стоит сосредоточиться сегодня?" → возвращает просроченные + срочные + высокоприоритетные задачи. "Отметь задачу 3 как выполненную и покажи мне сводку." → выполнено + статистика.

Стек: Python 3.11+ · FastMCP · SQLite · Pydantic v2 Статус: работает локально, реализовано 9 инструментов

Зачем этот проект

Создан для изучения MCP от начала до конца: жизненный цикл сервера, регистрация инструментов, транспорт stdio и то, как Claude выбирает инструменты на основе запросов на естественном языке. Это небольшой, но полноценный пример — то, что можно превратить в реальный внутренний инструмент на работе.

Как это работает

MCP-серверы запускаются как локальные подпроцессы. Claude Desktop общается с сервером через stdio, используя JSON-RPC. Когда вы вводите сообщение, Claude:

1. Выбирает, какой зарегистрированный инструмент подходит для запроса

2. Заполняет параметры из вашего естественного языка

3. Вызывает инструмент, получает структурированные данные (модели Pydantic)

4. Обобщает результат для вас на обычном языке

Claude Desktop  ──── JSON-RPC (stdio) ────  server.py  (FastMCP)
                                                │
                                         TaskRepository
                                                │
                                           tasks.db  (SQLite)

Инструменты

Приоритеты: low · medium · high · urgent Статусы: pending · in_progress · completed · cancelled

Структура проекта

mcp-task-manager/
├── server.py           # FastMCP entry point, tool registration, lifespan
├── core/
│   ├── models.py       # Pydantic models + enums (Task, TaskCreate, TaskUpdate, TaskSummary)
│   └── repository.py   # SQLite DAO — CRUD, search, summary
├── tools/
│   └── __init__.py     # 9 MCP tool functions (thin layer over repository)
├── pyproject.toml
└── .env.example

Три уровня, у каждого своя ответственность:

• tools/ — поверхность, обращенная к MCP. Каждая функция имеет docstring, который читает Claude, чтобы понять, когда и как ее вызывать.

• core/repository.py — доступ к SQLite. Чистый SQL, индексированный по status, priority, due_date.

• core/models.py — валидация, сериализация, перечисления (enums).

Установка

Требования: Python 3.11+, Claude Desktop.

git clone https://github.com/soltyDude/mcp-task-manager.git
cd mcp-task-manager

python -m venv .venv
source .venv/bin/activate        # Windows: .venv\Scripts\activate

pip install -e .
cp .env.example .env

Подключение к Claude Desktop

Откройте конфигурацию Claude Desktop:

• macOS — ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows — %APPDATA%\Claude\claude_desktop_config.json

Добавьте сервер:

{
  "mcpServers": {
    "mcp-task-manager": {
      "command": "/absolute/path/to/mcp-task-manager/.venv/bin/python",
      "args": ["/absolute/path/to/mcp-task-manager/server.py"]
    }
  }
}

Перезапустите Claude Desktop. Инструменты появятся под иконкой 🔌.

Конфигурация

.env поддерживает две переменные:

DATABASE_PATH=tasks.db       # where SQLite stores data
SERVER_NAME=mcp-task-manager # name shown in Claude Desktop

Пример сессии

You:    Add a task: refactor the auth filter, high priority, due tomorrow, tags: backend, security

Claude: Created task #1 — "Refactor the auth filter" (high, due 2025-04-19, tags: backend, security)

You:    What's my plan for today?

Claude: 📅 Day plan for 2025-04-18
        🔥 FOCUS (urgent + high priority)
          [1] [HIGH] Refactor the auth filter  #backend #security
        📊 Total: 1 | In progress: 0 | Overdue: 0

You:    Mark it in progress and show a summary

Claude: Task #1 updated — status: in_progress.
        📊 Total: 1 | Pending: 0 | In progress: 1 | Completed: 0 | Overdue: 0

Заметки по проектированию

Несколько решений, которые стоит отметить, если вы читаете это как рецензент:

• Репозиторий с областью видимости жизненного цикла. TaskRepository создается один раз в контекстном менеджере lifespan библиотеки FastMCP и внедряется через ctx.request_context.lifespan_context. Инструменты остаются без состояния; детали подключения не просачиваются в код инструментов.

• Перечисления вместо магических строк. Priority и TaskStatus — это str enums, проверяемые Pydantic при вводе, хранящиеся как строки в SQLite и типизированные везде между ними.

• Теги как JSON в столбце TEXT. Прагматично для SQLite — не нужна промежуточная таблица для локального инструмента. Поиск использует LIKE по сериализованному JSON. Если когда-нибудь проект переедет на Postgres, это станет text[] или настоящей таблицей тегов.

• Индексация горячих путей. status, priority, due_date — три столбца, по которым идет каждый фильтр.

• plan_day удаляет дубликаты. Запросы по срочным и высокоприоритетным задачам могут пересекаться со списком просроченных, поэтому итоговый список фокуса строится с использованием множества seen.

Ограничения / следующие шаги

• Пока нет тестов — в планах: pytest с in-memory фикстурой SQLite для уровня репозитория.

• Нет повторяющихся задач.

• Поиск основан на LIKE; для большего набора данных обновлением станет SQLite FTS5.

• По дизайну — для одного пользователя на одной машине. Многопользовательский режим потребует замены SQLite на Postgres и добавления столбца пользователя.

Лицензия

MIT