YouGile MCP

Русский · English · Changelog

MCP server for YouGile · MCP-сервер для YouGile

Русский

MCP-сервер, через который Claude и другие AI-ассистенты работают с YouGile вашей компании: задачами, досками, колонками, чатами, сотрудниками, стикерами. Основа — официальный REST API v2.

Возможности

• Работа с задачами по-человечески. Названия досок и колонок, имена исполнителей, номера задач и даты вместо UUID и меток времени. Перенос карточки сам проходит цепочку Workflow.
• Весь API. 65 операций в 10 доменных инструментах плюс справочный yougile_help.
• Задачи по номеру. Сквозной ID-123 или проектный DEV-12.
• Общий лимит запросов. YouGile пропускает 50 запросов в минуту на всю компанию, включая тех, кто работает в интерфейсе. Сервер держит лимит сам: один счётчик на все сессии, запущенные на компьютере. При ответе 429 все сессии ждут вместе.
• Права поверх прав YouGile. Можно ограничить сессию чтением, выбранными проектами, запретить отдельные операции, требовать подтверждения человека перед записью в проекты, которые видят клиенты.
• Безопасные повторы. При сбое сети повторяются только запросы, которые нельзя выполнить дважды по ошибке: чтение, изменение и создание с ключом идемпотентности. Ключ идемпотентности сервер добавляет сам.
• Ключ — только из переменной окружения. Он не попадает ни в файлы настроек, ни в модель. Эндпоинты входа по логину и паролю модели недоступны.

Серверная версия — подключение по адресу, без установки, вход через логин YouGile — готовится. Адрес появится здесь.

Быстрый старт

Нужен uv — он сам поставит Python.

Пока пакет не опубликован на PyPI, вместо uvx yougile-mcp пишите uvx --from git+https://github.com/indalo-tech/yougile-mcp yougile-mcp.

1. Получите ключ API

uvx yougile-mcp setup

Команда спросит логин и пароль YouGile. Они используются только для запроса к YouGile и нигде не сохраняются. Если у вас несколько компаний, выберите нужную. Если для компании уже есть ключ, команда предложит взять его: YouGile разрешает не больше 30 ключей на аккаунт. В конце она покажет ключ и готовые строки подключения.

Ключ действует с вашими правами в YouGile. Храните его как пароль.

2. Подключите

Claude Code, для всех проектов пользователя:

claude mcp add yougile --scope user -e YOUGILE_API_KEY=ваш_ключ -- uvx yougile-mcp

Claude Desktop, Cursor и другие клиенты — запись в mcpServers:

{
  "mcpServers": {
    "yougile": {
      "command": "uvx",
      "args": ["yougile-mcp"],
      "env": { "YOUGILE_API_KEY": "ваш_ключ" }
    }
  }
}

3. Проверьте

YOUGILE_API_KEY=ваш_ключ uvx yougile-mcp check

Покажет версию, пользователя и компанию, сколько проектов, досок и колонок видно, действующие права, часовой пояс и найденные файлы настроек. Проверка тратит 5 запросов.

Инструменты для задач

Принимают названия и номера, показывают имена и даты. Для повседневной работы начинайте с них.

Даты пишутся как 2026-09-30 или 30.09.2026, со временем — 2026-09-30 18:00. Дата без времени сохраняется как полночь по часовому поясу компании — так же, как в интерфейсе YouGile.

Доменные инструменты — весь API

Каждый доменный инструмент принимает operation (список допустимых значений есть в схеме) и один плоский объект params, где вместе лежат параметры пути, запроса и тела:

{ "operation": "update", "params": { "id": "ID-123", "completed": true } }

Настройки репозитория и пользователя

Сервер ищет .yougile.json вверх от текущей папки (обычно это корень репозитория) и общий файл ~/.yougile-mcp.json. Настройки репозитория перекрывают общие. Путь к файлу можно задать явно через YOUGILE_CONFIG.

{
  "project": "Разработка",
  "board": "Бэкенд",
  "role": "member",
  "projects": ["Разработка"],
  "confirm_projects": ["Клиенты"],
  "deny": ["tasks.delete", "users.*"],
  "workflows": {
    "Клиенты / Сайт": ["Очередь", "В работе", "На проверке", "Готово"]
  },
  "timezone": "Europe/Moscow",
  "instructions": "В задачах клиентских проектов пишите клиентским языком."
}

Эти права только сужают права YouGile: ключ всегда действует с правами пользователя, который его выпустил.

Как работает подтверждение. Если клиент умеет показывать запросы пользователю (MCP elicitation), человек подтверждает запись в окне клиента, и модель не может обойти этот шаг. Одно действие спрашивает подтверждение один раз, даже если делает несколько записей. Если клиент так не умеет, инструмент возвращает confirmation_required с текстом того, что будет записано. Модель должна показать его пользователю и повторить вызов с confirm=true только после его явного согласия.

Переменные окружения

Советы

• Структура компании (проекты, доски, колонки, сотрудники, стикеры) кэшируется на 5 минут — повторные вызовы не тратят лимит.
• В доменных инструментах чек-листы и стикеры при изменении задачи заменяются целиком; yougile_update_task делает это сам.
• Удалённые объекты скрыты из списков; чтобы их найти, добавьте includeDeleted: true.
• Списки отдают до 50 объектов, можно до 1000 через limit. Одним большим запросом лимит расходуется бережнее, чем многими маленькими.

Версии

• Актуальная версия — на бейдже вверху и на странице Releases; что изменилось — в CHANGELOG.md.
• Установленную версию показывают yougile-mcp --version и yougile-mcp check.
• Номера по SemVer: до 1.0 новые возможности поднимают вторую цифру, исправления — третью.
• Поставить конкретную версию: uvx --from git+https://github.com/indalo-tech/yougile-mcp@v0.2.0 yougile-mcp.

Как это устроено

Каталог операций собран из официальной спецификации YouGile (https://ru.yougile.com/api-json), её снимок лежит в пакете. Каждая операция отнесена к инструменту и уровню доступа: read, write или admin. Инструменты для задач вызывают те же операции, поэтому права и подтверждения действуют одинаково. Тесты не дадут выпустить версию, в которой новая операция API осталась без инструмента, а CI каждый раз сверяет снимок с опубликованной спецификацией.

Разработка

uv sync
uv run pytest
uv run ruff check src tests scripts
uv run --no-project python scripts/sync_spec.py   # обновить снимок спецификации

Запуск по HTTP для отладки: uv run yougile-mcp serve --transport http --port 8000.

Выпуск версии. Поменяйте __version__ в src/yougile_mcp/__init__.py, перенесите записи из [Unreleased] в новый раздел CHANGELOG.md (на двух языках), закоммитьте и отправьте тег: git tag v0.3.0 && git push origin v0.3.0. Workflow проверит, что тег совпадает с версией, прогонит тесты, соберёт пакет и опубликует GitHub Release с описанием из CHANGELOG.md, а если включена публикация на PyPI — и пакет на PyPI.

Публикация на PyPI идёт через Trusted Publishing, без токенов. Один раз: на pypi.org в Account settings → Publishing добавьте publisher для GitHub — проект yougile-mcp, владелец indalo-tech, репозиторий yougile-mcp, workflow release.yml, environment pypi. Затем включите шаг: gh variable set PUBLISH_PYPI --body true -R indalo-tech/yougile-mcp. Уже выпущенную версию можно отправить на PyPI через Actions → Release → Run workflow с её тегом.

Лицензия

MIT

English

An MCP server that lets Claude and other AI assistants work with your company's YouGile: tasks, boards, columns, chats, employees and stickers, on top of the official REST API v2.

Features

• Task work in human terms. Board and column names, assignee names, task numbers and dates instead of UUIDs and timestamps. Moving a card walks the Workflow chain by itself.
• The whole API. 65 operations in 10 domain tools, plus the yougile_help reference tool.
• Tasks by number. The company-wide ID-123 or the project one like DEV-12.
• A shared rate limit. YouGile allows 50 requests per minute per company, people in the web UI included. The server enforces the limit itself with one counter shared by every session running on the machine, and all of them back off together on HTTP 429.
• Permissions on top of YouGile's. Restrict a session to reading, to selected projects, deny specific operations, or require a human to confirm writes into projects your clients can see.
• Safe retries. After a network failure only requests that cannot be applied twice are retried: reads, updates, and creates carrying an idempotency key, which the server adds automatically.
• The key comes from the environment only. It never goes into config files or to the model. Login-and-password endpoints are not exposed to the model.

Hosted version — connect by URL, nothing to install, sign in with your YouGile login — is in the works. The address will appear here.

Quick start

You need uv; it installs Python for you.

Until the package is on PyPI, use uvx --from git+https://github.com/indalo-tech/yougile-mcp yougile-mcp instead of uvx yougile-mcp.

1. Get an API key

uvx yougile-mcp setup

It asks for your YouGile login and password. They are only used for the request to YouGile and are never stored. If you belong to several companies, pick one. If the company already has a key, the command offers to reuse it: YouGile allows at most 30 keys per account. At the end it prints the key and ready-to-paste connection snippets.

The key acts with your YouGile rights. Keep it as secret as a password.

2. Connect

Claude Code, for all projects of the user:

claude mcp add yougile --scope user -e YOUGILE_API_KEY=your_key -- uvx yougile-mcp

Claude Desktop, Cursor and other clients — an mcpServers entry:

{
  "mcpServers": {
    "yougile": {
      "command": "uvx",
      "args": ["yougile-mcp"],
      "env": { "YOUGILE_API_KEY": "your_key" }
    }
  }
}

3. Check

YOUGILE_API_KEY=your_key uvx yougile-mcp check

Shows the version, user and company, how many projects, boards and columns are visible, the effective permissions, the time zone and the config files found. The check costs 5 requests.

Task tools

They take names and numbers and show names and dates. Start with them for everyday work.

Dates are written as 2026-09-30 or 30.09.2026, with time as 2026-09-30 18:00. A date without time is stored as midnight in the company time zone, just as the YouGile UI does.

Domain tools — the whole API

Every domain tool takes an operation (the allowed values are in its schema) and one flat params object that holds path, query and body parameters together:

{ "operation": "update", "params": { "id": "ID-123", "completed": true } }

Repository and user config

The server looks for .yougile.json in the current directory and its parents (usually the repository root), and for a shared ~/.yougile-mcp.json. Repository settings override the shared ones. YOUGILE_CONFIG points to a file explicitly.

{
  "project": "Development",
  "board": "Backend",
  "role": "member",
  "projects": ["Development"],
  "confirm_projects": ["Clients"],
  "deny": ["tasks.delete", "users.*"],
  "workflows": {
    "Clients / Website": ["Queue", "In progress", "Review", "Done"]
  },
  "timezone": "Europe/Moscow",
  "instructions": "Use client-friendly language in client projects."
}

These permissions only narrow YouGile's own: the key always acts with the rights of the user who issued it.

How confirmation works. If the client can prompt the user (MCP elicitation), the person confirms the write in the client's UI and the model cannot skip that step. One action asks once, even when it performs several writes. Otherwise the tool returns confirmation_required with exactly what would be written; the model has to show it to the user and repeat the call with confirm=true only after explicit consent.

Environment variables

Tips

• The company structure (projects, boards, columns, employees, stickers) is cached for 5 minutes, so repeated calls do not spend the limit.
• In domain tools checklists and stickers are replaced as a whole on update; yougile_update_task handles that for you.
• Deleted objects are hidden from lists; add includeDeleted: true to find them.
• Lists return up to 50 objects, up to 1000 with limit. One large request spends the limit more wisely than many small ones.

Versions

• The current version is on the badge above and on the Releases page; what changed is in CHANGELOG.md.
• yougile-mcp --version and yougile-mcp check show the installed version.
• Numbers follow SemVer: before 1.0, new features bump the second number and fixes the third.
• Install a specific version: uvx --from git+https://github.com/indalo-tech/yougile-mcp@v0.2.0 yougile-mcp.

How it works

The operation catalog is built from YouGile's official spec (https://ru.yougile.com/api-json); a snapshot ships with the package. Each operation is mapped to a tool and an access level: read, write or admin. Task tools call the same operations, so permissions and confirmations apply identically. Tests refuse a release in which a new API operation is left without a tool, and CI compares the snapshot with the published spec on every run.

Development

uv sync
uv run pytest
uv run ruff check src tests scripts
uv run --no-project python scripts/sync_spec.py   # refresh the spec snapshot

HTTP transport for debugging: uv run yougile-mcp serve --transport http --port 8000.

Releasing. Bump __version__ in src/yougile_mcp/__init__.py, move the [Unreleased] entries into a new CHANGELOG.md section (in both languages), commit and push a tag: git tag v0.3.0 && git push origin v0.3.0. The workflow checks that the tag matches the version, runs the tests, builds the package and publishes a GitHub Release with the notes from CHANGELOG.md, and the package on PyPI when PyPI publishing is enabled.

PyPI publishing uses Trusted Publishing, no tokens. Once: on pypi.org under Account settings → Publishing add a GitHub publisher — project yougile-mcp, owner indalo-tech, repository yougile-mcp, workflow release.yml, environment pypi. Then enable the step: gh variable set PUBLISH_PYPI --body true -R indalo-tech/yougile-mcp. A version that is already released can be sent to PyPI via Actions → Release → Run workflow with its tag.

License

MIT