Mosaic MCP

Mosaic MCP服务器

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

特性

事务管理

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

V3 API支持

• 列表_关系_v3：检索关系的分页列表（V3）
• get_organization_me_v3：检索当前用户的组织信息（V3）
• convert_data_v3：JSON和X12格式之间的转换（V3）
• list_transactions_v3：使用各种筛选器列出事务（V3）
• get_transaction_v3：按ID获取特定交易（V3）
• get_transaction_message_v3：获取特定事务的消息内容（V3）
• 生成器标签v3：生成PDF或ZPL格式的装运标签（V3）

模式理解

• 采购订单架构：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

1. 编辑 .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 -获取自己的组织详细信息
• POST /v3/convert -在JSON和X12之间转换数据
• GET /v3/transactions -列出交易记录（V3）
• GET /v3/transactions/{transactionId} -获取特定交易（V3）
• GET /v3/transactions/{transactionId}/message -获取交易消息（V3）
• POST /v3/labels -生成发货标签（V3）

采购订单架构结构

服务器通过以下关键组件全面了解采购订单模式（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服务器的起点。