conduit-mcp

远程 MCP 服务器，通过三个元工具为多个 SaaS 集成提供前端。服务器不会向每个客户端暴露一百多个工具，而是暴露 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 + server 的 tsc 监视器、API 服务器和 next dev。按 ctrl+C 可全部停止。pnpm serve 跳过监视器，仅提供预构建的 API 和静态 Web 导出。

• 门户：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 使用可流式 HTTP。请求通过 entra 不记名令牌或 conduit API 密钥进行身份验证。对于仅支持 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 表存储保存所有状态（配置、插件注册表、角色、API 密钥、用量、MCP 会话）；azurite 在本地模拟。当设置 AZURE_KEYVAULT_URL 时，密钥进入密钥保管库，否则使用普通环境变量。

门户。 next.js 静态导出，在生产环境中由 API 服务器本身提供（apps/web/out）；本地监视模式改为运行 next dev。

部署

Dockerfile 构建一个自包含的服务器镜像，其中包含 Web 导出。CI（.github/workflows/deploy.yml）在每次推送到 main 时测试，然后构建并推送 ghcr.io/<owner>/<repo>:<sha>。仅首次发布时：包默认为私有，请在仓库设置 > 包中将其设为公共，以便应用服务无需注册表凭据即可拉取。

infra/main.bicep（订阅范围）预配资源组、应用服务、存储和密钥保管库。entra 应用注册通过以下两种方式之一完成：

设置向导，一次 bicep 运行。 使用空的 entra 参数部署并打开门户：引导向导通过设备代码登录，通过 Graph 创建应用注册，并将租户/客户端 ID 写入配置存储。/api/setup/* 在设置完成前是未认证的，第一个登录者成为管理员（首次使用信任）；之后设置门会将这些端点返回 404。

脚本化，两次 bicep 运行。 没有开放的设置窗口，服务器以已配置状态启动。entra 脚本需要运行 1 的输出（用于重定向 URI 的 Web 应用 URL、用于客户端密钥的密钥保管库名称），而 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 种子化到配置存储中（仅填充空白字段，配置放置保持权威）。

持续部署，可选加入。 为工作流创建 OIDC 联合，设置密钥 AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_SUBSCRIPTION_ID 和变量 AZURE_WEBAPP_NAME / AZURE_RESOURCE_GROUP，然后设置仓库变量 AZURE_DEPLOY=true。然后推送到 main 会将 Web 应用重新指向新推送的镜像。

门户内更新。 设置会显示注册表镜像是否与正在运行的构建不同（CI 将 git SHA 烘焙到镜像中），并可以重启应用以拉取它；重启使用 bicep 授予托管标识的仅重启自定义角色，因此在角色存在之前创建的部署需要重新运行 bicep 才能使用该按钮。