Metadata-Version: 2.5
Name: archery-sql-mcp
Version: 0.2.2
Summary: Archery SQL 查询 MCP 工具：自动登录 + 会话自愈 + 只读查询，供任意 MCP 客户端与 CLI 使用
License: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27
Requires-Dist: mcp>=1.2
Description-Content-Type: text/markdown

# archery-sql-mcp

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

## 安装

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

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

从内部 Git 仓库：

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

本地开发：

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

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

```bash
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`，冷启动自动复用（最长约两周），
过期自动重新登录，调用方无感。

## 自检与使用

```bash
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 query "SELECT count(*) FROM open_api_request_logs WHERE created_at > now() - interval '1 day'" --limit 10
```

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

## 接入 MCP 客户端

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

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

Claude Code：

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

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

| 工具 | 用途 |
|---|---|
| `query(sql, db_name?, instance_name?, limit=100)` | 只读查询（仅 SELECT / WITH），返回 `{status, columns, rows, row_count, elapsed_ms}` |
| `get_token()` | 登录并返回 token 概要（掩码显示，完整值在本机 session.json） |
| `refresh_token()` | 强制刷新 token（清缓存重新登录） |
| `list_instances()` | 列出有读权限(can_read)的数据库实例 |
| `instance_resources(resource_type, db_name?, instance_name?, schema_name?, tb_name?)` | 探查实例结构：schema / table / column |

## 配置说明

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

```json
{
  "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
    }
  }
}
```

## 错误行为

| 场景 | 行为 |
|---|---|
| session 过期 | 自动重登并重放请求，调用方无感 |
| 密码错 / 账号禁用 | 明确报错，不重试 |
| 非 SELECT 语句 | 客户端预检拒绝 |
| SQL 语法错 | 透传数据库错误原文 |
| 查询超时 | 报错并附 query_id |

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