Skip to main content
Glama

mcp-weeek

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

Установка

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

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

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

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 — глобальный конфиг приложения.

Related MCP server: Focalboard MCP Server

Команды

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/; один шаблон на скилл, различия между клиентами делаются плейсхолдерами {{AGENT_DOC}} и {{RULES_DIR}} при рендере. Шаблоны едут в пакет внутри dist/skills/templates/.

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

  • setup показывает скиллы в том же плане, что и клиентские конфиги (added / updated / unchanged), и применяет их только после подтверждения; --dry-run и --yes работают как обычно.

  • Локально отредактированный файл скилла будет показан как updated — то есть перезапись видна в плане до её применения.

  • setup --no-skills — настроить только MCP-клиентов, скиллы не трогать.

  • doctor отдельной проверкой skills предупреждает, если файлы отсутствуют или разошлись с пакетом (warn, не fail).

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

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

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.

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

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 и не может быть случайно опубликован.

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

pnpm install
pnpm compile
npm install --global .

Либо через tarball:

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

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

mcp-weeek setup

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

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

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

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:

{
  "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.

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

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

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

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

{
  "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 до первой записи.

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

mcp-weeek doctor

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

  • схема .weeek-mcp.json;

  • наличие токена;

  • авторизация и доступ к доске;

  • обязательные колонки и текстовые поля «ИИ-отчёт»/«ИИ-диалог»;

  • конфиги выбранных клиентов;

  • локальный executable;

  • MCP initialize и tools/list через in-memory transport.

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

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

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

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

mcp-weeek init-board

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

mcp-weeek init-board --yes

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

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

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, чтобы отчёт и переход в «Ожидает релиза» всегда выполнялись вместе.

Разработка

pnpm install
pnpm test
pnpm compile
pnpm test:package

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

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers