YonSuite MCP Gateway Skill

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

工具清单

> 📎 所有工具返回 {"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 配置文件位置

配置示例（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. 压力测试 — 切分潜在混淆变量、比较正确基线、量化不确定性、检查敏感性。不做压力测试的数据不交付

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

典型业务场景

客户销售分析

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 平台的业务查询；纯财务凭证/账簿/总账类查询。