本地 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工具。
{
"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。
{
"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继续下一页,继承参数、场景和最高单价。
{
"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,不自动翻页或扣点。
{
"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。
{
"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和支付保持关闭。固定样本和模拟供应商结果不能作为实时市场事实。