archery-sql-mcp 0.2.0__tar.gz

archery_sql_mcp-0.2.0/.gitignore

@@ -0,0 +1,6 @@
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+uv.lock

archery_sql_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,130 @@
+Metadata-Version: 2.5
+Name: archery-sql-mcp
+Version: 0.2.0
+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 永不出现在日志和工具返回值中。

archery_sql_mcp-0.2.0/README.md

@@ -0,0 +1,120 @@
+# 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 永不出现在日志和工具返回值中。

archery_sql_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,21 @@
+[project]
+name = "archery-sql-mcp"
+version = "0.2.0"
+description = "Archery SQL 查询 MCP 工具：自动登录 + 会话自愈 + 只读查询，供任意 MCP 客户端与 CLI 使用"
+readme = "README.md"
+requires-python = ">=3.10"
+license = { text = "MIT" }
+dependencies = [
+    "httpx>=0.27",
+    "mcp>=1.2",
+]
+
+[project.scripts]
+archery-sql-mcp = "archery_sql_mcp:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/archery_sql_mcp"]

archery_sql_mcp-0.2.0/src/archery_sql_mcp/__init__.py

@@ -0,0 +1,613 @@
+"""Archery SQL 查询 MCP 工具（单模块实现）。
+
+面向 Archery（Django）SQL 审核查询平台的只读查询封装：
+- 自动登录（Django CSRF 协议：csrftoken cookie + csrfmiddlewaretoken 表单）
+- 会话缓存（内存 + 磁盘），失效自动重登并重放请求
+- 两步异步查询（POST /query/ 入队 → GET /queryresult/ 轮询至终态）
+
+双模式运行：
+- 无参数启动 → MCP stdio server（任何 MCP host 可接入）
+- 子命令启动 → CLI：init / check / query
+
+配置优先级：环境变量 > 配置文件（~/.archery-mcp/config.json，多 profile）> 内置默认。
+密码仅存本地配置文件（init 时明示风险），日志与工具返回值中永不出现密码 / sessionid。
+"""
+
+from __future__ import annotations
+
+import argparse
+import asyncio
+import getpass
+import json
+import os
+import re
+import sys
+import time
+from pathlib import Path
+from typing import Any, Optional
+
+import httpx
+
+VERSION = "0.2.0"
+
+# ── 配置文件与会话缓存位置（可用 ARCHERY_CONFIG_DIR 整体改根目录） ──────────
+_CONFIG_DIR = Path(os.environ.get("ARCHERY_CONFIG_DIR", str(Path.home() / ".archery-mcp")))
+CONFIG_FILE = Path(os.environ.get("ARCHERY_CONFIG", str(_CONFIG_DIR / "config.json")))
+SESSION_FILE = _CONFIG_DIR / "session.json"
+
+# 内置默认值：公司线上库
+_DEFAULTS: dict[str, Any] = {
+    "base_url": "https://sql.tec-develop.com",
+    "instance_name": "alisg-haiyun-powerdata-pgsql-prod-01",
+    "db_name": "creativault_business",
+    "limit_num": 100,
+    "allowed_prefixes": ["select", "with"],
+    "poll_interval_s": 1.0,
+    "query_timeout_s": 60.0,
+    "request_timeout_s": 30.0,
+}
+
+MAX_LIMIT = 1000
+
+# 环境变量 → 配置键（优先级最高，不落盘，适合不想存密码的机器）
+_ENV_MAP = {
+    "ARCHERY_BASE_URL": "base_url",
+    "ARCHERY_USERNAME": "username",
+    "ARCHERY_PASSWORD": "password",
+    "ARCHERY_INSTANCE": "instance_name",
+    "ARCHERY_DB": "db_name",
+}
+
+_CSRF_INPUT_RE = re.compile(r'name="csrfmiddlewaretoken"[^>]*value="([^"]+)"')
+
+
+class ArcheryError(Exception):
+    """工具级错误，message 面向调用方展示。"""
+
+
+# ── 配置 ──────────────────────────────────────────────────────────────
+
+def load_profile() -> dict[str, Any]:
+    """合并三层配置：环境变量 > 配置文件 profile > 内置默认。"""
+    merged = dict(_DEFAULTS)
+    if CONFIG_FILE.exists():
+        try:
+            data = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as e:
+            raise ArcheryError(f"配置文件 JSON 解析失败({CONFIG_FILE}): {e}")
+        profile_name = os.environ.get("ARCHERY_PROFILE") or data.get("default_profile")
+        profiles = data.get("profiles") or {}
+        if profile_name and profile_name in profiles:
+            merged.update({k: v for k, v in profiles[profile_name].items() if v not in (None, "")})
+        elif profile_name:
+            raise ArcheryError(f"profile '{profile_name}' 不存在，可用: {list(profiles) or '无'}")
+    for env, key in _ENV_MAP.items():
+        val = os.environ.get(env)
+        if val:
+            merged[key] = val
+    if not merged.get("username") or not merged.get("password"):
+        raise ArcheryError(
+            f"未配置账号密码：请先运行 `archery-sql-mcp init`（写入 {CONFIG_FILE}），"
+            "或通过环境变量 ARCHERY_USERNAME / ARCHERY_PASSWORD 注入。"
+        )
+    return merged
+
+
+# ── 会话管理：自动登录 + 缓存 + 失效重登 ────────────────────────────────
+
+class SessionManager:
+    """Archery 登录态管理。Django session 过期表现为 302 → /login/。"""
+
+    def __init__(self, cfg: dict[str, Any]):
+        self.cfg = cfg
+        self.base = str(cfg["base_url"]).rstrip("/")
+        self.sessionid: Optional[str] = None
+        self.csrftoken: Optional[str] = None
+
+    # -- 磁盘缓存：冷启动优先复用（Django session 默认两周有效） --
+    def _load_cache(self) -> bool:
+        try:
+            if SESSION_FILE.exists():
+                data = json.loads(SESSION_FILE.read_text(encoding="utf-8"))
+                self.sessionid = data.get("sessionid")
+                self.csrftoken = data.get("csrftoken")
+        except Exception:
+            pass
+        return bool(self.sessionid)
+
+    def _save_cache(self) -> None:
+        try:
+            _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+            SESSION_FILE.write_text(
+                json.dumps(
+                    {"sessionid": self.sessionid, "csrftoken": self.csrftoken,
+                     "logged_in_at": time.strftime("%Y-%m-%d %H:%M:%S")},
+                    ensure_ascii=False, indent=2,
+                ),
+                encoding="utf-8",
+            )
+        except Exception:
+            pass  # 缓存写失败不影响本次会话
+
+    def invalidate(self) -> None:
+        self.sessionid = None
+        self.csrftoken = None
+        try:
+            SESSION_FILE.unlink(missing_ok=True)
+        except Exception:
+            pass
+
+    async def ensure(self) -> None:
+        if self.sessionid:
+            return
+        if self._load_cache():
+            return
+        await self.login()
+
+    async def login(self) -> None:
+        """Django CSRF 登录：GET /login/ 取 token → POST /authenticate/ → sessionid。"""
+        async with httpx.AsyncClient(
+            timeout=self.cfg["request_timeout_s"], follow_redirects=False
+        ) as client:
+            page = await client.get(f"{self.base}/login/")
+            page.raise_for_status()
+            m = _CSRF_INPUT_RE.search(page.text)
+            form_token = m.group(1) if m else ""
+            cookie_csrf = client.cookies.get("csrftoken") or ""
+            if not form_token or not cookie_csrf:
+                raise ArcheryError("登录页解析失败：未取到 csrfmiddlewaretoken / csrftoken")
+
+            resp = await client.post(
+                f"{self.base}/authenticate/",
+                data={
+                    "username": self.cfg["username"],
+                    "password": self.cfg["password"],
+                    "csrfmiddlewaretoken": form_token,
+                },
+                headers={"Referer": f"{self.base}/login/"},
+            )
+            # 成功：302 跳往非 /login 路径；失败：302 回 /login 或 200 带错误页
+            location = resp.headers.get("location", "")
+            if resp.status_code not in (301, 302) or "/login" in location:
+                reason = _extract_login_error(resp.text) or (
+                    f"HTTP {resp.status_code}"
+                    + (f" → {location}" if location else "")
+                    + "（用户名/密码错误，或账号被禁用）"
+                )
+                raise ArcheryError(f"Archery 登录失败: {reason}")
+
+            self.sessionid = client.cookies.get("sessionid")
+            self.csrftoken = client.cookies.get("csrftoken") or cookie_csrf
+            if not self.sessionid:
+                raise ArcheryError("登录成功但未取到 sessionid cookie")
+            self._save_cache()
+
+    def is_expired(self, resp: httpx.Response) -> bool:
+        """会话失效判定：302 重定向到登录页（Archery/Django 的'401'形态）。"""
+        if resp.status_code in (301, 302):
+            return "login" in (resp.headers.get("location") or "").lower()
+        return False
+
+    async def token_info(self, refresh: bool = False) -> dict[str, Any]:
+        """确保已登录并返回 token 概要。refresh=True 时强制重登（即'刷新 token'）。
+
+        token（sessionid）以掩码返回：完整值仅存于本机 session.json，
+        避免明文凭据进入 AI 对话历史 / 日志。
+        """
+        if refresh:
+            self.invalidate()
+            await self.login()
+        else:
+            await self.ensure()
+        sid = self.sessionid or ""
+        masked = (sid[:4] + "***" + sid[-4:]) if len(sid) > 8 else "***"
+        logged_in_at = ""
+        try:
+            if SESSION_FILE.exists():
+                logged_in_at = json.loads(
+                    SESSION_FILE.read_text(encoding="utf-8")
+                ).get("logged_in_at", "")
+        except Exception:
+            pass
+        return {
+            "logged_in": True,
+            "token_masked": masked,
+            "logged_in_at": logged_in_at,
+            "base_url": self.base,
+            "note": f"完整 token 已缓存于本机 {SESSION_FILE}，仅供本机调试使用",
+        }
+
+
+def _extract_login_error(html: str) -> Optional[str]:
+    """尽力从登录失败页面提取可读错误（不同 Archery 版本模板不同）。"""
+    for pat in (r'class="[^"]*alert[^"]*"[^>]*>([^<]{4,120})<',
+                r'<div class="text-danger[^"]*">\s*([^<]{4,120})'):
+        m = re.search(pat, html)
+        if m:
+            return m.group(1).strip()
+    return None
+
+
+# ── 查询客户端：两步异步 + 失效自动重登重放 ────────────────────────────
+
+class ArcheryClient:
+    def __init__(self, cfg: dict[str, Any]):
+        self.cfg = cfg
+        self.sm = SessionManager(cfg)
+
+    async def _authed(
+        self,
+        method: str,
+        path: str,
+        *,
+        data: Optional[dict] = None,
+        params: Optional[dict] = None,
+    ) -> httpx.Response:
+        """带会话的请求；失效自动重登一次并重放（密码错等确定性失败不会循环）。"""
+        last_resp: Optional[httpx.Response] = None
+        for _attempt in range(2):
+            await self.sm.ensure()
+            async with httpx.AsyncClient(
+                timeout=self.cfg["request_timeout_s"], follow_redirects=False
+            ) as client:
+                resp = await client.request(
+                    method, f"{self.sm.base}{path}",
+                    data=data, params=params,
+                    cookies={"csrftoken": self.sm.csrftoken or "",
+                             "sessionid": self.sm.sessionid or ""},
+                    headers={"X-CSRFToken": self.sm.csrftoken or "",
+                             "Referer": self.sm.base + "/"},
+                )
+            if not self.sm.is_expired(resp):
+                return resp
+            last_resp = resp
+            self.sm.invalidate()  # 触发下一轮 ensure() 重新登录
+        raise ArcheryError(
+            "会话失效且自动重新登录后仍未通过（账号可能被禁用或密码已变更），"
+            f"末次响应 HTTP {last_resp.status_code if last_resp else '?'}"
+        )
+
+    def _check_sql_allowed(self, sql: str) -> None:
+        body = re.sub(r"--[^\n]*", " ", sql)
+        body = re.sub(r"/\*.*?\*/", " ", body, flags=re.S)
+        first = body.strip().split(None, 1)[0].lower() if body.strip() else ""
+        allowed = [str(p).lower() for p in self.cfg.get("allowed_prefixes", [])]
+        if first not in allowed:
+            raise ArcheryError(
+                f"仅允许 {'/'.join(allowed)} 开头的只读语句，收到: '{first or '(空)'}'"
+            )
+
+    async def query(
+        self,
+        sql: str,
+        *,
+        db_name: Optional[str] = None,
+        instance_name: Optional[str] = None,
+        limit: Optional[int] = None,
+    ) -> dict[str, Any]:
+        self._check_sql_allowed(sql)
+        limit = min(max(int(limit or self.cfg["limit_num"]), 1), MAX_LIMIT)
+        started = time.monotonic()
+
+        resp = await self._authed(
+            "POST", "/query/",
+            data={
+                "instance_name": instance_name or self.cfg["instance_name"],
+                "db_name": db_name or self.cfg["db_name"],
+                "schema_name": "",
+                "tb_name": "",
+                "sql_content": sql,
+                "limit_num": limit,
+            },
+        )
+        try:
+            submitted = resp.json()
+        except Exception:
+            raise ArcheryError(f"/query/ 返回非 JSON (HTTP {resp.status_code})，请联系管理员确认平台版本兼容性")
+        if submitted.get("status") != 0:
+            raise ArcheryError(f"/query/ 提交失败: {submitted.get('msg') or submitted}")
+        query_id = (submitted.get("data") or {}).get("query_id")
+        if not query_id:
+            raise ArcheryError(f"/query/ 未返回 query_id: {submitted}")
+
+        # 轮询至终态
+        interval = float(self.cfg["poll_interval_s"])
+        timeout = float(self.cfg["query_timeout_s"])
+        while True:
+            resp = await self._authed("GET", "/queryresult/", params={"sql_query_id": query_id})
+            try:
+                payload = resp.json()
+            except Exception:
+                raise ArcheryError(f"/queryresult/ 返回非 JSON (HTTP {resp.status_code})")
+            data = payload.get("data") or {}
+            status = data.get("status", "")
+            if status == "finished":
+                err = data.get("err")
+                if err:
+                    raise ArcheryError(f"SQL 执行错误: {err}")
+                columns = data.get("column_list") or []
+                rows = data.get("rows") or []
+                return {
+                    "status": "finished",
+                    "columns": columns,
+                    "rows": rows,
+                    "row_count": len(rows),
+                    "elapsed_ms": int((time.monotonic() - started) * 1000),
+                }
+            if status in ("failed", "aborted"):
+                raise ArcheryError(f"查询失败: {data.get('err') or data}")
+            if time.monotonic() - started > timeout:
+                raise ArcheryError(
+                    f"查询超时(>{timeout:.0f}s)，query_id={query_id}，可稍后重试或缩小结果集"
+                )
+            await asyncio.sleep(interval)
+
+    async def _get_json(self, path: str, params: Optional[dict] = None) -> Any:
+        """GET 平台接口并解包：status!=0 报错，否则返回 data（无 data 时返回原 payload）。"""
+        resp = await self._authed("GET", path, params=params)
+        try:
+            payload = resp.json()
+        except Exception:
+            raise ArcheryError(f"{path} 返回非 JSON (HTTP {resp.status_code})")
+        if payload.get("status") != 0:
+            raise ArcheryError(f"{path} 调用失败: {payload.get('msg') or payload}")
+        return payload.get("data", payload)
+
+    async def list_instances(self) -> Any:
+        """列出当前账号有读权限(can_read)的所有数据库实例。"""
+        # tag_codes[] 是数组参数：tag_codes%5B%5D=can_read
+        return await self._get_json(
+            "/group/user_all_instances/", params={"tag_codes[]": ["can_read"]}
+        )
+
+    async def instance_resources(
+        self,
+        *,
+        instance_name: Optional[str] = None,
+        db_name: Optional[str] = None,
+        resource_type: str = "schema",
+        schema_name: Optional[str] = None,
+        tb_name: Optional[str] = None,
+    ) -> Any:
+        """查询实例资源：resource_type=schema 列 schema；table 列表；column 需 schema_name+tb_name。"""
+        params: dict[str, Any] = {
+            "instance_name": instance_name or self.cfg["instance_name"],
+            "db_name": db_name or self.cfg["db_name"],
+            "resource_type": resource_type,
+        }
+        if schema_name:
+            params["schema_name"] = schema_name
+        if tb_name:
+            params["tb_name"] = tb_name
+        return await self._get_json("/instance/instance_resource/", params=params)
+
+
+# ── CLI ───────────────────────────────────────────────────────────────
+
+def _ensure_utf8_stdout() -> None:
+    try:
+        sys.stdout.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+        sys.stderr.reconfigure(encoding="utf-8")  # type: ignore[union-attr]
+    except Exception:
+        pass
+
+
+def cmd_init(_args: argparse.Namespace) -> int:
+    _ensure_utf8_stdout()
+    print(f"将生成配置文件: {CONFIG_FILE}（密码明文存放于本机，不会进入任何 git 仓库）")
+    existing: dict[str, Any] = {}
+    if CONFIG_FILE.exists():
+        try:
+            existing = json.loads(CONFIG_FILE.read_text(encoding="utf-8"))
+            print("检测到已有配置，回车保留原值。")
+        except Exception:
+            existing = {}
+
+    old = existing.get("profiles", {}).get("prod", {})
+
+    def ask(prompt: str, default: str = "", secret: bool = False) -> str:
+        suffix = f" [{default}]" if default else ""
+        val = (getpass.getpass(prompt + suffix + ": ") if secret
+               else input(prompt + suffix + ": ")).strip()
+        return val or default
+
+    profile = {
+        "base_url": ask("Archery 地址", old.get("base_url", _DEFAULTS["base_url"])),
+        "username": ask("用户名", old.get("username", "")),
+        "password": ask("密码", old.get("password", ""), secret=True),
+        "instance_name": ask("默认实例", old.get("instance_name", _DEFAULTS["instance_name"])),
+        "db_name": ask("默认库", old.get("db_name", _DEFAULTS["db_name"])),
+    }
+    config = {"default_profile": "prod", "profiles": {"prod": profile}}
+    _CONFIG_DIR.mkdir(parents=True, exist_ok=True)
+    CONFIG_FILE.write_text(json.dumps(config, ensure_ascii=False, indent=2), encoding="utf-8")
+    print("配置已写入，正在验证登录…")
+
+    ok = asyncio.run(_login_check(profile))
+    if ok:
+        print("初始化完成 ✓  可运行 `archery-sql-mcp check` 做全链路自检。")
+        return 0
+    print("登录验证失败：请检查上面的错误，重新运行 init 修正。")
+    return 1
+
+
+async def _login_check(profile: dict[str, Any]) -> bool:
+    cfg = dict(_DEFAULTS)
+    cfg.update({k: v for k, v in profile.items() if v})
+    try:
+        sm = SessionManager(cfg)
+        await sm.login()
+        print(f"登录成功（session 已缓存到 {SESSION_FILE}）")
+        return True
+    except ArcheryError as e:
+        print(f"错误: {e}")
+        return False
+
+
+def cmd_check(_args: argparse.Namespace) -> int:
+    _ensure_utf8_stdout()
+    try:
+        cfg = load_profile()
+        result = asyncio.run(ArcheryClient(cfg).query("SELECT 1 AS ok", limit=1))
+        print(f"登录 + 查询链路正常 ✓  SELECT 1 → {result['rows']}  耗时 {result['elapsed_ms']}ms")
+        return 0
+    except ArcheryError as e:
+        print(f"错误: {e}")
+        return 1
+
+
+def cmd_query(args: argparse.Namespace) -> int:
+    _ensure_utf8_stdout()
+    try:
+        cfg = load_profile()
+        result = asyncio.run(ArcheryClient(cfg).query(
+            args.sql, db_name=args.db, instance_name=args.instance, limit=args.limit,
+        ))
+        print(json.dumps(result, ensure_ascii=False, indent=2))
+        return 0
+    except ArcheryError as e:
+        print(f"错误: {e}")
+        return 1
+
+
+def _new_mcp_server(name: str):
+    """兼容 mcp SDK 1.x/2.x：2.x 中 FastMCP 改名为 MCPServer，用法一致。"""
+    try:
+        from mcp.server.mcpserver import MCPServer as Server  # mcp >= 2
+    except ImportError:
+        from mcp.server.fastmcp import FastMCP as Server  # mcp 1.x
+    return Server(name)
+
+
+def cmd_instances(_args: argparse.Namespace) -> int:
+    _ensure_utf8_stdout()
+    try:
+        cfg = load_profile()
+        data = asyncio.run(ArcheryClient(cfg).list_instances())
+        print(json.dumps({"instances": data}, ensure_ascii=False, indent=2))
+        return 0
+    except ArcheryError as e:
+        print(f"错误: {e}")
+        return 1
+
+
+def run_mcp() -> None:
+    """MCP stdio server 模式（惰性 import，CLI 场景无需安装 mcp 包）。"""
+    mcp = _new_mcp_server("archery")
+
+    @mcp.tool()
+    async def query(
+        sql: str,
+        db_name: Optional[str] = None,
+        instance_name: Optional[str] = None,
+        limit: int = 100,
+    ) -> str:
+        """查询 Archery SQL 平台上的数据库（只读，仅允许 SELECT / WITH）。
+
+        默认连接线上生产库：实例 alisg-haiyun-powerdata-pgsql-prod-01，
+        库 creativault_business。可通过 db_name / instance_name 参数切换。
+        返回 JSON：{status, columns, rows, row_count, elapsed_ms}。
+
+        典型用途：排查线上业务数据（任务状态、错误信息、日志表等）。
+        """
+        try:
+            cfg = load_profile()
+            result = await ArcheryClient(cfg).query(
+                sql, db_name=db_name, instance_name=instance_name, limit=limit,
+            )
+            return json.dumps(result, ensure_ascii=False)
+        except ArcheryError as e:
+            return json.dumps({"error": str(e)}, ensure_ascii=False)
+
+    @mcp.tool()
+    async def get_token() -> str:
+        """获取 Archery 登录 token（执行/复用登录，返回会话状态与掩码 token）。
+
+        token 仅以掩码显示，完整值缓存于本机 ~/.archery-mcp/session.json。
+        """
+        try:
+            cfg = load_profile()
+            info = await SessionManager(cfg).token_info(refresh=False)
+            return json.dumps(info, ensure_ascii=False)
+        except ArcheryError as e:
+            return json.dumps({"error": str(e)}, ensure_ascii=False)
+
+    @mcp.tool()
+    async def refresh_token() -> str:
+        """强制刷新 Archery 登录 token（清空缓存并重新登录，返回新会话状态）。"""
+        try:
+            cfg = load_profile()
+            info = await SessionManager(cfg).token_info(refresh=True)
+            return json.dumps(info, ensure_ascii=False)
+        except ArcheryError as e:
+            return json.dumps({"error": str(e)}, ensure_ascii=False)
+
+    @mcp.tool()
+    async def list_instances() -> str:
+        """列出你在 Archery 平台上有读权限(can_read)的所有数据库实例。
+
+        用于 query 工具切换 instance_name 前确认实例名。
+        """
+        try:
+            cfg = load_profile()
+            data = await ArcheryClient(cfg).list_instances()
+            return json.dumps({"instances": data}, ensure_ascii=False)
+        except ArcheryError as e:
+            return json.dumps({"error": str(e)}, ensure_ascii=False)
+
+    @mcp.tool()
+    async def instance_resources(
+        resource_type: str = "schema",
+        db_name: Optional[str] = None,
+        instance_name: Optional[str] = None,
+        schema_name: Optional[str] = None,
+        tb_name: Optional[str] = None,
+    ) -> str:
+        """查询数据库实例的资源结构，便于编写 SQL 前探查。
+
+        resource_type=schema 列出库下 schema；table 列出表（可配 schema_name）；
+        column 列出字段（需 schema_name + tb_name）。
+        默认实例 alisg-haiyun-powerdata-pgsql-prod-01 / 库 creativault_business。
+        """
+        try:
+            cfg = load_profile()
+            data = await ArcheryClient(cfg).instance_resources(
+                instance_name=instance_name, db_name=db_name,
+                resource_type=resource_type, schema_name=schema_name, tb_name=tb_name,
+            )
+            return json.dumps({"resources": data}, ensure_ascii=False)
+        except ArcheryError as e:
+            return json.dumps({"error": str(e)}, ensure_ascii=False)
+
+    mcp.run()
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        prog="archery-sql-mcp",
+        description="Archery SQL 查询工具（无参数启动 = MCP server；子命令 = CLI）",
+    )
+    parser.add_argument("--version", action="version", version=f"%(prog)s {VERSION}")
+    sub = parser.add_subparsers(dest="command")
+
+    sub.add_parser("init", help="交互式初始化账号密码配置并验证登录")
+    sub.add_parser("check", help="全链路自检：登录 + SELECT 1")
+    sub.add_parser("instances", help="列出有读权限的数据库实例")
+
+    p_query = sub.add_parser("query", help="执行只读 SQL 查询")
+    p_query.add_argument("sql", help="SELECT / WITH 开头的 SQL 语句")
+    p_query.add_argument("--db", help="覆盖默认库名")
+    p_query.add_argument("--instance", help="覆盖默认实例名")
+    p_query.add_argument("--limit", type=int, help=f"返回行数上限（默认 100，最大 {MAX_LIMIT}）")
+
+    args = parser.parse_args()
+    if args.command is None:
+        run_mcp()  # 无参数 → MCP stdio 模式
+        return
+    handlers = {"init": cmd_init, "check": cmd_check, "query": cmd_query,
+                "instances": cmd_instances}
+    sys.exit(handlers[args.command](args))
+
+
+if __name__ == "__main__":
+    main()