Skip to main content
Glama
README.md
# mcp-weeek

Универсальный MCP CLI для интеграции AI-клиентов с задачами [Weeek](https://weeek.net). Один проектный конфиг привязывает один экземпляр сервера к одной доске. Колонки и поля «ИИ-отчёт»/«ИИ-диалог» резолвятся по имени, поэтому их ID не хардкодятся.

## Установка

```sh
npm install --global git+https://github.com/yaaaamm/mcp-weeek.git
```

Эта же команда обновляет: её можно запускать сколько угодно раз подряд.

Затем в корне подключаемого проекта:

```sh
mcp-weeek setup     # MCP-клиенты + скиллы /weeek-*
mcp-weeek update    # позже: подтянуть свежую версию и применить её здесь же
```

`setup` и `update` перед работой сами подтягивают свежую версию инструмента и перезапускаются ею — ходить в чекаут `mcp-weeek` не нужно. Подробности и флаги — в разделе [Установка и обновление](#установка-и-обновление).

Поддерживаемые клиенты:

- Codex — `.codex/config.toml`;
- Claude Code — `.mcp.json`;
- Google Antigravity — `.agents/mcp_config.json`;
- Claude Desktop — глобальный конфиг приложения.

## Команды

```text
mcp-weeek setup       настроить текущий проект и MCP-клиенты
mcp-weeek update      обновить конфиги клиентов и скиллы в текущем проекте
mcp-weeek doctor      проверить конфиг, токен, Weeek, клиентов и handshake
mcp-weeek init-board  показать и создать недостающие колонки/поля
mcp-weeek serve       запустить STDIO MCP-сервер
```

## После установки

1. В корне подключаемого проекта запусти `mcp-weeek setup` — он пропишет MCP-сервер и разложит скиллы `/weeek-*`.
2. Подготовь доску командой `mcp-weeek init-board --yes`.
3. Перезапусти AI-клиент и проверь подключение через `mcp-weeek doctor`.

- Новые задачи: `weeek_list_pending_tasks`.
- Возвраты после проверки человеком: `weeek_list_rework_tasks`.
- Если данных не хватает: `weeek_ask_question` сохранит вопрос в «ИИ-диалог» и перенесёт задачу в «Обсудить».
- После реализации: `weeek_finish_task` одновременно запишет «ИИ-отчёт» и перенесёт задачу в «Ожидает релиза».

После ответа человек дописывает его в «ИИ-диалог» и возвращает задачу в «Доработать ИИ». Эти две очереди не смешиваются.

## Скиллы `/weeek-*`

Одного MCP-сервера мало: инструменты `weeek_*` описывают, ЧТО можно сделать, а воркфлоу (какую задачу взять, когда клеймить, что писать в «ИИ-отчёт») живёт в скиллах. Поэтому `setup` ставит их вместе с конфигом клиента — в новом проекте `/weeek-tasks` доступен сразу, без ручного копирования.

Ставятся восемь скиллов:

| Скилл | Что делает |
| --- | --- |
| `/weeek-init` | подготовить доску: досоздать колонки и поля «ИИ-отчёт»/«ИИ-диалог» |
| `/weeek-errors` | взять следующую задачу из «Ошибки» и довести до «Ожидает релиза» |
| `/weeek-tasks` | то же для колонки «Доработки» |
| `/weeek-any` | то же, но берёт из любой колонки-источника по приоритету |
| `/weeek-rework` | взять возврат из «Доработать ИИ» и исправить по замечанию человека |
| `/weeek-changelog-update` | перед релизом собрать запись «Что нового» из «Ожидает релиза» и git-коммитов в `CHANGELOG.mdx` + `version.json` (инфраструктуру changelog создаёт отдельный скилл `weeek-setup-changelog`) |
| `/weeek-release` | после `git push` + деплоя перенести «Ожидает релиза» → «ВЫПОЛНЕНО ИИ» |
| `/weeek-setup-changelog` | один раз на проект развернуть саму changelog-инфраструктуру: `CHANGELOG.mdx` + `version.json` + кнопка «Что нового» с красной точкой + страница `/help/changelog` |

Куда именно кладутся файлы — зависит от `--clients`; каждый клиент читает свою папку и свой файл правил:

| Клиент | Папка | Ссылка на правила в тексте скилла |
| --- | --- | --- |
| `claude-code` | `.claude/skills/<имя>/SKILL.md` | `CLAUDE.md`, `.claude/rules/` |
| `codex` | `.codex/skills/<имя>/SKILL.md` | `AGENTS.md`, `.codex/rules/` |
| `antigravity` | `.agents/skills/<имя>/SKILL.md` | `AGENTS.md`, `.agents/rules/` |

`claude-desktop` проектные скиллы не читает и пропускается.

Источник истины — [`src/skills/templates/`](src/skills/templates/); один шаблон на скилл, различия между клиентами делаются плейсхолдерами `{{AGENT_DOC}}` и `{{RULES_DIR}}` при рендере. Шаблоны едут в пакет внутри `dist/skills/templates/`.

Поведение при повторном запуске:

- `setup` показывает скиллы в том же плане, что и клиентские конфиги (`added` / `updated` / `unchanged`), и применяет их только после подтверждения; `--dry-run` и `--yes` работают как обычно.
- Локально отредактированный файл скилла будет показан как `updated` — то есть перезапись видна в плане до её применения.
- `setup --no-skills` — настроить только MCP-клиентов, скиллы не трогать.
- `doctor` отдельной проверкой `skills` предупреждает, если файлы отсутствуют или разошлись с пакетом (`warn`, не `fail`).

## Установка и обновление

Команда одна и та же для первой установки и для обновления, клонировать и собирать руками не нужно:

```sh
npm install --global git+https://github.com/yaaaamm/mcp-weeek.git
```

### Почему сборка называется `compile`, а `dist` коммитится

Это не стиль, а обязательное условие работоспособности установки, и оно легко ломается по неосторожности.

Устанавливая пакет из git, npm (pacote, `GitFetcher.#prepareDir`) смотрит на имена скриптов в `package.json`. Если есть хоть одно из **`postinstall`, `build`, `preinstall`, `install`, `prepack`, `prepare`**, он запускает внутри клона вложенный `npm install --force --include=dev`. Причём `build` работает только как признак: npm его не выполняет, но его наличия достаточно.

Эта вложенная установка наследует конфиг родителя, включая префикс, и приводит к двум поломкам:

- установка поверх уже установленной копии падает с `ENOTEMPTY` — то есть ломается ровно обновление;
- пакет подсовывается симлинком на временный клон в кэше; клон удаляется, и остаётся установка без работающего бинарника.

Поэтому в `package.json` нет ни одного из этих имён: сборка называется `compile`, проверка перед упаковкой — `verify:pack`. Раз при установке ничего не собирается, готовый `dist` лежит в репозитории; установка становится обычной распаковкой, как у пакета из registry, и повторяется сколько угодно раз.

Цена — `dist` в диффах. Чтобы он не отставал от исходников, CI падает, если `pnpm compile` меняет закоммиченный `dist`, и отдельно — если в `scripts` появилось запрещённое имя. То же самое проверяет тест в [self-update.test.ts](src/cli/self-update.test.ts).

Но руками её звать обычно не приходится: `setup` и `update` перед работой сами переустанавливают инструмент из репозитория и перезапускают команду уже новой сборкой. Поэтому проект всегда получает актуальные скиллы, даже если про обновление никто не помнил.

```sh
mcp-weeek update          # подтянуть свежую версию и применить её здесь
mcp-weeek update --self   # только переустановить инструмент, проект не трогать
```

Почему переустановка, а не сравнение версий: пакет не публикуется в registry, а `dist` коммитится — значит записанный в сборке коммит всегда на один отстаёт от коммита, который её привозит, и сравнение рапортовало бы «устарел» вечно. Переустановка стоит несколько секунд сети и всегда даёт верный ответ.

Обновление не имеет права мешать работе: если сети нет или npm упал, в выводе появится `Self-update failed, continuing with the installed version`, и команда продолжится на установленной версии. Выключить обновление насовсем — `--no-self-update`.

### Что считается «правленым руками»

Каждый установленный SKILL.md помечается во фронтматтере строкой `x-mcp-weeek: <версия> <хеш>`. По ней инструмент отличает файл, который никто не трогал, от файла с ручными правками:

- файл не менялся с установки — обновляется молча, вопросов не задаётся;
- файл правили руками или он скопирован мимо инструмента — сохраняется, а в выводе появляется строка `needs confirmation`. Заменить его можно `mcp-weeek update --overwrite-skills`;
- `--no-skills` вообще не трогает скиллы.

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

## Установка из локального клона

Пока registry scope не выбран, пакет защищён `"private": true` и не может быть случайно опубликован.

Установка прямо из локального репозитория:

```sh
pnpm install
pnpm compile
npm install --global .
```

Либо через tarball:

```sh
pnpm pack --pack-destination ./artifacts
npm install --global ./artifacts/mcp-weeek-1.8.0.tgz
```

Для публикации в приватный npm-compatible registry сначала задай реальный scope, например `@company/mcp-weeek`, убери локальный флаг `private`, добавь `publishConfig.access = "restricted"` и настрой registry в пользовательском `~/.npmrc`. Registry-токен нельзя добавлять в репозиторий, проектный `.env` или MCP-конфиги.

После установки клиенты не обращаются к registry: `setup` записывает абсолютные пути к локальному Node.js и установленному `dist/cli.js`.

## Быстрый setup

Интерактивно из корня подключаемого проекта:

```sh
mcp-weeek setup
```

Неинтерактивно:

```sh
mcp-weeek setup \
  --board-url "https://app.weeek.net/ws/12345/project/2/board/3" \
  --env-file apps/api/.env \
  --clients codex,claude-code,antigravity \
  --yes
```

Только посмотреть изменения:

```sh
mcp-weeek setup \
  --board-url "https://app.weeek.net/ws/12345/project/2/board/3" \
  --env-file apps/api/.env \
  --clients codex,claude-code,antigravity \
  --dry-run
```

`setup` выполняет read-only проверку токена и доступа к доске, рассчитывает все изменения до первой записи, сохраняет чужие MCP-серверы и после установки запускает `doctor`.

## Проектный конфиг

`setup` создаёт `.weeek-mcp.json`:

```json
{
  "version": 1,
  "boardUrl": "https://app.weeek.net/ws/12345/project/2/board/3",
  "auth": {
    "source": "env-file",
    "file": "apps/api/.env",
    "variable": "WEEEK_API_TOKEN"
  }
}
```

`workspaceId`, `projectId` и `boardId` извлекаются из URL и не дублируются. Относительный путь к `.env` считается от `.weeek-mcp.json`.

Также поддерживается токен из окружения:

```json
{
  "version": 1,
  "boardUrl": "https://app.weeek.net/ws/12345/project/2/board/3",
  "auth": {
    "source": "env",
    "variable": "WEEEK_API_TOKEN"
  }
}
```

### Поля постановщика (`intakeFields`)

Необязательный блок: поля, которые заполняет автор задачи, чтобы ИИ сразу знал, где искать проблему. Имена и варианты у каждого проекта свои, поэтому они живут в конфиге, а `init-board` только досоздаёт недостающее.

```json
{
  "version": 1,
  "boardUrl": "https://app.weeek.net/ws/12345/project/2/board/3",
  "auth": { "source": "env", "variable": "WEEEK_API_TOKEN" },
  "intakeFields": [
    { "name": "URL", "type": "text" },
    { "name": "Раздел", "type": "select", "options": ["Объекты", "Карта"] },
    { "name": "Локация", "type": "select", "options": ["Шапка", "Таблица"] },
    { "name": "Уточнение", "type": "text" }
  ]
}
```

- Поддерживаются типы `text` и `select`; у `select` должен быть хотя бы один вариант.
- В существующем select-поле досоздаются только недостающие варианты; цвета берутся по кругу из палитры Weeek.
- Поле с тем же именем, но другим типом не трогается: `init-board` сообщает о конфликте.

JSON Schema поставляется внутри пакета: `schema/weeek-mcp.schema.json`.

## Безопасность токена

- Значение токена не записывается в `.weeek-mcp.json` или клиентские конфиги.
- При `env-file` парсится файл, но извлекается только указанная переменная.
- `DATABASE_URL`, JWT, SSH и другие значения не импортируются в `process.env` и не передаются MCP-процессу.
- Токены и содержимое `.env` не выводятся в preview, `doctor` и ошибки.
- Глобальный конфиг Claude Desktop получает timestamped backup перед изменением.
- Если имя MCP-сервера уже занято чужой командой, `setup` завершится с `CLIENT_CONFIG_CONFLICT` до первой записи.

## Диагностика и восстановление

```sh
mcp-weeek doctor
```

Проверяются:

- схема `.weeek-mcp.json`;
- наличие токена;
- авторизация и доступ к доске;
- обязательные колонки и текстовые поля «ИИ-отчёт»/«ИИ-диалог»;
- конфиги выбранных клиентов;
- локальный executable;
- MCP `initialize` и `tools/list` через in-memory transport.

После обновления Node.js или глобального пакета восстанови абсолютные пути:

```sh
mcp-weeek setup --repair --clients codex,claude-code,antigravity --yes
```

## Инициализация новой доски

Обычный `setup` доску не изменяет. Сначала посмотри план:

```sh
mcp-weeek init-board
```

Применить без дополнительного вопроса:

```sh
mcp-weeek init-board --yes
```

**На новой доске сначала заведи хотя бы одну задачу.** У API Weeek нет эндпоинта, который возвращает поля доски: они видны только в задачах. На доске без задач пустой список полей означает «неизвестно», а не «полей нет», и создание могло бы задублировать уже существующие поля — повторный запуск плодил бы копии «ИИ-отчёта». Поэтому на такой доске `init-board` создаёт колонки, поля пропускает и прямо об этом пишет. После появления любой задачи повторный запуск создаст недостающие поля.

Добавить необязательные manual-колонки:

```sh
mcp-weeek init-board --include-optional --yes
```

Команда идемпотентна: существующие колонки и поля сопоставляются регистронезависимо по нормализованному имени. «Доработать ИИ» и «ИИ-диалог» входят в стандартную обязательную схему. Если в конфиге есть `intakeFields`, план включает и их: недостающие поля, недостающие варианты и конфликты типов.

Граница «обязательное / опциональное» проходит по одному признаку: **обязательна любая колонка, в которую какой-нибудь `weeek_*` кладёт задачу.** С 1.8.0 сюда входит и «Подтвердить (у меня нет такой ошибки)» — цель `weeek_reject_task`; раньше она лежала среди опциональных, и на доске без неё инструмент падал, пока кто-нибудь не догадается прогнать `--include-optional`. В опциональных остался только ручной учёт, который никакой инструмент не читает и не пишет: «Ручная доработка», «Готово», «Принято Manual».

## MCP-инструменты

`weeek_init_board`, `weeek_list_boards`, `weeek_list_columns`, `weeek_list_tasks`, `weeek_list_pending_tasks`, `weeek_list_rework_tasks`, `weeek_get_task`, `weeek_ask_question`, `weeek_move_task`, `weeek_update_task`, `weeek_complete_task`, `weeek_set_ai_report`, `weeek_finish_task`, `weeek_reject_task`, `weeek_download_image`.

### Списки задач: пагинация и мультидосочность

`GET /tm/tasks` отдаёт страницу по 20 задач и флаг `hasMore`. До 1.8.0 все три list-инструмента делали один запрос и молча теряли остаток: 19.08.2026 `/weeek-release` отрапортовал о разобранной колонке, где осталось 8 задач из 26, а changelog собрался по 18 из 26.

Теперь `weeek_list_tasks`, `weeek_list_pending_tasks` и `weeek_list_rework_tasks` читают **все** страницы (`perPage`/`offset`) и отдают полный список. Клиенту крутить пагинацию не нужно.

- `weeek_list_tasks` возвращает компактный список + `totalCount`. Без этого полный JSON колонки в 26 задач весит ~1 МБ: каждая задача тащит `options[]` всех select-полей и текст «ИИ-отчёта». Сырой ответ одной страницы доступен через `raw: true` — только для отладки, он обрезается.
- `truncated: true` (в `weeek_list_tasks`; по колонкам — в pending/rework) означает, что упёрлись в предохранитель в 50 страниц и список НЕполный. В норме всегда `false`.
- **Членство в колонке определять по `locations[]`, а не по верхнему `boardColumnId`.** Задача может лежать сразу на нескольких досках, и тогда верхний `boardColumnId` — колонка чужой доски. Такие задачи отдаются с полем `locations`; фильтр только по `boardColumnId` их теряет (реальный случай: #3210/#3208 висели в колонке 534 доски 133 через `locations`, а сверху показывали 624 доски 175).

Основной workflow:

1. `weeek_list_pending_tasks`.
2. `weeek_get_task`.
3. `weeek_move_task` с ролью `AI_IN_PROGRESS`.
4. Реализация задачи.
5. `weeek_finish_task({ taskId, report })` одним обновлением записывает «ИИ-отчёт» и перемещает задачу в `AWAITING_RELEASE`.

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

1. `weeek_list_rework_tasks` читает только колонку «Доработать ИИ».
2. `weeek_get_task` показывает замечания и историю «ИИ-диалога».
3. Задача перемещается в `AI_IN_PROGRESS`, исправляется и проверяется.
4. `weeek_finish_task({ taskId, report })` вместе обновляет «ИИ-отчёт» и возвращает задачу в `AWAITING_RELEASE`.

Если требования или замечания непонятны, `weeek_ask_question` можно вызвать для любой задачи. Инструмент сохраняет предыдущую историю, дописывает вопрос в «ИИ-диалог» и одним обновлением перемещает задачу в «Обсудить». Public API V1 не предоставляет endpoint комментариев к задачам, поэтому «ИИ-диалог» используется как поддерживаемая замена.

## Legacy-совместимость

Старый запуск `node dist/index.js` продолжает принимать:

- `WEEEK_API_TOKEN`;
- `WEEEK_BOARD_ID`;
- `WEEEK_PROJECT_ID`;
- необязательный `WEEEK_WORKSPACE_ID`.

Новые проекты должны использовать `.weeek-mcp.json` и `mcp-weeek serve`.

`weeek_complete_task` сохранён только для совместимости: он выставляет `isCompleted=true`. Для завершения AI-задачи используется `weeek_finish_task`, чтобы отчёт и переход в «Ожидает релиза» всегда выполнялись вместе.

## Разработка

```sh
pnpm install
pnpm test
pnpm compile
pnpm test:package
```

`test:package` собирает tarball, устанавливает его во временный global prefix и запускает установленную CLI-команду `mcp-weeek --help`.