Archery MCP 2FA

为 @seaxlab/archery-mcp 增加 Archery TOTP 双因素认证（2FA）支持的持久补丁。

本项目不直连数据库，也不会绕过 Archery 的权限、脱敏、限流或审计机制。它只扩展登录流程，使启用了 TOTP 的 Archery 账号也能通过 MCP 服务完成认证。

当前补丁仅适用于 @seaxlab/archery-mcp@3.0.2。升级上游依赖前，请先确认补丁仍然兼容并重新生成补丁文件。

功能

• 启动时自动使用配置中的 Archery 账号和密码登录。
• 检测到 TOTP 验证时，在交互式终端中提示输入 6 位验证码。
• 无交互式终端时，提供 MCP 工具完成认证。
• 认证成功后复用同一个 Archery 会话。
• TOTP 验证码仅用于当前请求，不写入配置文件或元数据缓存。
• 使用 patch-package 在安装依赖后自动应用补丁。

环境要求

• Node.js 24 或更高版本。
• npm 10 或更高版本。
• 可访问的 Archery 服务；上游包标明支持 Archery v1.8.5。
• 已启用 TOTP 的 Archery 账号，或普通账号密码。

快速开始

1. 获取项目并安装依赖

git clone <repository-url>
cd archery-mcp-2fa
npm ci

npm ci 完成后，postinstall 脚本会自动应用 patches/ 中的 2FA 补丁。

2. 准备配置文件

可以基于上游包提供的示例创建配置：

mkdir -p ~/.config/archery-mcp
cp node_modules/@seaxlab/archery-mcp/config.example.toml \
  ~/.config/archery-mcp/pro.toml
chmod 600 ~/.config/archery-mcp/pro.toml

编辑 ~/.config/archery-mcp/pro.toml，至少填写以下内容：

env = "pro"

[server]
host = "127.0.0.1"
port = 3000

[archery]
base_url = "https://archery.example.com"
username = "mcp_service"
password = "replace-with-a-strong-password"

[query]
default_limit = 100
max_limit = 500

[cache]
enabled = true
ttl_seconds = 604800
exclude_instance_names = []
exclude_instance_ids = []

配置文件包含明文密码，请始终限制文件权限，并且不要将真实配置提交到版本库。

完整配置项说明请参阅上游项目安装后的 node_modules/@seaxlab/archery-mcp/README.md 和 config.example.toml。

3. 启动服务

通过命令行参数指定配置文件：

npm start -- --config ~/.config/archery-mcp/pro.toml

也可以使用环境变量：

ARCHERY_MCP_CONFIG=~/.config/archery-mcp/pro.toml npm start

默认 MCP 地址为：

http://127.0.0.1:3000/mcp

健康检查地址为：

http://127.0.0.1:3000/health

TOTP 认证流程

交互式终端

如果账号启用了 TOTP，启动时终端会提示：

archery-mcp [env=pro] Archery requires TOTP authentication
请输入当前 6 位 TOTP 验证码:

输入身份验证器当前显示的验证码。认证成功后，服务开始监听端口：

archery-mcp [env=pro] TOTP authentication succeeded
archery-mcp [env=pro] listening on http://127.0.0.1:3000/mcp

验证码无效时可直接重试。Archery 会话过期或进程重启后，需要重新验证。

无交互式终端

当服务由容器、后台任务或进程管理器启动，且没有可交互终端时，服务仍会启动，并注册以下 MCP 工具：

工具	说明
archery_auth_status	发起登录，或查看当前账号登录及 2FA 认证状态
archery_submit_otp	提交当前 6 位 TOTP 验证码并完成登录

认证步骤：

1. 调用 archery_auth_status。
2. 如果返回 two_factor_required: true，让用户提供身份验证器当前显示的 6 位验证码。
3. 调用 archery_submit_otp，参数为 { "otp": "123456" }。
4. 确认返回 authenticated: true 后，再调用查询或 SQL 审核工具。

除上述两个认证工具外，其余 MCP 工具与上游 @seaxlab/archery-mcp 保持一致。

MCP 客户端配置

使用支持 Streamable HTTP 的 MCP 客户端连接：

{
  "mcpServers": {
    "archery": {
      "type": "streamable-http",
      "url": "http://127.0.0.1:3000/mcp"
    }
  }
}

Codex 可在 ~/.codex/config.toml 中配置：

[mcp_servers.archery]
url = "http://127.0.0.1:3000/mcp"

Claude Code 可使用命令行添加：

claude mcp add --transport http archery http://127.0.0.1:3000/mcp

项目结构

.
├── patches/
│   └── @seaxlab+archery-mcp+3.0.2.patch  # TOTP 支持补丁
├── package.json                           # 依赖和启动脚本
├── package-lock.json                      # 锁定依赖版本
└── README.md

常用命令

命令	说明
npm ci	按锁文件安装依赖并自动应用补丁
npm install	安装或更新依赖并自动应用补丁
npm start -- --config <path>	使用指定 TOML 配置启动服务
npx patch-package @seaxlab/archery-mcp	修改依赖后重新生成补丁

请勿直接使用 npx -y @seaxlab/archery-mcp@3.0.2 启动，否则运行的是未包含本项目 2FA 补丁的官方 npm 包。

安全说明

• 默认只监听 127.0.0.1。MCP HTTP 端点本身没有鉴权，不应直接暴露到公网。
• 如需跨机器访问，请在反向代理层增加 TLS、访问认证和网络访问控制。
• Archery 密码保存在 TOML 配置中，请设置 chmod 600 并使用专用的最小权限服务账号。
• 不要将真实密码、TOTP 验证码、会话 Cookie、内部 Archery 地址或生产配置提交到仓库、Issue 或日志中。
• TOTP 会通过 MCP 请求传递。使用远程 MCP 客户端时，请确保通信链路可信且已加密。

兼容性与维护

补丁直接作用于上游包的构建产物，因此上游版本变化可能导致补丁无法应用或行为不兼容。升级时建议：

1. 更新 package.json 中的 @seaxlab/archery-mcp 版本。
2. 执行 npm install 并检查补丁冲突。
3. 在 node_modules/@seaxlab/archery-mcp 中重新实现和验证 2FA 修改。
4. 运行 npx patch-package @seaxlab/archery-mcp 生成新补丁。
5. 在交互式终端和无交互式终端中分别验证认证流程。

贡献

欢迎提交 Issue 或 Pull Request。提交代码前请确保没有包含真实账号、密码、验证码、Cookie、内部域名或其他敏感信息。

致谢与声明

本项目基于 @seaxlab/archery-mcp 的公开发行包制作补丁，并非 Archery 或上游包维护者的官方项目。Archery 和相关名称的权利归其各自所有者所有。