客户端接入 / 本地 MCP stdio 接入
MCP / STDIO

本地 MCP stdio 接入

让支持stdio MCP的客户端自己启动DataNavoAPI工具进程。先从匿名样本开始,再按需连接客户Key和TEST预算。

配置DataNavoAPI本地stdio MCP,区分匿名demo与客户simulated,按find、describe、quote、call和read_more完成显式调用,用account只读查询账户与用量。

先启动网站,保留完整项目

在DataNavoAPI项目目录运行npm run local。MCP进程通过本机HTTP连接网站;它不是一个独立数据后端,也不是远程MCP地址。

保留完整项目,入口脚本复用public/sdk/guanliu.mjs。客户端启动node scripts/mcp-server.mjs,不能用npm包装命令把启动日志混入stdio协议。

匿名演示配置

把args里的占位路径换成DataNavoAPI项目的真实绝对路径。command可使用本机Node绝对路径;这有助于GUI客户端找不到node时定位运行时。

demo是默认模式,四个工具为find、describe、call、read_more。无需客户Key,不消耗TEST,也没有客户quote或account工具。

JSON / DEMO CONFIG
{
  "mcpServers": {
    "guanliu": {
      "command": "node",
      "args": [
        "/absolute/path/to/guanliu/scripts/mcp-server.mjs"
      ]
    }
  }
}

客户模拟配置

需要预算和结算时,显式设置simulated及客户Key。Key只放在你的本机客户端配置,不发到聊天或工具参数。修改环境配置后需重启对应MCP进程。

配置中的Key是占位符,必须替换。live模式使用gl_live_只读已有真实记录;缺少有效Key或非法端口会启动失败,不会自动降级。主机固定127.0.0.1,默认端口4321。

JSON / CUSTOMER CONFIG
{
  "mcpServers": {
    "guanliu": {
      "command": "node",
      "args": [
        "/absolute/path/to/guanliu/scripts/mcp-server.mjs"
      ],
      "env": {
        "GUANLIU_MCP_MODE": "simulated",
        "GUANLIU_MCP_PORT": "4321",
        "GUANLIU_CUSTOMER_API_KEY": "YOUR_GL_TEST_CUSTOMER_KEY"
      }
    }
  }
}

用七个工具保留决策顺序

客户模式增加quote、account和run。quote与account只读;run创建预算需要显式确认,读取预算不执行。按find发现、describe读合同、quote读当前费用与条件,再由你确认call。只有call或read_more可能产生本地TEST消费。

  • find:按query或platform查公开目录,不执行。
  • describe:用capability读取参数和演示输入。
  • quote:客户模式只读价格、钱包、预算与blockers,不预留。
  • account:只读账户钱包、当前Key预算、用量和回执;standing按原幂等编号只读查询。
  • run:显式confirm后创建本地TEST任务预算,需独立幂等编号;get只读,不发起数据调用。
  • call:客户模式必填idempotency_key,可设scenario和max_credits。
  • read_more:使用mcp.next_page_token继续下一页,继承参数、场景和最高单价。
MCP / FIRST QUOTE
{
  "tool": "quote",
  "arguments": {
    "capability": "x.users.get",
    "params": {
      "username": "guanliu_demo"
    },
    "max_credits": 1
  }
}

查询共享钱包与当前Key用量

account省略what或设置balance时读取账户与预算,balance不接受filters;what=usage时接受status、capability、UTC日期from/to、page、pageSize过滤。默认all、第1页、20条,pageSize可选20/50/100。

钱包由所有Key共享,预算随轮换组继承;用量仅属于当前Bearer Key,不是每次重试次数。用量按记录时间、预算按准入时间计算。新Key不会继承旧Key的用量列表。

成功outcome=read,失败not_executed,outcome_unknown始终为false;无幂等编号和下一页令牌。下一页再次调用account并显式指定page,不使用read_more,不自动翻页或扣点。

MCP / READ ONLY
{
  "tool": "account",
  "arguments": {
    "what": "usage",
    "filters": {
      "status": "all",
      "page": 1,
      "pageSize": 20
    }
  }
}

用account读取模拟执行回执

客户模式为七个工具。account的what可为balance、usage、calls、receipt或result。calls支持state与分页筛选;receipt/result必须提供原请求UUID request_id,且不接受filters。

读取已保存结果不会继续原执行。result外层HTTP200和outcome=read表示本次读取成功;data.response.status保存原成功、失败或超时状态。pending的结果读取返回409,outcome_unknown=false。

MCP / SAVED CALLS
{
  "tool": "account",
  "arguments": {
    "what": "calls",
    "filters": {
      "state": "all",
      "page": 1,
      "pageSize": 20
    }
  }
}

从MCP结果识别执行状态

报价outcome=quoted仅表示报价读取成功;检查data.eligible。执行HTTP200是succeeded,202是pending。isError=false的pending不能当成业务成功。

next_page_token只在当前进程保留10分钟,重启后失效。客户下一页使用新编号,同一页重试继续用原编号;MCP不自动轮询或翻页。

运输结果unknown时保留原参数、场景、编号手动查回执。不能因为MCP进程重启就把同一任务当作新请求执行。

按边界排查连接

连不上网站:核对本机服务和GUANLIU_MCP_PORT。脚本找不到:核对项目完整性与绝对路径。没有quote或account:确认当前是simulated而不是demo。

401/403:检查Key有效期与能力权限。402:查看报价blockers及预算。409:检查同一编号是否混用了参数或场景。调用失败不会自动充值。

核对已经保存的真实请求

v0.28 增加明确的 live 只读入口。JavaScript / Python 使用 GuanliuLiveReadClient;CLI 使用 --mode live;stdio MCP 使用 GUANLIU_MCP_MODE=live。默认模拟模式保持原行为。

只读取当前 gl_live_ Key 的账户免费授权、用量、回执与保存结果。MCP 仅提供 find、describe、account,account 的 what=balance/usage/calls/standing/receipt/result;不执行新的请求,也不充值或支付。

pending 与 unknown 不自动重试。免费预留按供应商和单位分开,实际供应商成本未知;同账户其他 Key 占用幂等编号时不泄露其回执。

下一步

真实API和支付保持关闭。固定样本和模拟供应商结果不能作为实时市场事实。