Archery MCP

面向 Archery 的安全只读 Model Context Protocol 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 客户端配置示例：

{
  "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：

.\build-exe.ps1 -Python python

脚本会依次安装构建依赖、执行全部单元测试、使用 PyInstaller 生成单文件 EXE，并通过真实 MCP stdio 握手检查全部工具。成功产物位于：

dist/archery-mcp.exe

GitHub Actions 中的“构建 Windows EXE”工作流支持手动触发，也会在推送 v* 标签时自动构建并上传 archery-mcp-windows-x64 Artifact。

安装方式二：Docker

使用方无需安装 Python，但需要安装 Docker。镜像使用标准输入输出传输 MCP 协议，因此必须使用 -i 保持 stdin 打开。

构建并验证镜像

Windows PowerShell：

.\build-docker.ps1 -Image archery-mcp:local -Python python

也可以手工执行：

docker build -t archery-mcp:local .
python scripts/smoke_test_docker.py archery-mcp:local

Docker MCP 客户端配置

下面的 -e ARCHERY_* 只传递变量名，实际值来自 MCP 客户端进程环境，不会出现在 Docker 命令行参数中：

{
  "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。在宿主机设置所需环境变量后，可以执行：

docker compose build
docker compose run --rm archery-mcp

不要使用缺少 -i 的 docker run，否则容器无法接收 MCP 客户端发送的 stdio 消息。

安装方式三：Python

需要 Python 3.10 或更高版本。

git clone <仓库地址>
cd archery-mcp
python -m venv .venv

Windows PowerShell：

.\.venv\Scripts\python.exe -m pip install .

Linux 或 macOS：

./.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 示例：

{
  "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，只返回文件路径、实际行数、分页次数和是否因显式限制而截断。

示例参数：

{
  "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 的最小权限服务账号。

本地开发

python -m pip install -e ".[test]"
python -m pytest -q

提交代码前请阅读 贡献指南。安全问题请按 安全策略 处理。

许可证

本项目使用 MIT License。许可证文件保留标准英文法律文本。