feiguazhitou-mcp-cli 0.1.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +260 -0
- package/USER-GUIDE.md +139 -0
- package/dist/agent-guide.js +278 -0
- package/dist/agent-guide.js.map +1 -0
- package/dist/cli-error.js +30 -0
- package/dist/cli-error.js.map +1 -0
- package/dist/cli.js +952 -0
- package/dist/cli.js.map +1 -0
- package/dist/constants.js +42 -0
- package/dist/constants.js.map +1 -0
- package/dist/fs-utils.js +40 -0
- package/dist/fs-utils.js.map +1 -0
- package/dist/i18n.js +9 -0
- package/dist/i18n.js.map +1 -0
- package/dist/lease-lock.js +57 -0
- package/dist/lease-lock.js.map +1 -0
- package/dist/mcporter.js +249 -0
- package/dist/mcporter.js.map +1 -0
- package/dist/profile.js +262 -0
- package/dist/profile.js.map +1 -0
- package/dist/refresh.js +180 -0
- package/dist/refresh.js.map +1 -0
- package/dist/schema.js +39 -0
- package/dist/schema.js.map +1 -0
- package/dist/skills.js +139 -0
- package/dist/skills.js.map +1 -0
- package/dist/tool-catalog.js +126 -0
- package/dist/tool-catalog.js.map +1 -0
- package/package.json +42 -0
- package/skills/feiguazhitou-mcp-cli/SKILL.en.md +99 -0
- package/skills/feiguazhitou-mcp-cli/SKILL.md +130 -0
- package/skills/feiguazhitou-mcp-cli/skill.en.json +39 -0
- package/skills/feiguazhitou-mcp-cli/skill.json +39 -0
package/README.md
ADDED
|
@@ -0,0 +1,260 @@
|
|
|
1
|
+
# 飞瓜智投 MCP CLI
|
|
2
|
+
|
|
3
|
+
将飞瓜智投客户端提供的本机 Streamable HTTP MCP 服务,在运行时 discovery 后转换为稳定的
|
|
4
|
+
Shell CLI。生成的 MCP tool 命令来自当前服务 schema,所以客户端增删或调整工具后,执行
|
|
5
|
+
`refresh` 即可更新,不需要改 launcher 源码。
|
|
6
|
+
|
|
7
|
+
## 使用范围、数据处理与免责声明
|
|
8
|
+
|
|
9
|
+
- 本项目仅在用户自己的电脑上,将飞瓜智投客户端提供的本机 MCP 请求转发为 CLI 调用;运行时的 discovery、schema 读取和命令生成也仅用于完成这项转接。
|
|
10
|
+
- 本项目不提供数据分析、账号托管、云端同步、远程转发或项目方运营的服务端,也不会将 MCP 请求或返回业务数据上传至项目方。
|
|
11
|
+
- CLI 不会保存 tool 的请求参数或 tool 返回的业务数据。调用结果仅按命令约定输出到当前进程的 stdout/stderr。Agent 未收到用户的“不保存”选择时,会通过单个 Header 配置命令默认保存 Header 凭据,并告知用户。
|
|
12
|
+
- `config set header HEADER --value-stdin` 会将单个 Header 值(包括 API Key)保存到本机单独的未加密凭据文件;支持 POSIX 权限的系统会限制为当前用户读写。该命令不会把凭据写入普通配置、tool catalog、生成 bundle 或命令输出。用户要求不保存时,Agent 使用 `config unset header` 与 `config set header-env`,只保留环境变量引用。
|
|
13
|
+
- 为了让 CLI 能工作,本机数据目录会保存非业务运行元数据,例如 MCP endpoint 与超时配置、环境变量名称、生成的 CLI bundle、tool 名称与 schema、schema hash 和刷新时间;其中不包含 Header 的实际值或 tool 调用结果。唯一例外是用户允许保存时的独立凭据文件。
|
|
14
|
+
- 终端历史、终端重定向文件、操作系统日志、用户自己的脚本,以及飞瓜智投客户端和第三方 MCP 服务各自的数据处理规则,不在本 CLI 的控制范围内。请仅在已获授权的账号和数据范围内使用,并自行确认适用的业务规则与合规要求。
|
|
15
|
+
- 本项目不保证第三方 MCP 服务的可用性、数据准确性或 tool 执行产生的业务结果;由第三方服务执行或返回的内容及其副作用,仍由用户和相应第三方服务负责。
|
|
16
|
+
|
|
17
|
+
## 前置条件
|
|
18
|
+
|
|
19
|
+
- 飞瓜智投客户端正在运行,且目标账号已完成罗盘登录、监视器在线。
|
|
20
|
+
- CLI 与客户端运行在同一台电脑。服务只绑定 `127.0.0.1`,不能远程访问。
|
|
21
|
+
- 推荐 Node.js 24+,与 MCPorter 的正式 engines 要求一致。
|
|
22
|
+
|
|
23
|
+
## 快速开始
|
|
24
|
+
|
|
25
|
+
```bash
|
|
26
|
+
npm install
|
|
27
|
+
npm run build
|
|
28
|
+
|
|
29
|
+
export FEIGUAZHITOU_CLI_MCP_URL="http://127.0.0.1:19528/mcp"
|
|
30
|
+
export FEIGUAZHITOU_CLI_API_KEY="<only-when-required>"
|
|
31
|
+
# 可选:仅使用用户当前 MCP 配置提供的数组;不要在 Agent 中写死工具名。
|
|
32
|
+
export FEIGUAZHITOU_CLI_AUTO_APPROVE="$AUTO_APPROVE_JSON"
|
|
33
|
+
|
|
34
|
+
node dist/cli.js describe --output json
|
|
35
|
+
node dist/cli.js refresh --output json
|
|
36
|
+
node dist/cli.js tools list --output json
|
|
37
|
+
node dist/cli.js doctor --output text
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
全局安装后的启动命令为 `feiguazhitou-mcp-cli`。端口在飞瓜智投客户端设置中可以变化,客户端
|
|
41
|
+
设置页显示的 endpoint 是唯一权威值。
|
|
42
|
+
|
|
43
|
+
面向日常使用者的完整操作说明见 [USER-GUIDE.md](USER-GUIDE.md)。
|
|
44
|
+
|
|
45
|
+
### 粘贴给 AI 助手安装
|
|
46
|
+
|
|
47
|
+
发布到 npm 后,可将下面整段 Prompt 原样粘贴给 AI 助手。它使用发布包
|
|
48
|
+
`feiguazhitou-mcp-cli`,不会要求用户手工拼装 CLI 命令或直接连接 MCP:
|
|
49
|
+
|
|
50
|
+
```text
|
|
51
|
+
你是我的本地终端助手。请在我的电脑上安装并配置 npm 包 `feiguazhitou-mcp-cli`,并严格遵守以下规则。
|
|
52
|
+
|
|
53
|
+
1. 先检查 Node.js 和 npm;本 CLI 需要 Node.js >= 20.19。若不满足,说明问题并停止,不要猜测或静默替换运行时。
|
|
54
|
+
2. 执行 `npm install --global feiguazhitou-mcp-cli`,随后执行 `feiguazhitou-mcp-cli --version` 与
|
|
55
|
+
`feiguazhitou-mcp-cli describe --output json`。`describe` 只读取本地协议,不会连接 MCP;先以它给出的当前契约为准。
|
|
56
|
+
3. 我可能会提供标准 `mcpServers` JSON。该 JSON 只供你理解配置:不要把整份 JSON 交给 CLI,不要让 CLI 解析它,也不要通过其中的 URL 直接连接 MCP。若有多个 server 而目标不明确,先问我选哪一个。
|
|
57
|
+
4. 只映射当前 `describe` 明确支持的字段,并逐项配置:
|
|
58
|
+
- endpoint/url:执行 `feiguazhitou-mcp-cli config set endpoint URL`。
|
|
59
|
+
- headers:先告知我,默认会将每个 Header 保存到本机未加密凭据文件;我没有明确要求“不保存”时,逐个使用
|
|
60
|
+
`feiguazhitou-mcp-cli config set header HEADER --value-stdin`,并且只通过标准输入提供 Header 值,绝不能把密钥放进命令行、回复、项目文件或日志。
|
|
61
|
+
若我要求不保存,对每个 Header 先执行 `feiguazhitou-mcp-cli config unset header HEADER`,再执行
|
|
62
|
+
`feiguazhitou-mcp-cli config set header-env HEADER ENV_VAR`;实际值只放进后续 CLI 进程的环境变量。
|
|
63
|
+
- autoApprove:将用户配置中的原始 JSON 数组原样放入每个后续 CLI 进程的
|
|
64
|
+
`FEIGUAZHITOU_CLI_AUTO_APPROVE` 环境变量。它只标记本地工具目录,不是 HTTP Header,不会发送给 MCP,也不替代未知或高影响操作的明确授权。
|
|
65
|
+
- 未知或未来字段:保留为参考;不要拒绝、删除或臆造映射。
|
|
66
|
+
5. 配置完成后,串行执行 `feiguazhitou-mcp-cli doctor --output json`、
|
|
67
|
+
`feiguazhitou-mcp-cli refresh --output json` 和 `feiguazhitou-mcp-cli tools list --output json`。不要并发执行
|
|
68
|
+
`doctor`、`refresh` 或 `run`;所有工具调用只能使用 `feiguazhitou-mcp-cli run COMMAND ...`。
|
|
69
|
+
6. 最后只报告不含敏感值的结果:安装版本、连接/刷新状态和可用工具数量。不要回显 API Key、Cookie、Header 值、账号数据或工具业务结果。
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
### Agent 依据标准 MCP JSON 逐项配置
|
|
73
|
+
|
|
74
|
+
用户可以把完整 `mcpServers` JSON 直接发给 Agent。JSON 只供 Agent 理解和逐项配置 CLI,CLI 不读取或
|
|
75
|
+
解析整份配置,也不会替 Agent 做字段映射。Agent 应先读取 `feiguazhitou-mcp-cli describe --output json`,依据
|
|
76
|
+
用户指定的 server 和当前 CLI 契约处理各字段;配置有多个 server 而目标不清楚时先询问。
|
|
77
|
+
|
|
78
|
+
当前常见字段的处理方式如下。它们是 Agent 的映射参考,不是固定字段白名单:
|
|
79
|
+
|
|
80
|
+
```bash
|
|
81
|
+
# Agent 从所选 server 识别出当前 CLI 支持的 endpoint 后逐项设置。
|
|
82
|
+
feiguazhitou-mcp-cli config set endpoint URL
|
|
83
|
+
|
|
84
|
+
# 用户未要求不保存时,对每个 Header 单独执行;Header 值只经标准输入传入。
|
|
85
|
+
feiguazhitou-mcp-cli config set header HEADER_NAME --value-stdin < HEADER_VALUE_SOURCE
|
|
86
|
+
|
|
87
|
+
# 用户要求不保存时,删除同名本机凭据并只记录环境变量名称。
|
|
88
|
+
feiguazhitou-mcp-cli config unset header HEADER_NAME
|
|
89
|
+
feiguazhitou-mcp-cli config set header-env HEADER_NAME ENV_VAR
|
|
90
|
+
|
|
91
|
+
# 如果用户配置含 autoApprove,Agent 将原始 JSON 数组放入后续 CLI 进程环境。
|
|
92
|
+
export FEIGUAZHITOU_CLI_AUTO_APPROVE="$AUTO_APPROVE_JSON"
|
|
93
|
+
|
|
94
|
+
# 所有逐项设置完成后,明确连接 MCP 生成当前目录。
|
|
95
|
+
feiguazhitou-mcp-cli refresh --output json
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
默认保存的 Header 位于本机未加密凭据文件,CLI 会说明此事;支持 POSIX 权限的系统会限制为当前用户读写。`autoApprove` 只标记本地 tool catalog,不会作为 HTTP Header 发往 MCP,也不替代高影响操作的明确授权。对于未知或未来字段,Agent 应保留其参考意义,并只在当前 `describe` 已定义相应 CLI 配置或环境变量时才映射;不能臆造映射、删掉字段,或拿配置中的 URL 直连 MCP。
|
|
99
|
+
|
|
100
|
+
配置完成后,Agent 先执行 `feiguazhitou-mcp-cli tools list --output json`,再从当前目录选择 command,用 `tools show` 读取参数并通过 `feiguazhitou-mcp-cli run COMMAND ...` 调用。
|
|
101
|
+
|
|
102
|
+
## 运行时配置
|
|
103
|
+
|
|
104
|
+
| 环境变量 | 用途 |
|
|
105
|
+
| --- | --- |
|
|
106
|
+
| `FEIGUAZHITOU_CLI_MCP_URL` | Streamable HTTP endpoint;未设置时默认 `http://127.0.0.1:19528/mcp`。 |
|
|
107
|
+
| `FEIGUAZHITOU_CLI_API_KEY` | 可选的 `api_key` HTTP Header 值,只在当前进程使用。需要让 CLI 保存时,Agent 使用 `config set header api_key --value-stdin`。 |
|
|
108
|
+
| `FEIGUAZHITOU_CLI_MCP_HEADERS` | 额外 HTTP Header 的 JSON 对象。直接设置时只在当前进程使用;环境变量的值会覆盖已保存的同名 Header。 |
|
|
109
|
+
| `FEIGUAZHITOU_CLI_AUTO_APPROVE` | 原 MCP 客户端 `autoApprove` 的 JSON 数组;接受 MCP tool 名或生成 command 名,在 local tool catalog 中标记 `autoApproved`。不发送给服务端,也不替代人工授权。 |
|
|
110
|
+
| `FEIGUAZHITOU_CLI_MCP_TIMEOUT` | MCPorter discovery、生成 CLI 和当前 `run` 调用使用的超时毫秒数,默认 90000,范围 1-300000。`run` 每次都会使用当前值,无需因仅修改超时而 `refresh`。超时错误不重试;`--output json` 下未产生 MCP 输出的超时会作为 `COMMAND_FAILED` 返回,原始错误在 `error.details.stderr`。 |
|
|
111
|
+
| `FEIGUAZHITOU_CLI_DATA_DIR` | 本地配置、生成产物和本地锁的数据目录。 |
|
|
112
|
+
| `FEIGUAZHITOU_CLI_LANG` | launcher 自有文案的输出语言。默认中文;设为 `en` 时输出英文。MCP 的 tool 描述、schema、参数和返回数据保持原样。 |
|
|
113
|
+
|
|
114
|
+
Agent 从用户配置中读取 Header 时,若用户未选择不保存,默认使用单个 Header 保存命令;Header 值只经标准输入输入,不能出现在命令行参数中:
|
|
115
|
+
|
|
116
|
+
```bash
|
|
117
|
+
feiguazhitou-mcp-cli config set header api_key --value-stdin < API_KEY_SOURCE
|
|
118
|
+
```
|
|
119
|
+
|
|
120
|
+
用户要求不保存时,Agent 清除同名本机凭据并保存环境变量引用;实际值只在调用 CLI 的进程环境中提供。`autoApprove` 是客户端侧策略信息,Agent 从用户 JSON 中读取它的原始数组并写入 `FEIGUAZHITOU_CLI_AUTO_APPROVE`;CLI 不把它作为 HTTP Header 发送:
|
|
121
|
+
|
|
122
|
+
```bash
|
|
123
|
+
feiguazhitou-mcp-cli config unset header api_key
|
|
124
|
+
feiguazhitou-mcp-cli config set header-env api_key FEIGUAZHITOU_CLI_API_KEY
|
|
125
|
+
export FEIGUAZHITOU_CLI_API_KEY="<runtime-api-key>"
|
|
126
|
+
export FEIGUAZHITOU_CLI_AUTO_APPROVE="$AUTO_APPROVE_JSON"
|
|
127
|
+
```
|
|
128
|
+
|
|
129
|
+
可用 `feiguazhitou-mcp-cli tools list --output json` 查看每个当前 catalog tool 的
|
|
130
|
+
`autoApproved` 标记。该标记不会授权服务端操作;遇到未来出现的未知或高影响 tool,仍须先读取 schema
|
|
131
|
+
并取得明确授权。
|
|
132
|
+
|
|
133
|
+
## Agent 稳定协议
|
|
134
|
+
|
|
135
|
+
新的集成应使用稳定 launcher 协议,而不是依赖会随 MCP schema 改变的顶层动态命令:
|
|
136
|
+
|
|
137
|
+
```bash
|
|
138
|
+
# 纯本地,不连接 MCP
|
|
139
|
+
feiguazhitou-mcp-cli describe --output json
|
|
140
|
+
|
|
141
|
+
# 只读取本地已激活 artifact;首次使用时会返回 ARTIFACT_MISSING
|
|
142
|
+
feiguazhitou-mcp-cli tools list --output json
|
|
143
|
+
|
|
144
|
+
# 明确连接 MCP、发现 schema 并生成或更新 artifact
|
|
145
|
+
feiguazhitou-mcp-cli refresh --output json
|
|
146
|
+
|
|
147
|
+
# 可传 MCP 原始 tool 名或生成命令名,读取完整 inputSchema
|
|
148
|
+
feiguazhitou-mcp-cli tools show lottery_info --output json
|
|
149
|
+
|
|
150
|
+
# 只执行本地 catalog 中的命令;不会隐式 refresh
|
|
151
|
+
feiguazhitou-mcp-cli run lottery-info \
|
|
152
|
+
--raw '{"uid":"...","roomid":"..."}' --output json
|
|
153
|
+
```
|
|
154
|
+
|
|
155
|
+
`describe`、`tools list`、`tools show` 与 `run` 遇到 launcher 可处理的失败时,传入
|
|
156
|
+
`--output json` 会返回 `feiguazhitou-mcp-cli.error/v1`。若生成 CLI 在产生 MCP 响应前失败(例如超时),
|
|
157
|
+
也会返回 `COMMAND_FAILED`;原始生成 CLI 错误位于 `error.details.stderr`。常见恢复方式见
|
|
158
|
+
[USER-GUIDE.md](USER-GUIDE.md)。
|
|
159
|
+
|
|
160
|
+
## 动态发现与调用
|
|
161
|
+
|
|
162
|
+
调用方不得直接连接本机 MCP endpoint,也不得通过其他 MCP client 调用 tool。`feiguazhitou-mcp-cli`
|
|
163
|
+
是唯一允许的调用入口,CLI 会在内部完成 MCP 连接。
|
|
164
|
+
|
|
165
|
+
飞瓜本机 MCP 按单会话使用。不要并发执行 `run`、`refresh` 或 `doctor`;必须等待上一条会连接 MCP 的命令完全结束后,再执行下一条。CLI 不会自动排队,因此 Agent 或脚本应自行串行调用。
|
|
166
|
+
|
|
167
|
+
`refresh` 是唯一推荐的 schema discovery 入口:它连接 MCP,读取当前 schema,并用 MCPorter
|
|
168
|
+
生成命令。`tools list` 和 `tools show` 默认只读取本地 artifact,不会隐式联网。目录超过 7 天未检查时,
|
|
169
|
+
它们只显示刷新提示,不会自动连接 MCP。服务更新后:
|
|
170
|
+
|
|
171
|
+
```bash
|
|
172
|
+
feiguazhitou-mcp-cli refresh --output json
|
|
173
|
+
feiguazhitou-mcp-cli tools list --output json
|
|
174
|
+
```
|
|
175
|
+
|
|
176
|
+
先读取单个工具的 schema;对对象、数组或多项可选参数组合使用 `--raw`,并让 stdout 保持 JSON:
|
|
177
|
+
|
|
178
|
+
```bash
|
|
179
|
+
feiguazhitou-mcp-cli tools show COMMAND --output json
|
|
180
|
+
feiguazhitou-mcp-cli run COMMAND \
|
|
181
|
+
--raw '{"key":"value"}' --output json
|
|
182
|
+
|
|
183
|
+
# 对复杂 JSON,从文件读取
|
|
184
|
+
feiguazhitou-mcp-cli run COMMAND --raw @request.json --output json
|
|
185
|
+
|
|
186
|
+
# 或从标准输入读取
|
|
187
|
+
cat request.json | feiguazhitou-mcp-cli run COMMAND --raw - --output json
|
|
188
|
+
```
|
|
189
|
+
|
|
190
|
+
生成命令暴露的标量 flag 也可以直接使用,中文和带空格的值遵循正常 shell 引号规则;没有通用的位置参数简写。例如:
|
|
191
|
+
|
|
192
|
+
```bash
|
|
193
|
+
feiguazhitou-mcp-cli run live-detail-history-live \
|
|
194
|
+
--uid "..." --query-times "近30日" --output json
|
|
195
|
+
```
|
|
196
|
+
|
|
197
|
+
`FEIGUAZHITOU_CLI_MCP_TIMEOUT` 只覆盖当前进程。默认 90000ms;需要不同的长期等待上限时,可将自定义毫秒值写入本地非敏感配置。新值会在下一次 `run` 中立即生效:
|
|
198
|
+
|
|
199
|
+
```bash
|
|
200
|
+
feiguazhitou-mcp-cli config set timeout MILLISECONDS
|
|
201
|
+
```
|
|
202
|
+
|
|
203
|
+
artifact 会保留生成时的默认超时,`tools list` 和 `tools show` 会在
|
|
204
|
+
`artifact.currentTimeoutMatches` 中显示它是否与当前值一致。该字段只说明生成默认值是否不同;
|
|
205
|
+
`run` 始终把当前超时传给生成 CLI,不会因超时不一致而拒绝执行。
|
|
206
|
+
|
|
207
|
+
CLI 不会改写 MCP 返回数据。服务版本可能将金额、计数、时间或比例表示为直接值、文本,或
|
|
208
|
+
`{ "unit", "value" }` 结构;调用方应读取当前返回 schema 后再解析。
|
|
209
|
+
|
|
210
|
+
工具调用的业务失败也会保留原 MCP 输出:MCP 标准 `isError: true`、飞瓜返回 `ok: false`,或
|
|
211
|
+
`BaseResp.StatusCode` 为非零时,CLI 会以退出码 `1` 结束。脚本和 Agent 可以直接依据退出码判断失败,
|
|
212
|
+
无需猜测业务字段;CLI 不会重试或改写第三方返回内容。若超时等生成 CLI 级错误发生在 MCP 响应前,
|
|
213
|
+
`--output json` 会返回 `COMMAND_FAILED`,并在 `error.details.stderr` 保留原始错误文本。
|
|
214
|
+
|
|
215
|
+
CLI 只接受 `describe`、`tools list/show`、显式 `refresh` 与 `run` 等固定 launcher 命令。
|
|
216
|
+
顶层动态工具命令、`agent`、裸 `tools` 与 `tool NAME` 均会被拒绝;先从 catalog 读取 command,
|
|
217
|
+
再通过 `run COMMAND` 执行。
|
|
218
|
+
|
|
219
|
+
## Skill 协议
|
|
220
|
+
|
|
221
|
+
包内提供 `feiguazhitou-mcp-cli.skills/v1`,供 Agent 发现安装和排障指南:
|
|
222
|
+
|
|
223
|
+
```bash
|
|
224
|
+
node dist/cli.js skills protocol
|
|
225
|
+
node dist/cli.js skills list --output json
|
|
226
|
+
node dist/cli.js skills show feiguazhitou-mcp-cli
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
该 Skill 只指导连接、刷新和排障,不固定 MCP tool 清单。它不会自动安装到 Codex,也不会
|
|
230
|
+
执行 Skill 中的命令;日常安装和调用方式见 [USER-GUIDE.md](USER-GUIDE.md)。
|
|
231
|
+
|
|
232
|
+
## 压缩打包
|
|
233
|
+
|
|
234
|
+
执行下面的命令会先构建,再在 `artifacts/` 创建可分发的 gzip tarball:
|
|
235
|
+
|
|
236
|
+
```bash
|
|
237
|
+
npm run package
|
|
238
|
+
```
|
|
239
|
+
|
|
240
|
+
默认产物名为 `artifacts/feiguazhitou-mcp-cli-<version>.tgz`,其中包含 `dist`、Skill、README
|
|
241
|
+
和 `USER-GUIDE.md`,不包含开发 `docs/`。可用本地压缩包安装:
|
|
242
|
+
|
|
243
|
+
```bash
|
|
244
|
+
npm install --global ./artifacts/feiguazhitou-mcp-cli-<version>.tgz
|
|
245
|
+
```
|
|
246
|
+
|
|
247
|
+
## 测试
|
|
248
|
+
|
|
249
|
+
```bash
|
|
250
|
+
npm test
|
|
251
|
+
npm run test:integration
|
|
252
|
+
npm run test:pack
|
|
253
|
+
npm run test:e2e:mock
|
|
254
|
+
npm run test:e2e:real
|
|
255
|
+
```
|
|
256
|
+
|
|
257
|
+
`test:e2e:mock` 在随机本机端口启动带固定 mock 数据的飞瓜智投 MCP,通过 canonical `run` 覆盖十个工具的
|
|
258
|
+
依赖链与对象/数组响应容器,不断言固定业务值。`test:e2e:fixture` 保留为同一测试的兼容脚本。
|
|
259
|
+
`test:e2e:real` 则连接运行中的本机飞瓜智投 MCP,
|
|
260
|
+
以实时授权账号和最新场次执行同一条只读工作流;它仅用于开发与验收。
|
package/USER-GUIDE.md
ADDED
|
@@ -0,0 +1,139 @@
|
|
|
1
|
+
# 飞瓜智投 MCP CLI 使用说明
|
|
2
|
+
|
|
3
|
+
`feiguazhitou-mcp-cli` 是运行在用户自己电脑上的本地转接工具。它把飞瓜智投客户端提供的
|
|
4
|
+
本机 MCP 服务转换为命令行调用;它不会提供云端服务、上传业务数据,或保存 tool 的请求与返回结果。
|
|
5
|
+
|
|
6
|
+
## 使用前确认
|
|
7
|
+
|
|
8
|
+
- 飞瓜智投客户端正在同一台电脑上运行,且目标账号已完成所需登录。
|
|
9
|
+
- 使用客户端设置页显示的本机 MCP endpoint;不要猜测端口。
|
|
10
|
+
- 已安装 Node.js `>=20.19` 和 npm。
|
|
11
|
+
|
|
12
|
+
## 安装
|
|
13
|
+
|
|
14
|
+
```bash
|
|
15
|
+
npm install --global feiguazhitou-mcp-cli
|
|
16
|
+
feiguazhitou-mcp-cli --version
|
|
17
|
+
```
|
|
18
|
+
|
|
19
|
+
安装后,所有工具调用都必须经过 `feiguazhitou-mcp-cli`。不要直接请求 MCP URL,也不要用其他
|
|
20
|
+
MCP client 连接本机服务。
|
|
21
|
+
|
|
22
|
+
## 交给 AI 助手配置
|
|
23
|
+
|
|
24
|
+
最省事的方式是将 npm README 中“粘贴给 AI 助手安装”的完整 Prompt 和你的标准 `mcpServers` JSON
|
|
25
|
+
一起发给 AI 助手。AI 应自行理解 JSON 并逐项配置 CLI,不能把整份 JSON 交给 CLI 解析。
|
|
26
|
+
|
|
27
|
+
配置中有多个 server 而目标不明确时,AI 应先询问你。未知或未来字段只是参考信息,不能被删除、拒绝或
|
|
28
|
+
自行映射。
|
|
29
|
+
|
|
30
|
+
## 手动配置
|
|
31
|
+
|
|
32
|
+
先查看当前 CLI 协议;该命令只读取本地信息,不会连接 MCP:
|
|
33
|
+
|
|
34
|
+
```bash
|
|
35
|
+
feiguazhitou-mcp-cli describe --output json
|
|
36
|
+
```
|
|
37
|
+
|
|
38
|
+
### Endpoint
|
|
39
|
+
|
|
40
|
+
默认 endpoint 是 `http://127.0.0.1:19528/mcp`。客户端设置页显示其他地址时,单独设置它:
|
|
41
|
+
|
|
42
|
+
```bash
|
|
43
|
+
feiguazhitou-mcp-cli config set endpoint URL
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Header 和 API Key
|
|
47
|
+
|
|
48
|
+
用户未明确要求“不保存”时,AI 会默认逐个保存 Header。保存位置是本机未加密凭据文件;支持 POSIX
|
|
49
|
+
权限的系统会限制为当前用户读写。实际 Header 值不会写入普通配置、工具目录、生成 bundle 或命令输出。
|
|
50
|
+
|
|
51
|
+
将值仅通过标准输入传入,避免放进命令行历史。把 `api_key` 替换为实际 Header 名:
|
|
52
|
+
|
|
53
|
+
```bash
|
|
54
|
+
read -rs HEADER_VALUE
|
|
55
|
+
printf '%s' "$HEADER_VALUE" | feiguazhitou-mcp-cli config set header api_key --value-stdin
|
|
56
|
+
unset HEADER_VALUE
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
不希望 CLI 保存 Header 时,删除同名的已保存值,只保存环境变量名称;实际值需要在每次调用 CLI 的进程
|
|
60
|
+
环境中提供:
|
|
61
|
+
|
|
62
|
+
```bash
|
|
63
|
+
feiguazhitou-mcp-cli config unset header api_key
|
|
64
|
+
feiguazhitou-mcp-cli config set header-env api_key FEIGUAZHITOU_CLI_API_KEY
|
|
65
|
+
export FEIGUAZHITOU_CLI_API_KEY="<runtime-api-key>"
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### autoApprove
|
|
69
|
+
|
|
70
|
+
若原始 MCP 配置包含 `autoApprove`,把其中的原始 JSON 数组放入后续 CLI 进程的环境变量:
|
|
71
|
+
|
|
72
|
+
```bash
|
|
73
|
+
export FEIGUAZHITOU_CLI_AUTO_APPROVE="$AUTO_APPROVE_JSON"
|
|
74
|
+
```
|
|
75
|
+
|
|
76
|
+
它只在本地工具目录中显示 `autoApproved: true`,不会作为 HTTP Header 发给 MCP,也不会授予服务端权限或
|
|
77
|
+
替代你对未知、高影响操作的明确授权。
|
|
78
|
+
|
|
79
|
+
## 连接、发现和调用
|
|
80
|
+
|
|
81
|
+
飞瓜本机 MCP 按单会话使用。请等待上一条会连接 MCP 的命令结束后,再执行下一条;不要并发执行
|
|
82
|
+
`doctor`、`refresh` 或 `run`。
|
|
83
|
+
|
|
84
|
+
```bash
|
|
85
|
+
# 检查本机客户端和当前连接配置
|
|
86
|
+
feiguazhitou-mcp-cli doctor --output text
|
|
87
|
+
|
|
88
|
+
# 连接 MCP,读取当前 schema 并生成本地工具目录
|
|
89
|
+
feiguazhitou-mcp-cli refresh --output json
|
|
90
|
+
|
|
91
|
+
# 读取本地工具目录和某个工具的准确参数 schema
|
|
92
|
+
feiguazhitou-mcp-cli tools list --output json
|
|
93
|
+
feiguazhitou-mcp-cli tools show COMMAND --output json
|
|
94
|
+
|
|
95
|
+
# 仅通过 CLI 调用目录中的工具
|
|
96
|
+
feiguazhitou-mcp-cli run COMMAND --raw '{"key":"value"}' --output json
|
|
97
|
+
```
|
|
98
|
+
|
|
99
|
+
复杂输入可从文件或标准输入读取:
|
|
100
|
+
|
|
101
|
+
```bash
|
|
102
|
+
feiguazhitou-mcp-cli run COMMAND --raw @request.json --output json
|
|
103
|
+
cat request.json | feiguazhitou-mcp-cli run COMMAND --raw - --output json
|
|
104
|
+
```
|
|
105
|
+
|
|
106
|
+
## 常用环境变量
|
|
107
|
+
|
|
108
|
+
| 环境变量 | 用途 |
|
|
109
|
+
| --- | --- |
|
|
110
|
+
| `FEIGUAZHITOU_CLI_MCP_URL` | 覆盖当前进程使用的 MCP endpoint。 |
|
|
111
|
+
| `FEIGUAZHITOU_CLI_API_KEY` | 当前进程的 `api_key` Header 值。 |
|
|
112
|
+
| `FEIGUAZHITOU_CLI_MCP_HEADERS` | 额外 HTTP Header 的 JSON 对象。 |
|
|
113
|
+
| `FEIGUAZHITOU_CLI_AUTO_APPROVE` | 原 MCP 配置中的 `autoApprove` JSON 数组,仅用于本地目录标记。 |
|
|
114
|
+
| `FEIGUAZHITOU_CLI_MCP_TIMEOUT` | 当前进程的超时毫秒数。默认 90000,范围 1-300000。 |
|
|
115
|
+
| `FEIGUAZHITOU_CLI_LANG` | 设为 `en` 时让 CLI 自有文案输出英文。 |
|
|
116
|
+
|
|
117
|
+
需要长期修改超时可执行:
|
|
118
|
+
|
|
119
|
+
```bash
|
|
120
|
+
feiguazhitou-mcp-cli config set timeout 120000
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
新值会在下一次 `run` 立即生效,不需要重新 `refresh`。
|
|
124
|
+
|
|
125
|
+
## 常见问题
|
|
126
|
+
|
|
127
|
+
| 情况 | 处理方式 |
|
|
128
|
+
| --- | --- |
|
|
129
|
+
| `ARTIFACT_MISSING` | 执行 `feiguazhitou-mcp-cli refresh --output json`,再重试。 |
|
|
130
|
+
| MCP 工具更新后找不到命令 | 执行 `refresh`,再用 `tools list` 读取新目录。 |
|
|
131
|
+
| `COMMAND_FAILED` 或超时 | 这是第三方 MCP 或本机客户端返回的失败;检查客户端、登录状态、endpoint 和超时后再手动重试。CLI 不会自动重试。 |
|
|
132
|
+
| 目录提示超过 7 天未检查 | 按需执行一次 `refresh`;`tools list` 不会自行联网。 |
|
|
133
|
+
|
|
134
|
+
## 数据和安全边界
|
|
135
|
+
|
|
136
|
+
- CLI 只在本机转发 MCP 请求,不会上传 tool 请求或结果。
|
|
137
|
+
- 不要把 API Key、Cookie、Header 值、账号数据或业务结果写进脚本、项目文件、终端共享记录或问题反馈。
|
|
138
|
+
- 默认保存 Header 时,凭据文件未加密;不希望保存时使用“Header 和 API Key”中的环境变量方案。
|
|
139
|
+
- 对未来出现的陌生、会修改账号状态、发布内容、删除数据或触发外部动作的工具,先阅读 `tools show` 的 schema,并获得明确授权后再执行。
|