SignalEDI

SignalEDI 开发者 MCP 服务

将 AI 编码助手连接到 SignalEDI，以发现、搭建、验证和测试 X12 集成。此 MCP 服务基于与传统应用相同的公开指南和 /api/v1 REST 契约，为开发者提供 AI 原生体验。它与 SignalEDI 的 REST API、OpenAPI 规范、webhook、SDK 和文档相辅相成，而非取而代之。

此软件包是对 SignalEDI 现有 MCP 适配器的升级。0.5 版新增了公开开发者发现、资源模板、代码示例、受管控的连接控制平面工具、严格的工具输入验证，以及明确的能力配置，同时保留了现有的解析器、事务、合作伙伴工具包和 QuickBooks 适配器。

软件包	@signaledi/mcp-server
MCP 注册表	io.github.SignalEDI/mcp-server
传输方式	stdio
运行时	Node 22+
运行时依赖项	@modelcontextprotocol/sdk 1.30.0（2025 协议代际）
默认访问权限	始终可免密访问 docs；经过身份验证的工具需要明确指定 sandbox 或 production

能力配置

将 SIGNALEDI_MCP_PROFILE 设置为以下配置之一。工具发现和直接工具调用都会限制在当前启用的配置范围内。

配置	身份验证	可用范围
docs	无	仅限公开文档资源和本地合成辅助工具；提供的文档内容和凭据绝不会上传。OpenAPI 资源会执行不含内容的公开 GET 请求。即使主机环境中存在密钥，这也始终是默认配置。
sandbox	单独配置的非生产密钥以及显式基本 URL	经过身份验证的解析/验证、通用合作伙伴工具包发现、租户数据读取，以及针对单独配置的沙盒实施的受保护变更。拒绝访问规范的 SignalEDI 生产主机。
production	获准用于生产环境的平台密钥、精确的 https://signaledi.com 基本 URL，以及 SIGNALEDI_MCP_ALLOW_PRODUCTION=1	允许列表中的交易/QBO 状态/工具包/连接读取；优先在沙盒中创建连接草稿；受保护的连接配置、已保存绑定的连通性测试和上线交接请求；出站发送和 QBO 到 EDI 的导出。解析/验证、QBO 实体浏览、QBO 同步、断开连接、通用生命周期控制和生产环境激活仍处于隐藏状态。

该配置是在 MCP 适配器内部实施的最低权限边界，不能替代 API 授权，也不是数据治理边界。对于出站发送和 QBO 导出，服务会根据当前启用的配置注入 SANDBOX 或 PRODUCTION；模型无法自行选择。随后，API 会将该值绑定到所选的合作伙伴连接。生产环境交付要求存在有效且不可变的生产版本，沙盒交付则要求沙盒环境已验证/激活。

每次经过身份验证的调用都需要基本 platform 作用域。连接清单需要 platform:connections:read；创建草稿和配置还需要 platform:connections:write；生产环境配置和上线交接还需要 platform:connections:production。这些领域作用域不授权文档交付或 QuickBooks 操作。仅具有已弃用的通用 platform:write 和 platform:production 作用域的凭据，会被领域作用域操作拒绝，必须通过受支持的密钥轮换流程替换。发布前，运维人员应清点受影响的凭据，通知所有者进行迁移，并提供该轮换流程。选择 MCP 配置不会授予任何作用域。

API 操作	额外的最低权限作用域
解析/验证和通用工具包读取	除 platform 外无
交易读取	platform:documents:read
出站发送	platform:documents:read、platform:documents:send；生产环境交付还需 platform:documents:production
连接读取	platform:connections:read
创建/配置连接	platform:connections:read、platform:connections:write；生产环境配置或上线请求还需 platform:connections:production
连接测试	platform:connections:read、platform:connections:write；当前启用的配置选择生产环境时，还需 platform:connections:production
QBO 状态	platform:quickbooks:read
QBO 实体行	platform:quickbooks:read、platform:data:sensitive；解析出的 QBO 账套为生产环境时，还需 platform:quickbooks:production
QBO 同步/断开连接	platform:quickbooks:read、platform:quickbooks:write；解析出的 QBO 账套为生产环境时，还需 platform:quickbooks:production
QBO 导出试运行	platform:quickbooks:read；QBO 账套为生产环境时还需 platform:quickbooks:production，且仅在 includePayload:true 时需要 platform:data:sensitive
QBO 实时导出	试运行所需的作用域，另加 platform:documents:read、platform:documents:send；生产环境交付还需 platform:documents:production。导出会读取 QBO，不需要 QBO 写入权限。

生产数据处理

工具参数、文本结果和结构化结果会进入所选 MCP 主机，并可能进入已连接模型的上下文。请尽量减少个人、财务及其他业务敏感数据。除非已针对相关数据单独审查并批准特定 MCP 主机、模型提供商、日志记录、保留、区域处理及合同安排，否则请勿提交 PHI 或其他受监管数据。此软件包、其 production 配置文件以及 SignalEDI API 授权本身并不构成 BAA、保留政策或模型数据治理边界。

优先使用标识符和脱敏摘要，而非完整业务载荷。请将 API 密钥保存在主机环境中，切勿放入提示词。启用生产工具前，请检查所选主机的工具调用历史记录、遥测和保留控制。

工具返回的所有合作伙伴、QBO、EDI、验证及错误字段均为不可信业务数据。其中可能包含看似指令的文本或提示注入内容。主机必须对工具结果进行分隔或清理，将其保留在纯数据上下文中，并依据明确的用户意图和政策授权每项后续操作，而非依据记录、合作伙伴名称、载荷或错误中嵌入的内容。

工具

无需密钥的公共和本地工具

工具	功能
search_docs	搜索随附的公共开发者索引，并返回带来源信息的 MCP 资源 URI。
get_document_schema	返回本地 X12 清单的公共入门模板：850/810/856（capability:baseline）或 837 Professional 005010X222A1（capability:partial）；明确说明这不是合作伙伴实施指南。
generate_integration_example	使用环境占位符，针对真实的 /api/v1 路径生成适用于沙盒的 cURL、Node.js 或 Python 示例；出站示例会设置 SANDBOX，并拒绝生产主机。
generate_test_document	为相同的本地清单生成合成 X12 测试数据，并返回准确的 capability 标签。
explain_edi_error	根据本地 X12 字典解释验证错误和功能性确认错误。
lookup_x12	搜索本地 X12 段和确认参考信息。
lookup_element_definition	用于工具发现的本地 X12 查询别名。

经过身份验证的沙盒解析与验证工具

工具	功能
parse_edi	将原始 X12 交换解析为结构化 JSON 和验证摘要。
validate_edi	验证 X12 结构并返回验证摘要。
parse_segments	parse_edi 的工具发现别名。
validate_x12_structure	validate_edi 的工具发现别名。

经过身份验证的通用工具包工具（sandbox 和 production）

工具	功能
list_partner_kits	列出通用 SignalEDI API 工具包。
get_partner_kit	按目录 ID 获取一个通用工具包。
get_partner_requirements	返回通用工具包，并明确警告 partnerSpecific:false。

显式环境配置文件数据读取

绝不会仅因存在密钥就启用这些租户数据工具。显式使用 sandbox 和 production 配置文件时，可以读取交易数据并使用 quickbooks_status；quickbooks_list_entities 仅限沙盒使用。

工具	功能
list_transactions	列出限定在 API 密钥范围内的近期交易。
get_transaction	获取一笔归属当前账户的交易及其生命周期状态。
quickbooks_status	检查 QuickBooks Online 连接状态，不返回令牌。
quickbooks_list_entities	预览 Invoice、Estimate、PurchaseOrder、Customer、Vendor 或 Item 行，用于映射（仅限沙盒）。

受治理的连接控制平面（sandbox 和 production）

连接工具基于公开的 /api/v1/connections 契约运行。MCP 会在 API 的脱敏表示上再应用一层响应允许列表：可以返回不透明的网关／证据引用和配置状态布尔值，但绝不会返回已存储的凭据、密钥引用、原始传输配置、私钥、证书或令牌。

工具	功能
list_connections	通过游标分页列出租户范围内的 AS2/SFTP 和合法旧版 API 连接摘要，并可选按合作伙伴／生命周期筛选。
get_connection	查看单个 AS2/SFTP 或旧版 API 连接的安全环境、网关、审批、测试覆盖情况、就绪状态和后续操作。
create_connection_draft	创建或恢复幂等的、优先使用沙盒的 DRAFT；created 用于区分新建和匹配后复用，且无法激活 production。
configure_connection	将现有网关引用和受限的 X12 ISA/GS 标识符绑定到 AS2/SFTP 的 SANDBOX 或 PRODUCTION 环境；ISA15 由服务器控制，且不接受任何凭据材料。配置 production 需要 platform:connections:production，且仍不会激活交付。旧版 API 记录在此处保持只读，应使用受治理的 API 连接界面。
test_connection	在从活动配置文件注入的环境中测试已保存的准确连接。此操作会向合作伙伴网络发送流量、记录脱敏证据、要求由主机强制执行审核并提供幂等键，且绝不接受端点或凭据，也不会激活 production。
request_connection_go_live	请求 API 将经服务器验证为 READY 的连接仅迁移至 GO_LIVE_APPROVED。SignalEDI 员工激活仍是单独的 MFA／治理操作。

这里刻意不提供通用的生命周期转换工具。test_connection 可以为已保存的准确绑定创建权威的连通性证据；其他中间测试／认证阶段则来自证据或入驻项目状态，而非模型的声明。这里不提供 production 激活、回滚或隔离工具。

显式写入配置文件的工具

工具	功能
send_outbound_document	在活动的 sandbox/production 环境中提交出站 EDI 文档。
quickbooks_sync_to_qbo	将有限范围的交易选择推送至 QBO（仅限 sandbox）；买方和供应商方向均明确指定，all:true 使用游标分页。
quickbooks_export_to_edi	在活动的 sandbox/production 环境中，将 QBO 发票／采购订单预览或导出为 EDI。默认会对试运行结果中的有效负载进行脱敏；完整有效负载需要 includePayload:true、platform:data:sensitive 和由主机强制执行的 confirm:true。
quickbooks_disconnect	撤销并移除工作区的 QBO 连接（仅限 sandbox）。

每个工具都会发布输入和输出架构。服务器自行验证输入、拒绝未知字段，并返回可读文本和包含命名空间契约元数据的 structuredContent。

变更安全

docs 中不包含写入工具。每次实时变更都必须设置 confirm:true，并由调用方生成一个长度为 8–128 个可打印 ASCII 字符、且首尾不含空格的 idempotencyKey。外发消息、QBO 同步／导出／断开连接，以及连接创建／配置／测试／上线请求均会强制执行持久化的 API 端重放保护，并标注为幂等。QBO 断开连接仅限沙盒环境，并会报告 Intuit 撤销待处理，而不会声称已完成。confirm:true 是调用工作流作出的声明；MCP 服务无法独立证明已获人类批准，因此宿主必须将该操作呈交审核。

MCP 客户端不会自动重试变更操作或解析／验证 POST 请求。解析／验证会上传合成或已批准的测试数据，也可能记录沙盒使用情况，因此其注解仍为非只读且非幂等。只读 GET 请求保留有界的瞬时错误重试行为。

除非在验证目标后设置 SIGNALEDI_MCP_ALLOW_CUSTOM_BASE_URL=1，否则会拒绝自定义基础 URL。包含凭据、路径、查询参数或片段的 URL 会被拒绝。仅允许 localhost 使用 HTTP，且仍须启用自定义主机选项。

适配器将原始 EDI 输入限制为 65,536 个 UTF-8 字节，将序列化 JSON 请求正文限制为 1 MiB，将 API 响应限制为 4 MiB。输入架构会公布字符数／集合上限；在网络使用前会重新检查字节限制，流式响应超出上限时会取消。

资源和提示词

稳定的指导内容以资源而非操作工具的形式提供：

• signaledi://quickstart
• signaledi://openapi
• signaledi://developer-workflows
• signaledi://x12-reference
• signaledi://documents/{transactionSet}/schema

文档架构也会作为资源模板提供。提示词包括 scaffold-integration、onboard-partner 和 debug-rejection；脚手架搭建和入门提示词默认使用合成数据，并且在确认使用隔离沙盒前不会执行写入操作。

快速入门

运行公共文档配置：

npx -y @signaledi/[email protected]

只有在已配置非生产环境基础地址和密钥后，才能配置经过身份验证的沙盒配置。Claude Code 项目配置（.mcp.json）会从宿主环境展开 ${NAME}：

{
  "mcpServers": {
    "signaledi": {
      "command": "npx",
      "args": ["-y", "@signaledi/[email protected]"],
      "env": {
        "SIGNALEDI_MCP_PROFILE": "sandbox",
        "SIGNALEDI_API_KEY": "${SIGNALEDI_SANDBOX_API_KEY}",
        "SIGNALEDI_BASE_URL": "${SIGNALEDI_SANDBOX_BASE_URL}",
        "SIGNALEDI_MCP_ALLOW_CUSTOM_BASE_URL": "1"
      }
    }
  }
}

在原生 Windows 上，Claude Code 必须通过 cmd 启动 npm shim：

{
  "mcpServers": {
    "signaledi": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@signaledi/[email protected]"],
      "env": {
        "SIGNALEDI_MCP_PROFILE": "sandbox",
        "SIGNALEDI_API_KEY": "${SIGNALEDI_SANDBOX_API_KEY}",
        "SIGNALEDI_BASE_URL": "${SIGNALEDI_SANDBOX_BASE_URL}",
        "SIGNALEDI_MCP_ALLOW_CUSTOM_BASE_URL": "1"
      }
    }
  }
}

Cursor 使用 .cursor/mcp.json、mcpServers 和 ${env:NAME} 引用：

{
  "mcpServers": {
    "signaledi": {
      "command": "npx",
      "args": ["-y", "@signaledi/[email protected]"],
      "env": {
        "SIGNALEDI_MCP_PROFILE": "sandbox",
        "SIGNALEDI_API_KEY": "${env:SIGNALEDI_SANDBOX_API_KEY}",
        "SIGNALEDI_BASE_URL": "${env:SIGNALEDI_SANDBOX_BASE_URL}",
        "SIGNALEDI_MCP_ALLOW_CUSTOM_BASE_URL": "1"
      }
    }
  }
}

Claude Code 插件

这个公共仓库也是面向社区插件目录的 Claude Code / Cowork 插件。该插件通过 stdio 启动同一个 npm 包——没有并行的 MCP 实现；SignalEDI 也不提供托管的远程 MCP URL，因此请跳过远程 OAuth 连接器目录。

插件清单	.claude-plugin/plugin.json（name：signaledi）
MCP 配置	.mcp.json → npx -y @signaledi/[email protected]
技能	skills/signaledi-mcp-profiles/
本地验证	claude plugin validate . --strict（在此文件夹中运行；Claude Code CLI）
提交（控制台）	platform.claude.com/plugins/submit
提交（claude.ai Team/Enterprise）	claude.ai/admin-settings/directory/submissions/plugins/new

文档：提交你的插件。官方 claude-plugins-official 市场采用精选机制；向社区提交仍需提供公共 GitHub 仓库并运行 claude plugin validate。一键安装需要 npm 上的 @signaledi/[email protected]。

Claude Desktop（MCPB）

将同一个 stdio 服务打包为 Claude Desktop 扩展（.mcpb）。源文件：mcpb/manifest.json + scripts/build-mcpb.mjs。完整的构建和提交说明请参阅 mcpb/README.md。

npm ci
npm run build:mcpb
# → dist/signaledi-mcp-server-0.5.0.mcpb

双击 .mcpb、将其拖入 Claude Desktop，或通过 Settings → Extensions → Advanced → Install Extension… 安装。扩展设置映射到与 server.json 相同的环境变量（SIGNALEDI_API_KEY、SIGNALEDI_BASE_URL、SIGNALEDI_MCP_PROFILE 等）。作者／发布者：SignalEDI · [email protected] · https://signaledi.com。

目录提交（仅限手动）： 不要从此 Agent／CI 提交。准备就绪后，构建并测试该制品，再按照 Anthropic 的桌面扩展提交表单操作。工具：@anthropic-ai/mcpb（mcpb pack / mcpb validate）。规范：使用 MCPB 构建桌面扩展。

Google Antigravity

位于 antigravity-plugin/ 的手动 Antigravity / Gemini 风格插件文件夹（将 mcp_config.json 接入 npx -y @signaledi/[email protected]）。MCP Store 不支持自助上架；请复制该文件夹进行安装：

范围	路径
全局	~/.gemini/config/plugins/signaledi
工作区	.agents/plugins/signaledi（或 _agents/plugins/signaledi）

请参阅 antigravity-plugin/README.md。品牌：仅限 SignalEDI。

Cursor Marketplace

此公开仓库已打包为 Cursor Plugin，供官方 Marketplace 使用。该插件通过 stdio 启动同一个 npm 包，不存在并行的 MCP 实现。

插件清单	.cursor-plugin/plugin.json（name：signaledi）
MCP 配置	mcp.json → npx -y @signaledi/[email protected]
标志	assets/logo.svg（相对路径）
技能	skills/signaledi-mcp-profiles/
提交	cursor.com/marketplace/publish → 仓库 https://github.com/SignalEDI/mcp-server

安装（上架后）： 打开 Customize → Marketplace，搜索 SignalEDI 并安装。

配置： 在 Plugins → Configure 下设置插件变量（不要在仓库或提示词中存放密钥）：

变量	典型值
SIGNALEDI_MCP_PROFILE	docs（默认）、sandbox 或 production
SIGNALEDI_API_KEY	权限最小化的工作区密钥（docs 配置不使用此项）
SIGNALEDI_BASE_URL	已验证的非生产环境源，或生产环境专用的 https://signaledi.com
SIGNALEDI_MCP_ALLOW_CUSTOM_BASE_URL	仅对已验证的自定义主机设为 1
SIGNALEDI_MCP_ALLOW_PRODUCTION	仅在使用生产配置和规范基址时设为 1

插件 mcp.json 使用与上述控制面板变量对应的 ${VAR} 占位符（不同于项目 .cursor/mcp.json 中手动配置所用的 ${env:NAME} 语法）。未设置的占位符会在无密钥的 docs 配置下保持失败关闭。Marketplace 一键安装要求 npm 上发布 @signaledi/[email protected]（或更新的匹配版本锁定）；在该版本发布之前，仍可使用已发布版本通过本地／手动 npx 进行验证。

发布须遵守 Cursor Marketplace Publisher Terms。Marketplace 插件必须开源并通过人工审核；请参阅 marketplace security。

隐私政策

SignalEDI 的产品隐私政策发布于 https://signaledi.com/privacy。MCP 适配器通过 stdio 在本地运行；经过身份验证的调用会将工具输入发送到你配置的 SignalEDI API 主机。工具参数、文本结果和结构化结果会进入 MCP 主机，也可能进入模型上下文——请参阅上文的 生产数据处理。联系方式：[email protected]。

VS Code 使用 .vscode/mcp.json、顶层 servers 对象，以及用于机密信息的密码输入：

{
  "inputs": [
    {
      "type": "promptString",
      "id": "signaledi-api-key",
      "description": "SignalEDI non-production sandbox API key",
      "password": true
    },
    {
      "type": "promptString",
      "id": "signaledi-api-base",
      "description": "Verified non-production SignalEDI API base URL"
    }
  ],
  "servers": {
    "signaledi": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@signaledi/[email protected]"],
      "env": {
        "SIGNALEDI_MCP_PROFILE": "sandbox",
        "SIGNALEDI_API_KEY": "${input:signaledi-api-key}",
        "SIGNALEDI_BASE_URL": "${input:signaledi-api-base}",
        "SIGNALEDI_MCP_ALLOW_CUSTOM_BASE_URL": "1"
      }
    }
  }
}

对于已配置的本地沙盒，请将以下值添加到所选客户端的 env 对象中，并使用该客户端针对密钥的环境引用语法：

{
  "SIGNALEDI_MCP_PROFILE": "sandbox",
  "SIGNALEDI_API_KEY": "<host environment reference to SIGNALEDI_SANDBOX_API_KEY>",
  "SIGNALEDI_BASE_URL": "http://localhost:3100",
  "SIGNALEDI_MCP_ALLOW_CUSTOM_BASE_URL": "1"
}

生产环境采用明确选择加入的方式，并在未满足条件时默认拒绝。仅使用规范源站，并将密钥保存在 MCP 主机环境中：

{
  "SIGNALEDI_MCP_PROFILE": "production",
  "SIGNALEDI_API_KEY": "<host environment reference to SIGNALEDI_PRODUCTION_API_KEY>",
  "SIGNALEDI_BASE_URL": "https://signaledi.com",
  "SIGNALEDI_MCP_ALLOW_PRODUCTION": "1"
}

生产配置不接受自定义主机，也不接受缺失或隐式的基础 URL。移除配置项、密钥、规范基础 URL 或选择加入标记中的任意一项，都会阻止启动。

切勿将真实密钥或机密信息粘贴到提示词中。MCP 服务环境变量由主机进程解析，而不是由模型解析。

配置

环境变量	默认值	用途
SIGNALEDI_MCP_PROFILE	docs	功能边界：docs、显式指定的 sandbox，或显式指定的 production。仅提供密钥绝不会启用远程工具。
SIGNALEDI_API_KEY	—	最小权限工作区密钥；在 docs 中会被忽略，在需要身份验证的配置中则为必需。它需要基础 platform 范围，以及每个工具已发布的域范围。不要向 MCP 主机授予旧版的宽泛写入/生产范围。
SIGNALEDI_BASE_URL	仅用于不含内容的文档 OpenAPI GET 请求的公共生产基础 URL	沙盒需要显式指定经过验证的非生产源站；生产环境必须严格使用 https://signaledi.com。
SIGNALEDI_MCP_ALLOW_CUSTOM_BASE_URL	—	仅当主机是经过验证的 localhost、预览环境或沙盒时，才设为 1。
SIGNALEDI_MCP_ALLOW_PRODUCTION	—	设为 1 作为独立的生产环境选择加入标记；其他配置会忽略此项。
SIGNALEDI_MCP_TELEMETRY	已启用	设为 0 可禁用本地脱敏指标行。指标包含工具、配置、结果/代码、延迟和请求 ID，不包含有效载荷或机密信息。

服务器仅向 stdout 写入 JSON-RPC，并且仅向 stderr 写入日志。

暂不支持的功能

对于尚无稳定、租户隔离 API 支持的托管功能，MCP 不会虚构实现：

• suggest_mapping 和 validate_mapping 等待结构化映射验证服务和合作伙伴指南来源信息契约就绪。
• create_sandbox_project、create_test_partner、submit_test_document 和 get_test_results 等待稳定的租户隔离生命周期/测试路由就绪。
• generate_webhook_fixture 和 verify_webhook_signature 等待统一的运行时签名契约；当前主要投递/重放路径与补救路径的签名方式不同。
• 生产环境不开放凭据轮换、原始网关配置、映射部署、任意合作伙伴编辑、手动证据/生命周期声明、生产激活/回滚/隔离、QBO 同步/断开连接，以及文档重新传输。生产配置仅限于上文所述的白名单读取操作，以及由服务器门控的草稿/配置/连接测试/上线请求/出站/QBO 导出操作。

本地开发

node test.mjs
npm run test:stdio
npm start

单元测试使用合成数据和模拟 HTTP。stdio 集成测试会在不调用实时 API 的情况下测试 docs、sandbox 和 production 的发现流程。有关发布门槛，请参阅 RELEASE_NOTES_0.5.0.md。

架构与仓库权威性

MCP client
  <-> @signaledi/mcp-server over stdio
      |- public documentation resources and local synthetic helpers
      `- profile-gated calls to the conventional SignalEDI /api/v1 REST API

独立的 GitHub 仓库 SignalEDI/mcp-server 是规范来源，也是 npm/MCP Registry 自动发布的唯一授权来源。私有仓库 SignalEDI/platform 可以保留一份同步的验证快照，用于其托管 API/后端契约；请参阅 MIRROR.md。所有示例均为合成数据，必须确保不包含客户、健康、财务和凭据数据。