Archery MCP server

archery-mcp

<!-- mcp-name: io.github.itzhouq/archery-mcp -->

Unofficial read-only MCP server for Archery — let your AI coding agent inspect production table schema and validate release SQL through your own Archery platform, with permissions, row limits and data masking still enforced by Archery itself.

中文：archery-mcp 是一个 MCP Server，把 Archery SQL 审核平台的在线查询与 SQL 检查能力带给 AI 编码助手（Claude Code、Cursor、Codex CLI 等）。AI 在写代码时可以直接查看线上表结构、验证数据特征、检查上线 SQL 规范，而不需要你手动比对环境差异。

[!IMPORTANT]

- 本项目与 Archery 官方无隶属关系，是独立的非官方客户端；

- 本项目按"现状"提供（MIT License）。使用者须自行取得公司授权并遵守公司数据安全规定，作者不对违规使用及其后果负责；

- 安全模型：本 MCP 不在本地过滤 SQL 或遮蔽数据，权限、行数上限、超时与脱敏完全由你自己的 Archery 平台执行——请给 MCP 配置专用的最小权限账号（见安全模型）。

为什么做这个

日常迭代业务系统时，常见的三个痛点：

1. test 和 prod 的表结构、索引可能不一致。AI 拿着过时或想当然的表结构写代码、写上线脚本，错误要到上线前人工比对时才发现；
2. 上线脚本靠人工比对环境差异来写。版本迭代需要 DDL/DML 时，你得手动 DESC 生产表、核对索引，再让 AI 照着写——重复、低效、易错；
3. 有些数据清洗依赖生产数据的真实特征（脏数据分布、边界记录、字段实际取值），test 环境的数据无法完整呈现。

这些问题的共同解法是：让 AI 在编码工作流中随时、只读地"看见"生产库——而不是绕过审批直连数据库。如果公司已经在用 Archery 管理 SQL 查询和上线工单，权限、审计、脱敏、工单流都已经在 Archery 里，那么把 Archery 的查询能力封装成 MCP 工具，就是最稳妥的路径。这正是 archery-mcp 做的事。

工作原理

flowchart LR
    A["MCP 客户端<br/>Claude Code / Cursor / Codex CLI"] -->|"MCP stdio"| B["archery-mcp<br/>锁定目标 + 内置规范检查"]
    B -->|"会话登录 + CSRF + TOTP"| C["Archery 平台<br/>权限 · 审计 · 脱敏 · 行数限制"]
    C -->|"只读在线查询"| D[("生产数据库")]

• 服务端锁定目标：启动时通过环境变量固定实例、数据库和模式，AI 调用工具时不能切换查询目标，防止模型误连其他库；
• 策略下沉 Archery：SQL 是否可执行、返回行数、超时、脱敏、审计全部由 Archery 配置和账号权限决定，本 MCP 原样转发、原样返回，不做二次过滤；
• sqlcheck 双路检查**：内置规范（本地静态规则）+ Archery 平台检查（/api/v1/workflow/sqlcheck/）合并出结论，平台不可用时优雅降级。

工具列表

sqlcheck 内置规范要点（规则实现在 src/archerymcp/sql_rules.py，errlevel 语义与 Archery 一致：0 通过 / 1 警告 / 2 错误）：

• 上线 SQL 仅支持 DML/DDL，不接受 SELECT（错误）；
• UPDATE/DELETE 必须带 WHERE 条件（错误）；
• 存储过程 / 函数 / 触发器 / DO 块不接受（错误）；
• 事务控制语句（BEGIN/COMMIT 等）警告——平台会逐条执行并自动提交；
• 临时表、CTE/窗口函数/CREATE TABLE AS、TRUNCATE、DROP DATABASE/SCHEMA、混提 DDL 与 DML 均给出警告。

与其他方案的区别

定位差异：archery-mcp 面向"嵌入日常迭代开发流"——固定目标、只读优先、上线前检查，牺牲灵活性换取更低的误操作面。

快速开始

前置条件：Python 3.11+，一个能访问 Archery 的账号（建议专用最小权限账号），且账号有在线查询权限。

方式一：uvx（推荐，无需安装）

uvx archery-mcp

方式二：pip

pip install archery-mcp

方式三：源码

git clone https://github.com/itzhouq/archery-mcp
cd archery-mcp
python -m pip install -e .

MCP 客户端配置

以 Claude Code 为例，在项目根目录 .mcp.json（或全局配置）中加入：

Shortened. The full README is on GitHub.