Yougile Mcp

YouGile MCP

[English](#yougile-mcp) | [Русский](#русская-версия)

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:

~~~sh

macOS / Linux

sh scripts/bootstrap.sh ~~~

~~~powershell

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

~~~sh cp config.example.yaml config.local.yaml export YOUGILEACMEAPIKEY='replace-me' export YOUGILEACMEWRITERAPI_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

~~~json { "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:

~~~sh 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](docs/setup-assistant.md#automatic-start-and-desktop-clients).

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:

| Method | Purpose | | --- | --- | | POST /api-v2/auth/companies | List organisations for the supplied account. | | POST /api-v2/auth/keys | Create a key for the selected organisation. |

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](docs/setup-assistant.md), 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.

~~~sh export YOUGILEMCPHTTP_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](deploy/kubernetes).

Development and release checks

~~~sh 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](config.example.yaml)
• [Architecture and threat model](docs/architecture-and-threat-model.md)
• [Migration guide for unsafe integrations](docs/migration-from-unsafe-mcp.md)
• [Security policy](SECURITY.md)

License

[MIT](LICENSE). 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-скрипт:

~~~sh

macOS / Linux

sh scripts/bootstrap.sh ~~~

~~~powershell

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: политика изменится только для запущенного процесса.

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

~~~sh cp config.example.yaml config.local.yaml export YOUGILEACMEAPIKEY='replace-me' export YOUGILEACMEWRITERAPI_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.

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

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

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

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

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

~~~sh 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. Полная двуязычная инструкция — в [руководстве мастера](docs/setup-assistant.md#автозапуск-и-десктоп-клиенты).

В работающем мастере нет внешнего бэкенда, аналитики, телеметрии, аккаунта, базы данных или прокси. Браузер общается только с локальным процессом, а тот выполняет только эти документированные запросы к фиксиро

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: cvtmysxul
• Source: cvtmysxul/yougile-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.