kctl-mcp 0.2.0__py3-none-any.whl

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/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/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/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/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/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/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"))]

kctl_mcp/schema.py

@@ -0,0 +1,211 @@
+"""Turn a Typer command tree into MCP tool definitions.
+
+No per-CLI code is needed: `commands tree --json` already emits every parameter's
+opts, type, requiredness, default, choices and flag-ness. This module is the
+translation, plus the filtering the projection demands.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import subprocess
+from dataclasses import dataclass, field
+from typing import Any
+
+from .core.exceptions import McpError
+from .projection import MODE_GATEWAY, Projection
+
+#: Typer's type names mapped onto JSON Schema.
+_TYPE_MAP = {
+    "str": "string",
+    "int": "integer",
+    "float": "number",
+    "bool": "boolean",
+    "Path": "string",
+}
+
+#: Never surfaced as a tool parameter. The profile decides which tenant and which
+#: environment a command touches, so exposing it would let a model pick production.
+BLOCKED_PARAMS = frozenset({"profile", "json", "quiet", "verbose", "format", "no_header", "version", "help"})
+
+#: Introspection is a local subprocess; a CLI that hangs must not hang the server.
+INTROSPECT_TIMEOUT = 60
+
+
+def clean_env() -> dict[str, str]:
+    """Environment for a machine-readable subprocess call.
+
+    kctl-lib's update notifier writes "WARN Update available: ..." to *stdout*,
+    which corrupts any JSON a caller is trying to parse. The fleet already
+    disables it in CI with this variable; the bridge needs it for the same reason.
+    """
+    env = dict(os.environ)
+    env["KCTL_NO_UPDATE_CHECK"] = "1"
+    env["NO_COLOR"] = "1"
+    env["TERM"] = "dumb"
+    return env
+
+
+def first_json_object(text: str) -> str:
+    """Strip any preamble a CLI printed before its JSON document."""
+    start = text.find("{")
+    return text[start:] if start > 0 else text
+
+
+@dataclass(frozen=True)
+class ToolDef:
+    name: str
+    description: str
+    input_schema: dict[str, Any]
+    command_path: str
+    params: list[dict[str, Any]] = field(default_factory=list)
+
+
+def introspect(cli: str, timeout: int = INTROSPECT_TIMEOUT) -> dict[str, Any]:
+    """Read a CLI's own command tree. The CLI is the authority on its surface."""
+    try:
+        result = subprocess.run(
+            [cli, "commands", "tree", "--json"],
+            capture_output=True,
+            text=True,
+            timeout=timeout,
+            env=clean_env(),
+        )
+    except FileNotFoundError:
+        raise McpError(f"{cli} is not installed or not on PATH") from None
+    except subprocess.TimeoutExpired:
+        raise McpError(f"{cli} commands tree timed out after {timeout}s") from None
+    if result.returncode != 0:
+        raise McpError(f"{cli} commands tree failed: {result.stderr.strip()[:200]}")
+    try:
+        return json.loads(first_json_object(result.stdout))
+    except json.JSONDecodeError as exc:
+        raise McpError(f"{cli} commands tree returned invalid JSON: {exc}") from None
+
+
+def walk_commands(node: dict[str, Any], prefix: str = "") -> list[tuple[str, dict[str, Any]]]:
+    """Flatten the tree into (command path, command node) pairs."""
+    found: list[tuple[str, dict[str, Any]]] = []
+    for command in node.get("commands") or []:
+        if command.get("hidden"):
+            continue
+        name = command.get("name", "")
+        path = f"{prefix} {name}".strip()
+        found.append((path, command))
+    for group in node.get("groups") or []:
+        if group.get("hidden"):
+            continue
+        name = group.get("name", "")
+        found.extend(walk_commands(group, f"{prefix} {name}".strip()))
+    return found
+
+
+def param_schema(param: dict[str, Any]) -> tuple[str, dict[str, Any]] | None:
+    """One Typer parameter as a JSON Schema property, or None when it must not surface."""
+    name = str(param.get("name", ""))
+    if not name or name in BLOCKED_PARAMS:
+        return None
+
+    prop: dict[str, Any] = {
+        "type": "boolean" if param.get("is_flag") else _TYPE_MAP.get(str(param.get("type")), "string")
+    }
+    if param.get("help"):
+        prop["description"] = str(param["help"])
+    if param.get("choices"):
+        prop["enum"] = list(param["choices"])
+    if param.get("default") is not None:
+        prop["default"] = param["default"]
+    return name, prop
+
+
+def tool_name(server: str, command_path: str) -> str:
+    """`odoo` + `analyze run` -> `odoo_analyze_run`."""
+    return f"{server}_{command_path.replace(' ', '_').replace('-', '_')}"
+
+
+def build_tools(tree: dict[str, Any], projection: Projection) -> list[ToolDef]:
+    """Every exposed command as an MCP tool."""
+    tools: list[ToolDef] = []
+    for path, command in walk_commands(tree):
+        if path.startswith("commands") or not projection.allows(path):
+            continue
+        properties: dict[str, Any] = {}
+        required: list[str] = []
+        params: list[dict[str, Any]] = []
+        for param in command.get("params") or []:
+            built = param_schema(param)
+            if built is None:
+                continue
+            key, prop = built
+            properties[key] = prop
+            params.append(param)
+            if param.get("required"):
+                required.append(key)
+        schema: dict[str, Any] = {"type": "object", "properties": properties}
+        if required:
+            schema["required"] = required
+        tools.append(
+            ToolDef(
+                name=tool_name(projection.name, path),
+                description=str(command.get("help") or path),
+                input_schema=schema,
+                command_path=path,
+                params=params,
+            )
+        )
+    return tools
+
+
+def gateway_tools(projection: Projection) -> list[ToolDef]:
+    """The two-tool projection for a large CLI.
+
+    A discover/run pair keeps every allowed command reachable without putting
+    hundreds of schemas in the model's context -- the same two-call shape the
+    fleet already documents for analytics.
+    """
+    exposed = ", ".join(projection.expose) or "nothing"
+    return [
+        ToolDef(
+            name=f"{projection.name}_discover",
+            description=(
+                f"Search {projection.cli} commands and their exact flags. "
+                f"Exposed surface: {exposed}. Call this before {projection.name}_run."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {"keyword": {"type": "string", "description": "Filter commands by keyword."}},
+                "required": ["keyword"],
+            },
+            command_path="__discover__",
+        ),
+        ToolDef(
+            name=f"{projection.name}_run",
+            description=(
+                f"Run one exposed {projection.cli} command and return its JSON. "
+                "Use the exact command path returned by discover."
+            ),
+            input_schema={
+                "type": "object",
+                "properties": {
+                    "command": {
+                        "type": "string",
+                        "description": "Command path, e.g. 'analyze run'.",
+                    },
+                    "args": {
+                        "type": "array",
+                        "items": {"type": "string"},
+                        "description": "Flags and values, e.g. ['--date-from', '2026-01-01'].",
+                    },
+                },
+                "required": ["command"],
+            },
+            command_path="__run__",
+        ),
+    ]
+
+
+def build(tree: dict[str, Any], projection: Projection) -> list[ToolDef]:
+    if projection.mode == MODE_GATEWAY:
+        return gateway_tools(projection)
+    return build_tools(tree, projection)

kctl_mcp/server.py

@@ -0,0 +1,93 @@
+"""The MCP server: a projection, served over stdio.
+
+The protocol handling is the official SDK's; everything interesting is in
+`projection.py` (what may be exposed) and `invoke.py` (how it is run).
+"""
+
+from __future__ import annotations
+
+import json
+from typing import Any
+
+from .core.exceptions import McpError, NotExposedError
+from .invoke import build_invocation, discover, run
+from .projection import MODE_GATEWAY, Projection
+from .schema import ToolDef, build, introspect
+
+
+def load_tools(projection: Projection) -> list[ToolDef]:
+    """Every tool this projection exposes. Gateway mode never introspects."""
+    if projection.mode == MODE_GATEWAY:
+        return build(tree={}, projection=projection)
+    return build(introspect(projection.cli), projection)
+
+
+def dispatch(projection: Projection, tools: list[ToolDef], name: str, arguments: dict[str, Any]) -> str:
+    """Route one tool call. Unknown names and unexposed commands are refused, not guessed."""
+    tool = next((t for t in tools if t.name == name), None)
+    if tool is None:
+        raise NotExposedError(f"unknown tool {name!r}")
+
+    profile = projection.resolve_profile()
+
+    if tool.command_path == "__discover__":
+        return discover(projection, str(arguments.get("keyword", ""))).output
+
+    if tool.command_path == "__run__":
+        command = str(arguments.get("command", ""))
+        raw_args = arguments.get("args") or []
+        args = [str(a) for a in raw_args] if isinstance(raw_args, list) else []
+        result = run(build_invocation(projection, command, args, profile))
+        return result.output
+
+    return run(build_invocation(projection, tool.command_path, flags_for(tool, arguments), profile)).output
+
+
+def flags_for(tool: ToolDef, arguments: dict[str, Any]) -> list[str]:
+    """Turn a tool call's JSON object back into CLI flags.
+
+    Only parameters the schema declared are considered, so an argument the model
+    invents cannot reach the command line.
+    """
+    by_name = {p.get("name"): p for p in tool.params}
+    args: list[str] = []
+    for key, value in arguments.items():
+        param = by_name.get(key)
+        if param is None or value is None:
+            continue
+        opts = param.get("opts") or []
+        flag = opts[0] if opts else f"--{str(key).replace('_', '-')}"
+        if param.get("is_flag"):
+            if value:
+                args.append(flag)
+            continue
+        if param.get("param_type") == "argument":
+            args.append(str(value))
+            continue
+        args += [flag, str(value)]
+    return args
+
+
+async def serve(projection: Projection) -> None:  # pragma: no cover - protocol I/O
+    """Run the stdio server. Imported lazily so the CLI works without the SDK."""
+    import mcp.types as types
+    from mcp.server import Server
+    from mcp.server.stdio import stdio_server
+
+    tools = load_tools(projection)
+    server: Server = Server(f"kctl-{projection.name}")
+
+    @server.list_tools()
+    async def list_tools() -> list[types.Tool]:
+        return [types.Tool(name=t.name, description=t.description, inputSchema=t.input_schema) for t in tools]
+
+    @server.call_tool()
+    async def call_tool(name: str, arguments: dict[str, Any] | None) -> list[types.TextContent]:
+        try:
+            text = dispatch(projection, tools, name, arguments or {})
+        except McpError as exc:
+            text = json.dumps({"error": f"{type(exc).__name__}: {exc}"})
+        return [types.TextContent(type="text", text=text)]
+
+    async with stdio_server() as (read, write):
+        await server.run(read, write, server.create_initialization_options())

kctl_mcp-0.2.0.dist-info/METADATA

@@ -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.dist-info/RECORD

@@ -0,0 +1,14 @@
+kctl_mcp/__init__.py,sha256=wkGQvsQnLHA8WNUqHG3VMS8LASKesCITo30omq2VSC0,113
+kctl_mcp/cli.py,sha256=UFtFK6AKa6o-PgoCFZcqJArMcxOCxGi9d_aiIn78hXM,5362
+kctl_mcp/invoke.py,sha256=QT-rnZpGwU8U9Y7QrBGyQkR5OiRBqXoBwoTSBqet1-c,3974
+kctl_mcp/projection.py,sha256=jTrmUd9K6Bi6Mw80bcDIcuUaqrZBVGOaXwn30bpOhSg,4487
+kctl_mcp/schema.py,sha256=y7s8UP9aYU-epygZaP1pD6WIyZjbb_-UsayRFlSl91o,7540
+kctl_mcp/server.py,sha256=6uqA6_1MI2KTD_Thvpnucxp_SU9rs2VCr93XXLR9RFA,3610
+kctl_mcp/core/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+kctl_mcp/core/callbacks.py,sha256=QscNwfHIqCoDzELgYgxErKPIFzru54K0H_Lkvb6sHK8,247
+kctl_mcp/core/config.py,sha256=B0AiYmEU3tN-fVG82_Rvq1O2jue1kyd0PP1lNaZlyxw,582
+kctl_mcp/core/exceptions.py,sha256=13eAFiV-37gwFh3Ovn62Yjad4Q3Ka4Bysurk1kc3TpU,353
+kctl_mcp-0.2.0.dist-info/METADATA,sha256=FQJlU52x0FX_hEkiFJARMgVgBwdjdFgg0babTJ9cS6g,302
+kctl_mcp-0.2.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+kctl_mcp-0.2.0.dist-info/entry_points.txt,sha256=m-mmjU4ooPqYzIcaN_SwaocGff6SyO4OKaEg0qt-0bo,47
+kctl_mcp-0.2.0.dist-info/RECORD,,

kctl_mcp-0.2.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

kctl_mcp-0.2.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+kctl-mcp = kctl_mcp.cli:_run