> For the complete documentation index, see [llms.txt](https://docs.goassay.ai/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goassay.ai/developers/zh/shi-yong-gong-ju-jin-jie/cli-reference.md).

# assay-mcp CLI 参考

查阅 assay-mcp 支持的命令、参数和终端要求。

先用 `status` 查看当前连接，用 `doctor` 检查本地配置：

```sh
npx -y @goassay-ai/mcp status
npx -y @goassay-ai/mcp doctor
```

下方所有命令均运行最新发布的包。assay-mcp 输出的命令会包含确切版本，例如 `@goassay-ai/mcp@<version>`；两种写法都可以。**需要终端**表示 stdin 和 stdout 都必须是交互式终端流。其他命令不强制要求这一点，但登录和钱包批准仍需要你参与。

## 查看和诊断

| 命令                                                 | 用途和参数                                                       |
| -------------------------------------------------- | ----------------------------------------------------------- |
| `npx -y @goassay-ai/mcp status [--profile <name>]` | 显示配置文件的登录、智能体、支付密钥状态、本地上限和支出、付费 URL 及已记录的安装。不会更新过期令牌。       |
| `npx -y @goassay-ai/mcp doctor [--profile <name>]` | 检查项目配置、终端环境、本地明确许可和密钥链可用性。不修改文件。退出码 0 表示没有问题；1 表示发现问题或检查失败。 |
| `npx -y @goassay-ai/mcp --version`                 | 将包版本输出到 stdout。                                             |
| `npx -y @goassay-ai/mcp --help`                    | 输出顶层用法。此位置的 `-h` 和 `help` 是别名。                              |

`status` 会区分链上确认的支付密钥状态和仅由 Assay 报告的状态。“Can't confirm”或“unknown”不表示权限已关闭。

## 登录和退出

| 命令                                                                      | 用途和参数                                                                         |
| ----------------------------------------------------------------------- | ----------------------------------------------------------------------------- |
| `npx -y @goassay-ai/mcp login [--profile <name>] [--url <url-or-path>]` | 输出并打开批准链接。重新登录会替换配置文件的当前连接。`--url` 使用与 `serve` 相同的源站检查来选择部署；默认使用配置文件的部署。      |
| `npx -y @goassay-ai/mcp logout [--profile <name>]`                      | 尝试撤销登录，再删除本地令牌、支付密钥、支出状态和设置。保留限额和付费 URL。影响使用此配置文件的所有服务器。不会撤销密钥的链上权限；请阅读输出的说明。 |
| `npx -y @goassay-ai/mcp enable-paid [--profile <name>]`                 | 输出并打开现有密钥的批准页面。不能创建密钥，也不能代你批准钱包签名。                                            |

批准步骤见[安装 assay-mcp](/developers/zh/shi-yong-gong-ju-ru-men/install-assay-mcp.md)和[付费流程](/developers/zh/shi-yong-gong-ju-ru-men/how-paying-works.md)。

## 管理客户端条目

| 命令                                                                                                                                                               | 用途                                                                        |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- |
| `npx -y @goassay-ai/mcp add <url-or-path> [--client <id>] [--name <name>] [--scope user\|project] [--profile <name>] [--force] [--log-file <absolute-path.log>]` | 在客户端安装一个 URL。默认为用户范围和 `default` 配置文件。已有匹配安装会被保留，除非你指定其他名称或强制替换。           |
| `npx -y @goassay-ai/mcp list`                                                                                                                                    | 列出 `add` 写入的安装，并逐项与客户端配置比较：`ok`、`missing`、`changed` 或 `unreadable`。不接受参数。 |
| `npx -y @goassay-ai/mcp remove <name> [--client <id>] [--scope user\|project]`                                                                                   | 删除辅助命令写入的条目及其安装记录。可指定客户端和范围以消除歧义。已编辑的条目会留给你在客户端中移除。不会退出登录。                |

| `add` 参数                         | 含义                                                                                                                        |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `--client <id>`                  | 可选 `claude-code`、`codex`、`cursor`、`vscode`、`windsurf`、`gemini`、`claude-desktop`。省略时，使用唯一检测到的客户端 CLI，或交互选择；否则辅助命令会要求提供此参数。 |
| `--name <name>`                  | 覆盖建议的短服务器名称。以小写字母开头，只含小写字母、数字和连字符。辅助命令也会检查客户端的工具名称长度限制。                                                                   |
| `--scope user\|project`          | 选择用户设置或当前项目。各客户端支持的范围不同。                                                                                                  |
| `--profile <name>`               | 使用独立的本地登录和安全状态。                                                                                                           |
| `--force`                        | 替换同名冲突条目，或重装匹配条目。不会批准付款。                                                                                                  |
| `--log-file <absolute-path.log>` | 将日志文件传给已安装的服务器。仅限用户范围。                                                                                                    |

`list`、`remove` 和 `status` 只能看到 `add` 写入的条目，看不到你按照[安装 assay-mcp](/developers/zh/shi-yong-gong-ju-ru-men/install-assay-mcp.md)手动添加的条目。

如果已明确指定客户端或没有歧义，`add` 可以不使用终端运行。只有交互式用户范围安装会询问是否允许付费调用，并要求输入配置文件名称。项目范围绝不会添加这项许可。范围限制（包括 Windows）见 [URL 与配置文件](/developers/zh/shi-yong-gong-ju-jin-jie/urls-and-profiles.md)。

## 付款许可和限额

| 命令                                                                                                                                                         | 用途                                     | 交互式终端 |
| ---------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------- | ----- |
| `npx -y @goassay-ai/mcp allow-paid <url-or-path> [--profile <name>]`                                                                                       | 允许通过此规范化路径和查询参数进行付费调用。新增许可时要求输入配置文件名称。 | 需要    |
| `npx -y @goassay-ai/mcp disallow-paid <url-or-path> [--profile <name>]`                                                                                    | 移除此 URL 的付费许可。免费调用仍可使用。                | 需要    |
| `npx -y @goassay-ai/mcp limits [--profile <name>]`                                                                                                         | 显示本地单次调用、滚动日限额、确认和提供方设置。               | 不需要   |
| `npx -y @goassay-ai/mcp limits set --per-call <usd> --per-day <usd> [--confirm-above <usd-or-off>] [--providers <address-list-or-off>] [--profile <name>]` | 修改本地签名限额。不会修改链上上限。                     | 需要    |

| `limits set` 参数                     | 含义                                        |
| ----------------------------------- | ----------------------------------------- |
| `--per-call <usd>`                  | 必填，非负美元金额，最多六位小数。不得超过 `--per-day`。        |
| `--per-day <usd>`                   | 必填，本地滚动 24 小时窗口的非负美元金额。                   |
| `--confirm-above <usd-or-off>`      | 超过此金额时提示确认，或用 `off` 关闭提示。省略会保留现值。         |
| `--providers <address-list-or-off>` | 逗号分隔的收款方地址，1–100 项；`off` 表示不限制。省略会保留现有列表。 |

用 `status` 查看获准 URL；没有 `paid-urls` 命令。这些设置如何影响调用，见[支出限额](/developers/zh/shi-yong-gong-ju-ru-men/spending-limits.md)和[访问策略](/developers/zh/shi-yong-gong-ju-jin-jie/access-policy.md)。

## 运行 MCP 服务器

AI 客户端通常会启动此进程，并通过 stdio 通信。省略 `serve`（包括直接以 serve 参数开头）也会启动同一服务器。

```sh
npx -y @goassay-ai/mcp serve --name assay
```

| 参数                               | 默认值               | 含义                                                         |
| -------------------------------- | ----------------- | ---------------------------------------------------------- |
| `--url <url-or-path>`            | 内置 Assay 源站上的 `/` | 选择一个 MCP URL。                                              |
| `--name <name>`                  | 未显式指定名称           | 与客户端条目的服务器名称一致，用于处理工具名称长度。最多 56 个字符，以小写字母开头，只含小写字母、数字和连字符。 |
| `--profile <name>`               | `default`         | 选择本地登录、密钥和安全状态。                                            |
| `--no-paid`                      | 关闭                | 此进程绝不为付款签名。                                                |
| `--log-level <level>`            | `warn`            | `error`、`warn`、`info` 或 `debug`。                           |
| `--log-file <absolute-path.log>` | 无                 | 同时将诊断日志追加到本地文件。                                            |

配置文件名称以小写字母或数字开头，只含小写字母、数字和连字符，最多 32 个字符。只有上方列出 `--profile` 的命令才支持它。它不是 `list` 或 `remove` 的全局参数。

## 环境变量与无界面使用

| 变量              | 含义                                                                                                                                                                                                                         |
| --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `ASSAY_API_KEY` | 智能体 API 密钥（`assay_sk_live_…`）。设置后，服务器会用它代替浏览器登录。它只从环境变量读取，不会从参数或文件读取。在 Assay 中智能体的 **Keys** 下创建；参阅[管理智能体、已连接应用与支付密钥](https://docs.goassay.ai/use-tools/zh/manage-agents-apps-and-keys)。设置该变量时，`add --scope project` 会拒绝运行。 |

`assay-mcp` 始终需要操作系统密钥链：macOS Keychain、Windows Credential Manager 或 Linux Secret Service。即使设置了 `ASSAY_API_KEY` 也是如此，因为支付密钥保存在密钥链中。暂不支持没有密钥链的机器，例如 CI 运行器和容器。

## 确认是否成功

修改客户端条目后用 `list` 检查；修改本地权限后，为目标配置文件运行 `status`。安装后请重启客户端。一般退出码：0 表示完成，1 表示失败，2 表示用法错误或因要求终端而拒绝。取消输入确认会返回 0 并显示 **Nothing changed.**；请查看状态以确认是否发生变更。

<details>

<summary>可选：允许使用环境中的网络代理</summary>

| 命令                                                                             | 用途                                     | 交互式终端 |
| ------------------------------------------------------------------------------ | -------------------------------------- | ----- |
| `npx -y @goassay-ai/mcp settings [--profile <name>]`                           | 显示是否允许环境 HTTP 代理；默认拒绝。                 | 不需要   |
| `npx -y @goassay-ai/mcp settings set --allow-env-proxy on [--profile <name>]`  | 输入配置文件名称后，允许该配置文件使用环境代理设置。只启用你自行配置的代理。 | 需要    |
| `npx -y @goassay-ai/mcp settings set --allow-env-proxy off [--profile <name>]` | 恢复拒绝环境代理设置。                            | 需要    |

此许可涵盖 `HTTPS_PROXY`、`HTTP_PROXY`、其小写形式，以及 Node 的环境代理设置。不允许禁用 TLS 证书检查。参阅[安全模型](/developers/zh/shi-yong-gong-ju-jin-jie/security-model.md)。

</details>

<details>

<summary>可选：日志文件规则</summary>

使用以 `.log` 结尾的绝对路径，父目录必须已存在。不接受符号链接或其他用户的文件。现有文件必须以 `# assay-mcp log v1` 开头；MCP 不会追加到任意文件。在 POSIX 上，日志文件仅供你的用户访问。常规命令输出和日志使用 stderr；stdout 留给 MCP 消息和 `--version`。

</details>

## 错误

| 原因                            | 解决方法                               |
| ----------------------------- | ---------------------------------- |
| 未知选项或缺少值                      | 使用该命令支持的参数。帮助别名仅在顶层可用。             |
| Interactive terminal required | 请自行在 stdin 和 stdout 都连接终端的环境中修改设置。 |
| 无法解析现有配置                      | 在客户端中修正；辅助命令拒绝重写格式错误的配置。           |

## 延伸阅读

* [URL 与配置文件](/developers/zh/shi-yong-gong-ju-jin-jie/urls-and-profiles.md)
* [重试与幂等](/developers/zh/shi-yong-gong-ju-jin-jie/retries-and-idempotency.md)

## 下一步

* [故障排查](/developers/zh/shi-yong-gong-ju-jin-jie/troubleshooting.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.goassay.ai/developers/zh/shi-yong-gong-ju-jin-jie/cli-reference.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.