PlanfixMCP

MCP-сервер для ПланФикс REST API, предоставляющий инструменты для работы с задачами, контактами, проектами и комментариями в LLM-ассистентах.

Установка и запуск

1. Установите uv.

2. Склонируйте проект и установите зависимости:

   git clone <url>
   cd PlanfixMCP
   uv sync

3. Создайте файл .env на основе .env.example и укажите в нем:

   • PLANFIX_BASE_URL: Базовый URL вашего REST API (например, https://account.planfix.com/rest).

   • PLANFIX_API_TOKEN: Ваш Bearer-токен.

Related MCP server: openapi-mcp

Настройка API Token

1. Получение токена: перейдите в Управление аккаунтом -> Интеграции -> REST API. Создайте приложение или выберите существующее, затем скопируйте Bearer-токен. Подробности в справке.

2. Настройка: скопируйте файл .env.example в .env и вставьте полученный токен в поле PLANFIX_API_TOKEN.

Настройка прав доступа (Scopes)

В настройках вашего аккаунта (Управление аккаунтом -> Интеграции -> REST API) выберите права:

• Рекомендуемый минимум (только чтение): common_metadata + все права *_readonly (task, comment, project, contact, object, file).

• Для записи (создание/обновление): добавьте *_add, *_update.

• Избегайте: system_settings, user_add, user_update — они избыточны.

Затем запустите сервер (через stdio для MCP-клиента):

uv run planfix-mcp

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

Все параметры задаются через .env файл или переменные окружения:

Режим «только для чтения»

PLANFIX_READ_ONLY=true отключает все изменяющие операции и оставляет только чтение данных. В этом режиме доступны:

• все GET-маршруты (task_by_id, contact_by_id, project_by_id, ...);

• POST-маршруты чтения списков — operationId начинается с get- (task_list, task_comments, comment_list, contact_list, project_list, ...);

• справочные POST-маршруты: списки фильтров, записи data-тегов и справочников (task_filters, contact_filters, ...).

Создание, обновление и удаление задач, контактов, проектов, комментариев и файлов в этом режиме недоступны. Для записи добавьте права из раздела «Настройка прав доступа (Scopes)» и запустите сервер без этого флага.

CLI-аргументы

Все настройки из .env можно переопределить при запуске:

Массовая выгрузка и сводки

Для больших объёмов данных (сотни задач, тысячи комментариев) не выгружайте сырые данные в диалог — сервер сам делает тяжёлую работу и возвращает компактный результат:

• export_tasks — сервер пагинирует /task/list, строит дерево задач (проект → задача → подзадачи), при необходимости тянет /task/{id}/comments/list и пишет файлы (Obsidian Markdown или JSON). Возвращает только манифест [{taskId, name, project, files, commentCount}]. В контекст LLM не попадает ни одна строка сырых данных.

Структура каталога выгрузки:

<PLANFIX_EXPORT_DIR>/
    Проект/
        Задача/
            Задача-1.md        ← описание + комментарии 1..100
            Задача-2.md        ← комментарии 101..200
            Подзадача/
                Подзадача-1.md
        Другая задача/ ...
    Без проекта/ ...

• Задачи без проекта складываются в папку «Без проекта».

• При совпадении имени папки/файла добавляется номер задачи: «Задача (42)».

• Подзадачи определяются рекурсивно через фильтр ПланФикс «Непосредственная надзадача» (type 73); дерево строится от задач, отобранных фильтром.

Markdown-файлы формируются в Obsidian-формате:

• имя файла: <название задачи>-<N>.md, где N — номер чанка комментариев (описание и frontmatter — только в первом файле);

• YAML-frontmatter: account, taskId, project, status, created, start, due, updated, commentCount, chunk, totalChunks;

• HTML из описаний и комментариев вырезается (чистый текст);

• каждый комментарий — блок - {дата-время} · [{commentId}](https://{host}/task/{id}/?comment={cid}) со ссылкой на комментарий в ПланФикс.

• task_summary — компактная сводка по задачам без записи файлов: [{taskId, name, status, endDateTime, commentCount}].

Оба инструмента принимают шорткаты фильтрации (сервер превращает их в сложные фильтры ПланФикс):

Даты принимаются в ISO-формате (2026-08-01). output_dir у export_tasks — относительный путь внутри PLANFIX_EXPORT_DIR; абсолютные пути и .. отклоняются. PLANFIX_EXPORT_DIR в свою очередь задаёт базовый каталог: относительный путь резолвится от cwd, в котором запущен сервер (обычно — проект, открытый в MCP-клиенте).

Примеры использования

Полная выгрузка всех видимых задач с комментариями в export/ (значения по умолчанию):

export_tasks()

Выгрузка задач конкретного проекта с комментариями в отдельную подпапку:

export_tasks(project=42, output_dir="project-42", include_comments=true)

Выгрузка задач со сроком раньше 01.08.2026, без комментариев:

export_tasks(end_date_before="2026-08-01", include_comments=false)

Выгрузка задач исполнителя в JSON (машиночитаемый формат без комментариев):

export_tasks(assignee="user:5", format="json")

Выгрузка по сохранённому фильтру задач (id из task_filters) с заданным полем поиска:

export_tasks(filter_id="12345", fields="id,name,status,endDateTime")

Сводка по проекту без записи файлов (быстрый обзор):

task_summary(project=42)

Сводка задач со сроками, попадающими в окно, с количеством комментариев:

task_summary(start_date_after="2026-08-01", end_date_before="2026-08-15", include_comment_counts=true)

Промпты для AI-агента

Готовые формулировки — вставьте их в диалог с LLM-ассистентом, у которого подключён этот MCP-сервер:

«Выгрузи все мои задачи с комментариями в Obsidian-файлы в папку planfix-export и покажи манифест выгрузки.»

«Сделай сводку всех задач проекта "Внедрение": id, название, статус и срок — без выгрузки файлов.»

«Найди задачи со сроком раньше 01.09.2026 и выгрузи их в файлы без комментариев.»

«Выгрузи задачи, где исполнитель user:5, в JSON-формате.»

«Покажи сводку задач, где я постановщик, отсортированных по сроку.»

«Собери задачи по сохранённому фильтру "Горящие" и выгрузи с комментариями в папку backup/.»

«Обойди задачи проекта 42 и напиши краткое резюме по каждой, используя выгруженные файлы, а не сырые данные.»

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

Добавьте сервер в mcp вашего opencode.json (или аналогичного конфига клиента):

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "planfix": {
      "type": "local",
      "command": ["uv", "--project", "D:/Projects/dy-team/PlanfixMCP", "run", "--env-file", ".env", "planfix-mcp"],
      "cwd": ".",
      "enabled": true
    }
  }
}

Локальный .env проекта MCP-клиентом не читается, поэтому он подгружается явно:

• --project D:/Projects/dy-team/PlanfixMCP — путь к проекту (укажите свой после git clone);

• --env-file .env — загружает переменные из файла .env проекта;

• cwd: "." — рабочая директория сервера (относительный путь .env и каталог выгрузки резолвятся от неё; по умолчанию — директория рабочего пространства клиента).

Сервер объявляется один раз в блоке mcp и становится доступен всем агентам opencode — встроенным (build, plan) и кастомным. Отдельно прописывать его для каждого агента не нужно: инструменты planfix_* сразу появляются в их списке инструментов.

Подключение для других агентов

Подключение для любого другого агента аналогичное — используется тот же самый блок mcp с той же командой. Кастомному агенту достаточно просто существовать в конфиге, и сервер будет ему доступен:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "planfix": {
      "type": "local",
      "command": ["uv", "--project", "D:/Projects/dy-team/PlanfixMCP", "run", "--env-file", ".env", "planfix-mcp"],
      "cwd": ".",
      "enabled": true
    }
  },
  "agent": {
    "planfix-analyst": {
      "description": "Готовит сводки и выгрузки по задачам ПланФикс.",
      "mode": "subagent",
      "prompt": "Ты работаешь с задачами ПланФикс: для обзора используй planfix_task_summary, для массовой выгрузки — planfix_export_tasks."
    }
  }
}

Если нужно ограничить доступ к инструментам для конкретного агента — сделайте это через permission агента (см. документацию opencode), сам сервер прописывать у агента не требуется.

Установка через AI-агента

Вы можете поручить установку и настройку этого MCP-сервера AI-агенту, используя следующий промпт:

"Клонируй репозиторий PlanfixMCP по адресу <url>, установи зависимости через uv sync и помоги мне создать файл .env с настройками доступа к API ПланФикс (PLANFIX_BASE_URL и PLANFIX_API_TOKEN). После этого проверь работоспособность тестами и добавь конфигурацию сервера в мой opencode.json."

Разработка и вклад в проект

Мы приветствуем Pull Requests! Если вы хотите помочь в развитии проекта:

1. Развертывание окружения:

   uv sync

2. Запуск тестов: Перед отправкой изменений убедитесь, что все тесты проходят:

   uv run pytest -q

3. Обновление OpenAPI-спеки: Если API ПланФикс изменилось, обновите локальную копию спеки и перегенерируйте словари:

   uv run python scripts/update_spec.py
   uv run python scripts/gen_dictionaries.py

4. Pull Requests:

   • Создайте отдельную ветку для ваших изменений.

   • Убедитесь, что код соответствует стилю проекта (Python 3.10+, snake_case).

   • Важно: Никогда не коммитьте .env файлы или API-токены.