# Archery MCP 2FA

为 [`@seaxlab/archery-mcp`](https://www.npmjs.com/package/@seaxlab/archery-mcp) 增加 Archery TOTP 双因素认证（2FA）支持的持久补丁。

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

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

## 功能

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

## 环境要求

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

## 快速开始

### 1. 获取项目并安装依赖

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

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

### 2. 准备配置文件

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

```bash
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`，至少填写以下内容：

```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. 启动服务

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

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

也可以使用环境变量：

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

默认 MCP 地址为：

```text
http://127.0.0.1:3000/mcp
```

健康检查地址为：

```text
http://127.0.0.1:3000/health
```

## TOTP 认证流程

### 交互式终端

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

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

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

```text
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 客户端连接：

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

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

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

Claude Code 可使用命令行添加：

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

## 项目结构

```text
.
├── 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 和相关名称的权利归其各自所有者所有。