redisctl 0.1.0__tar.gz

redisctl-0.1.0/.gitignore

@@ -0,0 +1,18 @@
+.env
+__pycache__/
+*.py[cod]
+.venv/
+dist/
+*.egg-info/
+.ruff_cache/
+.playwright-mcp/
+.claude/settings.local.json
+.DS_Store
+
+# 本地 MCP 配置：各人自备、可含个人令牌，不进仓库
+.mcp.json
+.redis-cluster/
+
+# 本机运行的配置（由 config/gateway.example.toml 派生），不进仓库
+config/gateway.toml
+.env.secret

redisctl-0.1.0/PKG-INFO

@@ -0,0 +1,7 @@
+Metadata-Version: 2.5
+Name: redisctl
+Version: 0.1.0
+Summary: Redis MCP Gateway 命令行客户端 —— 从不直连 Redis
+Requires-Python: >=3.12
+Requires-Dist: httpx>=0.28.0
+Requires-Dist: typer>=0.15.0

redisctl-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[project]
+name = "redisctl"
+version = "0.1.0"
+description = "Redis MCP Gateway 命令行客户端 —— 从不直连 Redis"
+requires-python = ">=3.12"
+dependencies = [
+    "httpx>=0.28.0",
+    "typer>=0.15.0",
+]
+
+[project.scripts]
+redisctl = "redisctl.main:main"
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[tool.hatch.build.targets.wheel]
+packages = ["redisctl"]

redisctl-0.1.0/redisctl/__init__.py

@@ -0,0 +1,7 @@
+"""Redis MCP Gateway 命令行客户端。
+
+**从不直连 Redis。** 所有调用都走网关的 HTTP 接口，
+凭据留在网关侧；本包不依赖任何 Redis 客户端。
+"""
+
+__version__ = "0.1.0"

redisctl-0.1.0/redisctl/cli.py

@@ -0,0 +1,214 @@
+"""由**发现到的**操作清单构造 typer 应用。
+
+与网关侧的 MCP 工具生成同理：typer 需要真实的函数签名来推导参数，
+所以按操作声明生成带显式形参的函数，而不是用一个 `**kwargs` 的通用分发。
+
+差别在于操作清单是**运行时从网关拉来的**，不是编译期从注册表导入的 ——
+这样 CLI 与网关不会各有一份必然分叉的清单（章程原则 IV）。
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+import typer
+
+from .client import GatewayError, call
+from .discovery import Operation, Param
+
+#: CLI 自带的命令名。发现到的操作**不得**与它们重名，
+#: 否则子命令会被静默覆盖 —— 那种错很难查。
+BUILTIN_COMMANDS = frozenset({"version", "operations", "refresh"})
+
+#: 网关侧的参数类型 → typer 能推导的 Python 注解
+_TYPER_ANNOTATION = {
+    "str": "str",
+    "int": "int",
+    "float": "float",
+    "bool": "bool",
+    # 复杂类型在命令行上以 JSON 文本传入，由 _parse_value 解析
+    "dict": "str",
+    "list": "str",
+}
+
+
+def _parse_value(param: Param, raw: Any) -> Any:
+    """把命令行上的字符串转成网关期望的类型。"""
+    if raw is None:
+        return None
+    if param.type in {"dict", "list"}:
+        try:
+            return json.loads(raw)
+        except (TypeError, ValueError) as exc:
+            example = '{"a":1}' if param.type == "dict" else '["a","b"]'
+            raise typer.BadParameter(
+                f"需要 JSON 文本，例如 {example}", param_hint=f"--{param.name}"
+            ) from exc
+    return raw
+
+
+def _option_source(param: Param) -> str:
+    """生成一个 typer.Option 的源码片段。"""
+    flag = param.name.replace("_", "-")
+    help_text = repr(param.description or "")
+    if param.required:
+        default = "..."
+    elif param.default is None:
+        default = "None"
+    else:
+        default = repr(param.default)
+    return f"typer.Option({default}, '--{flag}', help={help_text})"
+
+
+def _make_command(operation: Operation):
+    """按操作声明生成一个 typer 命令函数。"""
+    pieces: list[str] = []
+    for param in operation.params:
+        pieces.append(f"{param.name}: {_TYPER_ANNOTATION[param.type]} = {_option_source(param)}")
+    pieces.append(
+        "environment: str | None = typer.Option("
+        "None, '--environment', '-e', "
+        "help='目标环境（如 dev / fat / prod）。省略则用网关配置的默认环境；两者都没有时会报错。')"
+    )
+
+    source = (
+        f"def {operation.name}({', '.join(pieces)}):\n"
+        f"    raw = {{k: v for k, v in locals().items() if k != 'environment'}}\n"
+        f"    return _invoke({operation.name!r}, raw, environment)\n"
+    )
+
+    def _invoke(name: str, raw: dict, environment: str | None) -> None:
+        op = _OPERATIONS_BY_NAME[name]
+        params = {}
+        for param in op.params:
+            value = raw.get(param.name)
+            if value is None:
+                continue
+            params[param.name] = _parse_value(param, value)
+        _display(name, params, environment, write=op.write)
+
+    namespace: dict[str, Any] = {"_invoke": _invoke, "typer": typer}
+    exec(compile(source, f"<generated:{operation.name}>", "exec"), namespace)
+    fn = namespace[operation.name]
+    fn.__doc__ = _help_text(operation)
+    return fn
+
+
+def _help_text(operation: Operation) -> str:
+    suffix = "【写操作，只读环境会被拒绝】" if operation.write else ""
+    return f"{operation.summary}{suffix}\n\n集群行为：{operation.cluster_note}"
+
+
+def _display(name: str, params: dict, environment: str | None, *, write: bool) -> None:
+    try:
+        body = call(name, params, environment, write=write)
+    except GatewayError as exc:
+        typer.secho(f"[{exc.code}] {exc.message}", fg=typer.colors.RED, err=True)
+        if exc.hint:
+            typer.secho(f"提示：{exc.hint}", fg=typer.colors.YELLOW, err=True)
+        raise typer.Exit(code=1) from exc
+    typer.echo(json.dumps(body, ensure_ascii=False, indent=2, default=str))
+
+
+#: 由 build_app 填充。生成出来的命令函数通过它按名字回查操作声明。
+_OPERATIONS_BY_NAME: dict[str, Operation] = {}
+
+
+def build_app(operations: list[Operation]) -> typer.Typer:
+    """由发现到的操作清单构造 typer 应用。"""
+    global _OPERATIONS_BY_NAME
+    _OPERATIONS_BY_NAME = {op.name: op for op in operations}
+
+    collisions = BUILTIN_COMMANDS & set(_OPERATIONS_BY_NAME)
+    if collisions:
+        # 静默覆盖会让某个命令凭空消失，而这在远端很难排查
+        typer.secho(
+            f"网关的操作清单与 CLI 自带命令重名：{sorted(collisions)}。"
+            "请先把这些操作改名。",
+            fg=typer.colors.RED, err=True,
+        )
+        raise typer.Exit(code=2)
+
+    built = typer.Typer(
+        name="redisctl",
+        help=(
+            "Redis MCP Gateway 命令行客户端。\n\n"
+            "所有调用都经过网关的护栏、环境路由与审计 —— 本工具**从不直连 Redis**，"
+            "也不持有 Redis 凭据。"
+        ),
+        no_args_is_help=True,
+        add_completion=False,
+    )
+
+    for operation in operations:
+        built.command(name=operation.name, help=_help_text(operation))(_make_command(operation))
+
+    _register_builtins(built, operations)
+    return built
+
+
+def _register_builtins(built: typer.Typer, operations: list[Operation]) -> None:
+    """注册 CLI 自带的三个命令。"""
+
+    @built.command(name="version", help="显示 redisctl 版本。")
+    def version() -> None:
+        from . import __version__
+
+        typer.echo(f"redisctl {__version__}")
+
+    @built.command(name="refresh", help="强制重新从网关拉取操作清单（刷新本地缓存）。")
+    def refresh() -> None:
+        from .client import gateway_token, gateway_url
+        from .discovery import DiscoveryError, fetch_operations, write_cache
+
+        try:
+            fetched = fetch_operations(gateway_url(), gateway_token())
+        except DiscoveryError as exc:
+            typer.secho(f"刷新失败：{exc}", fg=typer.colors.RED, err=True)
+            raise typer.Exit(code=1) from exc
+
+        write_cache(gateway_url(), fetched)
+        typer.echo(f"已刷新，网关当前提供 {len(fetched)} 个操作。")
+        if len(fetched) != len(operations):
+            # 本次进程的命令列表已经构造完了，改动从下次调用开始生效 ——
+            # 不说清楚的话，用户会以为刷新没生效
+            typer.secho(
+                f"注意：本次运行已经按 {len(operations)} 个操作构造好命令，"
+                "新的清单从下次执行起生效。",
+                fg=typer.colors.YELLOW,
+            )
+
+    @built.command(name="operations", help="列出从网关发现到的操作（排查用）。")
+    def list_operations(
+        only_writes: bool = typer.Option(False, "--writes", help="只列写操作"),
+        as_json: bool = typer.Option(False, "--json", help="输出原始 JSON"),
+    ) -> None:
+        selected = [op for op in operations if (op.write if only_writes else True)]
+        if as_json:
+            typer.echo(
+                json.dumps([op.to_payload() for op in selected], ensure_ascii=False, indent=2)
+            )
+            return
+        typer.echo(f"从网关发现 {len(operations)} 个操作：\n")
+        for op in selected:
+            kind = "写" if op.write else "读"
+            required = "  ".join(
+                f"--{p.name.replace('_', '-')}" for p in op.params if p.required
+            )
+            typer.echo(f"  [{kind}] {op.name:<28} {required}")
+
+
+def run(operations: list[Operation]) -> None:
+    """构造应用并交给 typer 运行。"""
+    build_app(operations)()
+
+
+def warn(message: str) -> None:
+    typer.secho(f"提示：{message}", fg=typer.colors.YELLOW, err=True)
+
+
+def fail(message: str, code: int = 2) -> None:
+    typer.secho(message, fg=typer.colors.RED, err=True)
+    sys.exit(code)

redisctl-0.1.0/redisctl/client.py

@@ -0,0 +1,108 @@
+"""调用网关的 HTTP 客户端。
+
+**只跟网关说话，从不连 Redis。** 本包不依赖任何 Redis 客户端 ——
+它不知道集群在哪，也不持有 Redis 凭据。这是这套设计的核心：
+Redis 集群可以放在开发者完全不可达的私有子网里。
+"""
+
+from __future__ import annotations
+
+import os
+from typing import Any
+
+import httpx
+
+DEFAULT_TIMEOUT = 30.0
+
+
+class GatewayError(Exception):
+    """网关返回了业务错误。带错误码与提示，供 CLI 直接展示。"""
+
+    def __init__(self, code: str, message: str, hint: str | None = None) -> None:
+        super().__init__(message)
+        self.code = code
+        self.message = message
+        self.hint = hint
+
+
+def gateway_url() -> str:
+    url = (os.getenv("REDISCTL_API_URL") or "").strip()
+    if not url:
+        raise SystemExit(
+            "缺少环境变量 REDISCTL_API_URL（网关地址，"
+            "例如 https://host/mcp-gateway/redis/api）"
+        )
+    return url.rstrip("/")
+
+
+def gateway_token() -> str:
+    token = (os.getenv("REDISCTL_TOKEN") or "").strip()
+    if not token:
+        raise SystemExit(
+            "缺少环境变量 REDISCTL_TOKEN（网关令牌）。\n"
+            "注意：不要用含 TOKEN / KEY / SECRET / AUTH 的变量名承载它 —— "
+            "某些客户端会把这类变量读成空字符串且不报警。"
+        )
+    return token
+
+
+def caller_credential_headers() -> dict[str, str]:
+    """调用方自带的 Redis 身份凭据。
+
+    这是**转发**给网关的，不是本地用来连 Redis 的 —— 网关收到后用这个身份
+    去操作 Redis，让操作在 Redis 侧归因到你本人。
+
+    只在不为空时才带上：头存在但值为空会被网关判为畸形并拒绝（那是刻意的，
+    因为空值通常意味着环境变量没导出，静默回落会造成「成功但归因错了」）。
+    """
+    headers: dict[str, str] = {}
+    username = (os.getenv("REDISCTL_REDIS_USERNAME") or "").strip()
+    password = os.getenv("REDISCTL_REDIS_PASSWORD") or ""
+    if username:
+        headers["X-Redis-Username"] = username
+    if password:
+        headers["X-Redis-Password"] = password
+    return headers
+
+
+def call(
+    operation_name: str,
+    params: dict[str, Any],
+    environment: str | None,
+    *,
+    write: bool,
+    timeout: float = DEFAULT_TIMEOUT,
+) -> dict:
+    """调用网关的一个操作，返回响应体。
+
+    读用 GET、写用 POST —— 与网关的 REST 契约一致。
+    """
+    base = gateway_url()
+    if environment:
+        params = {**params, "environment": environment}
+
+    headers = {"Authorization": f"Bearer {gateway_token()}", **caller_credential_headers()}
+
+    try:
+        with httpx.Client(timeout=timeout) as client:
+            if write:
+                response = client.post(f"{base}/{operation_name}", json=params, headers=headers)
+            else:
+                response = client.get(f"{base}/{operation_name}", params=params, headers=headers)
+    except httpx.HTTPError as exc:
+        raise GatewayError("connection_failed", f"无法连接网关：{exc}") from exc
+
+    try:
+        body = response.json()
+    except ValueError as exc:
+        raise GatewayError(
+            "invalid_response", f"网关返回了非 JSON 响应（HTTP {response.status_code}）"
+        ) from exc
+
+    if response.status_code >= 400 or not body.get("ok", False):
+        raise GatewayError(
+            body.get("error", "error"),
+            body.get("message", "网关返回了错误"),
+            body.get("hint"),
+        )
+    return body

redisctl-0.1.0/redisctl/discovery.py

@@ -0,0 +1,234 @@
+"""运行时发现网关的操作清单，并缓存到本地。
+
+## 为什么是「运行时发现」而不是「把注册表复制一份」
+
+复制两份清单必然分叉，而网关的护栏正建立在注册表的声明之上
+（章程原则 IV）。让 CLI 在运行时从网关拉取，单一事实来源得以保持。
+
+额外好处：网关返回的是**能力探测之后**注册的操作，所以 CLI 永远只暴露
+网关实际提供的能力 —— 本机集群没有 JSON/Search 模块时是 36 个，
+上游装了模块就是 40 个，CLI 自动跟上，不会出现
+「CLI 里有这条命令，但网关根本没有」的错位。
+
+## 缓存策略
+
+**网络优先，失败回退缓存。** 缓存有 TTL（默认 1 小时），陈旧就重新拉；
+拉不到时若有旧缓存就照旧用，并在 stderr 给个提示 ——
+命令行工具不该因为一次网络抖动就完全不能用。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import os
+import time
+from dataclasses import dataclass, field
+from pathlib import Path
+
+import httpx
+
+DEFAULT_TTL_SECONDS = 3600
+#: 缓存的格式版本。格式变了要让旧缓存失效，而不是解析出错后报莫名其妙的 KeyError。
+CACHE_SCHEMA_VERSION = 1
+
+
+class DiscoveryError(Exception):
+    """发现操作清单失败，且没有可用缓存。"""
+
+
+@dataclass(frozen=True)
+class Param:
+    name: str
+    type: str
+    required: bool
+    default: object = None
+    description: str = ""
+
+
+@dataclass(frozen=True)
+class Operation:
+    name: str
+    category: str
+    write: bool
+    summary: str
+    cluster_note: str
+    params: tuple[Param, ...] = field(default_factory=tuple)
+    requires: str | None = None
+
+    @classmethod
+    def from_payload(cls, raw: dict) -> Operation:
+        return cls(
+            name=raw["name"],
+            category=raw.get("category", ""),
+            write=bool(raw.get("write", False)),
+            summary=raw.get("summary", ""),
+            cluster_note=raw.get("cluster_note", ""),
+            requires=raw.get("requires"),
+            params=tuple(
+                Param(
+                    name=p["name"],
+                    type=p.get("type", "str"),
+                    required=bool(p.get("required", False)),
+                    default=p.get("default"),
+                    description=p.get("description", ""),
+                )
+                for p in raw.get("params", [])
+            ),
+        )
+
+    def to_payload(self) -> dict:
+        return {
+            "name": self.name,
+            "category": self.category,
+            "write": self.write,
+            "summary": self.summary,
+            "cluster_note": self.cluster_note,
+            "requires": self.requires,
+            "params": [
+                {
+                    "name": p.name,
+                    "type": p.type,
+                    "required": p.required,
+                    "default": p.default,
+                    "description": p.description,
+                }
+                for p in self.params
+            ],
+        }
+
+
+def cache_dir() -> Path:
+    base = os.getenv("XDG_CACHE_HOME") or (Path.home() / ".cache")
+    return Path(base) / "redisctl"
+
+
+def cache_path(base_url: str) -> Path:
+    """按网关地址分别缓存 —— 不同网关的操作集可能完全不同。"""
+    digest = hashlib.sha256(base_url.encode()).hexdigest()[:16]
+    return cache_dir() / f"operations-{digest}.json"
+
+
+def _ttl_seconds() -> int:
+    raw = (os.getenv("REDISCTL_CACHE_TTL") or "").strip()
+    if not raw:
+        return DEFAULT_TTL_SECONDS
+    try:
+        return max(0, int(raw))
+    except ValueError:
+        return DEFAULT_TTL_SECONDS
+
+
+def read_cache(base_url: str) -> tuple[list[Operation], float] | None:
+    """读缓存，返回 (操作列表, 抓取时间戳)。没有或不可用则返回 None。"""
+    path = cache_path(base_url)
+    if not path.is_file():
+        return None
+    try:
+        payload = json.loads(path.read_text(encoding="utf-8"))
+    except (OSError, ValueError):
+        return None
+
+    if payload.get("schema_version") != CACHE_SCHEMA_VERSION:
+        return None
+    if payload.get("base_url") != base_url:
+        return None
+    try:
+        operations = [Operation.from_payload(o) for o in payload["operations"]]
+    except (KeyError, TypeError, ValueError):
+        return None
+    return operations, float(payload.get("fetched_at", 0))
+
+
+def write_cache(base_url: str, operations: list[Operation]) -> None:
+    """写缓存。**写失败不算错误** —— 缓存是优化，不是依赖。"""
+    path = cache_path(base_url)
+    try:
+        path.parent.mkdir(parents=True, exist_ok=True)
+        path.write_text(
+            json.dumps(
+                {
+                    "schema_version": CACHE_SCHEMA_VERSION,
+                    "base_url": base_url,
+                    "fetched_at": time.time(),
+                    "operations": [op.to_payload() for op in operations],
+                },
+                ensure_ascii=False,
+            ),
+            encoding="utf-8",
+        )
+    except OSError:
+        pass
+
+
+def fetch_operations(base_url: str, token: str, *, timeout: float = 10.0) -> list[Operation]:
+    """从网关拉操作清单。任何失败都抛 DiscoveryError。"""
+    url = f"{base_url.rstrip('/')}/operations"
+    try:
+        response = httpx.get(
+            url,
+            headers={"Authorization": f"Bearer {token}"},
+            timeout=timeout,
+        )
+    except httpx.HTTPError as exc:
+        raise DiscoveryError(f"无法连接网关 {url}：{exc}") from exc
+
+    if response.status_code == 401:
+        raise DiscoveryError(
+            "网关拒绝了令牌（401）。请检查 REDISCTL_TOKEN 是否有效、是否已过期。"
+        )
+    if response.status_code != 200:
+        raise DiscoveryError(f"网关返回 HTTP {response.status_code}：{response.text[:200]}")
+
+    try:
+        payload = response.json()
+    except ValueError as exc:
+        raise DiscoveryError(
+            f"网关返回了非 JSON 响应。请确认 REDISCTL_API_URL 指向网关的 /api 路径"
+            f"（当前为 {base_url}）。"
+        ) from exc
+
+    if payload.get("schema_version") != CACHE_SCHEMA_VERSION:
+        raise DiscoveryError(
+            f"网关的操作清单格式版本为 {payload.get('schema_version')}，"
+            f"本版本 redisctl 支持 {CACHE_SCHEMA_VERSION}。请升级 redisctl。"
+        )
+
+    try:
+        return [Operation.from_payload(o) for o in payload["operations"]]
+    except (KeyError, TypeError, ValueError) as exc:
+        raise DiscoveryError(f"操作清单的响应结构无法解析：{exc}") from exc
+
+
+def discover(
+    base_url: str, token: str, *, force_refresh: bool = False
+) -> tuple[list[Operation], str | None]:
+    """发现操作清单。
+
+    返回 (操作列表, 提示信息)。提示信息是给 stderr 的警告，正常时为 None。
+
+    顺序：新鲜缓存 → 网络 → 陈旧缓存兜底。
+    """
+    cached = read_cache(base_url)
+    ttl = _ttl_seconds()
+    now = time.time()
+
+    if cached and not force_refresh:
+        operations, fetched_at = cached
+        if now - fetched_at < ttl:
+            return operations, None
+
+    try:
+        operations = fetch_operations(base_url, token)
+    except DiscoveryError as exc:
+        if cached:
+            operations, fetched_at = cached
+            age = int(now - fetched_at)
+            return operations, (
+                f"无法刷新操作清单（{exc}），改用 {age} 秒前的缓存。"
+                "命令列表可能不是最新的。"
+            )
+        raise
+
+    write_cache(base_url, operations)
+    return operations, None

redisctl-0.1.0/redisctl/main.py

@@ -0,0 +1,47 @@
+"""`redisctl` 包入口点。
+
+顺序是固定的：**先读配置 → 再发现操作 → 最后构造命令行**。
+因为命令列表是从网关拉来的，不先发现就无法构造 typer 应用 ——
+这是「运行时发现」方案的固有代价，换来的是与网关零耦合、
+且永远不会出现「CLI 有这条命令、网关却没有」的错位。
+"""
+
+from __future__ import annotations
+
+import os
+
+from .cli import fail, run, warn
+from .client import gateway_token, gateway_url
+from .discovery import DiscoveryError, discover
+
+
+def main() -> None:
+    base_url = gateway_url()
+    token = gateway_token()
+
+    # 逃逸口：让用户在网关长时间不可达时显式选择「用旧缓存」而不是每次等超时
+    force_refresh = (os.getenv("REDISCTL_REFRESH") or "").strip().lower() in {
+        "1", "true", "yes", "on",
+    }
+
+    try:
+        operations, notice = discover(base_url, token, force_refresh=force_refresh)
+    except DiscoveryError as exc:
+        fail(
+            f"无法从网关获取操作清单：{exc}\n\n"
+            "redisctl 的命令列表由网关提供，因此这一步是必须的。\n"
+            "请检查：\n"
+            f"  1. REDISCTL_API_URL 是否指向网关的 /api 路径（当前 {base_url}）\n"
+            "  2. REDISCTL_TOKEN 是否有效\n"
+            "  3. 网络是否可达网关",
+        )
+        return
+
+    if notice:
+        warn(notice)
+
+    run(operations)
+
+
+if __name__ == "__main__":
+    main()