edgegate-mcp

edgegate-mcp

适用于 EdgeGate 的 MCP 服务——可直接在 Snapdragon 设备上，通过 Claude Code、Cursor 或 Claude Desktop 设置边缘 AI 回归门禁。

它能做什么？

EdgeGate 通过 Qualcomm AI Hub 在真实的 Snapdragon 硬件上运行 AI 模型回归测试，然后生成带签名的证据包，可将其附加到 CI 门禁。本 npm 包将 EdgeGate 的 REST API 封装为 61 个 MCP 工具，并附带技能，让你可以通过提示词驱动整个流程：

> Use the edgegate MCP to set up a CI gate for my MobileNet ONNX model.
> Gates: inference_time_ms ≤ 10, peak_memory_mb ≤ 150.
> Devices: Galaxy S24, Galaxy S23.

安装

# 1. Generate an API key in the EdgeGate dashboard
# https://edgegate.frozo.ai/workspace/<id>/settings#api-keys

# 2. Run the installer from the edgegate-mcp package (writes config for Claude Code / Cursor / Desktop)
npx [email protected] edgegate-mcp-install

重启 MCP 客户端即可。

在网页上使用（claude.ai、ChatGPT）

无需安装，也无需 API 密钥。将托管端点添加为自定义连接器，并在浏览器中批准：

https://edgegate.frozo.ai/mcp

• Claude — 设置 → 连接器 → 添加自定义连接器。
• ChatGPT — 设置 → 应用和连接器 → 启用开发者模式，然后创建使用 OAuth 身份验证的连接器。

登录 EdgeGate 并批准一次即可；你可以随时在仪表板的 设置 → 已连接的 AI 应用 下断开连接。托管端点无法访问你的文件系统，因此 edgegate_export_run_report 会直接内联返回报告，而不是写入文件。

任何支持 Streamable HTTP 的客户端也可以使用 API 密钥作为 bearer token 来连接：

claude mcp add --transport http edgegate https://edgegate.frozo.ai/mcp --header "Authorization: Bearer egk_live_..."

自托管：edgegate-mcp/http 中的 handleMcpRequest 是一个符合 Web 标准的 (Request) => Response 处理程序，可挂载到任何 fetch 运行时。

手动配置

如果你想自行编辑配置文件，该服务是一个标准的 stdio MCP 服务。将以下内容添加到客户端的配置中：

Claude Code（~/.claude.json）

{
  "mcpServers": {
    "edgegate": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "edgegate-mcp"],
      "env": {
        "EDGEGATE_API_KEY": "egk_live_...",
        "EDGEGATE_API_URL": "https://edgegateapi.frozo.ai"
      }
    }
  }
}

Cursor（~/.cursor/mcp.json）

格式与 Claude Code 相同，但不包含 type 字段。

Claude Desktop（macOS 上的 ~/Library/Application Support/Claude/claude_desktop_config.json）

格式与 Cursor 相同。

工具

输入架构和示例请参阅 docs/tools.md。

EdgeGate 提供 61 个 MCP 工具。此表由 src/server.ts 生成——添加工具后运行 npm run docs:tools。

工具	用途
edgegate_setup_workspace	确认或列出 API 密钥可访问的 EdgeGate 工作区。在新对话中首先运行此工具，以确定其他工具应使用哪个 workspace_id。
edgegate_create_pipeline	创建新的 EdgeGate 回归流水线。定义流水线将强制执行的模型、设备和门限（例如 inference_time_ms ≤ 10）。对于 LLM：在模型上设置 llm_compile_source，而不是 artifact_id。EdgeGate 将在首次运行时通过 AI Hub 编译并链接；后续运行会重用缓存的组合模型。ttft_ms 和 tps 门限有效；二者均根据各组件的性能分析数据推导得出（prompt 角色的 inference_time → TTFT；token 角色的 1000/inference_time → TPS）。每次 LLM 门限运行需要 3 个 AI Hub 性能分析作业（每个组件一个），CV 成本约为 3 倍。
edgegate_run_gate	针对某条流水线触发一次 EdgeGate 运行。返回可通过 edgegate_check_status 轮询的 run_id。
edgegate_check_status	获取 EdgeGate 运行的当前状态，包括各设备的指标以及通过或未通过的门限。
edgegate_get_report	列出工作区中近期的 EdgeGate 运行及其状态、持续时间和触发方式。
edgegate_get_audit_report	获取已完成 EdgeGate 运行的签名审计报告 PDF URL。用于合规记录。
edgegate_setup_github_action	生成 GitHub Actions 工作流 YAML 和 gh 密钥命令，使每个 PR 都能将 EdgeGate 作为 CI 门禁运行。
edgegate_compare_runs	对比两次 EdgeGate 运行——标准流水线指标／门限或 Behavioral-Gate 汇总信号。如果无法进行可靠对比，则报告 REGRESSION / IMPROVEMENT / NEUTRAL，或 NO BASELINE / NOT COMPARABLE / INSUFFICIENT EVIDENCE。省略 baseline_run_id 时，会自动选择同一流水线中近期一次 PASSED 运行。没有流水线的运行（包括 Behavioral-Gate 运行）必须明确指定 baseline_run_id，且评估集和门限配置必须匹配。
edgegate_export_run_report	下载 EdgeGate 运行的易读 Markdown 报告并保存到磁盘。返回绝对文件路径以及前 30 行的预览。可选择包含运行与基线的对比部分（include_diff=true）。
edgegate_import_huggingface_model	导入包含预构建 ONNX 文件的公开 Hugging Face 模型。EdgeGate 会下载该文件并将其注册为 Artifact。返回可直接传递给 edgegate_create_pipeline 的 artifact_id。默认轮询直到导入完成（poll_for_completion=true）；设为 false 可立即返回作业 ID。
edgegate_predict_npu_coverage	在消耗任何 AI Hub 额度之前，预测哪些 ONNX 运算会在 Qualcomm Hexagon NPU 上运行，哪些会回退到 CPU。返回按计算量加权的 NPU 覆盖率（更能如实反映延迟的数值）、运算数量覆盖率、风险等级、各运算的 CPU 回退情况以及修复建议。此结果基于启发式；实际设备运行结果仍为最终依据。
edgegate_list_promptpacks	列出 EdgeGate 工作区中的所有 promptpack。返回包含 promptpack_id、版本、用例数量、发布状态和创建日期的 Markdown 表格。使用 include_unpublished=false 可隐藏草稿包。
edgegate_create_promptpack	在 EdgeGate 工作区中创建新的 promptpack。promptpack 定义回归流水线要评估的测试用例（提示词、预期输出、各用例的覆盖设置）。需要工作区管理员角色。创建后不可更改；更新时请提升版本号。
edgegate_publish_promptpack	在 EdgeGate 工作区中发布某个 promptpack 版本，使其可在流水线中引用。新建的包默认为未发布——创建后调用 edgegate_publish_promptpack，即可完成创建 → 发布 → 使用的流程。需要工作区管理员角色。此操作具有幂等性。
edgegate_connect_huggingface	为此工作区保存个人 HuggingFace 访问令牌，使导入流程能够读取私有／受限／Qualcomm 组织的代码库（大多数 qualcomm/、Intel/ 和许多 Xenova/* 代码库会对匿名端点返回 401）。加密前会通过 HF whoami 验证令牌，且绝不会以明文回显。如果集成已存在，此工具会轮换令牌。需要管理员角色。
edgegate_get_huggingface_integration	查看此工作区是否已连接个人 HuggingFace 令牌（以及该令牌当前是否已启用或禁用）。不会返回令牌本身。
edgegate_disconnect_huggingface	永久删除工作区的 HuggingFace 集成。后续 HF 导入将回退到匿名访问。需要所有者角色。
edgegate_connect_qaihub	为此工作区保存 Qualcomm AI Hub API 令牌，使 EdgeGate 能够在真实 Snapdragon 设备上提交编译和性能分析作业。令牌在静态存储时会加密，初次连接后绝不会以明文形式返回。如果集成已存在，此工具会自动轮换令牌。需要管理员角色。
edgegate_get_qaihub_integration	查看此工作区是否已连接 Qualcomm AI Hub 令牌，以及令牌当前是否已启用。不会返回令牌本身。
edgegate_disconnect_qaihub	永久删除工作区的 Qualcomm AI Hub 集成。之后，此工作区中的任何新 EdgeGate 运行都会因 NO_AIHUB_TOKEN 而失败，直到重新连接令牌。需要所有者角色。
edgegate_create_workspace	创建新的 EdgeGate 工作区。调用者会自动成为所有者。受计划层级的工作区数量限制。创建后，按常规连接 Qualcomm AI Hub 并定义流水线。
edgegate_list_api_keys	列出此工作区中的所有 API 密钥（id、名称、前缀...后缀、状态、最后使用时间）。绝不会返回明文。需要所有者角色。
edgegate_create_api_key	为此工作区创建新的 API 密钥。响应中的明文令牌只会返回一次——请立即将其复制到 CI 密钥或本地环境中。需要 Pro 层级或更高层级。需要所有者角色。
edgegate_revoke_api_key	按 id 撤销 API 密钥。此密钥会立即被后续所有请求拒绝；记录会保留（并设置 revoked_at），以保留审计跟踪。此操作具有破坏性。需要所有者角色。
edgegate_list_members	列出此工作区的所有成员及其电子邮件地址和角色。至少需要查看者角色。
edgegate_list_devices	列出 EdgeGate 可定位的所有 Qualcomm AI Hub 设备（Snapdragon 手机、QRD/CRD 参考平台、IoT Dragonwing、汽车、XR）。返回按类别分组的 Markdown 表格。构建 create_pipeline 设备矩阵时，请原样使用 id 列中的值。无需 workspace_id——设备目录为全局目录。
edgegate_list_device_targets	列出客户自己连接的设备（Jetson、Snapdragon 主机、网关），并根据各设备的心跳计算实时／离线状态（每 30 秒发送一次心跳，时间窗口为 90 秒）。这些是通过 edgegate-runner agent 连接的工作区设备群——不是全局 AI Hub 设备目录（查询该目录请使用 edgegate_list_devices）。如果列表为空，响应会包含可供客户复制粘贴的连接说明。
edgegate_run_device_benchmark	按名称／id 将 ONNX 基准测试任务分发到客户的一台已连接设备（Jetson、Snapdragon 主机、网关）。设备端 Agent 会在约 30 秒内接收任务，并报告延迟／内存结果。支持多种芯片：适用于客户连接的任何厂商设备。需要管理员角色。
edgegate_invite_member	按指定角色（owner / admin / viewer）通过电子邮件将现有 EdgeGate 用户添加到此工作区。v1 仅能添加现有用户，不会向外部地址发送邀请邮件。需要管理员角色；只有所有者才能添加其他所有者。
edgegate_change_member_role	更改此工作区中成员的角色。不能将最后一位所有者降级——请先将另一位成员提升为所有者。需要所有者角色。
edgegate_remove_member	从此工作区移除成员。该用户会立即失去访问权限；其流水线和运行记录会保留。不能移除最后一位所有者。此操作具有破坏性。需要所有者角色。
edgegate_setup_byo_storage	仅限 Enterprise。轻松设置 BYO 存储——在 EdgeGate 中创建待处理授权（返回 External ID），并返回 Agent 应运行的准确 AWS CLI 命令，以便在客户的 AWS 账户中创建 IAM 角色。与 edgegate_attach_byo_role 配合使用以完成设置。新设置优先使用此工具，而不是 edgegate_register_byo_bucket——Agent 无需自行确定信任策略或猜测角色名称。需要所有者角色。非 Enterprise 工作区会返回 402；如果存在非待处理授权，则会提示 Agent 先断开连接。
edgegate_attach_byo_role	edgegate_setup_byo_storage 的第 2 阶段。将新建的 Role ARN 提交给 EdgeGate，由 EdgeGate 运行 sts:AssumeRole 和默认拒绝的 HEAD 探测，以验证信任策略和权限策略是否正确。成功后将授权状态切换为 'active'；失败时则返回带有常见配置错误检查清单的类型化 BYO_* 错误。修复 IAM 后，可使用相同的 role_arn 再次调用。
edgegate_register_byo_bucket	仅限 Enterprise。新设置请改用 edgegate_setup_byo_storage——此工具仅适用于已拥有 IAM 角色且只想注册其 ARN 的情况。将工作区的客户自有 S3 存储桶和 IAM 角色注册为 BYO 存储授权。EdgeGate 工作进程会通过 AssumeRole 进入你的 AWS 账户以读取模型字节——这些字节绝不会离开你的账户。返回必须添加到角色信任策略中的 External ID。需要所有者角色。非 Enterprise 工作区会返回 402；已有授权时会返回 409。
edgegate_check_byo_bucket	针对工作区的 BYO 授权重新运行 AssumeRole 和 HeadObject 就绪探测。返回更新后的授权状态；如果失败，还会返回类型化 BYO_* 错误代码，以及常见 IAM／存储桶／KMS 配置错误的检查清单。需要管理员角色。
edgegate_register_byo_artifact	将已注册存储桶中的现有 S3 URI 注册为 EdgeGate Artifact。EdgeGate 会对该 URI 执行 HeadObject，以确认键存在并获取大小／etag——字节不会通过 EdgeGate 上传。返回可直接传递给 edgegate_create_pipeline / edgegate_run_gate 的 artifact_id。需要管理员角色。前置条件：Enterprise 计划、有效的 BYO 授权，且存储桶与该授权匹配。
edgegate_disconnect_byo_bucket	删除工作区的 BYO 存储授权。EdgeGate 将停止尝试从你的存储桶读取数据。如果仍有 Artifacts 引用该授权，则会拒绝操作（409），并列出安全的后续处理方式（通过控制面板轮换 External ID，或先删除这些 Artifacts）。此操作具有破坏性。需要所有者角色。
edgegate_llm_compile	通过 Qualcomm AI Hub 提交多组件 LLM 编译和链接作业。返回 compile_job_id；使用 edgegate_check_llm_compile_status 轮询。费用受工作区每月 LLM 编译额度限制（Pro 层级默认为每月 100 次）。每次编译都会生成一个组合 QNN_DLC 链接模型和 3 个组件 Artifact（prompt / token / kv_cache）。底层的编译目标运行时为 QNN_DLC，尽管标签显示为 genie——该标签仅用于提示下游的性能分析任务如何分发。
edgegate_check_llm_compile_status	轮询 LLM 编译作业。返回状态（queued|running|completed|failed）、完成时的 composite_artifact_id、失败时的 error_detail，以及 progress.compile_jobs_done / total。
edgegate_get_byo_audit	获取工作区仅追加的 BYO 存储审计日志（每次 AssumeRole、HeadObject、GetObject、KMS Decrypt）。支持按 artifact_id、run_id、since 时间戳筛选，并支持游标分页。每条记录中的 aws_request_id 可用于与你自己的 CloudTrail 交叉引用。需要管理员角色。
edgegate_list_eval_packs	列出客户可克隆使用的内置行为评估集入门包。返回每个包的 id、名称、用例数量和平衡情况（must_refuse / task 数量）。通过 edgegate_create_eval_set(clone_from=) 将其克隆到新的评估集中。无需 workspace_id——评估包库为全局库。
edgegate_create_eval_set	创建新的行为评估集及其首个草稿版本。可从内置包（clone_from）或明确指定的用例初始化，也可同时使用二者，或都不使用（创建空草稿）。每个用例包含六个字段：case_id、prompt、category（jailbreak|forbidden_action|task|format）、forbidden_actions、must_refuse、expected_task_answer。此处不会验证草稿——只有 edgegate_publish_eval_set 才会冻结并设置门槛。需要工作区写入权限。
edgegate_list_eval_sets	列出工作区的行为评估集——eval_set_id、名称、最新版本和创建日期。使用 eval_set_id 调用更新／发布／新建版本工具。
edgegate_update_eval_set	替换某个草稿评估集版本的全部用例（提供完整替换列表，而不是增量补丁）。已发布的版本不可更改——如果此处返回 409，必须先使用 edgegate_new_eval_set_version 创建新的草稿分支。此操作不会改变版本的草稿状态；需另行发布。需要工作区写入权限。
edgegate_publish_eval_set	验证草稿评估集版本，并将其冻结为不可变、已签名且由哈希锚定的版本。成功后返回 eval_set_sha256 + artifact_id（将二者传入 3b Behavioral-Gate 运行）。验证失败时会返回平衡性／结构违规信息，且版本仍为草稿（最低要求：≥5 个 must_refuse-with-forbidden 用例 + ≥1 个 task 用例）。需要工作区写入权限。
edgegate_new_eval_set_version	从已发布版本分支创建新草稿（版本号 +1），并以原有用例为初始内容——这是发布后编辑的流程。使用 edgegate_update_eval_set 编辑新草稿，然后重新发布。原始已发布版本（以及绑定到其 sha 的所有引用／运行）不会受到影响。需要工作区写入权限。
edgegate_list_workflow_endpoints	列出工作区中保存的 API／工作流端点——即 API 门禁的目标（n8n、Zapier、Make 或任何兼容 OpenAI 的 API）。返回可传递给 edgegate_capture_reference 和 edgegate_create_bg_run 的各个 endpoint_id。绝不会返回凭据；只会显示是否已保存凭据及其最后 4 个字符。
edgegate_create_workflow_endpoint	保存 API／工作流端点，以便行为门禁能够将其作为目标。此工具是为需认证的端点设置门禁的唯一方式：凭据会在此处以信封加密方式存储，绝不会返回；而携带凭据的内联 http 描述符会被拒绝（422）。使用已保存的端点还可让 EdgeGate 拒绝与基线端点不同的运行。需要工作区管理员权限。
edgegate_probe_workflow_endpoint	向已保存的端点发送一个测试请求，并将原始响应与 EdgeGate 从中提取的文本并列显示。请在捕获基线之前运行此工具：它是唯一能发现 response_text_path 设置错误的工具；此类错误会导致提取的文本为空——空文本会被判定为拒绝，因此全为空的基线会让之后的每个门禁都轻松通过。
edgegate_capture_reference	触发参考预言机捕获——Behavioral Gate 用于进行差异比较的已知良好基线。必须且只能指定一种类型：hf_repo（自动 FP16，EdgeGate 运行同一未量化模型）、reference_upload_artifact_id（由客户提供的黄金版本），或 endpoint_id/http（API 或工作流端点——n8n、Zapier、Make 或任何兼容 OpenAI 的 API；EdgeGate 会针对每个用例调用一次，无需安装任何东西）。返回可供轮询的 job_id。需要工作区管理员权限。
edgegate_check_reference_capture_status	轮询参考捕获作业。状态为 done 时，返回 reference_artifact_id——一个 ArtifactKind.REFERENCE Artifact，可将其传递给 edgegate_create_bg_run，作为门禁可信的基线。需要工作区管理员权限。
edgegate_compile_genie	为 Behavioral Gate 的可自托管运行器提交 3 路 genie 编译。必须且只能指定一种通道选择器：hf_repo（通道 A——EdgeGate 编译 HuggingFace 代码库）、onnx_artifact_ids（通道 B——适用于 genie 的多部分 ONNX，进行编译并链接），或 bundle_artifact_id（通道 C——已预编译的包）。返回可供轮询的 job_id。需要工作区管理员权限。
edgegate_check_genie_compile_status	轮询 genie 编译作业。状态为 done 时，返回 bundle_artifact_id——可传递给 edgegate_create_bg_run 的已编译 genie 包。需要工作区管理员权限。
edgegate_create_bg_run	将门禁目标、已发布的评估集和参考预言机组合为一次 behavioral-gate 运行。支持三种目标：已编译的 genie 包（bundle_artifact_id，通过可自托管运行器在设备上运行）、设备端 LLM（geniex_model），或 API／工作流端点（endpoint_id/http——n8n、Zapier、Make、兼容 OpenAI；EdgeGate 默认直接执行，因此无需安装任何东西，结果标记为 API-verified，而非 hardware-certified）。如果参考基线使用了不同版本的评估集（eval_set_sha256 不同）或不同端点，则会因不匹配而报错并提供提示。需要工作区管理员权限。
edgegate_cancel_run	取消尚未进入终态的运行，释放工作区唯一的活动运行名额。适用于一直排队等待设备但设备始终未响应的 behavioral-gate 运行（否则会阻止新运行）。如果运行已进入终态，则返回 409。
edgegate_rerun_bg	重新运行现有 behavioral-gate 运行：将其已验证配置（相同的包、评估集、参考基线、系统提示词和设备）复制到一个新的排队运行中——无需重新提供 Artifact ID。如果工作区已有活动运行，则返回 409（请先取消该运行）。
edgegate_setup_bg_github_action	生成 Behavioral-Gate GitHub Actions 设置——可自托管运行器的前置条件、工作流 YAML（使用 edgegate-bg 复合操作）以及 gh 密钥命令。与标准门禁运行不同，BG 会在真实设备上运行模型，因此需要连接了设备的可自托管运行器。
edgegate_export_compliance_report	导出某次运行的合规预设报告（例如 ISO 26262 验证证据）——根据标准条款（配置标识、验证、变更管理、工具分类、完整性）重新整理该运行已签名的证据。这是验证证据，不是合规认证。格式化的评估人员 PDF 位于控制面板的运行页面。
edgegate_export_field_recorder_report	导出指定日期范围的 Field Recorder《欧盟 AI 法案》第 12 条记录保存报告——包含已部署模型在设备端行为的签名哈希链证据（条款 12(1)/12(2)(a)/12(2)(b)/完整性映射、事件摘要、Ed25519 签名）。这是验证证据，不是合规认证。格式化的评估人员 PDF 位于 Field Recorder 控制面板页面。
edgegate_recorder_status	获取工作区的 Field Recorder 状态：记录事件数、重放／差异分类（passed/diverged/no_reference）、哈希链完整性（已验证、缺口、签名密钥）以及正在上报的设备。只读。
edgegate_trigger_replay	使用已认证参考（同一模型的一次 PASSED 门禁运行）以及输入匹配的基线，重放待处理的已记录事件。判定结果会异步生成——请轮询 edgegate_recorder_status。没有已认证参考的事件会归为 no_reference。

技能

可直接调用的斜杠命令：

• /edgegate-init — 完整的入门流程（从零开始 → CI 门禁）
• /edgegate-gate — 在现有流水线上触发一次运行
• /edgegate-status — 检查运行状态和指标
• /edgegate-audit — 获取某次运行的证据包
• /edgegate-compare — 对比两次运行（自动基线），给出 REGRESSION/IMPROVEMENT/NEUTRAL 结论
• /edgegate-export — 将运行报告保存为 Markdown 文件（用于 PR 评论、Slack、合规）
• /edgegate-import — 导入 Hugging Face ONNX 模型（匿名导入；私有、受限或 qualcomm-org 仓库需使用工作区令牌）
• /edgegate-connect-huggingface — 将个人 HuggingFace 令牌关联到工作区，以便导入流程读取私有、受限或 qualcomm-org 仓库
• /edgegate-connect-qaihub — 连接 Qualcomm AI Hub 令牌，以便在 Snapdragon 设备上实际编译和分析运行
• /edgegate-workspace-setup — 端到端初始化全新工作区（创建 → 连接 AI Hub → API 密钥 → 邀请队友）
• /edgegate-members — 列出、邀请、更改角色或移除工作区成员
• /edgegate-promptpacks — 列出已有的提示词包，或使用生成的测试用例创建新提示词包
• /edgegate-byo-storage — Enterprise BYO 存储入门流程（注册授权 → 粘贴 External ID → 验证探测 → 首个制品 → 首次运行 → 审计日志）

许可证

MIT — 参见 LICENSE。