AI导哈

EDI交易管理服务器

为Orderful的Mosaic交易API提供模型上下文协议(MCP)服务，支持创建和管理EDI交易，并理解采购订单和其他EDI文档结构。

  • by Will-orderful
  • TypeScript
  • 本地部署
  • 1 星标
  • 更新于
在 GitHub 查看 Will-orderful/mosaicMCP

使用说明

Mosaic MCP服务器

用于Orderful Mosaic事务API的MCP（模型上下文协议）服务器，具有全面的EDI模式理解。该服务器为AI模型提供安全访问，以创建和管理EDI交易，同时了解采购订单和其他EDI文档模式的结构。

特性

事务管理

  • create_transaction：创建EDI交易（850份采购订单、855份确认书、856份发货通知、810份发票）
  • 接受_交付：接受带票据的交易交付
  • 故障_交付：带票据的交易交付失败
  • get_delivery：检索交货详细信息和状态
  • list_inbox_transactions：从特定收件箱获取交易

复合交易（旧版未版本化 /transactions)

  • list_交易：列出带有过滤器的复合事务（方向、业务编号、类型、流、ISA ID、状态、创建时间范围）
  • get_transaction：通过数字EDI交易ID获取复合交易
  • get_posite_transaction：通过UUID获取复合事务
  • get_transaction_errors：获取复合事务的集成有效负载或验证错误

授权警告：这四个端点需要使用代理组织上下文进行WEB_ANY承载令牌身份验证。仅通过以下方式进行身份验证的呼叫 orderful-api-key 返回403。使用v3等效项(list_transactions_v3, get_transaction_v3)用于API-key工作流。

V3 API支持

  • 列表_关系_v3：贸易伙伴关系分页列表
  • get_organization_me_v3：您的组织详细信息（ISA ID、帐户）
  • list_transactions_v3：使用过滤器进行历史交易搜索（日期范围、流、发送方/接收方ISA、类型、业务编号、验证/交付/确认状态、参考标识符）
  • get_transaction_v3：检索单个交易，可选地使用 expand=message
  • get_transaction_message_v3：检索事务的Orderful JSON消息有效负载
  • create_transaction_v3：V3使用发送方/接收方对象创建流（仅限测试流）
  • create_transaction_raw_v3：从原始EDI（例如原始X12）创建交易（仅限测试流）
  • confirm_delivey_v3：批量确认交货状态(DELIVERED / FAILED)对于一个或多个交易
  • get_transaction_aknowledgment_v3：获取交易的确认记录
  • set_transaction_aknowledgment_v3：设置确认状态(ACCEPTED / REJECTED)带有可选错误消息
  • convert_data：在格式之间转换（例如原始X12↔ 有序JSON）通过 /v3/convert
  • generate_label：通过生成运输标签 /v3/labels

模式理解

  • 采购订单架构：EDI 850采购订单结构的详细Zod模式
  • 确认模式：EDI 855采购订单确认结构的详细Zod模式
  • 发货通知架构：EDI 856预先发货通知结构的详细Zod模式
  • 发票架构：EDI 810发票结构的详细Zod模式

资源

  • info://server-info：服务器功能和配置
  • info://authentication-guide：关于如何获取Orderful API密钥的说明
  • schema://purchase-order：主采购订单Zod模式
  • schema://purchase-order-acknowledgment：主采购订单确认Zod模式
  • schema://advance-ship-notice：主要提前发货通知Zod模式
  • schema://invoice：主发票Zod模式
  • schema://v3/components：Mosaic V3端点的OpenAPI组件模式
  • links://orderful-documentation：有序Mosaic API文档链接
  • links://edi-standards：EDI标准和X12规范的链接
  • links://transaction-guides：Mosaic API集成和最佳实践指南
  • links://label-templates：经过认证的UCC-128标签模板目录
  • zod://shared：EDI的常见Zod模式组件
  • zod://po：采购订单（850）Zod文件
  • zod://poack：订单确认书（855）Zod文件
  • zod://invoice：发票（810）Zod文件
  • zod://asn：预先发货通知（856）Zod文件

快速入门（直接从GitHub）

使用此MCP服务器的最简单方法是直接从GitHub下载，而无需下载任何内容。

克劳德桌面版

添加到您的Claude桌面配置(~/Library/Application Support/Claude/claude_desktop_config.json 在macOS上）：

{
  "mcpServers": {
    "mosaic": {
      "command": "npx",
      "args": ["github:Will-orderful/mosaicMCP"],
      "env": {
        "MOSAIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

克劳德代码

添加到您的Claude Code MCP设置中：

{
  "mcpServers": {
    "mosaic": {
      "command": "npx",
      "args": ["github:Will-orderful/mosaicMCP"],
      "env": {
        "MOSAIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

光标

添加到光标MCP配置(~/.cursor/mcp.json):

{
  "mcpServers": {
    "mosaic": {
      "command": "npx",
      "args": ["github:Will-orderful/mosaicMCP"],
      "env": {
        "MOSAIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

帆板运动

添加到您的Windsurf MCP配置(~/.codeium/windsurf/mcp_config.json):

{
  "mcpServers": {
    "mosaic": {
      "command": "npx",
      "args": ["github:Will-orderful/mosaicMCP"],
      "env": {
        "MOSAIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Cline（VS代码扩展）

添加到您的VS代码设置(settings.json):

{
  "cline.mcpServers": {
    "mosaic": {
      "command": "npx",
      "args": ["github:Will-orderful/mosaicMCP"],
      "env": {
        "MOSAIC_API_KEY": "your-api-key-here"
      }
    }
  }
}

Continue.dev

添加到您的继续配置(~/.continue/config.json):

{
  "mcpServers": [
    {
      "name": "mosaic",
      "command": "npx",
      "args": ["github:Will-orderful/mosaicMCP"],
      "env": {
        "MOSAIC_API_KEY": "your-api-key-here"
      }
    }
  ]
}

泽德

添加到Zed设置(~/.config/zed/settings.json):

{
  "context_servers": {
    "mosaic": {
      "command": {
        "path": "npx",
        "args": ["github:Will-orderful/mosaicMCP"],
        "env": {
          "MOSAIC_API_KEY": "your-api-key-here"
        }
      }
    }
  }
}

替换 your-api-key-here 使用您的Orderful API密钥。请参阅 身份验证指南 下面介绍如何获取API密钥。

备注：无论您使用哪种LLM后端（Claude、GPT-4、Gemini等），这些工具都支持MCP（模型上下文协议）。

本地安装（替代方案）

如果您更喜欢在本地运行或需要修改服务器：

  1. 克隆或下载此存储库
  2. 安装依赖项：
    npm install

配置（本地安装）

  1. 复制环境模板：

    cp env-example.txt .env

  2. 编辑 .env 使用您的Orderful API凭证：

    MOSAIC_API_KEY=your_actual_api_key_here
MOSAIC_API_BASE_URL=https://api.orderful.com  # Optional, defaults to production API
MOSAIC_ORGANIZATION_ID=your_org_id_here       # Optional, if required by your setup

获取API证书

获取您的Orderful API凭证：

  1. 登录Orderful https://app.orderful.com
  2. 导航到 设置 （左侧菜单中的齿轮图标）
  3. 选择 API密钥 从设置子菜单
  4. 你的 组织ID 显示在页面顶部
  5. 创建或复制现有API密钥（使用 测试 发展关键）

备注：在开发集成时，请始终使用测试API密钥，以避免影响生产数据。

用法

运行服务器

使用以下命令启动MCP服务器：

npm start

或者直接使用Node.js：

node server.js

连接到MCP客户端

此服务器使用stdio传输，使其与支持stdio连接的MCP客户端兼容。服务器将启动并等待MCP协议消息。

示例用法

连接到MCP兼容客户端（如Claude Desktop或其他MCP主机）后，您可以：

创建交易：

// Create a purchase order
create_transaction({
  type: "850_PURCHASE_ORDER",
  stream: "test",
  message: {
    purpose: "original",
    purchaseOrderType: "standalone",
    purchaseOrderNumber: "PO-12345",
    purchaseOrderDate: "2025-01-15",
    // ... full purchase order structure
  },
  senderId: "BUYER001",
  receiverId: "SUPPLIER001"
})

管理交付：

// Accept a delivery
accept_delivery({
  transactionId: 12345,
  deliveryId: "delivery-uuid",
  note: "Order received successfully"
})

// Get delivery details
get_delivery({
  transactionId: 12345,
  deliveryId: "delivery-uuid"
})

理解模式：

// Get purchase order schema details
read_resource({
  uri: "schema://purchase-order"
})

身份验证帮助：

// Learn how to obtain your API keys
read_resource({
  uri: "info://authentication-guide"
})

访问文档链接：

// Get Orderful Mosaic API documentation links
read_resource({
  uri: "links://orderful-documentation"
})

// Find EDI standards and specifications
read_resource({
  uri: "links://edi-standards"
})

// Access Mosaic integration guides
read_resource({
  uri: "links://transaction-guides"
})

// Access the Label Template Directory
read_resource({
  uri: "links://label-templates"
})

Zod模式的基础：

// Read the primary Purchase Order Zod schema
read_resource({
  uri: "zod://po"
})

// Read shared schema components (Parties, Quantities, etc.)
read_resource({
  uri: "zod://shared"
})

收件箱管理：

// List transactions in an inbox
list_inbox_transactions({
  inboxId: 123,
  limit: 50
})

V3 API使用示例：

列出关系：

list_relationships_v3({
  autoSend: "ENABLED",
  limit: 10
})

转换数据：

convert_data_v3({
  content: { /* JSON object */ },
  contentType: "application/json",
  accept: "application/edi-x12"
})

生成标签：

generate_label_v3({
  labelData: {
    type: "WALMART_PALLET_SINGLE",
    shipFrom: { name: "Your Company", ... },
    shipTo: { name: "Walmart DC", ... },
    // ... rest of label data
  },
  format: "pdf"
})

支持的API端点

事务端点

  • POST /transactions -创建新的EDI交易
  • POST /transactions/{transactionId}/deliveries/{deliveryId}/accept -接受交货
  • POST /transactions/{transactionId}/deliveries/{deliveryId}/fail -交货失败
  • GET /transactions/{transactionId}/deliveries/{deliveryId} -获取交货详细信息
  • GET /inboxes/{inboxId}/transactions -在收件箱中列出交易记录

V3 API端点

  • GET /v3/relationships -列出关系
  • GET /v3/organizations/me -获取自己的组织详细信息
  • GET /v3/transactions -列出/搜索交易记录
  • GET /v3/transactions/{transactionId} -获取交易
  • GET /v3/transactions/{transactionId}/message -获取交易消息
  • POST /v3/transactions -创建交易（V3）
  • POST /v3/transactions/raw -从原始EDI创建
  • POST /v3/transactions/confirm-delivery -批量确认交货
  • GET /v3/transactions/{transactionId}/acknowledgment -获得确认
  • POST /v3/transactions/{transactionId}/acknowledgment -设置确认
  • POST /v3/convert -在不同格式之间转换数据
  • POST /v3/labels -生成发货标签

注意 list_transactions_v3 日期过滤器：the createdAt 查询使用区间表示法 [startISO,endISO)示例： createdAt=[2026-04-15T00:00:00Z,2026-05-15T23:59:59Z).

安全: create_transaction, create_transaction_v3，以及 create_transaction_raw_v3 只允许TEST流——live在客户端被阻止。

采购订单架构结构

服务器通过以下关键组件全面了解采购订单模式（EDI 850）：

标题信息

  • 目的：交易目的（原始、取消、变更等）
  • purchaseOrderType：订单类型（独立、直运、一揽子等）
  • 采购订单编号：唯一订单标识符
  • 购买订单日期：订单发布日期

派对

  • 买方：采购方信息
  • 船。：交货目的地
  • billTo：计费地点
  • 供应商：产品/服务提供商
  • 应付帐款：付款处理方

系列商品

  • purchaseOrderLineId：行项目标识符
  • 数量：订购数量
  • 价格：：定价信息
  • 产品ID：产品标识（SKU、UPC等）
  • 产品属性：产品规格
  • 参考文献：线路级参考号

财务信息

  • 买方货币/卖方货币：货币规格
  • 销售条款：付款条件
  • 税：税务计算
  • 津贴/费用：订单总额调整

物流

  • 承运商详细信息：运输和路线信息
  • 日期：各种订单相关日期
  • 包装：包装要求

项目结构

.
├── package.json           # Project configuration and dependencies
├── server.js              # Main MCP server implementation
├── env-example.txt        # Environment configuration template
├── referenceResources/
│   └── docs.json         # OpenAPI specification for supported endpoints
├── zod/                  # Zod schema definitions
│   ├── po.zod.ts         # Purchase Order schema
│   ├── poAck.zod.ts      # Purchase Order Acknowledgment schema
│   ├── asn.zod.ts        # Advance Ship Notice schema
│   ├── invoice.zod.ts    # Invoice schema
│   └── shared.zod.ts     # Shared schema components
└── README.md             # This documentation

支持的交易类型

  • 850_采购_订购：采购订单交易
  • 855_采购_订单_知识：采购订单确认书
  • 856_装运通知_舱单：提前发货通知
  • 810_语音：发票交易记录

需求

  • Node.js 18.0.0或更高版本
  • npm用于包管理
  • 有效的有序API凭证

许可证

MIT许可证-您可以自由地将此代码用作您自己的MCP服务器的起点。

相关 MCP