archery-sql-mcp

Archery SQL 平台（sql.tec-develop.com）查询工具：自动登录 + 会话自愈 + 只读查询。 双模式运行——无参数启动为 MCP stdio server（任何 MCP 客户端可接入），带子命令则为 CLI。

安装

发布到 PyPI 后（最短路径）：

uvx archery-sql-mcp --help          # 免安装直接跑
uv tool install archery-sql-mcp     # 或安装为全局命令

从内部 Git 仓库：

uv tool install git+https://git.tec-do.cn/<group>/archery-mcp.git

本地开发：

git clone <仓库地址> && cd archery-mcp
uv run --project . archery-sql-mcp --help

初始化账号密码（一次性）

archery-sql-mcp init

交互式录入 Archery 地址 / 用户名 / 密码（不回显）/ 默认实例 / 默认库， 写入 ~/.archery-mcp/config.json 并立即登录验证。

密码为本地明文存储（仅存于本机用户目录，不进任何 git 仓库）。 不想落盘的机器可改用环境变量：ARCHERY_USERNAME / ARCHERY_PASSWORD / ARCHERY_BASE_URL / ARCHERY_INSTANCE / ARCHERY_DB。

会话缓存于 ~/.archery-mcp/session.json，冷启动自动复用（最长约两周）， 过期自动重新登录，调用方无感。

自检与使用

archery-sql-mcp check    # 登录 + SELECT 1 全链路验证
archery-sql-mcp instances # 列出有读权限的数据库实例
archery-sql-mcp query "SELECT id, status, error_message FROM cv_video_script_audit_tasks ORDER BY created_at DESC LIMIT 10"
archery-sql-mcp redis "scan 0 match creator_email:* count 100"   # 只读查线上 Redis

仅允许 SELECT / WITH 开头的语句（可在配置 allowed_prefixes 扩展）。

一键注册到各 agent 客户端

# 注册到全部支持的 agent 的用户级配置（zcode / claude-code / claude-desktop / codex / cursor）
uvx archery-sql-mcp install-mcp

# 仅注册指定 agent，写入当前目录的项目级配置（进 git 共享，command 自动用可移植的 uvx）
uvx archery-sql-mcp install-mcp --agents claude-code,codex --scope project

写入规则：合并式更新（保留配置文件中的既有内容）、幂等（重复执行不产生重复条目）、 用户级默认写入本机 uvx 绝对路径、项目级默认写入可移植的命令名 uvx（加 --portable 强制全局可移植）。 各 agent 写入位置：ZCode ~/.zcode/cli/config.json（mcp.servers）· Claude Code ~/.claude.json / 项目 .mcp.json · Claude Desktop %APPDATA%\Claude\claude_desktop_config.json · Codex ~/.codex/config.toml（mcp_servers 段）· Cursor ~/.cursor/mcp.json / 项目 .cursor/mcp.json。写入后重启对应客户端会话生效。

接入 MCP 客户端（手工方式）

ZCode（~/.zcode/cli/config.json）、Claude Desktop、Cursor（~/.cursor/mcp.json）同构：

{
  "mcpServers": {
    "archery": {
      "command": "uvx",
      "args": ["--from", "git+https://git.tec-do.cn/<group>/archery-mcp.git", "archery-sql-mcp"]
    }
  }
}

Claude Code：

claude mcp add archery -- uvx --from git+https://git.tec-do.cn/<group>/archery-mcp.git archery-sql-mcp

接入后 agent 可调用 5 个工具：

配置说明

配置优先级：环境变量 > ~/.archery-mcp/config.json > 内置默认。 配置文件支持多 profile（ARCHERY_PROFILE 选择）：

{
  "default_profile": "prod",
  "profiles": {
    "prod": {
      "base_url": "https://sql.tec-develop.com",
      "username": "xxx",
      "password": "yyy",
      "instance_name": "alisg-haiyun-powerdata-pgsql-prod-01",
      "db_name": "creativault_business",
      "limit_num": 100,
      "allowed_prefixes": ["select", "with"],
      "poll_interval_s": 1,
      "query_timeout_s": 60
    }
  }
}

错误行为

密码与 sessionid 永不出现在日志和工具返回值中。