nexus-mcp

MCP-сервер, предоставляющий систему управления проектами Nexus/TaskBridge для Claude Code, чтобы агенты могли читать и обновлять задачи напрямую, а не человек вручную передавал состояние. В паре с двумя навыками в claude-templates — nexus-plan-work (для PM/BA/Team Lead, создание) и nexus-pick-up-task (для разработчиков, потребление).

Общается с публичным API /api/v1/* системы PM — не с внутренними конечными точками nexus-vscode, которые зарезервированы для официальных расширений. См. DEVLOG.md о том, почему, и о полной истории разработки.

Настройка (один раз, на человека)

Четыре шага по порядку — сам по себе вход в систему не сообщает Claude Code о существовании nexus-mcp. Это отдельный шаг (2 ниже). Нигде в этом списке не нужен git clone — npx загружает, собирает и запускает прямо из GitHub.

1. Войдите в систему — генерирует токен через Developer Portal и сохраняет его в связке ключей ОС (@napi-rs/keyring — никогда в файле):

export NEXUS_API_URL=http://27.254.62.17:8090
npx -y -p github:tanakorncode/nexus-mcp nexus-mcp-login

Проведёт вас через $NEXUS_API_URL/developer → создайте приложение → предоставьте области tasks:read tasks:write projects:read members:read sprints:read → сгенерируйте токен — затем предложит вставить этот токен и адрес вашей электронной почты.

2. Зарегистрируйте в Claude Code — выберите один (оба не нужны, но могут сосуществовать):

• Для себя, для каждого репозитория, один раз (нужен CLI claude — сначала npm install -g @anthropic-ai/claude-code):

  claude mcp add nexus-mcp -s user -e NEXUS_API_URL=http://27.254.62.17:8090 -- npx -y github:tanakorncode/nexus-mcp

  После этого нигде не нужен .mcp.json.

• Или, если в открываемом вами репозитории уже есть .mcp.json в корне (например, pea-thailand-backoffice-be) — ничего делать не нужно, Claude Code подхватит его сам при открытии этого репозитория. Актуально только если вы не выполнили шаг выше.

3. Перезагрузите Claude Code (новое окно / перезапустите сессию) — требуется в любом случае, работающая сессия не подхватывает только что зарегистрированный сервер сама. Первое подключение медленнее (npx загружает и собирает заново); после этого кэшируется. Подтвердите одноразовый запрос доверия.

4. Проверьте — попросите Claude вызвать whoami. Если он определит ваше имя, все четыре шага сработали.

Установите также навыки (один раз на человека — подробности в claude-templates/README.md):

mkdir -p ~/.claude/skills
git clone --depth 1 https://github.com/tanakorncode/claude-templates /tmp/claude-templates
cp -r /tmp/claude-templates/skills/nexus-pick-up-task ~/.claude/skills/
cp -r /tmp/claude-templates/skills/nexus-plan-work ~/.claude/skills/

Разработка самого nexus-mcp

Если вы изменяете код самого этого репозитория, а не просто используете его, клонируйте его, чтобы правки вступали в силу без повторной публикации:

git clone https://github.com/tanakorncode/nexus-mcp
cd nexus-mcp
npm install
npm run build
npm link          # makes the `nexus-mcp` command available anywhere on this machine

Укажите в .mcp.json "command": "nexus-mcp" (без args) вместо формы npx во время итераций — пересоберите (npm run build) и перезагрузите окно Claude Code, чтобы изменения вступили в силу; в противном случае процесс MCP-сервера держит в памяти старый код.

Related MCP server: project-manager

Два навыка и когда каждый применяется

• nexus-plan-work — разбиение функции на эпик/историю/задачу. Используйте до того, как работа появится. Здесь важна дисциплина: одна история на функцию, охватывающую несколько репозиториев, одна задача на репозиторий под ней, repositoryId задан для каждой задачи (самое часто пропускаемое поле, и его невозможно восстановить позже, если упустить).

• nexus-pick-up-task — поиск, понимание и выполнение задачи, завершающееся PR и обновлением статуса. Используйте, когда работа уже существует и кто-то (человек или запланированная проверка) готов приступить к ней.

Прочтите сами файлы навыков для полного пошагового описания — этот README не будет их дублировать.

Инструменты

Идентификация и обнаружение

Чтение задач

Создание (см. nexus-plan-work)

Передача

Необязательно: запланированная проверка задач (только уведомление)

scripts/check-my-tasks.sh запускается без интерфейса (claude -p) и проверяет list_my_tasks по таймеру, отправляя уведомление macOS, если что-то готово — он не начинает писать код сам по себе (--allowedTools ограничен инструментами только для чтения плюс Bash(osascript*), так что структурно не может редактировать файлы, даже если бы захотел).

launchctl load ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist   # enable, runs every 2h
launchctl unload ~/Library/LaunchAgents/com.pea-thailand.nexus-task-check.plist # disable
tail -f ~/Library/Logs/nexus-task-check.log                                     # watch it run
./scripts/check-my-tasks.sh                                                     # run once, right now

Сам plist не в этом репозитории (это локальная конфигурация машины, на человека) — скопируйте тот, что в записи DEVLOG.md от 2026-08-22, или спросите того, кто настроил свой.

Это только проверяет; человек всё равно должен открыть Claude Code и сказать «go» после уведомления — см. DEVLOG.md, если хотите узнать, почему на этом всё останавливается.

Известные ограничения

• Нет поддержки комментариев, нет привязки коммитов — эти маршруты существуют только во внутреннем API, доступном только расширениям, а не в /api/v1/*. Для добавления потребуются новые маршруты pm-system.

• Нет создания эпиков через API — эпики редки/планируются руководителем; используйте пользовательский интерфейс продукта.

• Нет загрузки вложений/встраиваний через API (чтение работает — get_task возвращает и то, и другое) — прикрепляйте ссылки Figma/скриншоты через пользовательский интерфейс продукта.

• Запросы, ограниченные репозиторием, историей и фильтром по меткам, возвращают результаты только после того, как кто-то действительно установит repositoryId/storyId/labelIds в задачах — ничего не выводится автоматически.