Archery MCP

基于 MCP streamable-http 传输、通过 Archery HTTP 接口访问 Archery 的 MCP 服务。不直连任何数据库，权限、脱敏、限流和审计仍由 Archery 完成。

MCP 工具列表

| 工具 | 说明 | | --- | --- | | archery_ping | 检查配置、Archery 连通性和登录状态 | | archery_list_query_instances | 列出当前服务账号可用于只读查询的 Archery 实例（默认走本地元数据缓存） | | archery_list_resources | 列出指定实例下的数据库、Schema、表或字段 | | archery_query | 通过 Archery 执行只读 SQL（未传实例时使用环境变量配置的默认实例） | | archery_query_logs | 获取服务账号可见的 Archery 查询日志 | | archery_refresh_metadata_cache | 手动刷新实例和数据库元数据缓存 | | archery_list_sql_review_resource_groups | 列出服务账号可用于 SQL 上线审核的资源组 | | archery_list_sql_review_instances | 按资源组列出 SQL 上线审核可写实例 | | archery_list_sql_review_databases | 按资源组和审核实例列出数据库 | | archery_resolve_sql_review_target | 先将数据库名中的 - 归一化为 _，再结合 SQL 正文识别 DDL/DML 并反查审核目标；多目标时要求显式选择 | | archery_submit_sql_review | 检测 SQL 并创建 SQL 上线审核工单（error 阻断，warning 放行） |

环境要求

• Node.js 24 或更高版本。
• Archery v1.8.5；SQL 检测使用 /simplecheck/，创建工单使用 /autoreview/。

使用配置

1. 准备配置文件

配置全部来自一个 TOML 文件，一个文件对应一个环境。复制 config.example.toml 后按需修改：

cp config.example.toml ~/.config/archery-mcp/pro.toml
chmod 600 ~/.config/archery-mcp/pro.toml

文件含明文密码，务必控制权限，且不要提交到仓库。

2. 启动服务

配置文件路径通过 --config 或 ARCHERY_MCP_CONFIG 指定，两者都未提供时拒绝启动：

npx -y @seaxlab/archery-mcp --config ~/.config/archery-mcp/pro.toml

启动后默认监听 http://127.0.0.1:3000/mcp。多环境并行时，每个环境一份 TOML、一个进程、一个端口，缓存目录按 env 自动隔离。

3. MCP 客户端接入

在客户端的 MCP 配置中按 URL 接入：

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

Claude Code 也可以用命令行添加：

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

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

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

或用命令行添加：

codex mcp add archery --url http://127.0.0.1:3000/mcp

4. 配置项

完整样例见 config.example.toml。

| 配置项 | 必填 | 默认值 | 说明 | | --- | --- | --- | --- | | env | 是 | 无 | 当前环境标识，须匹配 ^[a-z0-9][a-z0-9_-]*$；决定默认缓存目录，并在 archery_ping 和 /health 中回显 | | server.host | 否 | 127.0.0.1 | MCP HTTP 服务监听地址 | | server.port | 否 | 3000 | MCP HTTP 服务监听端口 | | archery.base_url | 是 | 无 | Archery 地址，会自动去掉末尾 / | | archery.username | 是 | 无 | 服务账号用户名 | | archery.password | 是 | 无 | 服务账号密码 | | query.default_instance_name | 否 | 无 | archery_query 未传 instance_name 时使用的默认实例名 | | query.default_limit | 否 | 100 | 查询默认返回条数上限 | | query.max_limit | 否 | 500 | MCP 侧允许的最大返回条数，须不小于 default_limit | | cache.enabled | 否 | true | 是否启用查询及 SQL 审核元数据缓存 | | cache.ttl_seconds | 否 | 604800 | 缓存有效期（秒），默认 7 天 | | cache.dir | 否 | ~/.cache/archery-mcp/<env> | 缓存目录，支持 ~ 展开；目录下固定生成 metadata-cache.json 和 sql-review-metadata-cache.json | | cache.exclude_instance_names | 否 | [] | 不写入缓存的实例名黑名单 | | cache.exclude_instance_ids | 否 | [] | 不写入缓存的实例 ID 黑名单 | | sql_review.groups | 否 | [] | SQL 上线资源组数组表，每项含正整数 group_id 和非空 group_name；SQL 审核只遍历这里显式配置的资源组，为空时拒绝加载审核元数据 |

配置文件不存在、TOML 语法错误、出现未知键、字段缺失或校验失败时，服务以 ARCHERY_CONFIG_MISSING 前缀报错并拒绝启动。启动时若检测到配置文件对同组或其他用户可读，会打印权限提示但不阻断。

SQL 审核不会扫描或缓存 sql_review.groups 之外的资源组。首次读取审核元数据时会在独立文件中构建“资源组 → can_write 实例 → 数据库”的原子快照，三个审核列表工具、目标反查和提交共用该快照；实例名称和 ID 黑名单同时作用于查询与审核缓存。目标解析根据 sql_content 识别 DDL/DML，并将输入数据库名中的 - 归一化为 _；资源组名称必须包含对应的 DDL/DML 标识，实例名称包含标识时必须一致，未包含时继承资源组类型。自动反查存在多个目标时停止并要求显式选择；提交按 group_name + instance_name + db_name + sql_type 精确定位显式目标，缓存中无法唯一定位时强制刷新一次。资源组 ID 或名称重复时，服务拒绝启动。

5. 从 2.x 升级

3.0 起配置只从 TOML 读取，全部 ARCHERY_* 环境变量（ARCHERY_MCP_CONFIG 除外）不再生效。按上表把原有环境变量搬进 TOML 即可，注意三处结构变化：

• ARCHERY_SQL_REVIEW_GROUPS 的 JSON 字符串改为 [[sql_review.groups]] 数组表；
• ARCHERY_METADATA_CACHE_EXCLUDE_* 的逗号分隔字符串改为原生数组；
• 两个缓存文件路径合并为单个 cache.dir。

缓存格式同时升到 v3 并带上 env，旧缓存自动作废重建，无需手工清理。未指定配置文件路径且检测到残留的 2.x 环境变量时，启动错误会附带迁移提示。

服务默认只监听回环地址，MCP 端点本身没有鉴权；如需跨机器访问，请通过反向代理增加认证和 TLS。