@zltquant/zlt-mcp 0.5.0 → 0.6.0-beta.0

package/README.md

@@ -7,13 +7,18 @@
 
 ## 接入
 
-WorkBuddy 使用配套 Skill，并由 Skill 调用 npm CLI 完成任务，无需配置 MCP 连接器：
+WorkBuddy 用户可从 SkillHub 安装 [zlt-quant Skill](https://skillhub.cn/skills/org-gir79457/zlt-quant)，由 Skill 调用本包的 CLI 完成量化任务，无需配置 MCP 连接器。CLI 调用示例：
 
 ```powershell
 npx -y @zltquant/zlt-mcp list --json
 npx -y @zltquant/zlt-mcp call zlt-runtime-doctor --args-json '{}'
 ```
 
+使用 `--help` 和 `call --help` 获取当前调用契约；`list --tool mcp-wait --json`
+只查询一个工具的完整 schema，未知名字返回非零退出码。简单查询直接输出，无参数可省略参数选项；
+复杂配置用 `--args-file`，大结果或下游证据才使用结果文件。保留独立 stderr 和 CLI 原始退出码，
+调用成功后再解析结果，不通过管道隐藏失败。Skill 负责工作流，不维护第二份接口契约。
+
 业务调用支持 `call --output-json <新文件路径>`：完整 JSON 写入文件，stdout 返回含
 `ok`、`tool`、`resultFile`、`cliProvenance`、精简 `data` 的回执。
 输出目录须已存在，已有文件会在执行工具前报错；每次使用新文件名。完整参数与大段数据从结果文件读取。
@@ -48,6 +53,8 @@ npm i @zltquant/zlt-mcp --prefix "$env:USERPROFILE\.zlt-quant" --registry https:
 
 ## 配套技能
 
+推荐从 SkillHub 安装 [zlt-quant Skill](https://skillhub.cn/skills/org-gir79457/zlt-quant)，用于策略生成、回测执行与验收、结果分析和环境准备。
+
 量化技能（策略生成、回测执行与验收、结果分析、装机引导）见 gitee 组合仓，
 克隆后运行 `install.ps1`：
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@zltquant/zlt-mcp",
-  "version": "0.5.0",
+  "version": "0.6.0-beta.0",
   "description": "智量通 ZLT Quant MCP server（Windows x64；量化策略创建与本地回测）",
   "bin": {
     "zlt-mcp": "./zlt-mcp-proxy.bundle.cjs"

package/zlt-mcp-proxy.bundle.cjs

@@ -27547,12 +27547,27 @@ if (process.argv.length <= 2) {
   startMcpServer();
 } else {
   const program2 = new Command();
-  program2.name(CLI_NAME).description("MCP proxy for ZLTHost IPC service").version(resolveCliVersion());
+  program2.name(CLI_NAME).description("MCP proxy for ZLTHost IPC service").version(resolveCliVersion()).addHelpText("after", "\nDiscovery: list for names; list --tool <name> --json for one complete input schema.\nUse call --help for input, output and diagnostic handling.");
   program2.command("__keepalive <kind> <id> [codePath]", { hidden: true }).action(async (kind, id, codePath) => {
     if (kind !== "backtest") throw new Error(`Unsupported keepalive kind: ${kind}`);
     await keepMcpBacktestAlive(id, codePath);
   });
-  program2.command("call <tool>").description("Call any MCP tool through the bundled MCP server").option("--args-json <json>", "JSON object containing tool arguments").option("--args-file <path>", "Read the JSON argument object from a file").option("--output-json <path>", "Save the complete result to a new JSON file and print a compact receipt").option("--timeout-ms <ms>", "MCP request inactivity timeout in milliseconds").option("--max-total-timeout-ms <ms>", "Optional hard upper bound for the request").option("--no-progress", "Suppress progress diagnostics on stderr").action(async (tool, options) => {
+  program2.command("call <tool>").description("Call any MCP tool through the bundled MCP server").option("--args-json <json>", "JSON object containing tool arguments").option("--args-file <path>", "Read the JSON argument object from a file").option("--output-json <path>", "Save the complete result to a new JSON file and print a compact receipt").option("--timeout-ms <ms>", "MCP request inactivity timeout in milliseconds").option("--max-total-timeout-ms <ms>", "Optional hard upper bound for the request").option("--no-progress", "Suppress progress diagnostics on stderr").addHelpText("after", `
+Input: omitted arguments mean {}; use --args-json for small objects and --args-file
+for nested configuration or shell-sensitive text. Follow the selected tool schema
+from list --tool <name> --json. Windows paths must be native paths (C:/...), not /c/....
+Output: by default stdout contains the complete MCP JSON envelope plus cliProvenance.
+JSON business responses are inside content[].text (or structuredContent when present).
+Use --output-json for large results or downstream evidence: it saves the complete
+envelope and prints only a compact receipt. The parent directory must exist and the
+file must be new. A receipt is not the full business response.
+Diagnostics: preserve stderr separately and check this process's exit code before
+parsing output. Do not discard stderr, merge it into JSON, or pipe calls through
+head/tail/parsers that can hide the CLI exit code. --no-progress only disables progress.
+If saving fails after execution, the complete response is on stdout; preserve it
+and inspect the returned state before retrying any operation that may have run.
+Credentials belong in the configured local credential store, never in arguments.
+`).action(async (tool, options) => {
     let outputFd;
     try {
       const args = parseMcpArgs(options.argsJson, options.argsFile);
@@ -27592,9 +27607,14 @@ if (process.argv.length <= 2) {
       if (outputFd !== void 0) fs13.closeSync(outputFd);
     }
   });
-  program2.command("list").description("List MCP tools exposed by the bundled server").option("--json", "Emit the complete tools/list response as JSON").action(async (options) => {
+  program2.command("list").description("List MCP tools exposed by the bundled server").option("--json", "Emit the complete tools/list response as JSON").option("--tool <name>", "Select one exact tool name; combine with --json for its complete schema").addHelpText("after", "\nReuse discovery within a task. Query one schema with list --tool <name> --json.\nUnknown names fail with exit code 1. Preserve stderr separately from JSON stdout.").action(async (options) => {
     try {
-      const result = await listMcpTools();
+      let result = await listMcpTools();
+      if (options.tool !== void 0) {
+        const tools2 = Array.isArray(result.tools) ? result.tools.filter((tool) => tool.name === options.tool) : [];
+        if (tools2.length === 0) throw new Error(`Unknown tool: ${options.tool}. Use list to discover available names.`);
+        result = { ...result, tools: tools2 };
+      }
       if (options.json) {
         process.stdout.write(JSON.stringify(withCliProvenance(result)) + "\n");
         return;