YouGile MCP

English | Русский

An unofficial, security-focused Model Context Protocol server for the YouGile REST API. It provides a named, policy-controlled toolset for YouGile rather than a generic HTTP proxy.

YouGile and its trademarks belong to their respective owners. This project is not affiliated with or endorsed by YouGile.

Highlights

• Local stdio and bearer-protected Streamable HTTP transports.

• Separate profiles, scopes, policies, caches, rate limits and audit records for each tenant.

• Read-only access by default, with an optional direct-write profile for tasks, chats, projects and boards.

• Secrets stay in environment variables, protected files or HashiCorp Vault; they are never accepted through MCP tools.

• OpenAPI validation of mutation payloads, response-size limits, redaction and untrusted-content marking.

• Optional inbound webhooks with tenant-bound secrets, replay protection, retention and storage limits.

• Upload validation by path allowlist, size, MIME type and file signature.

• A local browser setup assistant for obtaining an organisation ID, creating an API key through official YouGile methods, and generating a key-free configuration.

Requirements

• Node.js 20 or later and pnpm 11 for the manual path below

• A YouGile account that may create an API key; use the local assistant below if you do not yet have one

One-command local bootstrap

From a source checkout, use the bootstrap script instead of installing Node.js or pnpm globally:

# macOS / Linux
sh scripts/bootstrap.sh

# Windows PowerShell
.\scripts\bootstrap.ps1

It uses an already-installed Node.js 20+ when available. Otherwise, it downloads the pinned Node.js 24.18.0 LTS archive from official nodejs.org, verifies its SHA-256, and keeps it inside the ignored .tools/ directory in this project. It then fetches pnpm 11.9.0 and the locked project dependencies from the public official npm registry, builds the project and starts yougile-mcp setup.

The script needs neither administrator privileges nor a global Node.js/pnpm installation. It does not ask for or transmit a YouGile login, password, API key or organisation data. Its only configured download origins are nodejs.org and registry.npmjs.org; normal HTTPS transport metadata, such as an IP address, reaches those hosts. After it starts, the setup assistant follows the local-only data flow described below. If a Windows execution policy blocks the local script, run powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1; this changes policy only for that launched process.

Quick start

cp config.example.yaml config.local.yaml
export YOUGILE_ACME_API_KEY='replace-me'
export YOUGILE_ACME_WRITER_API_KEY='replace-me'
pnpm install --frozen-lockfile
pnpm run build
node dist/cli.js config validate --config config.local.yaml
node dist/cli.js --config config.local.yaml --transport stdio

Do not put an API key in YAML, desktop-client configuration, prompts or command-line arguments. Configure it only through a secret provider. The example configuration uses environment variables; protected files and HashiCorp Vault are supported too.

Desktop client configuration

{
  "mcpServers": {
    "yougile": {
      "command": "/absolute/path/to/yougile-mcp",
      "args": [
        "--config",
        "/absolute/path/to/config.local.yaml",
        "--transport",
        "stdio"
      ]
    }
  }
}

Keep the default profile read-only. If you configure multiple profiles, a write must name its profile explicitly.

Local setup assistant

Run the assistant on macOS, Linux or Windows after building the project:

pnpm run build
node dist/cli.js setup

It prints a loopback URL on 127.0.0.1. Step 3 is intentionally sequential: choose the access level, press Create configuration, and only then choose one start mode. The assistant writes config.local.yaml into the directory where setup was started, without an API key. Terminal for this session opens a new Terminal/PowerShell window and starts MCP there; use it only when an MCP client connects through that terminal. Codex or Claude Desktop needs no Terminal: select the apps, let the assistant add their local MCP entry, then restart them so they launch MCP themselves. Local service at sign-in is for an always-available loopback HTTP endpoint. The default is tasks and chats; write-capable generated profiles send changes directly to YouGile. The assistant never replaces an existing config.local.yaml silently. A quiet terminal after the start command is normal for a stdio MCP server: it is waiting for an MCP client.

Automatic start: Codex, Claude Desktop or a local service

After configuration, the same final screen offers two independent opt-in choices:

• Codex and/or Claude Desktop: the assistant adds only the yougile stdio entry to the selected desktop-client configuration. The client starts MCP when it starts; there is no permanently running process. Restart the selected application afterwards. Claude’s JSON configuration is written to its standard per-user location on macOS and Windows; on Linux it uses the per-user XDG configuration location used by the Claude Desktop beta.

• Local background service: the assistant enables a bearer-protected Streamable HTTP listener only on 127.0.0.1:8765/mcp, then starts it at the next user sign-in and now. It installs a LaunchAgent on macOS, a systemd --user unit on Linux (or XDG autostart where a user systemd service is unavailable), or a Task Scheduler task on Windows. It never creates a public listener or a cloud service. Configure an HTTP-capable MCP client separately with the local endpoint and its bearer credential.

Both choices show a separate confirmation because they must survive a restart. Only after that confirmation, the assistant writes the YouGile key — and, for the HTTP service, a generated bearer secret — to the current user’s protected local secrets.json file. On macOS/Linux the directory is mode 0700 and the file mode 0600; on Windows the file ACL is restricted to the current user. Neither secret is placed in config.local.yaml, Codex configuration or Claude configuration. See the complete bilingual setup-assistant guide.

There is no external backend, analytics, telemetry, account, database or proxy in the running assistant. The browser talks only to the local process; that process makes only these documented requests to the fixed official cloud API https://yougile.com/api-v2:

While either official request is in progress, the page shows its exact method, route, redacted request body and redacted response body. Passwords, API keys, tokens, credentials and login addresses are masked before they reach that UI block; the trace is held only in the current page memory and is not logged or stored. By default, passwords and API keys are never written to a file, log, URL, cookie, localStorage or sessionStorage. Organisation data is written only to the explicit config.local.yaml setup output. The explicit automatic-start choices are the sole exception: after a separate confirmation, they store the API key locally in the protected secret file described above. Password fields are cleared after each request. See the complete bilingual setup-assistant guide, including the code/test evidence and self-hosted YouGile guidance.

Streamable HTTP

Enable transports.streamable_http, set a long bearer secret and bind it to the permitted profiles. Deploy it behind TLS and a reverse proxy.

export YOUGILE_MCP_HTTP_BEARER='a-long-random-secret'
node dist/cli.js --config /etc/yougile-mcp/config.yaml --transport streamable-http

Available endpoints:

• POST, GET, DELETE /mcp — authenticated Streamable HTTP MCP.

• GET /health — unauthenticated health check.

• GET /metrics — authenticated Prometheus metrics.

• POST /webhooks/yougile/{tenant} — optional tenant-authenticated webhook receiver.

For a container deployment, see the Dockerfile and the hardened Kubernetes example in deploy/kubernetes.

Development and release checks

pnpm run check
pnpm run build
pnpm run openapi:check
pnpm run audit
pnpm run sbom
node dist/cli.js config validate --config config.example.yaml
pnpm pack --dry-run --json

The CI workflow checks Node.js 20 and 22, runs the test suite and build, validates the example configuration and OpenAPI contract, generates an SBOM, checks the package contents and builds the container image.

Documentation

• Example configuration

• Architecture and threat model

• Migration guide for unsafe integrations

• Security policy

License

MIT. Before publishing, make sure the copyright holder named in LICENSE is the person or organisation that owns the code.

Русская версия

Неофициальный MCP-сервер для YouGile REST API с упором на безопасность. Вместо универсального HTTP-прокси он предоставляет именованный набор инструментов с политиками доступа.

YouGile и связанные товарные знаки принадлежат их правообладателям. Проект не аффилирован с YouGile и не одобрен компанией.

Возможности

• Локальный stdio и Streamable HTTP с Bearer-аутентификацией.

• Раздельные профили, области доступа, политики, кэш, лимиты и аудит для каждого тенанта.

• Доступ только на чтение по умолчанию и опциональный профиль с прямой записью для задач, чатов, проектов и досок.

• Секреты хранятся в переменных окружения, защищённых файлах или HashiCorp Vault; MCP-инструменты их не принимают.

• Проверка mutation-пейлоадов по OpenAPI, ограничение размера ответов, редактирование секретов и маркировка недоверенного текста.

• Опциональные входящие webhook’и с секретом на тенант, защитой от повторов, сроком хранения и лимитами объёма.

• Проверка загружаемых файлов по разрешённому пути, размеру, MIME-типу и сигнатуре файла.

• Локальный браузерный мастер: получить ID организации, выпустить ключ официальными методами YouGile и создать конфиг без ключа.

Требования

• Node.js 20 или новее и pnpm 11 для ручного запуска ниже

• Учётная запись YouGile, которой разрешено создавать API-ключи; если ключа ещё нет, используйте локальный мастер ниже

Локальный запуск одной командой

В клоне репозитория можно не ставить Node.js и pnpm глобально, а выполнить bootstrap-скрипт:

# macOS / Linux
sh scripts/bootstrap.sh

# Windows PowerShell
.\scripts\bootstrap.ps1

Если Node.js 20+ уже есть, скрипт использует его. Иначе он скачает закреплённый архив Node.js 24.18.0 LTS с официального nodejs.org, проверит SHA-256 и сохранит runtime только в игнорируемой папке проекта .tools/. Затем скрипт получит pnpm 11.9.0 и зафиксированные в lockfile зависимости из публичного официального npm registry, соберёт проект и запустит yougile-mcp setup.

Права администратора и глобальная установка Node.js/pnpm не нужны. Скрипт не запрашивает и не передаёт логин, пароль, API-ключ или данные организации YouGile. Его единственные явно заданные адреса загрузки — nodejs.org и registry.npmjs.org; обычные HTTPS-метаданные, например IP-адрес, дойдут до этих хостов. После запуска мастер работает по описанной ниже локальной схеме. Если Windows запретит запуск локального файла политикой исполнения, выполните powershell -ExecutionPolicy Bypass -File .\scripts\bootstrap.ps1: политика изменится только для запущенного процесса.

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

cp config.example.yaml config.local.yaml
export YOUGILE_ACME_API_KEY='replace-me'
export YOUGILE_ACME_WRITER_API_KEY='replace-me'
pnpm install --frozen-lockfile
pnpm run build
node dist/cli.js config validate --config config.local.yaml
node dist/cli.js --config config.local.yaml --transport stdio

Не храните API-ключ в YAML, конфигурации десктопного клиента, промптах или аргументах командной строки. Используйте только провайдер секретов. В примере применяется переменная окружения; также поддерживаются защищённые файлы и HashiCorp Vault.

Конфигурация десктопного клиента

{
  "mcpServers": {
    "yougile": {
      "command": "/absolute/path/to/yougile-mcp",
      "args": [
        "--config",
        "/absolute/path/to/config.local.yaml",
        "--transport",
        "stdio"
      ]
    }
  }
}

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

Локальный мастер настройки

После сборки запустите мастер одинаковой командой на macOS, Linux и Windows:

pnpm run build
node dist/cli.js setup

Команда напечатает loopback-адрес на 127.0.0.1. Третий шаг намеренно разбит на последовательность: выберите уровень доступа, нажмите «Создать конфигурацию», и только потом выберите один способ запуска. Мастер создаст config.local.yaml в папке, из которой был запущен setup, без API-ключа. «Terminal для этой сессии» откроет новое окно Terminal/PowerShell и запустит MCP там; это нужно только когда клиент подключается через этот терминал. Для Codex или Claude Desktop Terminal не нужен: выберите приложения, мастер добавит локальную MCP-запись, затем перезапустите приложения — они сами запустят MCP. «Локальный сервис при входе» нужен для постоянно доступного loopback HTTP endpoint. По умолчанию выбран режим «Задачи и чаты»; профили с изменениями сразу отправляют их в YouGile. Уже существующий config.local.yaml мастер никогда не заменяет молча. Если терминал после запуска выглядит тихим, это нормально для stdio MCP-сервера: он ждёт подключения клиента.

Автозапуск: Codex, Claude Desktop или локальный сервис

После настройки тот же финальный экран предлагает два независимых варианта по выбору:

• Codex и/или Claude Desktop: мастер добавляет только stdio-запись yougile в конфигурацию выбранного десктопного клиента. Клиент запускает MCP при своём старте; постоянно работающего процесса не будет. Затем перезапустите выбранное приложение. JSON-конфигурация Claude записывается в стандартное пользовательское место на macOS и Windows; на Linux используется XDG-путь пользователя, который применяет beta-версия Claude Desktop.

• Локальный фоновый сервис: мастер включает Bearer-защищённый Streamable HTTP listener только на 127.0.0.1:8765/mcp, запускает его сейчас и при следующем входе пользователя. На macOS ставится LaunchAgent, на Linux — systemd --user (либо XDG-autostart, если пользовательский systemd недоступен), на Windows — задача Планировщика. Публичного listener’а и облачного сервиса не появляется. HTTP-совместимый MCP-клиент настраивается отдельно на локальный endpoint и Bearer-учётные данные.

Оба варианта показывают отдельное подтверждение, потому что должны пережить перезагрузку. Только после него мастер записывает ключ YouGile — а для HTTP-сервиса ещё и сгенерированный Bearer-секрет — в защищённый локальный secrets.json текущего пользователя. На macOS/Linux каталог имеет права 0700, файл — 0600; на Windows ACL файла ограничивается текущим пользователем. Ни один секрет не попадает в config.local.yaml, конфигурацию Codex или Claude. Полная двуязычная инструкция — в руководстве мастера.

В работающем мастере нет внешнего бэкенда, аналитики, телеметрии, аккаунта, базы данных или прокси. Браузер общается только с локальным процессом, а тот выполняет только эти документированные запросы к фиксированному официальному cloud API https://yougile.com/api-v2:

Во время каждого официального запроса страница показывает точный метод, маршрут, замаскированное тело запроса и замаскированное тело ответа. Пароли, API-ключи, токены, учётные данные и адреса логина маскируются до попадания в этот блок; след хранится только в памяти текущей страницы и не логируется и не сохраняется. По умолчанию логин, пароль и API-ключ не записываются в файл, лог, URL, cookie, localStorage или sessionStorage. Данные организации попадают только в явно созданный config.local.yaml. Единственное исключение — явно выбранный автозапуск: после отдельного подтверждения API-ключ сохраняется локально в описанный выше защищённый файл секретов. Поля с паролями очищаются после каждого запроса. Полное двуязычное руководство, доказательство через код и тест, а также правила для self-hosted YouGile — в документации мастера.

Streamable HTTP

Включите transports.streamable_http, задайте длинный Bearer-токен и ограничьте его разрешёнными профилями. Разворачивайте сервер за TLS и reverse proxy.

export YOUGILE_MCP_HTTP_BEARER='a-long-random-secret'
node dist/cli.js --config /etc/yougile-mcp/config.yaml --transport streamable-http

Доступные конечные точки:

• POST, GET, DELETE /mcp — аутентифицированный Streamable HTTP MCP.

• GET /health — неаутентифицированная проверка состояния.

• GET /metrics — Prometheus-метрики с аутентификацией.

• POST /webhooks/yougile/{tenant} — опциональный webhook-приёмник с аутентификацией тенанта.

Для контейнерного развёртывания смотрите Dockerfile и пример защищённого Kubernetes-развёртывания в deploy/kubernetes.

Проверки перед релизом

pnpm run check
pnpm run build
pnpm run openapi:check
pnpm run audit
pnpm run sbom
node dist/cli.js config validate --config config.example.yaml
pnpm pack --dry-run --json

CI проверяет Node.js 20 и 22, запускает тесты и сборку, валидирует пример конфигурации и OpenAPI-контракт, генерирует SBOM, проверяет состав npm-пакета и собирает Docker-образ.

Документация

• Пример конфигурации

• Архитектура и модель угроз

• Миграция с небезопасных интеграций

• Политика безопасности

Лицензия

MIT. Перед публикацией убедитесь, что в LICENSE указан человек или организация, которым принадлежат права на код.