MediaSFU

MediaSFU MCP 集成工具包

官方 MediaSFU MCP 工具包可帮助开发者和支持 MCP 的 Agent 规划、搭建脚手架、诊断和加固 MediaSFU 前端与后端集成。

使用 npm 直接运行 stdio 服务：

npx -y @mediasfu/mcp-sdk-tools

如需可重复使用的 MCP 客户端配置，请固定为受支持的主版本：

{
  "mcpServers": {
    "mediasfu": {
      "command": "npx",
      "args": ["-y", "@mediasfu/mcp-sdk-tools@1"]
    }
  }
}

在 Windows 上，如果 MCP 客户端无法解析 npm shim，请使用 npx.cmd。你 也可以全局安装并运行显式可执行文件：

npm install --global @mediasfu/mcp-sdk-tools@1
mediasfu-mcp

mediasfu-mcp-http 可执行文件会启动可选的本地 Streamable HTTP 传输。客户端示例请参阅 LOCAL_MCP_SETUP.md。

使用自己的账户执行操作（账户模式）

mediasfu-mcp-account 可让你的助手使用 MediaSFU API 密钥创建和结束房间、发起 AI Agent 和 SIP 通话、列出录制内容、设置房间 Webhook，以及读取余额和用量。它通过 stdio 在本地运行；密钥保留在 MCP 客户端的环境中，仅发送至 https://mediasfu.com，并会从每个工具结果中隐藏。

{
  "mcpServers": {
    "mediasfu-account": {
      "command": "npx",
      "args": ["-y", "-p", "@mediasfu/mcp-sdk-tools@1", "mediasfu-mcp-account"],
      "env": {
        "MEDIASFU_API_USERNAME": "<api username>",
        "MEDIASFU_API_KEY": "<api key>"
      }
    }
  }
}

前往 mediasfu.com/api-keys 获取这两个值。请从沙盒密钥开始：以 s 开头的房间属于沙盒环境，以 p 开头的房间属于生产环境。

区域	工具
房间	mediasfu_create_room、mediasfu_join_room、mediasfu_list_rooms、mediasfu_get_room、mediasfu_room_stats、mediasfu_delete_room（结束房间）
Agent 和电话通话	mediasfu_initiate_call、mediasfu_start_call_agent、mediasfu_stop_call_agent、mediasfu_switch_call_source、mediasfu_end_call、mediasfu_list_calls、mediasfu_get_call_state、mediasfu_get_call_summary、mediasfu_list_sip_numbers，以及保持、播放、录制和回拨控制
录制内容	mediasfu_list_recordings
Webhook	mediasfu_get_webhook、mediasfu_set_webhook
用量	mediasfu_get_balance、mediasfu_get_room_usage
默认设置	mediasfu_create_event_settings、mediasfu_update_event_settings

读取类工具会立即运行。任何创建、更改、发起通话或结束操作都会先返回带有预览的 confirmation_required；只有助手再次使用 confirm: true 调用时才会执行，这样你就能批准每个计费或破坏性操作。

支持的 SDK 平台

• 共享运行时和后端集成
• ReactJS
• Angular
• React Native
• React Native Expo
• Vue
• Flutter
• Kotlin / Android / KMP
• Swift / Apple 平台
• Unity

默认的公开接口提供 159 个集成工具。33 个文档构建和兼容性工具仅供内部使用；只有在可信的本地维护者工作区中，才设置 MCP_INCLUDE_INTERNAL_TOOLS=1 以公开完整的 192 个工具接口。

核心工具

每个 SDK 都提供：

• sdk.recommend
• app.scaffold
• integration.plan
• env.preflight
• room.bootstrap
• feature.map
• runtime.diagnose
• fix.suggest
• api.reference.search
• room.flow.explain
• ui.mode.recommend
• ui.overrides.guide
• security.proxy.rooms

共享能力还提供了从 MediaSFU 的无头、微件、电话和 AI 通话控制集成中提炼出的生产模式：

• shared::frontend.architecture.plan
• shared::headless.integration.plan
• shared::widget.integration.plan
• shared::telephony.call-control.plan
• shared::solution.capsule.plan
• shared::external-media.integration.plan
• shared::participant-control.integration.plan
• shared::room.lifecycle.plan
• shared::embedded.layout.plan
• shared::room.authority.plan
• shared::product.pattern.plan
• shared::custom-recording.scene.plan
• shared::runtime.readiness.diagnose
• shared::lifecycle.cleanup.audit
• shared::credential.broker.plan
• shared::backend.integration.guide

微件规划器会区分 6 个独立自定义元素、纯脚本交付、模块化 npm 导入，以及可选的 React/无头入口。它还会返回经过审核的软件包状态，因此不会将软件包发布和托管交付误认为完整的实时运行时证据。

工具名称采用 sdkId::toolId 格式，例如 reactjs::integration.plan。

能力证据与 SDK 时效性

sdk-registry.json 记录检测到的软件包名称和版本、清单与参考文档哈希，以及各 SDK 的证据主题。feature.map 会以 sdkRelease 和 capabilityEvidence 的形式返回这些信息。

证据状态采用保守定义：

• documented 表示随附的 SDK 参考文档中有该能力的证据。
• not-evidenced 表示随附的参考文档无法证明该能力；这并不表示 SDK 不支持该能力。

如果清单、随附的参考文档、实时软件包版本、规范软件包路径或证据配置发生偏差，npm run registry:check 就会失败。如果发现 MediaSFU SDK 工作区但未将其注册，也会失败。维护者可以使用 npm run registry:write 刷新已审核的变更。

feature.map 还会返回规范的语言无关操作 ID、证据状态词汇、精确的 SDK 覆盖标识和安全边界。MCP 注册表会存储一个绑定哈希的目录参考和一个简洁的绑定哈希运行时契约参考。后者记录运行时注册表架构、必需的稳定契约 ID、完整的契约 ID 列表、源路径和 SHA-256，但不会复制各 SDK 的证据条目。自定义录制场景见规范的自定义录制指南；MCP 能力面会提供常规录制生命周期，并指引集成者参考该指南，了解可移植的场景契约和由服务端负责的完成规则。规范的产品模式索引和入门项目目录将 Familiar Calls、Live Auction、Watch Together、Agents、VOIP 和 SpacesTek 的可运行参考链接到各自独立认证的平台证据。生命周期、布局、权限、产品模式和自定义录制规划器会公开这些契约，但不会将应用组合或共享核心导出视为跨 SDK 的证明。在本地运行 npm run catalog:check，可检测操作、覆盖、安全或运行时契约是否发生偏差。

安全脚手架生成

除非明确设置 apply: true，否则脚手架生成仅进行试运行。应用模式：

• 从 projectRoot 解析路径，默认为 MCP 进程的工作目录；
• 仅在相对路径 outputDir 下写入，默认为 mediasfu-generated/sdkId；
• 拒绝路径遍历；
• 除非设置 overwrite: true，否则拒绝覆盖现有文件；
• 生成 MEDIASFU_INTEGRATION.md，其中包含检测到的 SDK 版本和运行时检查清单；
• 绝不生成长期凭据占位符。

ReactJS 会根据 MediaSFU 前端当前使用的无头运行时模型，生成符合生产模式的 TypeScript/React 起始代码。对于其他 SDK，如果其软件包 API 尚未经过此 Node 发布流程的编译验证，则会生成适配版本的实施方案。这样可以避免将推测性源代码呈现为可直接编译的代码。

示例：

node ./scripts/mcp-engine.mjs run reactjs app.scaffold --input '{"apply":true,"projectRoot":"/path/to/app","outputDir":"src/mediasfu"}'

从经过身份验证的后端获取作用域受限的房间／会话材料。切勿将长期有效的 MediaSFU API 密钥放入浏览器存储、移动设备偏好设置、源代码、日志或随桌面／移动／游戏二进制文件一起分发的内容中。

本地运行

npm install
npm run validate
npm run registry:check
npm run mcp:server:selftest
npm run mcp:http:selftest
npm run release:check

实用示例：

node ./scripts/mcp-engine.mjs list reactjs
node ./scripts/mcp-engine.mjs run reactjs integration.plan --input '{"appType":"meeting"}'
node ./scripts/mcp-engine.mjs run reactjs api.reference.search --input '{"query":"create room"}'
node ./scripts/mcp-engine.mjs run reactjs feature.map --input '{"requestedFeatures":["conference","screen-share"]}'
node ./scripts/mcp-engine.mjs run shared frontend.architecture.plan --input '{"mode":"auto","needsWidget":true}'

MCP 传输方式

Stdio 入口：scripts/mcp-stdio-server.mjs。

Streamable HTTP 入口：scripts/mcp-http-server-v2.mjs。它在 /mcp 提供公开的只读工具，并在 /mcp/actions 提供作用域受限的 MediaSFU 账户操作。

默认情况下，stdio 和公开 HTTP 工具接口均为只读。启用本地文件系统／命令副作用需要设置 MCP_ALLOW_LOCAL_SIDE_EFFECTS=1，且绝不能在共享端点上启用。

托管的 /mcp 端点有意不设身份验证，并永久保持只读。单独的 /mcp/actions 端点要求使用 Authorization: Bearer <username>:<disposableKey>，通过 MediaSFU 验证密钥，按密钥作用域筛选工具，并确认副作用。请参阅 server/README.md。

后端边界

对于 /v1/rooms、事件设置和一次性密钥约定，请使用 shared::backend.integration.guide。切勿向公开／stdio 工具发送凭据。操作端点仅接受精确文档所述 Authorization 标头中的一次性凭据，且绝不会将其暴露给工具或写入日志。

发布门禁

npm run release:check 会验证：

1. 全部 11 个清单和关键工具；
2. SDK 注册表偏差和未注册 SDK 的发现情况；
3. stdio 与 HTTP 公开工具接口的一致性；
4. 所有公开和内部适配器的覆盖情况；
5. 输入、副作用、路径、脱敏、超时和 HTTP 安全控制；
6. 生产架构、就绪状态、生命周期、凭据和证据行为；
7. 针对全部 11 个 SDK／运行时接口的真实隔离脚手架写入，包括冲突拒绝和清理。

发布前运行 npm run pack:dry-run 和 npm audit。发布有意作为单独的维护者操作。

其他公开设置和部署说明见 LOCAL_MCP_SETUP.md 和 server/README.md。

项目链接

• 网站和开发者文档：mediasfu.com
• 源码：github.com/MediaSFU/mcp-sdk-tools
• 问题反馈：github.com/MediaSFU/mcp-sdk-tools/issues
• 安全报告：SECURITY.md

MediaSFU MCP SDK Tools 根据 MIT License 发布。