# PlanfixMCP

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

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

1. Установите [uv](https://docs.astral.sh/uv/).
2. Склонируйте проект и установите зависимости:
   ```bash
   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-токен.

## Настройка API Token

1. **Получение токена**: перейдите в **Управление аккаунтом** -> **Интеграции** -> **REST API**. Создайте приложение или выберите существующее, затем скопируйте `Bearer-токен`. [Подробности в справке](https://planfix.com/ru/help/REST_API_%D0%90%D0%B2%D1%82%D0%BE%D1%80%D0%B8%D0%B7%D0%B0%D1%86%D0%B8%D1%8F).
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-клиента):
```bash
uv run planfix-mcp
```

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

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

| Переменная | Описание |
|---|---|
| `PLANFIX_BASE_URL` | Базовый URL REST API ПланФикс. |
| `PLANFIX_API_TOKEN` | Bearer-токен авторизации. |
| `PLANFIX_EXCLUDE_TECHNICAL_COMMENTS` | Если `true`, скрывает технические события (смена статусов, дат) в ленте комментариев. |
| `PLANFIX_READ_ONLY` | Если `true`, включает режим «только для чтения» — доступны лишь операции чтения (см. ниже). |
| `PLANFIX_TAGS` | Список тегов OpenAPI для фильтрации инструментов (по умолчанию: `task,contact,project,comments`). |
| `PLANFIX_EXPORT_DIR` | Базовый каталог для выгрузки задач в файлы (по умолчанию: `export/`). Относительный путь резолвится от рабочего каталога (cwd), в котором запущен сервер; абсолютный — фиксируется жёстко. |
| `PLANFIX_EXPORT_ACCOUNT` | Имя аккаунта для имён файлов и frontmatter (по умолчанию — поддомен из `PLANFIX_BASE_URL`). |
| `PLANFIX_EXPORT_COMMENTS_PER_FILE` | Сколько комментариев в одном файле Markdown (по умолчанию: `100`). |

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

`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` можно переопределить при запуске:

| Флаг | Назначение |
|---|---|
| `--transport stdio\|http` | Транспорт MCP (по умолчанию `stdio`). |
| `--base-url` | Базовый URL REST API (как `PLANFIX_BASE_URL`). |
| `--api-token` | Bearer-токен (как `PLANFIX_API_TOKEN`). |
| `--tags` | Теги OpenAPI для включения инструментов (как `PLANFIX_TAGS`). |
| `--include-operation-ids` / `--exclude-operation-ids` | Включение/исключение операций по operationId. |
| `--validate-output` | Валидировать ответы по схемам спеки (по умолчанию `true`). |
| `--export-dir` | Базовый каталог выгрузки задач (как `PLANFIX_EXPORT_DIR`). |
| `--export-account` | Имя аккаунта для frontmatter (как `PLANFIX_EXPORT_ACCOUNT`). |
| `--comments-per-file` | Комментариев в одном файле Markdown (как `PLANFIX_EXPORT_COMMENTS_PER_FILE`). |
| `--host` / `--port` | Адрес и порт для HTTP-транспорта (по умолчанию `127.0.0.1:8000`). |

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

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

- **`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}]`.

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

| Параметр | Поле ПланФикс |
|---|---|
| `endDateBefore` / `endDateAfter` | Дата планируемого завершения (type 14) |
| `startDateBefore` / `startDateAfter` | Дата планируемого начала (type 13) |
| `assigner` / `assignee` / `auditor` | Постановщик / исполнитель / аудитор (1/2/3), формат `user:5`, `contact:5`, `group:3` |
| `counterparty` | Контрагент (type 7) |
| `project` | Проект (type 5), номер проекта |
| `filterId` | Сохранённый фильтр задач (из `task_filters`) |
| `filters` | Полный массив `ComplexTaskFilter` (включая пользовательские поля) |

Даты принимаются в 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` (или аналогичного конфига клиента):

```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` с той же командой. Кастомному агенту достаточно просто существовать в
конфиге, и сервер будет ему доступен:

```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
    }
  },
  "agent": {
    "planfix-analyst": {
      "description": "Готовит сводки и выгрузки по задачам ПланФикс.",
      "mode": "subagent",
      "prompt": "Ты работаешь с задачами ПланФикс: для обзора используй planfix_task_summary, для массовой выгрузки — planfix_export_tasks."
    }
  }
}
```

Если нужно ограничить доступ к инструментам для конкретного агента — сделайте это
через `permission` агента (см. [документацию opencode](https://opencode.ai/docs/agents)),
сам сервер прописывать у агента не требуется.

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

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

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

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

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

1. **Развертывание окружения**:
   ```bash
   uv sync
   ```
2. **Запуск тестов**:
   Перед отправкой изменений убедитесь, что все тесты проходят:
   ```bash
   uv run pytest -q
   ```
3. **Обновление OpenAPI-спеки**:
   Если API ПланФикс изменилось, обновите локальную копию спеки и перегенерируйте словари:
   ```bash
   uv run python scripts/update_spec.py
   uv run python scripts/gen_dictionaries.py
   ```
4. **Pull Requests**:
   - Создайте отдельную ветку для ваших изменений.
   - Убедитесь, что код соответствует стилю проекта (Python 3.10+, snake_case).
   - **Важно**: Никогда не коммитьте `.env` файлы или API-токены.