ediFabric EDI

ediFabric MCP 服务

一个用于 EDI 的 MCP 服务，目前支持 X12 和 HIPAA。它可让 Claude、Cursor 和 GitHub Copilot 等 AI 助手使用你本机上的 ediFabric Native 将 EDI 转换为 JSON，或将 JSON 转回 EDI、验证文件，以及生成 997 和 999 回执。

你的 EDI 文件会保留在本机：服务在本地读取和写入文件，并向助手返回摘要，而非整个文件。

工具

工具	功能
parse_edi	将 EDI 文件转换为 JSON 并保存到文件，同时汇总交换和事务集
validate_edi	将 EDI 文件验证到 HIPAA SNIP 级别 4，并返回每个错误及其所在的段
acknowledge_edi	为 X12 文件保存 999 或 997；如果交换要求 TA1，也会一并生成
build_edi	将 EDI JSON 转换为 EDI 文件
split_edi	将文件中的每个事务集分别保存为独立的 EDI 文件
describe_spec	根据其他工具使用的模型描述事务集（标准或自定义）：列出循环和段及其 JSON 属性名称，或列出某个段的元素、类型、长度、代码和语法规则。使用 output: skeleton 时，会生成 JSON，其中包含供 build_edi 填写的必需部分
get_status	显示许可证及其检查方式、模型来源和允许使用的文件夹

工具会自动检测文件格式，也可通过可选的 format 参数指定格式。

可以尝试这样提问：

• “将 claims.837 验证到 SNIP 级别 4，并解释每个错误。”
• “为 inbound 文件夹中的每个文件生成 999。”
• “将 po.edi 转换为 JSON，把第 2 行的数量改为 12，再将其转回 X12。”
• “004010 中的 856 是什么样的？创建一个示例。”

安装

你需要 Node.js 18 或更高版本。服务可在 Windows x64、Linux x64 和 arm64，以及搭载 Apple silicon 的 macOS 上运行。

如果未设置 EDIFABRIC_SERIAL，服务会使用免费的演示序列号，该序列号每日配额较少，不适用于生产环境。请使用你从账户获取的专属序列号。

Claude Code

将其作为插件安装，安装时会要求你提供序列号，并将序列号保存在系统凭据存储中：

/plugin marketplace add EdiFabric/edifabric-mcp
/plugin install edifabric@edifabric

也可以单独添加该服务：

claude mcp add edifabric -e EDIFABRIC_SERIAL=YOUR_SERIAL -- npx -y @edifabric/mcp

在 Windows 上（不使用 WSL），通过 cmd 运行 npx：claude mcp add edifabric -e EDIFABRIC_SERIAL=YOUR_SERIAL -- cmd /c npx -y @edifabric/mcp。

Claude Desktop

从最新版本下载 edifabric-mcp-<version>.mcpb 并打开。Claude Desktop 会安装它，并要求你提供序列号和 EDI 文件夹。安装包已包含所有内容，因此无需 Node.js。

也可以在 Settings、Developer、Edit Config 下，将以下内容添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "edifabric": {
      "command": "npx",
      "args": ["-y", "@edifabric/mcp"],
      "env": {
        "EDIFABRIC_SERIAL": "YOUR_SERIAL",
        "EDIFABRIC_ALLOWED_DIRS": "C:\\EDI"
      }
    }
  }
}

Cursor

将以下内容添加到项目中的 .cursor/mcp.json，或添加到 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "edifabric": {
      "command": "npx",
      "args": ["-y", "@edifabric/mcp"],
      "env": { "EDIFABRIC_SERIAL": "YOUR_SERIAL" }
    }
  }
}

VS Code

将以下内容添加到 .vscode/mcp.json：

{
  "servers": {
    "edifabric": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@edifabric/mcp"],
      "env": { "EDIFABRIC_SERIAL": "YOUR_SERIAL" }
    }
  }
}

OpenAI Codex

将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.edifabric]
command = "npx"
args = ["-y", "@edifabric/mcp"]
env = { EDIFABRIC_SERIAL = "YOUR_SERIAL" }

Gemini CLI、Windsurf 等

Gemini CLI（~/.gemini/settings.json）、Windsurf（~/.codeium/windsurf/mcp_config.json）、Cline 和大多数其他客户端使用与 Claude Desktop 相同的 mcpServers 条目。

其他 MCP 客户端使用相同的命令 npx -y @edifabric/mcp 和相同的环境变量。

配置

变量	作用
EDIFABRIC_SERIAL	你的 ediFabric 序列号。默认使用演示序列号
EDIFABRIC_TOKEN	为你签发的令牌，供无法访问互联网的机器使用。参见许可与配额
EDIFABRIC_TOKEN_CACHE	缓存令牌的文件夹；设为 none 则仅将令牌保留在内存中。默认使用你的用户缓存文件夹
EDIFABRIC_ALLOWED_DIRS	工具可读写的文件夹，在 Windows 上以 ; 分隔，在其他系统上以 : 分隔。未设置时，服务使用 MCP 客户端共享的文件夹，或你的主文件夹
EDIFABRIC_MAP	包含本地或自定义模型的 map.json。参见模型
EDIFABRIC_OFFLINE	设为 true，仅使用 EDIFABRIC_MAP 中的模型
EDIFABRIC_LIBRARY	ediFabric Native 库的路径；如果使用的是随软件包安装的版本，则无需设置

模型

每个事务集都会使用与其类型和版本对应的模型进行读取和验证。默认情况下，服务会从 EdiNation 下载标准 X12 和 HIPAA 模型；它只会发送事务类型和版本，绝不会发送文件内容。

要使用本地或自定义模型（例如你在 EDI Spec Builder 中创建并为 ediFabric Native 下载的模型），请将它们列在 map.json 中，并将 EDIFABRIC_MAP 设为该文件：

{
  "default": "",
  "maps": {
    "837:005010X222A1": { "type": 1, "name": "model837P.json", "location": "." },
    "850:004010": { "type": 1, "name": "acme-850.json", "location": "models" }
  }
}

每个键都是来自 ST 或 GS 的事务集和版本。location 是相对于映射文件的路径。映射中未列出的事务仍会使用在线模型，除非 EDIFABRIC_OFFLINE 为 true。

describe_spec 也会以相同方式查找模型，因此也能描述你的自定义模型。它只会将下载的模型保留在内存中，绝不会保存它们。

许可与配额

许可证的检查方式取决于你的套餐。你无需选择：设置 EDIFABRIC_SERIAL 后，get_status 会显示适用的方式。

套餐	工作方式
Community	每次读取或写入 EDI 的工具调用都会在线检查并计入配额，因此服务需要互联网连接。每天最多可进行 250 次操作；参见定价
Developer	服务会获取此机器专用的令牌并保存，因此操作会在本地检查，重启时无需调用许可证服务。令牌会自动续期。此套餐最多支持 3 台机器
Enterprise、Perpetual	工作方式相同，但令牌不限定用于一台机器
已签发的令牌	将为你签发的令牌设为 EDIFABRIC_TOKEN，例如用于 Perpetual 许可证或无法访问互联网的站点。服务不会调用许可证服务。若同时未设置 EDIFABRIC_SERIAL，则只能使用 EDIFABRIC_MAP 中的模型

升级时，如果序列号未变，请保留原序列号；否则，将新序列号设为 EDIFABRIC_SERIAL，然后重启 MCP 客户端。describe_spec 和 get_status 不会读取或写入 EDI，因此不计为操作。与其他工具一样，describe_spec 会使用你的序列号下载模型。

此 MCP 服务基于 MIT 许可证开源。它通过 edifabric-x12 软件包使用的 ediFabric Native（用于 X12）遵循 ediFabric EULA 授权。

开发

npm install
npm test

测试需要 Node.js 22.9 或更高版本，以使用 --env-file-if-exists。测试会使用 test/fixtures 中的示例模型，并需要一个尚有配额的序列号。在 .env.local 文件中设置 EDIFABRIC_SERIAL=YOUR_SERIAL（该文件会被 git 忽略），或设置相应变量。测试需要 ediFabric Native 120 或更高版本：如果已安装的包版本较旧，请设置 EDIFABRIC_LIBRARY。设置 EDIFABRIC_ONLINE_TESTS=1，即可包含会在线下载模型的测试。若要交互式试用该服务，请运行 npm run inspect。

添加格式

每种 EDI 格式都在 src/formats 中有一个模块，并配有自己的 ediFabric Native 库和绑定包。若要添加一种格式，例如使用 edifabric-edifact-tools 添加 EDIFACT，请编写一个模块，使其成员与 src/formats/x12/index.js 相同，并在 src/formats/index.js 中注册。这样，工具、许可和模型便可用于该格式。只有在使用该格式的文件时，才会加载其库，因此绑定包可以设为可选依赖。test/formats.test.js 展示了一个使用替代库的完整示例。