conduit-mcp

여러 SaaS 통합을 세 가지 메타 도구 뒤에서 중개하는 원격 mcp 서버입니다. 모든 클라이언트에게 100개가 넘는 도구를 노출하는 대신, 서버는 list_integrations, find_tools, invoke_tool을 노출합니다. 클라이언트는 작업 설명으로 카탈로그를 검색하고, 일치하는 도구 스키마를 돌려받은 다음 정확한 이름으로 호출합니다. 관리자 포털은 플러그인, api 키, 역할, 사용량을 관리합니다.

번들 통합: HaloPSA, Hudu, CIPP, NinjaRMM, QuickBooks Online.

구성

Related MCP server: MCPHub

실행 방법

node >= 22와 corepack을 통한 pnpm이 필요합니다 (package.json의 packageManager에 버전 고정).

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

pnpm dev는 concurrently를 통해 모든 것을 하나의 터미널에서 실행하며, 출력은 프로세스별로 접두사가 붙습니다: azurite(인메모리 테이블 스토리지), sdk + 서버 tsc 워처, api 서버, next dev. ctrl+C로 모두 중지됩니다. pnpm serve는 워처를 건너뛰고 미리 빌드된 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를 사용합니다. 요청은 entra bearer 토큰 또는 conduit api 키로 인증됩니다. oauth만 지원하는 클라이언트를 위해 서버는 entra에 대한 인증 프록시를 수행합니다(권한 부여 서버 메타데이터 + 동적 클라이언트 등록). 세션과 이벤트 스트림은 테이블 스토리지에 유지되므로, 스트림은 재연결에도 유지됩니다.

카탈로그 + 메타 도구. 모든 플러그인 도구는 검색 가능한 카탈로그(minisearch)에 인덱싱됩니다. find_tools는 일치하는 도구 스키마를 반환하고, invoke_tool은 정확한 이름으로 실행하며 사용량을 기록합니다. 권한은 검색 결과와 호출을 모두 필터링하므로, 주체는 자신에게 부여된 권한이 허용하는 도구만 볼 수 있습니다.

플러그인. 플러그인은 conduit.plugin.json 매니페스트(id, 엔트리, 시크릿 이름, 포털 설정 ui, 공개 라우트)를 가진 소스 디렉터리입니다. 로더는 호스트의 sdk를 기준으로 esbuild로 엔트리를 로드 시 번들링하고, 해당 도구를 카탈로그에 등록하며, /api/plugins/:pluginId 아래에 포털 라우트를 마운트합니다. packages/plugins의 패키지는 자동으로 시드되며, 포털을 통해 git에서 추가로 설치할 수 있습니다. docs/writing-plugins.md는 sdk에 맞춰 플러그인을 작성하고 사용자 정의 플러그인을 설치하는 방법을 다룹니다.

인증 모델. 주체는 entra 사용자 또는 api 키입니다. 역할은 통합별 권한(읽기 전용 또는 전체, 개별 도구 단위까지)을 지니며 요청별로 확인됩니다. 포털 접근은 별도의 표면이며, 포털 역할은 mcp 도구 접근을 넓히지 않습니다. BOOTSTRAP_ADMIN_OID가 첫 관리자를 시드합니다.

스토리지 + 시크릿. azure table storage는 모든 상태(구성, 플러그인 레지스트리, 역할, api 키, 사용량, mcp 세션)를 보관합니다. 로컬에서는 azurite가 대신합니다. 시크릿은 AZURE_KEYVAULT_URL이 설정되면 key vault로 이동하고, 그렇지 않으면 일반 환경 변수에 저장됩니다.

포털. next.js 정적 내보내기로, 프로덕션에서는 api 서버 자체가 제공합니다(apps/web/out). 로컬 watch 모드에서는 대신 next dev를 실행합니다.

배포

Dockerfile은 웹 내보내기가 포함된 자립형 서버 이미지를 빌드합니다. ci(.github/workflows/deploy.yml)는 테스트를 수행한 후, main에 푸시할 때마다 ghcr.io/<owner>/<repo>:<sha>를 빌드하고 푸시합니다. 최초 게시 시에만 해당합니다: 패키지는 기본적으로 private이므로, 저장소 설정 > packages에서 public으로 전환하면 app service가 레지스트리 자격 증명 없이 가져올 수 있습니다.

infra/main.bicep(구독 범위)은 리소스 그룹, app service, storage, key vault를 프로비저닝합니다. entra 앱 등록은 다음 두 가지 방법 중 하나로 수행됩니다.

설정 마법사, bicep 1회 실행. entra 매개변수를 비워 둔 채 배포하고 포털을 엽니다. 부트스트랩 마법사는 device code로 로그인시키고, graph를 통해 앱 등록을 생성하며, tenant/client id를 구성 스토리지에 기록합니다. /api/setup/*는 설정이 완료될 때까지 인증을 요구하지 않으며, 첫 번째 로그인자가 관리자가 됩니다(trust-on-first-use). 이후 설정 게이트는 해당 엔드포인트에 404를 반환합니다.

스크립트 방식, bicep 2회 실행. 설정 창을 열지 않고, 서버는 이미 구성된 상태로 부팅됩니다. entra 스크립트는 1차 실행의 출력물(리디렉션 uri용 webapp url, 클라이언트 시크릿용 key vault 이름)이 필요하며, bicep는 자체적으로 앱 등록을 만들 수 없으므로, id를 앱 설정으로 저장하기 위해 2차 실행이 필요합니다.

# 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가 구성 저장소에 시드됩니다(빈 필드만 채우며, config put이 최종 권위를 유지합니다).

지속적 배포, 옵트인. 워크플로우용 oidc 페더레이션을 만들고, 시크릿 AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID와 변수 AZURE_WEBAPP_NAME / AZURE_RESOURCE_GROUP을 설정한 다음, 저장소 변수 AZURE_DEPLOY=true를 설정합니다. 그러면 main 푸시 시 webapp이 방금 푸시된 이미지를 가리키도록 다시 지정됩니다.

포털 내 업데이트. 설정에서는 레지스트리 이미지가 실행 중인 빌드와 다른지 표시하며(ci는 git sha를 이미지에 포함), 앱을 다시 시작해 해당 이미지를 가져올 수 있습니다. 이 재시작은 bicep가 관리 ID에 부여한 재시작 전용 사용자 지정 역할을 사용하므로, 해당 역할이 생기기 전에 생성된 배포는 버튼이 작동하려면 bicep를 다시 실행해야 합니다.