Archery MCP

archery-mcp

Archery 用の非公式・読み取り専用 MCP サーバー — Archery プラットフォームを通じて、AI コーディングエージェントが本番環境のテーブルスキーマを調査し、リリース SQL を検証できるようにします。権限、行数制限、データマスキングは Archery 自体によって引き続き適用されます。

中文：archery-mcp は MCP サーバーであり、Archery SQL 審査プラットフォームのオンラインクエリと SQL チェック機能を、AI コーディングアシスタント（Claude Code、Cursor、Codex CLI など）に提供します。AI はコード作成中に、本番環境のテーブル構造を直接確認し、データの特徴を検証し、リリース SQL の規約をチェックできます。環境間の差異を手作業で比較する必要はありません。

重要

• 本プロジェクトは Archery 公式とは無関係の、独立した非公式クライアントです。
• 本プロジェクトは「現状のまま」提供されます（MIT License）。利用者は自ら会社の承認を得て、会社のデータセキュリティ規定を遵守する必要があります。作者は、規定に違反した利用およびその結果について責任を負いません。
• セキュリティモデル：この MCP はローカルで SQL のフィルタリングやデータのマスキングを行いません。権限、行数制限、タイムアウト、マスキングはすべて、ご利用の Archery プラットフォームによって適用されます。MCP には最小権限の専用アカウントを設定してください（セキュリティモデルと免責事項を参照）。

作成の背景

業務システムを日常的に開発する中で、よくある課題が3つあります。

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 はそのまま転送し、そのまま返却し、二次フィルタリングは行いません。
• sql_check は二段階でチェック：組み込み規約（ローカルの静的ルール）と Archery プラットフォームのチェック（/api/v1/workflow/sqlcheck/）を統合して結果を出します。プラットフォームが利用できない場合は、適切に縮退動作します。

ツール一覧

ツール	説明
list_tables(keyword="")	固定対象のデータベースにあるテーブルを一覧表示します。キーワードで絞り込めます
describe_table(table_name)	テーブル構造（フィールド、型、デフォルト値、コメント）を確認します
query(sql, limit=None)	Archery のオンラインクエリで SQL を実行します（読み取り専用、そのまま転送）
query_history(limit=20, search="")	現在の Archery アカウントのクエリ履歴を確認します
sql_check(sql)	リリース SQL をチェックします：組み込み規約 + Archery プラットフォームのチェック。チェックのみで、実行はしません

sql_check の組み込み規約の要点（ルールは src/archery_mcp/sql_rules.py に実装されています。errlevel の意味は Archery と同じです：0 は合格／1 は警告／2 はエラー）。

• リリース SQL は DML/DDL のみをサポートし、SELECT は受け付けません（エラー）。
• UPDATE/DELETE には WHERE 条件が必要です（エラー）。
• ストアドプロシージャ／関数／トリガー／DO ブロックは受け付けません（エラー）。
• トランザクション制御ステートメント（BEGIN/COMMIT など）は警告されます。プラットフォームはステートメントを1つずつ実行し、自動コミットするためです。
• 一時テーブル、CTE／ウィンドウ関数／CREATE TABLE AS、TRUNCATE、DROP DATABASE/SCHEMA、DDL と DML の混在には警告が出ます。

他の方法との違い

方法	権限／監査／マスキング	対象の制御	リリース SQL のチェック
本番データベースに直接接続するデータベース MCP	❌ プラットフォームを迂回	モデルの自制に依存	❌
archery-mcp-server（Archery API を全面的にラップ）	✅ Archery 経由	クライアントが引数を渡し、複数インスタンスを自由に切り替え可能	プラットフォームのチェック
archery-mcp（本プロジェクト）	✅ Archery 経由	サーバー側で単一の対象を固定し、モデルは変更不可	組み込み規約とプラットフォームのチェックを統合

位置づけの違い：archery-mcp は「日常の開発フローに組み込む」ことを想定しています。対象を固定し、読み取り専用を優先し、リリース前にチェックを行います。柔軟性を犠牲にすることで、誤操作の可能性を抑えています。

クイックスタート

前提条件：Python 3.11 以降、Archery にアクセスできるアカウント（最小権限の専用アカウントを推奨）、およびオンラインクエリの権限。

方法1：uvx（推奨、インストール不要）

uvx archery-mcp

方法2：pip

pip install archery-mcp

方法3：ソースコード

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

MCP クライアントの設定

Claude Code を例に、プロジェクトのルートディレクトリにある .mcp.json（またはグローバル設定）に次の内容を追加します。

{
  "mcpServers": {
    "archery_mcp": {
      "command": "uvx",
      "args": ["archery-mcp"],
      "env": {
        "ARCHERY_BASE_URL": "https://archery.example.com",
        "ARCHERY_USERNAME": "你的 Archery 用户名",
        "ARCHERY_PASSWORD": "你的 Archery 密码",
        "ARCHERY_TOTP_SECRET": "",
        "ARCHERY_INSTANCE_NAME": "prod-app-db",
        "ARCHERY_DB_NAME": "app_db",
        "ARCHERY_SCHEMA_NAME": "public",
        "ARCHERY_QUERY_LIMIT": "100"
      }
    }
  }
}

Cursor / Codex CLI など、他のクライアントでも同じ command / args / env 構造を使用します。保存後、クライアントを再起動すれば設定が適用されます。認証情報はプロセスの環境変数を通じてのみ渡し、コミットするファイルには書き込まないでください。

設定項目

環境変数	必須	説明	デフォルト
ARCHERY_BASE_URL	✅	Archery のデプロイ先 URL。例：https://archery.example.com	—
ARCHERY_USERNAME	✅	Archery のユーザー名（最小権限の専用アカウントを推奨）	—
ARCHERY_PASSWORD	✅	Archery のパスワード	—
ARCHERY_TOTP_SECRET	—	アカウントで Google 認証システムを有効にしている場合の base32 キー（6桁の認証コードではありません）	空
ARCHERY_INSTANCE_NAME	✅	固定する Archery インスタンス名（アカウントがアクセスできる一覧に含まれている必要があります）	—
ARCHERY_DB_NAME	✅	固定するデータベース名	—
ARCHERY_SCHEMA_NAME	—	固定するスキーマ名。PostgreSQL では通常 public を指定し、MySQL では空欄にできます	public
ARCHERY_QUERY_LIMIT	—	query に limit が渡されなかった場合のデフォルト行数。0 は、アカウント権限に基づく Archery の最大制限に委ねることを意味します	100

安全模型与免责声明

由 Archery 负责的部分（本 MCP 原样委托，不做本地重复实现）：

• 实例/库/表的访问权限与资源组隔离；
• SQL 可执行性检查、高危语句正则（critical_ddl_regex）；
• 查询返回行数上限、查询超时；
• 数据脱敏规则（is_masked 会随查询结果返回）；
• 查询审计与历史（query_history 工具可直接查看）。

由 MCP 锁定的部分：

• 查询目标（实例/库/模式）在服务端配置中固定，工具调用不可切换；
• 凭据只通过环境变量传递，不落盘、不写日志。

部署建议：

1. 为 MCP 创建专用 Archery 账号，不要用管理员账号；
2. 只分配目标资源组/实例/库的查询权限；
3. 在 Archery 中配置数据脱敏规则；
4. 定期审计 Archery 查询历史；
5. sql_check 需要账号在 Archery 的 API 用户白名单（api_user_whitelist）内并拥有上线权限（sql.sql_submit）；不可用时本地规范结果仍会返回。

免责声明：本项目按"现状"提供，不含任何担保。使用本工具访问生产数据库前，请确认你已获得公司授权、遵守公司数据安全与合规规定。因违反公司规定或平台策略使用本工具导致的任何后果由使用者自行承担。

本地开发与验证

python -m pip install -e ".[dev]"
python -m pytest -q          # 46 个测试，全部 Mock，不访问真实 Archery
ruff check src tests scripts
bash scripts/check_sensitive.sh   # 敏感信息扫描

对真实 Archery 的冒烟验证（会登录并执行只读查询）：

ARCHERY_BASE_URL="https://archery.example.com" \
ARCHERY_USERNAME="你的用户名" \
ARCHERY_PASSWORD="你的密码" \
python scripts/smoke_readonly.py      # 表清单 → 表结构 → SELECT *
python scripts/smoke_sql_check.py     # 上线 SQL 检查（只检查不执行）
python scripts/smoke_mcp_stdio.py     # MCP stdio 全链路

架构与设计决策的完整说明见 docs/ARCHITECTURE.md，参与开发见 CONTRIBUTING.md。

FAQ

登录报"用户名或密码错误"，但网页能正常登录？ 账号大概率开启了两步验证。设置 ARCHERY_TOTP_SECRET 为 Google 身份验证器对应的 base32 密钥（绑定时的那串大写字母，不是实时的六位验证码）。

sql_check 提示"平台检查未执行"？ 账号需要在 Archery 系统配置 api_user_whitelist（API 用户白名单）内，并拥有 sql.sql_submit 权限。本地内置规范结果不受影响。

查询被 Archery 拒绝？ 检查账号在 Archery 中的资源组、实例与库权限，以及该账号的查询行数限制配置。MCP 会原样返回 Archery 的错误信息。

支持哪些 Archery 版本？ 针对 Archery v1.10.0 开发与实测。其他版本的 Web 端点行为未验证，遇到不兼容欢迎提 Issue（附上版本号与脱敏后的错误信息）。

为什么不在 MCP 侧过滤敏感字段？ 本地过滤会制造"看起来安全"的错觉，而权限与脱敏的真正执行点在 Archery。MCP 侧重复实现只会两套规则互相打架；把策略收敛到平台一处，审计才有一致的依据。这也是本项目的核心设计决策（详见 docs/ARCHITECTURE.md）。

Roadmap

• 跨实例 schema diff：对比 test 与 prod 的表结构/索引差异，直接生成变更清单（本项目最初要解决的痛点，欢迎讨论设计）；
• SQL 工单状态查询（只读）；
• 多目标白名单（target → 固定的实例/库/模式组合）；
• 内置规范规则可配置化。

致谢

• Archery —— 本项目封装的平台，SQL 审核与查询治理能力的真正执行者；
• ckall/archery-mcp-server —— 同生态的另一个优秀实现，思路有别，可对照选用。

关于作者

itzhouq，独立开发者，在 itzhouq.cn 记录 build in public 日常，做的小工具都收录在工具页。

本项目的开源复盘：让 AI 只读"看见"生产库：archery-mcp 开源复盘

License

MIT