内容
# Archery MCP
[](LICENSE)
面向 [Archery](https://github.com/hhyo/Archery) 的安全只读 [Model Context Protocol](https://modelcontextprotocol.io/) Server。项目使用 Archery 用户名和密码认证，维护 Django Session 与 CSRF 状态，并向 AI 客户端提供实例查询、工单查询和受限 SQL 查询工具。
## 功能特性
- 通过 Archery `/authenticate/` 接口使用用户名和密码登录。
- 自动处理 CSRF、复用 Session，并在会话过期后重新登录一次。
- 使用 SQL AST 解析器对只读 SQL 做本地强校验。
- 实例归属、查询权限、超时、行数限制、审计日志和数据脱敏继续由 Archery 服务端负责。
- 不提供工单审批、变更 SQL 执行或任意 HTTP 代理工具。
- 已在 Archery v1.14.0 上完成真实环境验证。
## MCP 工具
| 工具 | 说明 |
|---|---|
| `archery_health` | 检查 Archery 连通性并识别版本 |
| `archery_login_status` | 验证配置的账号能否建立 Session |
| `archery_list_instances` | 查询账号有权查看的实例，需要实例列表权限 |
| `archery_list_query_instances` | 查询账号可用于只读查询的实例 |
| `archery_list_databases` | 查询指定实例中的数据库 |
| `archery_query` | 执行一条受限只读查询，最多返回 5000 行 |
| `archery_export_query` | 将查询结果分批写入 CSV，默认不限制总行数 |
| `archery_list_workflows` | 查询当前账号可见的 SQL 工单 |
| `archery_workflow_status` | 查询工单状态 |
| `archery_workflow_detail` | 查询工单审核或执行明细 |
## 安装方式一：Windows EXE（推荐）
Windows 用户可以直接使用发布产物 `archery-mcp.exe`，无需安装 Python，也无需单独安装依赖。
MCP 客户端配置示例：
```json
{
"mcpServers": {
"archery": {
"command": "D:/tools/archery-mcp.exe",
"env": {
"ARCHERY_URL": "https://archery.example.com",
"ARCHERY_USERNAME": "service-account",
"ARCHERY_PASSWORD": "use-your-secret-store",
"ARCHERY_VERIFY_TLS": "true",
"ARCHERY_EXPORT_DIR": "D:/tools/archery-exports"
}
}
}
}
```
EXE 使用标准输入输出与 MCP 客户端通信，因此不要直接双击运行。启动和停止由 MCP 客户端负责。
### 本地构建 EXE
维护者需要 Python 3.10 或更高版本执行构建，最终使用者不需要 Python：
```powershell
.\build-exe.ps1 -Python python
```
脚本会依次安装构建依赖、执行全部单元测试、使用 PyInstaller 生成单文件 EXE，并通过真实 MCP stdio 握手检查全部工具。成功产物位于：
```text
dist/archery-mcp.exe
```
GitHub Actions 中的“构建 Windows EXE”工作流支持手动触发，也会在推送 `v*` 标签时自动构建并上传 `archery-mcp-windows-x64` Artifact。
## 安装方式二：Docker
使用方无需安装 Python，但需要安装 Docker。镜像使用标准输入输出传输 MCP 协议，因此必须使用 `-i` 保持 stdin 打开。
### 构建并验证镜像
Windows PowerShell：
```powershell
.\build-docker.ps1 -Image archery-mcp:local -Python python
```
也可以手工执行：
```bash
docker build -t archery-mcp:local .
python scripts/smoke_test_docker.py archery-mcp:local
```
### Docker MCP 客户端配置
下面的 `-e ARCHERY_*` 只传递变量名，实际值来自 MCP 客户端进程环境，不会出现在 Docker 命令行参数中：
```json
{
"mcpServers": {
"archery": {
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"--read-only",
"--tmpfs",
"/tmp:size=64m,mode=1777",
"--security-opt",
"no-new-privileges:true",
"-e",
"ARCHERY_URL",
"-e",
"ARCHERY_USERNAME",
"-e",
"ARCHERY_PASSWORD",
"-e",
"ARCHERY_VERIFY_TLS",
"-e",
"ARCHERY_TIMEOUT",
"-e",
"ARCHERY_EXPORT_DIR",
"--volume",
"D:/tools/archery-exports:/exports",
"archery-mcp:local"
],
"env": {
"ARCHERY_URL": "https://archery.example.com",
"ARCHERY_USERNAME": "service-account",
"ARCHERY_PASSWORD": "use-your-secret-store",
"ARCHERY_VERIFY_TLS": "true",
"ARCHERY_TIMEOUT": "30",
"ARCHERY_EXPORT_DIR": "/exports"
}
}
}
}
```
项目也提供 `docker-compose.yml`。在宿主机设置所需环境变量后，可以执行：
```bash
docker compose build
docker compose run --rm archery-mcp
```
不要使用缺少 `-i` 的 `docker run`，否则容器无法接收 MCP 客户端发送的 stdio 消息。
## 安装方式三：Python
需要 Python 3.10 或更高版本。
```bash
git clone <仓库地址>
cd archery-mcp
python -m venv .venv
```
Windows PowerShell：
```powershell
.\.venv\Scripts\python.exe -m pip install .
```
Linux 或 macOS：
```bash
./.venv/bin/python -m pip install .
```
## 环境变量
| 环境变量 | 说明 |
|---|---|
| `ARCHERY_URL` | Archery 根地址，例如 `https://archery.example.com` |
| `ARCHERY_USERNAME` | 最小权限服务账号用户名 |
| `ARCHERY_PASSWORD` | 服务账号密码 |
| `ARCHERY_VERIFY_TLS` | 是否校验 TLS 证书，默认为 `true` |
| `ARCHERY_TIMEOUT` | HTTP 超时时间，默认 30 秒，最大 120 秒 |
| `ARCHERY_EXPORT_DIR` | CSV 导出目录，Python/EXE 默认是当前目录下的 `exports` |
## Python 方式的 MCP 客户端配置
Windows 示例：
```json
{
"mcpServers": {
"archery": {
"command": "D:/path/to/archery-mcp/.venv/Scripts/python.exe",
"args": ["-m", "archery_mcp.server"],
"env": {
"ARCHERY_URL": "https://archery.example.com",
"ARCHERY_USERNAME": "service-account",
"ARCHERY_PASSWORD": "use-your-secret-store",
"ARCHERY_VERIFY_TLS": "true",
"ARCHERY_EXPORT_DIR": "D:/path/to/archery-exports"
}
}
}
}
```
不要将真实凭据提交到 Git。`${ENV_VAR}` 占位符是否生效取决于 MCP 客户端，建议通过客户端进程环境或密钥管理服务注入凭据。
## 查询安全
`archery_query` 只接受一条 `SELECT`、`WITH` 或集合查询，并拒绝：
- 多条 SQL；
- 新增、更新、删除、DDL 和管理命令；
- `FOR UPDATE` 等锁查询；
- 文件导入、文件读取和文件导出操作；
- `sleep`、`benchmark` 等延迟或资源消耗函数；
- 普通查询超过 5000 行的返回请求。
## 分页导出
`archery_export_query` 适合导出超过 Archery 单次查询上限的数据。默认每页查询 5000 行，不限制总行数，并持续分页到 Archery 返回不足一页为止。工具不会把大量数据返回给 AI，而是流式写入 CSV，只返回文件路径、实际行数、分页次数和是否因显式限制而截断。
示例参数：
```json
{
"instance_name": "read-replica",
"database": "example",
"sql": "select id, name from account order by id",
"page_size": 5000,
"max_rows": 0,
"filename": "accounts.csv"
}
```
多页导出要求 SQL 顶层包含稳定且尽量唯一的 `ORDER BY`，例如 `order by id`。传入 SQL 不能自行包含 `LIMIT` 或 `OFFSET`，分页条件由 MCP 统一生成。CSV 使用 UTF-8 BOM 以兼容 Excel，并对 `=`、`+`、`-`、`@` 等开头的文本增加前缀，降低 CSV 公式注入风险。
`max_rows=0` 表示不限制总行数；传入正数时可以主动设置本次导出上限。不限量导出可能持续占用 Archery 查询资源和本地磁盘，请确保 SQL 使用稳定排序，并监控导出目录容量。
导出文件只能写入 `ARCHERY_EXPORT_DIR`。Docker 模式必须把宿主机目录挂载到 `/exports`；Compose 默认将项目下的 `exports` 目录挂载进去。
CSV 可能包含敏感业务数据。请限制导出目录的操作系统访问权限，设置定期清理策略，不要把导出目录提交到 Git、打进镜像或暴露为公共下载目录。
本地 SQL 校验属于纵深防御，不能替代 Archery 或数据库权限。生产环境必须使用专用最小权限账号，优先关联只读数据库实例，并保持 Archery 的资源组、查询权限、超时、审计日志、行数限制和数据脱敏配置有效。
启用交互式 2FA 的账号无法用于机器登录。服务检测到 2FA 后会终止登录，应为 MCP 创建未启用交互式 2FA 的最小权限服务账号。
## 本地开发
```bash
python -m pip install -e ".[test]"
python -m pytest -q
```
提交代码前请阅读 [贡献指南](CONTRIBUTING.md)。安全问题请按 [安全策略](SECURITY.md) 处理。
## 许可证
本项目使用 [MIT License](LICENSE)。许可证文件保留标准英文法律文本。
