archery-sql-mcp 0.2.2__tar.gz → 0.3.0__tar.gz

{archery_sql_mcp-0.2.2 → archery_sql_mcp-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: archery-sql-mcp
-Version: 0.2.2
+Version: 0.3.0
 Summary: Archery SQL 查询 MCP 工具：自动登录 + 会话自愈 + 只读查询，供任意 MCP 客户端与 CLI 使用
 License: MIT
 Requires-Python: >=3.10
@@ -62,9 +62,25 @@ archery-sql-mcp query "SELECT count(*) FROM open_api_request_logs WHERE created_
 
 仅允许 `SELECT` / `WITH` 开头的语句（可在配置 `allowed_prefixes` 扩展）。
 
-## 接入 MCP 客户端
+## 一键注册到各 agent 客户端
 
-ZCode（`~/.zcode/mcp.json`）、Claude Desktop、Cursor（`~/.cursor/mcp.json`）同构：
+```bash
+# 注册到全部支持的 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`）同构：
 
 ```jsonc
 {

{archery_sql_mcp-0.2.2 → archery_sql_mcp-0.3.0}/README.md

@@ -52,9 +52,25 @@ archery-sql-mcp query "SELECT count(*) FROM open_api_request_logs WHERE created_
 
 仅允许 `SELECT` / `WITH` 开头的语句（可在配置 `allowed_prefixes` 扩展）。
 
-## 接入 MCP 客户端
+## 一键注册到各 agent 客户端
 
-ZCode（`~/.zcode/mcp.json`）、Claude Desktop、Cursor（`~/.cursor/mcp.json`）同构：
+```bash
+# 注册到全部支持的 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`）同构：
 
 ```jsonc
 {

{archery_sql_mcp-0.2.2 → archery_sql_mcp-0.3.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "archery-sql-mcp"
-version = "0.2.2"
+version = "0.3.0"
 description = "Archery SQL 查询 MCP 工具：自动登录 + 会话自愈 + 只读查询，供任意 MCP 客户端与 CLI 使用"
 readme = "README.md"
 requires-python = ">=3.10"

{archery_sql_mcp-0.2.2 → archery_sql_mcp-0.3.0}/src/archery_sql_mcp/__init__.py

@@ -21,6 +21,7 @@ import getpass
 import json
 import os
 import re
+import shutil
 import sys
 import time
 from pathlib import Path
@@ -28,7 +29,7 @@ from typing import Any, Optional
 
 import httpx
 
-VERSION = "0.2.2"
+VERSION = "0.3.0"
 
 # ── 配置文件与会话缓存位置（可用 ARCHERY_CONFIG_DIR 整体改根目录） ──────────
 _CONFIG_DIR = Path(os.environ.get("ARCHERY_CONFIG_DIR", str(Path.home() / ".archery-mcp")))
@@ -521,6 +522,150 @@ def cmd_instances(_args: argparse.Namespace) -> int:
         return 1
 
 
+# ── 一键注册 MCP 到各 agent 客户端 ────────────────────────────────────
+
+_AGENT_LABELS = {
+    "zcode": "ZCode",
+    "claude-code": "Claude Code",
+    "claude-desktop": "Claude Desktop",
+    "codex": "Codex CLI",
+    "cursor": "Cursor",
+}
+
+
+def _json_upsert(path: Path, mutate) -> None:
+    """读改写 JSON 配置（不存在则从 {} 开始），保留原有其它键。"""
+    data: dict[str, Any] = {}
+    if path.exists():
+        try:
+            data = json.loads(path.read_text(encoding="utf-8"))
+        except json.JSONDecodeError as e:
+            raise ArcheryError(f"{path} JSON 解析失败，请手工修复后重试: {e}")
+    mutate(data)
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(data, indent=2, ensure_ascii=False) + "\n", encoding="utf-8")
+
+
+def _toml_upsert(path: Path, section: str, body_lines: list[str]) -> None:
+    """向 TOML 插入/替换一个段（零依赖文本处理）。body 行需自带 `key = value`。"""
+    text = path.read_text(encoding="utf-8") if path.exists() else ""
+    header = f"[{section}]"
+    body = "\n".join(body_lines)
+    pattern = re.compile(
+        r"^\[" + re.escape(section) + r"\][^\n]*\n(?:(?!\n?\[)[^\n]*\n?)*", re.M
+    )
+    if pattern.search(text):
+        # 用 lambda 替换，避免 Windows 路径中的 \U 等被 re 当作模板转义
+        text = pattern.sub(lambda _m: header + "\n" + body + "\n", text)
+    else:
+        text = text.rstrip("\n") + ("\n\n" if text.strip() else "") + header + "\n" + body + "\n"
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(text, encoding="utf-8")
+
+
+def _entry_json(command: str, timeout_ms: bool) -> dict[str, Any]:
+    e = {"type": "stdio", "command": command, "args": ["archery-sql-mcp"]}
+    if timeout_ms:  # 仅 zcode 使用该字段
+        e["timeoutMs"] = 120000
+    return e
+
+
+def _toml_escape(s: str) -> str:
+    """TOML 单引号字面量字符串（Windows 路径无需转义反斜杠）。"""
+    return "'" + s.replace("'", "''") + "'"
+
+
+def install_mcp(
+    agents: list[str],
+    scope: str,
+    portable: Optional[bool],
+    home: Optional[Path] = None,
+    cwd: Optional[Path] = None,
+) -> list[str]:
+    """把 archery MCP server 注册进各 agent 配置。返回结果描述行列表。"""
+    home = home or Path.home()
+    cwd = cwd or Path.cwd()
+    uvx = shutil.which("uvx")
+    results: list[str] = []
+    unknown = [a for a in agents if a not in _AGENT_LABELS]
+    if unknown:
+        raise ArcheryError(f"未知 agent: {unknown}，可用: {list(_AGENT_LABELS)}")
+
+    for agent in agents:
+        # 项目级默认 portable（通常进 git 共享），用户级默认本机绝对路径
+        is_portable = portable if portable is not None else (scope == "project")
+        if is_portable:
+            command = "uvx"
+        elif uvx:
+            command = uvx
+        else:
+            results.append(f"[{agent}] 跳过：PATH 中未找到 uvx（可加 --portable 用命令名 uvx）")
+            continue
+
+        paths: list[tuple[str, Path]] = []
+        if agent == "zcode":
+            if scope in ("user", "both"):
+                paths.append(("user", home / ".zcode" / "cli" / "config.json"))
+            if scope in ("project", "both"):
+                paths.append(("project", cwd / ".zcode" / "config.json"))
+        elif agent == "claude-code":
+            if scope in ("user", "both"):
+                paths.append(("user", home / ".claude.json"))
+            if scope in ("project", "both"):
+                paths.append(("project", cwd / ".mcp.json"))
+        elif agent == "claude-desktop":
+            if scope == "project":
+                results.append("[claude-desktop] 跳过：桌面应用无项目级配置")
+                continue
+            appdata = Path(os.environ.get("APPDATA", str(home / "AppData" / "Roaming")))
+            paths.append(("user", appdata / "Claude" / "claude_desktop_config.json"))
+        elif agent == "codex":
+            if scope in ("user", "both"):
+                paths.append(("user", home / ".codex" / "config.toml"))
+            if scope in ("project", "both"):
+                paths.append(("project", cwd / ".codex" / "config.toml"))
+        elif agent == "cursor":
+            if scope in ("user", "both"):
+                paths.append(("user", home / ".cursor" / "mcp.json"))
+            if scope in ("project", "both"):
+                paths.append(("project", cwd / ".cursor" / "mcp.json"))
+
+        for level, path in paths:
+            try:
+                if agent == "zcode":
+                    _json_upsert(path, lambda d: d.setdefault("mcp", {}).setdefault(
+                        "servers", {}).__setitem__(
+                        "archery", _entry_json(command, timeout_ms=True)))
+                elif agent == "codex":
+                    _toml_upsert(path, "mcp_servers.archery", [
+                        f"command = {_toml_escape(command)}",
+                        'args = ["archery-sql-mcp"]',
+                    ])
+                else:  # claude-code / claude-desktop / cursor：顶层 mcpServers
+                    _json_upsert(path, lambda d: d.setdefault(
+                        "mcpServers", {}).__setitem__(
+                        "archery", _entry_json(command, timeout_ms=False)))
+                results.append(f"[{agent}/{level}] 已写入 {path} (command={command})")
+            except ArcheryError as e:
+                results.append(f"[{agent}/{level}] 失败: {e}")
+    return results
+
+
+def cmd_install_mcp(args: argparse.Namespace) -> int:
+    _ensure_utf8_stdout()
+    agents = list(_AGENT_LABELS) if args.agents == "all" else [
+        a.strip() for a in args.agents.split(",") if a.strip()
+    ]
+    try:
+        for line in install_mcp(agents, args.scope, args.portable):
+            print(line)
+        print("完成。重启对应 agent 的会话后生效；配置中的 server 名为 archery。")
+        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")
@@ -624,6 +769,23 @@ def main() -> None:
     sub.add_parser("check", help="全链路自检：登录 + SELECT 1")
     sub.add_parser("instances", help="列出有读权限的数据库实例")
 
+    p_install = sub.add_parser(
+        "install-mcp",
+        help="一键注册 archery MCP 到各 agent 客户端（zcode/claude-code/claude-desktop/codex/cursor）",
+    )
+    p_install.add_argument(
+        "--scope", choices=["user", "project", "both"], default="user",
+        help="user=各 agent 用户级配置；project=当前目录项目级配置（默认 user）",
+    )
+    p_install.add_argument(
+        "--agents", default="all",
+        help="逗号分隔：zcode,claude-code,claude-desktop,codex,cursor 或 all（默认 all）",
+    )
+    p_install.add_argument(
+        "--portable", action="store_true", default=None,
+        help="command 用命令名 uvx 而非本机绝对路径（项目级配置进 git 共享时推荐；默认项目级自动 portable）",
+    )
+
     p_query = sub.add_parser("query", help="执行只读 SQL 查询")
     p_query.add_argument("sql", help="SELECT / WITH 开头的 SQL 语句")
     p_query.add_argument("--db", help="覆盖默认库名")
@@ -635,7 +797,7 @@ def main() -> None:
         run_mcp()  # 无参数 → MCP stdio 模式
         return
     handlers = {"init": cmd_init, "check": cmd_check, "query": cmd_query,
-                "instances": cmd_instances}
+                "instances": cmd_instances, "install-mcp": cmd_install_mcp}
     sys.exit(handlers[args.command](args))