shield_lock
金大哥
← 返回 Skill 列表
extension
分类: 数据与分析需要 API Key

YonSuite MCP Gateway

YonSuite 业务数据网关，通过 MCP 协议提供数据查询与操作能力。暴露数据查询工具（销售/采购/生产/库存/客户/供应商/商机/待办等），后续扩展写数据操作。必须加载此技能的场景：用户要操作 YonSuite 业务数据——查销售订单、采购订单、生产工单、库存现存量、商机列表；查基础档案——客户、供应商、物料；做数据分析并出 HTML 报告。即使只说'查一下销售数据'、'看下库存'、'这个月采购了多少'、'帮我出份报告'、'查个客户'、'看下待办'也应触发。不适用：YonSuite 系统配置与权限管理；YS-Agent项目本身的操作；非 YonSuite 平台的业务查询；纯财务凭证/账簿/总账类查询。

person作者: user_6b69962fhubcommunity
download下载资源包

YonSuite MCP Gateway Skill

YonSuite 业务数据网关，通过 MCP 协议查询与操作业务数据。

工具清单

| 工具 | 用途 | |------|------| | mcp_yonsuite_query_sale_orders | 销售订单（支持日期筛选、汇总/明细模式） | | mcp_yonsuite_query_purchase_orders | 采购订单 | | mcp_yonsuite_query_production_orders | 生产订单 | | mcp_yonsuite_query_products | 物料档案 | | mcp_yonsuite_query_customers | 客户档案 | | mcp_yonsuite_query_vendors | 供应商档案 | | mcp_yonsuite_query_current_stock | 库存现存量 | | mcp_yonsuite_query_user_todos | 待办事项 | | mcp_yonsuite_query_opportunities | 商机列表 | | mcp_yonsuite_ys_api | 通用 YonSuite API 调用 |

📎 所有工具返回 {"records": [...], "summary": {"recordCount": N, "grandTotal": X, "grandTax": Y}}，字段已中文映射、税额已自动计算。 📎 采购分析完整工作流见 references/purchase-analysis-workflow.md（含 MCP 取数→计算口径→图表选型→决策输出→压力测试）

首次安装

pip install git+https://atomgit.com/gcw_cJbJuamU/yonsuite-mcp-server.git

设置凭证（写入 ~/.zshrc 或环境变量）：

export YONSUITE_APP_KEY=your_app_key
export YONSUITE_APP_SECRET=your_app_secret
export YONSUITE_TENANT_ID=your_tenant_id

注册 MCP：

hermes mcp add yonsuite --command ys-mcp-server \
  --env YONSUITE_APP_KEY=xxx YONSUITE_APP_SECRET=xxx YONSUITE_TENANT_ID=xxx

⚠️ --env 后面跟一个 KEY=VALUE 对，要传多个环境变量就按 --env KEY1=val1 KEY2=val2 KEY3=val3 依次排列，实测全部生效。 ⚠️ hermes mcp add 会弹出交互式确认「Enable all N tools? [Y/n/select]」。Agent 环境不能交互，用 echo y | 管道应答：echo y | hermes mcp add yonsuite --command ys-mcp-server --env ...。当前版本不支持 --approve/--yes 等跳过标志。 ⚠️ hermes mcp add 会弹出交互式确认「Enable all N tools? [Y/n/select]」。Agent 环境不能交互，用 echo y | 管道应答：echo y | hermes mcp add yonsuite ...。当前版本不支持 --approve/--yes 等跳过标志。

跨 Agent 配置

除 Hermes 外，YonSuite MCP 也可在其他 AI Agent 中配置使用，格式均为 MCP 标准 JSON 配置（Stdio 协议）。

通用 JSON 格式

{
  "mcpServers": {
    "yonsuite": {
      "command": "ys-mcp-server",
      "args": [],
      "env": {
        "YONSUITE_APP_KEY": "your_app_key",
        "YONSUITE_APP_SECRET": "your_app_secret",
        "YONSUITE_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

Agent 配置文件位置

| Agent | 配置文件 | 说明 | |-------|---------|------| | Claude Code | ~/.claude/settings.json → mcpServers | 全局生效，也可在项目级 .claude/settings.local.json 中覆盖 | | Cursor | ~/.cursor/mcp.json (全局) 或 .cursor/mcp.json (项目级) | 项目级优先级更高 | | Windsurf | ~/.codeium/windsurf/mcp_config.json | 全局配置 | | Codex | ~/.codex/mcp.json | 全局配置 | | OpenCode | ~/.config/opencode/opencode.jsonc | JSONC 格式，支持注释 | | Zed | 通过 ACP Registry 或 MCP 插件配置 | 需安装 MCP 插件后在设置中填入 | | Continue.dev | ~/.continue/config.json → experimental.mcpServers | VS Code/JetBrains 插件 | | OpenClaw | claw.yaml → mcp_servers | YAML 格式，与 Hermes 类似 |

配置示例（Claude Code）

在 ~/.claude/settings.json 中添加：

{
  "mcpServers": {
    "yonsuite": {
      "command": "ys-mcp-server",
      "env": {
        "YONSUITE_APP_KEY": "your_app_key",
        "YONSUITE_APP_SECRET": "your_app_secret",
        "YONSUITE_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

配置示例（Cursor）

在 ~/.cursor/mcp.json 中添加：

{
  "mcpServers": {
    "yonsuite": {
      "command": "ys-mcp-server",
      "env": {
        "YONSUITE_APP_KEY": "your_app_key",
        "YONSUITE_APP_SECRET": "your_app_secret",
        "YONSUITE_TENANT_ID": "your_tenant_id"
      }
    }
  }
}

⚠️ 跨 Agent 配置前需先完成 pip install 安装 ys-mcp-server 包。所有 Agent 共享同一个 Python 环境的已安装包，只需配一个 JSON 文件即可。

业务数据分析链路

取数后分析出报告，走两段流程：

① 加载 data-analysis 技能

先 skill_view(name='data-analysis') 加载，按 7 步法走：

  1. 从决策出发 — 问：这个分析支持什么决策？如果数据不会改变决策，先重构问题
  2. 锁定指标契约 — 定义实体、颗粒度、分子分母、排除项、时间窗口、时区、数据源。口径含糊就不往下算
  3. MCP 取数 — 用 mcp_yonsuite_* 查询工具。先加日期/名称过滤，汇总模式看全貌，再决定是否拉明细
  4. 分离提取/转换/解释 — 查询逻辑、清洗假设、分析结论分开写，不把业务假设藏在计算里
  5. 图表选型 — 趋势→折线，对比→柱状，组成→饼图，关系→散点。不加不改变决策的图
  6. 决策格式输出 — 答案 + 证据 + 置信度 + 限制条件 + 建议下一步，按 decision-briefs.md 模板
  7. 压力测试 — 切分潜在混淆变量、比较正确基线、量化不确定性、检查敏感性。不做压力测试的数据不交付

② 输出形式（择一或组合）

| 形式 | 姿势 | |:----|:----:| | 口头分析 | 按 decision-brief 模板，结论先行，method 靠后 | | HTML 报告 | 用 references/*-report-template.html 模板手写，用友红橙蓝配色 + G2Plot 图表 | | 正式 PPT | 加载 cyber-ppt 生成 |

典型业务场景

客户销售分析

query_customers(name) → 定位客户 → query_sale_orders() 拉数据 → 汇总金额、分析趋势 → 如需出报告走分析链路

库存检查

query_products(code/name) → 找物料 → query_stock(sku, warehouse) → 查现存量（禁 product_id）

订单跟踪

query_sale_orders(date_from, date_to) → 状态已中文映射，is_sum=true 按订单汇总、is_sum=false 按商品明细分列

商机跟进

query_opportunities(oppt_state="0") → 进行中的商机，金额自动处理，配合客户档案分析

待办处理

query_user_todos() → 单据类型已自动映射 → 根据类型调对应工具查看详情

注意事项

  • 查询先加日期/名称过滤，避免全量拉取
  • query_stock 用 sku 或 warehouse，不用 product_id
  • query_production_orders 日期过滤在客户端侧，大数据量注意性能
  • ys_api 的 get_*_detail 方法（如 get_purchase_order_detail）不吃订单编码（如 PO260709-0001），它需要内部数字 ID 作为「主表关联标识」。目前明细查询不可用，查询结果中的物料名称为空是已知限制
  • 分析链路：先加载 data-analysis 技能按 7 步法走，再选择输出形式（口头/HTML/PPT）

适用场景

YonSuite 业务数据网关，通过 MCP 协议提供数据查询与操作能力。暴露数据查询工具（销售/采购/生产/库存/客户/供应商/商机/待办等），后续扩展写数据操作。必须加载此技能的场景：用户要操作 YonSuite 业务数据——查销售订单、采购订单、生产工单、库存现存量、商机列表；查基础档案——客户、供应商、物料；做数据分析并出 HTML 报告。即使只说'查一下销售数据'、'看下库存'、'这个月采购了多少'、'帮我出份报告'、'查个客户'、'看下待办'也应触发。不适用：YonSuite 系统配置与权限管理；YS-Agent项目本身的操作；非 YonSuite 平台的业务查询；纯财务凭证/账簿/总账类查询。