conduit-mcp

удалённый MCP-сервер, который объединяет несколько SaaS-интеграций за тремя мета-инструментами. вместо того чтобы выставлять сотню с лишним инструментов каждому клиенту, сервер предоставляет list_integrations, find_tools и invoke_tool: клиенты ищут в каталоге по описанию задачи, получают подходящие схемы инструментов и вызывают их по точному имени. админ-портал управляет плагинами, ключами API, ролями и использованием.

Встроенные интеграции: HaloPSA, Hudu, CIPP, NinjaRMM, QuickBooks Online.

структура

Related MCP server: MCPHub

как запустить

требуется node >= 22 и pnpm через corepack (версия зафиксирована в package.json в поле packageManager).

corepack enable
scripts/setup.ps1    # or setup.sh: frozen-lockfile install + full workspace build
pnpm dev

pnpm dev запускает всё в одном терминале через concurrently, вывод с префиксом для каждого процесса: azurite (хранилище таблиц в памяти), watcher'ы tsc для sdk и сервера, api-сервер и next dev. ctrl+C останавливает всё. pnpm serve пропускает watcher'ы и обслуживает только предварительно собранные api и статический веб-экспорт.

• портал: http://localhost:3000 (next dev, проксирует api-запросы на :4000)

• api и mcp: http://localhost:4000 (/healthz, /mcp)

Без конфигурации сервер запускается в не настроенном состоянии, и портал показывает мастер начальной настройки, который проводит через настройку entra. Чтобы пропустить его, скопируйте .dev.env.example в .dev.env и заранее заполните ENTRA_TENANT_ID / ENTRA_CLIENT_ID / BOOTSTRAP_ADMIN_OID; pnpm dev загрузит их при старте.

Проверки по всему репозиторию: pnpm lint, pnpm typecheck, pnpm test, pnpm build.

как это работает

интерфейс mcp. /mcp говорит по streamable http. запросы аутентифицируются с помощью bearer-токена entra или ключа API conduit. для клиентов, которые поддерживают только oauth, сервер проксирует авторизацию на entra (метаданные сервера авторизации + динамическая регистрация клиента). сессии и потоки событий сохраняются в табличном хранилище, поэтому потоки переживают переподключения.

каталог + мета-инструменты. каждый инструмент плагина индексируется в поисковый каталог (minisearch). find_tools возвращает подходящие схемы инструментов, invoke_tool выполняет по точному имени и записывает использование. разрешения фильтруют и результаты поиска, и вызовы, поэтому субъект видит только те инструменты, которые разрешены его грантами.

плагины. плагин — это исходная директория с манифестом conduit.plugin.json (id, точка входа, имена секретов, ui настроек портала, публичные маршруты). загрузчик собирает точку входа с помощью esbuild во время загрузки против sdk хоста, регистрирует его инструменты в каталоге и монтирует любые маршруты портала в /api/plugins/:pluginId. пакеты в packages/plugins подключаются автоматически; дополнительные можно установить из git через портал. docs/writing-plugins.md описывает создание плагина на основе sdk и установку собственного.

модель аутентификации. субъекты — это пользователи entra или ключи API. роли несут гранты для каждой интеграции (только чтение или полный доступ, вплоть до отдельных инструментов) и разрешаются для каждого запроса; доступ к порталу — отдельная поверхность, роли портала никогда не расширяют доступ к инструментам mcp. BOOTSTRAP_ADMIN_OID задаёт первого администратора.

хранилище и секреты. azure table storage хранит всё состояние (конфигурация, реестр плагинов, роли, ключи API, использование, mcp-сессии); локально его заменяет azurite. секреты попадают в key vault, когда задан AZURE_KEYVAULT_URL, иначе — в обычные переменные окружения.

портал. статический экспорт next.js, который в продакшене обслуживает сам api-сервер (apps/web/out); в локальном режиме наблюдения вместо этого запускается next dev.

развертывание

Dockerfile собирает самодостаточный образ сервера с встроенным веб-экспортом. ci (.github/workflows/deploy.yml) запускает тесты, затем собирает и пушит ghcr.io/<owner>/<repo>:<sha> при каждом пуше в main. только при первой публикации: пакет по умолчанию приватный, переключите его на публичный в настройках репозитория > packages, чтобы app service мог его забрать без учётных данных реестра.

infra/main.bicep (область подписки) создаёт группу ресурсов, app service, хранилище и key vault. регистрация приложения entra происходит одним из двух способов:

мастер настройки, один запуск bicep. разверните с пустыми параметрами entra и откройте портал: мастер начальной настройки выполнит вход через device code, создаст регистрацию приложения через graph и запишет tenant/client id в конфигурационное хранилище. /api/setup/* не требует аутентификации, пока настройка не завершена, и первый вошедший становится администратором (доверие при первом использовании); после завершения настройки эти конечные точки возвращают 404.

скриптовый, два запуска bicep. нет открытого окна настройки, сервер запускается уже настроенным. скрипту entra нужны выходные данные первого запуска (url webapp для redirect uri, имя key vault для секрета клиента), а bicep сам не может создавать регистрации приложений, поэтому нужен второй запуск, чтобы записать id как настройки приложения.

# 1. infra, entra params blank. operatorObjectId grants the KV write step 2 needs
az deployment sub create -l eastus2 -f infra/main.bicep \
  -p image=ghcr.io/<owner>/conduit-mcp:<sha> bootstrapAdminOid=<your-oid> operatorObjectId=<your-oid>

# 2. app registration + client secret into key vault
#    PS7, az login as a user with Application.ReadWrite.OwnedBy, -DryRun to preview
./infra/scripts/setup-entra-app.ps1 -DisplayName "conduit-mcp" \
  -ProdUrl <webAppUrl output> -KeyVaultName <keyVaultName output>

# 3. same deployment plus the ids the script printed
az deployment sub create -l eastus2 -f infra/main.bicep \
  -p image=ghcr.io/<owner>/conduit-mcp:<sha> bootstrapAdminOid=<your-oid> operatorObjectId=<your-oid> \
     entraTenantId=<tenant-id> entraClientId=<client-id>

изменение настроек приложения перезапускает контейнер; при загрузке id записываются в хранилище конфигурации (заполняются только пустые поля, put конфигурации остаётся авторитетным).

непрерывное развертывание, по желанию. создайте oidc-федерацию для workflow, задайте секреты AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID и переменные AZURE_WEBAPP_NAME / AZURE_RESOURCE_GROUP, затем установите переменную репозитория AZURE_DEPLOY=true. пуши в main после этого перенаправляют webapp на только что запушенный образ.

обновления через портал. в настройках видно, отличается ли образ в реестре от запущенной сборки (ci встраивает git sha в образ), и можно перезапустить приложение, чтобы подтянуть его; перезапуск использует пользовательскую роль только для перезапуска, которую bicep выдаёт управляемому удостоверению, поэтому развёртывания, созданные до появления этой роли, требуют повторного запуска bicep, чтобы кнопка заработала.