且慢 MCP CLI

一个面向 OpenAPI Schema 的命令行工具，用于把接口能力以“工具”的形式暴露出来，支持工具发现、Schema 查询、配置管理和工具调用。

设计目标

这个 CLI 聚焦 5 个核心动作：

• 申请并配置 API Key
• 管理运行配置
• 浏览可用工具
• 查看工具完整 Schema
• 调用指定工具

为了让命令语义更清晰，本文档采用以下命名：

• config: 管理 CLI 配置
• api-key: 申请并配置 API Key
• tools: 列出工具摘要
• describe: 查看一个或多个工具的完整 Schema
• call: 调用工具
• update: 检查并升级 CLI

相较于直接使用 tool 作为查询命令，describe 更符合“查看定义 / 输出完整描述”的语义，也更容易和 tools 区分。

安装

npm install -g qieman-mcp-cli

安装后可通过 qieman-mcp-cli 命令使用。

核心概念

• 工具名：对应 OpenAPI 中的 operationId
• 工具列表：只展示工具名和简要描述，不展开请求参数和响应结构
• 工具 Schema：展示某个工具的完整定义，包括请求参数、请求体、响应结构等
• 配置项：当前仅支持一个配置项 apiKey

命令概览

| 命令 | 说明 | | --- | --- | | qieman-mcp-cli api-key prepare --phone <value> --x-sign <value> | 发起验证码登录并缓存申请上下文 | | qieman-mcp-cli api-key confirm --verify-code <value> | 确认验证码登录、申请 API Key 并写入配置 | | qieman-mcp-cli config | 查看当前配置 | | qieman-mcp-cli config set --api-key <value> | 设置 API Key | | qieman-mcp-cli tools | 列出所有工具的摘要信息 | | qieman-mcp-cli describe <toolName...> | 查看一个或多个工具的完整 Schema | | qieman-mcp-cli call <toolName> | 调用指定工具 | | qieman-mcp-cli update | 用阿里云 npm 镜像检查更新，并在有新版本时执行升级 |

命令说明

config

用于管理 CLI 运行所需的配置。当前版本只支持 apiKey。

推荐子命令设计：

qieman-mcp-cli config
qieman-mcp-cli config set --api-key <your-api-key>

行为说明：

• 不带参数时，输出当前配置状态
• set 用于写入 apiKey
• 文档和输出中应避免明文回显完整密钥，推荐只显示脱敏后的值

示例：

qieman-mcp-cli config set --api-key sk-xxxxxx
qieman-mcp-cli config

api-key

用于通过手机号验证码完成登录、申请 API Key，并自动写入本地配置。

推荐命令形式：

qieman-mcp-cli api-key prepare --phone <手机号> --x-sign <x-sign>
qieman-mcp-cli api-key confirm --verify-code <验证码>

行为说明：

• prepare 会调用注册验证码接口，并缓存 phone / x-sign / token
• 测试环境如果直接返回验证码，CLI 会直接打印，便于本地验证流程
• confirm 会使用缓存上下文完成验证码确认登录
• 若当前用户已有可用 API Key，会直接复用；否则自动发起申请
• 拿到 API Key 后，会自动写入 config

示例：

qieman-mcp-cli api-key prepare --phone 13900001234 --x-sign 1773740849149C98B84BC9E3B26ACD088D9BA8960DF3C
qieman-mcp-cli api-key confirm --verify-code 123456
qieman-mcp-cli config

tools

用于列出当前 CLI 可访问的全部工具，但只返回适合快速浏览的摘要信息。

输出内容建议仅包含：

• 工具名称，即 operationId
• 工具描述

不包含：

• 入参 Schema
• 出参 Schema
• 示例请求或示例响应

示例：

qieman-mcp-cli tools

示例输出：

getFundCampisiIndicator    获取基金 Campisi 归因指标
SearchFunds                搜索基金
GetStrategyDetails        查询策略详情

这个命令适合作为“能力导航页”，让用户先知道有哪些工具可用，再决定是否查看某个工具的完整定义。

describe

用于查看一个或多个工具的完整 Schema。

推荐命令形式：

qieman-mcp-cli describe <toolName...>

行为说明：

• 支持一次传入多个工具名
• 返回完整 Schema，而不是摘要
• 输出内容可直接用于调试、联调或生成调用参数

示例：

qieman-mcp-cli describe getFundCampisiIndicator
qieman-mcp-cli describe getFundCampisiIndicator SearchFunds

建议输出内容包含：

• 工具名称
• 工具描述
• 请求方法和路径
• Query / Path / Header / Body 参数定义
• 响应结构

如果工具不存在，应返回清晰错误信息，例如：

Tool not found: unknownTool

call

用于执行指定工具调用。

推荐命令形式：

qieman-mcp-cli call <toolName> --input '<json>'

或：

qieman-mcp-cli call <toolName> --input-file <path>

行为说明：

• toolName 对应 operationId
• 调用前应校验输入是否符合该工具的 Schema
• 调用失败时应返回明确错误原因
• 调用成功时输出工具返回结果

示例：

qieman-mcp-cli call getFundCampisiIndicator --input '{"fundCode":"000001","timePeriod":"LAST_YEAR"}'

如果同时支持字符串输入和文件输入，推荐优先使用 --input-file 处理复杂参数，避免转义问题。

update

用于检查当前 CLI 是否有新版本，并通过阿里云 npm 镜像执行升级。

推荐命令形式：

qieman-mcp-cli update
qieman-mcp-cli update --check-only

行为说明：

• 默认会请求 https://registry.npmmirror.com 查询当前包的最新版本
• 如果发现新版本，会自动执行全局安装升级
• 使用 --check-only 时只检查版本，不执行安装

示例：

qieman-mcp-cli update

推荐交互流程

典型使用方式如下：

1. 先用 qieman-mcp-cli tools 浏览工具列表
2. 用 qieman-mcp-cli describe <toolName> 查看目标工具的完整 Schema
3. 用 qieman-mcp-cli call <toolName> 发起调用

这组命令分别承担“发现能力”“理解能力”“执行能力”三个阶段，职责边界比较清晰。

命名建议

基于你的原始想法，推荐保留和调整如下：

• 保留 config：这是 CLI 中最常见、最直观的配置命令
• 保留 tools：很适合表达“列出所有工具”
• 将 tool 调整为 describe：比单数名词更像一个动作，也更能表达“查看完整定义”
• 保留 call：直接表达“调用工具”，语义明确
• 增加 update：用于自助检查和升级 CLI 版本

如果你希望更贴近 MCP / AI Tooling 领域，也可以考虑下面这组替代命名：

• config
• list
• inspect
• call
• update

但从可读性和一致性来看，config / tools / describe / call 会更容易被理解。

后续可扩展方向

如果后面继续增强，这个 CLI 还可以扩展：

• qieman-mcp-cli call --pretty：格式化输出结果
• qieman-mcp-cli tools --search <keyword>：按关键字过滤工具
• qieman-mcp-cli describe --format json：按 JSON 输出 Schema
• qieman-mcp-cli config unset --api-key：清除配置

当前如果只做最小可用版本，保留 config / tools / describe / call 这 4 个命令已经足够完整。