kctl-mcp 0.2.0__tar.gz

kctl_mcp-0.2.0/.gitignore

@@ -0,0 +1,39 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+*.egg
+dist/
+build/
+.eggs/
+
+# Virtual environments
+.venv/
+venv/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# Testing
+.pytest_cache/
+.coverage
+htmlcov/
+.mypy_cache/
+.ruff_cache/
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+.env.local
+
+# Agent memory (claude-mem regenerates AGENTS.md locally; not a committed guide)
+AGENTS.md
+
+# kctl-agent container render output (derived from agents.toml)
+out/

kctl_mcp-0.2.0/PKG-INFO

@@ -0,0 +1,10 @@
+Metadata-Version: 2.5
+Name: kctl-mcp
+Version: 0.2.0
+Summary: Turn any kctl-* Typer CLI into a curated MCP server, with no per-CLI code
+Requires-Python: >=3.12
+Requires-Dist: kctl-agent>=0.1.0
+Requires-Dist: kctl-lib>=0.14.0
+Requires-Dist: mcp>=1.0
+Requires-Dist: rich>=13.0
+Requires-Dist: typer>=0.9.0

kctl_mcp-0.2.0/README.md

@@ -0,0 +1,119 @@
+# kctl-mcp
+
+Turn any `kctl-*` CLI into an MCP server, with **no per-CLI code**.
+
+Every kctl CLI already emits complete per-parameter schemas via
+`commands tree --json` — opts, type, requiredness, default, choices, flag-ness. That is a
+tool definition. This package is the translation, plus the restraint that makes it safe.
+
+## The design work is restraint, not the bridge
+
+`kctl-odoo` has **1,179 commands**. `kctl-dokploy` has 283. A naive bridge would expose all
+of them, including `applications delete`, and would degrade tool selection for every other
+server in the session.
+
+Two rules prevent that:
+
+1. **Allow-list, not deny-list.** Nothing is exposed until a pattern names it. `deny` is a
+   second net, so widening an `expose` pattern by accident still cannot surface a destructive
+   command.
+2. **The profile binds at launch, never as a tool argument.** A model that can pass
+   `--profile` can reach production. This is the MCP form of the fleet's no-default-profile
+   rule, and it is enforced in three places: the parameter is stripped from every generated
+   schema, a model-supplied `--profile` flag is filtered out of argv, and `MCP-003` fails a
+   projection that does not declare `profile_from`.
+
+## Two modes
+
+| Mode | Shape | Use for |
+|---|---|---|
+| `tools` | one MCP tool per exposed command | curated surfaces, ≤30 tools |
+| `gateway` | exactly two tools: `<name>_discover(keyword)` and `<name>_run(command, args)` | large CLIs — all 1,179 Odoo commands stay reachable without 1,179 schemas in context |
+
+Gateway mode mirrors the two-call pattern the fleet already documents for analytics, and it
+never introspects at startup.
+
+## A projection
+
+```toml
+# mcp/odoo.toml
+name = "odoo"
+cli = "kctl-odoo"
+mode = "gateway"
+transport = "stdio"
+
+expose = ["analyze *", "kpi *", "dashboard *", "report quick", "report list", "doctor *"]
+deny   = ["*delete*", "*drop*", "*deploy*", "*restore*", "*apply*", "*push*", "*write*"]
+
+profile_from = "env:KCTL_ODOO_PROFILE"
+```
+
+## Commands
+
+| Command | Purpose |
+|---------|---------|
+| `kctl-mcp list` | The projections this repo declares. |
+| `kctl-mcp tools <name>` | The tools a projection would expose — without starting a server. |
+| `kctl-mcp audit <name>` | Which of a CLI's commands are exposed, and how many are hidden. |
+| `kctl-mcp schema <name>` | Raw MCP tool schemas, for debugging a client that mis-parses them. |
+| `kctl-mcp serve <name>` | Serve over stdio. This is what an MCP client launches. |
+
+`audit` is the review tool: it prints the exposed set against the total, so a projection can
+be checked at a glance.
+
+```
+$ kctl-mcp --json audit odoo
+total=1179 exposed=30 hidden=1149 over_budget=False
+```
+
+## Wiring a client
+
+```json
+{
+  "mcpServers": {
+    "odoo": {
+      "command": "kctl-mcp",
+      "args": ["serve", "odoo"],
+      "env": { "KCTL_ODOO_PROFILE": "idtpp-tpp-odoo-erp" }
+    }
+  }
+}
+```
+
+`kctl-agent` manages these entries; see `agents.toml`.
+
+## Safety
+
+Every guard lives in `invoke.py`, because that is the only place model input becomes a
+process:
+
+- the command path is re-checked against the projection on every call, never trusted from the
+  tool arguments — this matters most in gateway mode, where the model supplies the path;
+- a command path is a whitelist of `[a-z0-9-_ ]`, so `;`, `|`, `&&`, `$(…)` and `..` are
+  refused outright;
+- arguments are passed as an argv list with `shell=False`, so a hostile value stays one
+  element;
+- `--force`, `--yes`, `-y` and `--no-backup` are stripped, with their values;
+- arguments the model invents but the schema never declared are dropped;
+- output is capped at 60,000 characters so a runaway report cannot fill the context window;
+- subprocesses run with `KCTL_NO_UPDATE_CHECK=1`, because kctl-lib's update notifier writes
+  to *stdout* and corrupts any JSON a caller is parsing.
+
+## Governance
+
+Projections are governed by the `MCP-*` rule family in `kctl-agent`, which runs in the same
+`just conform` ratchet as everything else:
+
+```bash
+kctl-agent lint            # MCP-001..006 over every mcp/*.toml
+kctl-conform explain MCP-003
+```
+
+## Testing
+
+```bash
+uv run pytest packages/kctl-mcp/tests/ -v
+```
+
+No test executes a real CLI or opens a socket; the Typer tree is a fixture shaped exactly
+like real introspection output.

kctl_mcp-0.2.0/pyproject.toml

@@ -0,0 +1,43 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "kctl-mcp"
+version = "0.2.0"
+description = "Turn any kctl-* Typer CLI into a curated MCP server, with no per-CLI code"
+requires-python = ">=3.12"
+dependencies = [
+    "kctl-lib>=0.14.0",
+    "kctl-agent>=0.1.0",
+    "typer>=0.9.0",
+    "rich>=13.0",
+    "mcp>=1.0",
+]
+
+[project.scripts]
+kctl-mcp = "kctl_mcp.cli:_run"
+
+[tool.uv.sources]
+kctl-lib = { workspace = true }
+kctl-agent = { workspace = true }
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/kctl_mcp"]
+
+[tool.kctl-conform]
+kind = "meta"
+# A protocol bridge, not a service CLI:
+#   AFFORD-001 = no global --json/--profile; the profile binds at server launch
+#                and is deliberately NOT a runtime option (see MCP-005).
+#   AFFORD-004 = no `doctor ai-summary`; kctl-agent doctor covers MCP health.
+#   LAYOUT-006 = no core/client.py; it introspects local Typer apps.
+#   LAYOUT-003 = five flat commands live in a 165-line cli.py, well inside the
+#                SIZE-001 budget; a commands/ package would be one module per
+#                function. Same call as kctl-skill.
+exempt = [
+    "AFFORD-001",
+    "AFFORD-004",
+    "LAYOUT-003",
+    "LAYOUT-006",
+]

kctl_mcp-0.2.0/src/kctl_mcp/__init__.py

@@ -0,0 +1,5 @@
+"""kctl-mcp — a curated MCP projection of any kctl-* CLI."""
+
+__version__ = "0.2.0"
+
+__all__ = ["__version__"]

kctl_mcp-0.2.0/src/kctl_mcp/cli.py

@@ -0,0 +1,165 @@
+"""kctl-mcp — serve any kctl-* CLI as a curated MCP server."""
+
+from __future__ import annotations
+
+import json as _json
+from pathlib import Path
+from typing import Annotated
+
+import typer
+from kctl_lib import cli_entrypoint, register_introspection_commands
+
+from . import __version__
+from .core.callbacks import AppContext
+from .core.config import find_repo_root
+from .projection import MAX_TOOLS, discover_projections, load_projection
+from .schema import introspect, walk_commands
+from .server import load_tools
+
+app = typer.Typer(
+    name="kctl-mcp",
+    help="Serve any kctl-* CLI as a curated MCP server.",
+    no_args_is_help=True,
+)
+
+
+def _version_callback(value: bool) -> None:
+    if value:
+        typer.echo(f"kctl-mcp {__version__}")
+        raise typer.Exit()
+
+
+@app.callback()
+def main(
+    ctx: typer.Context,
+    json_output: Annotated[bool, typer.Option("--json", help="Emit JSON.")] = False,
+    quiet: Annotated[bool, typer.Option("--quiet", "-q", help="Suppress non-essential output.")] = False,
+    version: Annotated[
+        bool,
+        typer.Option("--version", "-V", callback=_version_callback, is_eager=True, help="Show version."),
+    ] = False,
+) -> None:
+    """Root callback."""
+    ctx.obj = AppContext(json_mode=json_output, quiet=quiet, format="json" if json_output else "pretty")
+
+
+def _projection(name: str, root: Path):  # type: ignore[no-untyped-def]
+    candidate = Path(name)
+    return load_projection(candidate if candidate.is_file() else root / "mcp" / f"{name}.toml")
+
+
+@app.command("list")
+def list_cmd(ctx: typer.Context) -> None:
+    """List the projections this repo declares."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    root = find_repo_root()
+    projections = discover_projections(root)
+
+    if actx.json_mode:
+        out.raw_json(
+            [{"name": p.name, "cli": p.cli, "mode": p.mode, "expose": p.expose, "deny": p.deny} for p in projections]
+        )
+        return
+    columns = [("name", "cyan"), ("cli", "white"), ("mode", "dim"), ("exposed patterns", "dim")]
+    rows = [[p.name, p.cli, p.mode, ", ".join(p.expose) or "(nothing)"] for p in projections]
+    out.table("MCP projections", columns, rows)
+
+
+@app.command("tools")
+def tools_cmd(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Projection name or path to an mcp/*.toml.")],
+) -> None:
+    """Show the tools a projection would expose, without starting a server."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    projection = _projection(name, find_repo_root())
+    tools = load_tools(projection)
+
+    if actx.json_mode:
+        out.raw_json(
+            [
+                {
+                    "name": t.name,
+                    "description": t.description,
+                    "input_schema": t.input_schema,
+                    "command": t.command_path,
+                }
+                for t in tools
+            ]
+        )
+        return
+
+    columns = [("tool", "cyan"), ("command", "white"), ("description", "dim")]
+    rows = [[t.name, t.command_path, (t.description or "")[:70]] for t in tools]
+    out.table(f"{projection.name} ({projection.mode} mode)", columns, rows)
+    if not actx.quiet:
+        typer.echo(f"\n{len(tools)} tool(s); budget {MAX_TOOLS}")
+
+
+@app.command("audit")
+def audit_cmd(
+    ctx: typer.Context,
+    name: Annotated[str, typer.Argument(help="Projection name.")],
+) -> None:
+    """Show which of a CLI's commands the projection exposes, and which it hides."""
+    actx: AppContext = ctx.obj
+    out = actx.output
+    projection = _projection(name, find_repo_root())
+    paths = [p for p, _ in walk_commands(introspect(projection.cli)) if not p.startswith("commands")]
+    exposed = [p for p in paths if projection.allows(p)]
+    hidden = [p for p in paths if not projection.allows(p)]
+
+    payload = {
+        "cli": projection.cli,
+        "mode": projection.mode,
+        "total_commands": len(paths),
+        "exposed": exposed,
+        "hidden_count": len(hidden),
+        "over_budget": len(exposed) > MAX_TOOLS and projection.mode == "tools",
+    }
+    if actx.json_mode:
+        out.raw_json(payload)
+        return
+    typer.echo(f"{projection.cli}: {len(paths)} command(s), {len(exposed)} exposed, {len(hidden)} hidden")
+    for path in exposed:
+        typer.echo(f"  + {path}")
+    if payload["over_budget"]:
+        out.warn(f'{len(exposed)} tools exceeds the budget of {MAX_TOOLS}; use mode = "gateway"')
+
+
+@app.command("serve")
+def serve_cmd(
+    name: Annotated[str, typer.Argument(help="Projection name or path to an mcp/*.toml.")],
+) -> None:
+    """Serve a projection over stdio. This is what an MCP client launches."""
+    import anyio
+
+    from .server import serve
+
+    projection = _projection(name, find_repo_root())
+    anyio.run(serve, projection)
+
+
+@app.command("schema")
+def schema_cmd(
+    name: Annotated[str, typer.Argument(help="Projection name.")],
+) -> None:
+    """Print the raw MCP tool schemas, for debugging a client that mis-parses them."""
+    projection = _projection(name, find_repo_root())
+    tools = load_tools(projection)
+    typer.echo(
+        _json.dumps(
+            [{"name": t.name, "description": t.description, "inputSchema": t.input_schema} for t in tools],
+            indent=2,
+        )
+    )
+
+
+register_introspection_commands(app)
+app = cli_entrypoint(app)
+
+
+def _run() -> None:
+    app()

kctl_mcp-0.2.0/src/kctl_mcp/core/callbacks.py

@@ -0,0 +1,13 @@
+from __future__ import annotations
+
+from dataclasses import dataclass
+from pathlib import Path
+
+from kctl_lib import AppContextBase
+
+
+@dataclass
+class AppContext(AppContextBase):
+    """Typer context for kctl-mcp."""
+
+    root: Path | None = None

kctl_mcp-0.2.0/src/kctl_mcp/core/config.py

@@ -0,0 +1,18 @@
+"""Workspace root resolution for the MCP bridge."""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from .exceptions import McpError
+
+_WORKSPACE_MARKER = "[tool.uv.workspace]"
+
+
+def find_repo_root(start: Path | None = None) -> Path:
+    current = (start or Path.cwd()).resolve()
+    for candidate in (current, *current.parents):
+        pyproject = candidate / "pyproject.toml"
+        if pyproject.is_file() and _WORKSPACE_MARKER in pyproject.read_text(encoding="utf-8"):
+            return candidate
+    raise McpError(f"no uv workspace root found from {current}")

kctl_mcp-0.2.0/src/kctl_mcp/core/exceptions.py

@@ -0,0 +1,15 @@
+from __future__ import annotations
+
+from kctl_lib import KctlError
+
+
+class McpError(KctlError):
+    """Base for every kctl-mcp failure."""
+
+
+class ProjectionError(McpError):
+    """An mcp/<name>.toml projection is missing, malformed, or unsafe."""
+
+
+class NotExposedError(McpError):
+    """A tool call named a command the projection does not expose."""

kctl_mcp-0.2.0/src/kctl_mcp/invoke.py

@@ -0,0 +1,120 @@
+"""Run an exposed command and return its output.
+
+Every guard that matters lives here, because this is the only place the bridge
+turns model input into a process:
+
+* the command path is re-checked against the projection, never trusted from the
+  tool call;
+* arguments are passed as an argv list, never through a shell;
+* the profile is injected from the launch environment and stripped from anything
+  the model supplied;
+* output is capped, because a runaway report should not fill the context window.
+"""
+
+from __future__ import annotations
+
+import subprocess
+from dataclasses import dataclass
+
+from .core.exceptions import NotExposedError
+from .projection import Projection
+from .schema import clean_env
+
+DEFAULT_TIMEOUT = 120
+
+#: Characters answered for by argv-passing, but a command path is a whitelist anyway.
+_PATH_CHARS = set("abcdefghijklmnopqrstuvwxyz0123456789-_ ")
+
+#: Truncation point for tool output, in characters.
+MAX_OUTPUT = 60_000
+
+#: Flags the model may never set: they choose the tenant, the environment, or
+#: bypass confirmation.
+BLOCKED_FLAGS = frozenset({"--profile", "-p", "--force", "--yes", "-y", "--no-backup"})
+
+
+@dataclass(frozen=True)
+class Invocation:
+    argv: list[str]
+    timeout: int = DEFAULT_TIMEOUT
+
+
+@dataclass(frozen=True)
+class Result:
+    ok: bool
+    output: str
+    exit_code: int
+
+
+def sanitise_path(command_path: str) -> str:
+    """A command path is a space-separated whitelist of command names, nothing else."""
+    cleaned = command_path.strip()
+    if not cleaned or not set(cleaned.lower()) <= _PATH_CHARS:
+        raise NotExposedError(f"invalid command path {command_path!r}")
+    return cleaned
+
+
+def filter_args(args: list[str]) -> list[str]:
+    """Drop flags the model must not control, with their values."""
+    out: list[str] = []
+    skip_next = False
+    for arg in args:
+        if skip_next:
+            skip_next = False
+            continue
+        base = arg.split("=", 1)[0]
+        if base in BLOCKED_FLAGS:
+            skip_next = "=" not in arg
+            continue
+        out.append(arg)
+    return out
+
+
+def build_invocation(
+    projection: Projection,
+    command_path: str,
+    args: list[str] | None = None,
+    profile: str | None = None,
+    timeout: int = DEFAULT_TIMEOUT,
+) -> Invocation:
+    """Assemble argv for one exposed command, or refuse."""
+    path = sanitise_path(command_path)
+    if not projection.allows(path):
+        raise NotExposedError(f"{path!r} is not exposed by the {projection.name} projection")
+    argv = [projection.cli]
+    if profile:
+        argv += ["--profile", profile]
+    argv.append("--json")
+    argv += path.split()
+    argv += filter_args(list(args or []))
+    return Invocation(argv=argv, timeout=timeout)
+
+
+def run(invocation: Invocation) -> Result:
+    """Execute without a shell. Failures come back as text, never as exceptions."""
+    try:
+        completed = subprocess.run(
+            invocation.argv,
+            capture_output=True,
+            text=True,
+            timeout=invocation.timeout,
+            shell=False,
+            env=clean_env(),
+        )
+    except FileNotFoundError:
+        return Result(False, f"{invocation.argv[0]} is not installed or not on PATH", 127)
+    except subprocess.TimeoutExpired:
+        return Result(False, f"timed out after {invocation.timeout}s", 124)
+
+    output = completed.stdout if completed.returncode == 0 else (completed.stderr or completed.stdout)
+    if len(output) > MAX_OUTPUT:
+        output = output[:MAX_OUTPUT] + f"\n... truncated at {MAX_OUTPUT} characters"
+    return Result(completed.returncode == 0, output.strip(), completed.returncode)
+
+
+def discover(projection: Projection, keyword: str, timeout: int = DEFAULT_TIMEOUT) -> Result:
+    """Gateway mode's discovery half: the CLI's own filtered command list."""
+    argv = [projection.cli, "commands", "list", "--json"]
+    if keyword:
+        argv += ["--filter", keyword]
+    return run(Invocation(argv=argv, timeout=timeout))

kctl_mcp-0.2.0/src/kctl_mcp/projection.py

@@ -0,0 +1,121 @@
+"""A projection decides which of a CLI's commands become MCP tools.
+
+The bridge itself is trivial -- every kctl CLI already emits full per-parameter
+schemas. The design work is restraint: `kctl-odoo` alone has hundreds of
+commands, and a server that exposed them all would degrade tool selection for
+every other server in the session.
+
+Two rules make that safe:
+
+1. **Allow-list, not deny-list.** Nothing is exposed until a pattern names it.
+   ``deny`` is a second net, not the mechanism.
+2. **The profile binds at launch, never as a tool argument.** A model that can
+   pass ``--profile`` can reach production. This is the MCP form of the fleet's
+   no-default-profile rule.
+"""
+
+from __future__ import annotations
+
+import os
+import tomllib
+from dataclasses import dataclass, field
+from fnmatch import fnmatchcase
+from pathlib import Path
+
+from .core.exceptions import ProjectionError
+
+MODE_TOOLS = "tools"
+MODE_GATEWAY = "gateway"
+VALID_MODES = (MODE_TOOLS, MODE_GATEWAY)
+
+TRANSPORT_STDIO = "stdio"
+VALID_TRANSPORTS = (TRANSPORT_STDIO,)
+
+#: Selection accuracy degrades as the tool list grows; past this a projection
+#: should switch to gateway mode instead of listing every command.
+MAX_TOOLS = 30
+
+#: Verbs that change the world. Never exposed unless a pattern names them exactly.
+DESTRUCTIVE_HINTS = ("delete", "drop", "destroy", "remove", "purge", "reset", "restore", "deploy")
+
+
+@dataclass(frozen=True)
+class Projection:
+    """One `mcp/<name>.toml`."""
+
+    name: str
+    cli: str
+    mode: str = MODE_TOOLS
+    transport: str = TRANSPORT_STDIO
+    expose: list[str] = field(default_factory=list)
+    deny: list[str] = field(default_factory=list)
+    profile_from: str = ""
+    path: Path | None = None
+
+    def resolve_profile(self, environ: dict[str, str] | None = None) -> str | None:
+        """Read the launch-bound profile. ``env:NAME`` is the only supported source."""
+        if not self.profile_from:
+            return None
+        source = environ if environ is not None else dict(os.environ)
+        if self.profile_from.startswith("env:"):
+            return source.get(self.profile_from[4:])
+        raise ProjectionError(f"{self.name}: profile_from must be 'env:<VAR>', got {self.profile_from!r}")
+
+    def allows(self, command_path: str) -> bool:
+        """True when this command may be invoked.
+
+        Deny always wins, and an empty allow-list exposes nothing -- a projection
+        that forgot to declare ``expose`` is inert rather than wide open.
+        """
+        if any(fnmatchcase(command_path, pattern) for pattern in self.deny):
+            return False
+        return any(fnmatchcase(command_path, pattern) for pattern in self.expose)
+
+
+def parse_projection(text: str, name: str = "", path: Path | None = None) -> Projection:
+    try:
+        raw = tomllib.loads(text)
+    except tomllib.TOMLDecodeError as exc:
+        raise ProjectionError(f"{name or 'projection'}: not valid TOML: {exc}") from None
+
+    cli = str(raw.get("cli", "")).strip()
+    if not cli:
+        raise ProjectionError(f"{name or 'projection'}: 'cli' is required")
+
+    mode = str(raw.get("mode", MODE_TOOLS))
+    if mode not in VALID_MODES:
+        raise ProjectionError(f"{name}: mode must be one of {', '.join(VALID_MODES)}, got {mode!r}")
+
+    transport = str(raw.get("transport", TRANSPORT_STDIO))
+    if transport not in VALID_TRANSPORTS:
+        raise ProjectionError(f"{name}: transport must be one of {', '.join(VALID_TRANSPORTS)}, got {transport!r}")
+
+    def str_list(key: str) -> list[str]:
+        value = raw.get(key, [])
+        if not isinstance(value, list) or not all(isinstance(v, str) for v in value):
+            raise ProjectionError(f"{name}: '{key}' must be a list of strings")
+        return list(value)
+
+    return Projection(
+        name=str(raw.get("name", name or cli.removeprefix("kctl-"))),
+        cli=cli,
+        mode=mode,
+        transport=transport,
+        expose=str_list("expose"),
+        deny=str_list("deny"),
+        profile_from=str(raw.get("profile_from", "")),
+        path=path,
+    )
+
+
+def load_projection(path: Path) -> Projection:
+    if not path.is_file():
+        raise ProjectionError(f"no projection at {path}")
+    return parse_projection(path.read_text(encoding="utf-8"), name=path.stem, path=path)
+
+
+def discover_projections(root: Path, subdir: str = "mcp") -> list[Projection]:
+    base = root / subdir
+    if not base.is_dir():
+        return []
+    return [load_projection(p) for p in sorted(base.glob("*.toml"))]