mcp-weeek
by yaaaamm
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`.
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues