toolgovern-cli 0.1.3__tar.gz → 0.1.4__tar.gz

{toolgovern_cli-0.1.3 → toolgovern_cli-0.1.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolgovern-cli
-Version: 0.1.3
+Version: 0.1.4
 Summary: Runtime governance middleware for AI agent tool calls -- gate shell, filesystem, network, and credential access before a tool executes.
 Project-URL: Homepage, https://github.com/RudrenduPaul/toolgovern
 Project-URL: Repository, https://github.com/RudrenduPaul/toolgovern
@@ -33,8 +33,11 @@ Provides-Extra: dev
 Requires-Dist: build<2,>=1.0; extra == 'dev'
 Requires-Dist: pytest<10,>=9.0.3; extra == 'dev'
 Requires-Dist: twine<7,>=5.0; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp[cli]>=2.0.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
+<!-- mcp-name: io.github.RudrenduPaul/toolgovern -->
 # toolgovern (Python)
 
 Gate every tool call an AI agent makes -- shell, filesystem, network, credential access -- before
@@ -302,6 +305,43 @@ structured-output envelope (`{ ok, command, data | error }`). **Not ported in th
 it generates a `.ts` file importing the JS/TS-only `toolgovern-integration-langgraph` /
 `toolgovern-integration-oma` packages, which are out of scope for a Python port by nature.
 
+## MCP Server
+
+toolgovern-cli ships a Model Context Protocol server, so an MCP-compatible agent (Claude
+Desktop, Claude Code, or any other MCP client) can call `validate` and `audit` directly instead
+of shelling out and parsing text.
+
+```bash
+pip install "toolgovern-cli[mcp]"
+```
+
+Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "toolgovern": {
+      "command": "toolgovern-mcp"
+    }
+  }
+}
+```
+
+The server exposes one tool, `run`, which takes the same argument list you'd pass to
+`toolgovern-cli` on the command line and returns its result as structured JSON -- it never
+raises, even on a bad file, a timeout, or non-JSON output; every failure comes back as
+`{"error": ...}` instead:
+
+```
+run(args=["validate", "./toolgovern.policy.yml", "--json"])
+```
+
+This is a generic subprocess wrapper around the real CLI (not a second implementation of each
+subcommand), so it stays in sync with `validate`, `audit`, and any future subcommand
+automatically. This is distinct from toolgovern's `mcp_trust` module, which is a client-side
+tool for verifying the trustworthiness of *other* MCP servers an agent connects to -- this
+section is about toolgovern-cli exposing its own MCP server for agents to call.
+
 ## The signed audit trail
 
 ```python

{toolgovern_cli-0.1.3 → toolgovern_cli-0.1.4}/README.md

@@ -1,3 +1,4 @@
+<!-- mcp-name: io.github.RudrenduPaul/toolgovern -->
 # toolgovern (Python)
 
 Gate every tool call an AI agent makes -- shell, filesystem, network, credential access -- before
@@ -265,6 +266,43 @@ structured-output envelope (`{ ok, command, data | error }`). **Not ported in th
 it generates a `.ts` file importing the JS/TS-only `toolgovern-integration-langgraph` /
 `toolgovern-integration-oma` packages, which are out of scope for a Python port by nature.
 
+## MCP Server
+
+toolgovern-cli ships a Model Context Protocol server, so an MCP-compatible agent (Claude
+Desktop, Claude Code, or any other MCP client) can call `validate` and `audit` directly instead
+of shelling out and parsing text.
+
+```bash
+pip install "toolgovern-cli[mcp]"
+```
+
+Claude Desktop config (`claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "toolgovern": {
+      "command": "toolgovern-mcp"
+    }
+  }
+}
+```
+
+The server exposes one tool, `run`, which takes the same argument list you'd pass to
+`toolgovern-cli` on the command line and returns its result as structured JSON -- it never
+raises, even on a bad file, a timeout, or non-JSON output; every failure comes back as
+`{"error": ...}` instead:
+
+```
+run(args=["validate", "./toolgovern.policy.yml", "--json"])
+```
+
+This is a generic subprocess wrapper around the real CLI (not a second implementation of each
+subcommand), so it stays in sync with `validate`, `audit`, and any future subcommand
+automatically. This is distinct from toolgovern's `mcp_trust` module, which is a client-side
+tool for verifying the trustworthiness of *other* MCP servers an agent connects to -- this
+section is about toolgovern-cli exposing its own MCP server for agents to call.
+
 ## The signed audit trail
 
 ```python

{toolgovern_cli-0.1.3 → toolgovern_cli-0.1.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "toolgovern-cli"
-version = "0.1.3"
+version = "0.1.4"
 description = "Runtime governance middleware for AI agent tool calls -- gate shell, filesystem, network, and credential access before a tool executes."
 readme = "README.md"
 requires-python = ">=3.9"
@@ -40,6 +40,12 @@ dev = [
   "build>=1.0,<2",
   "twine>=5.0,<7",
 ]
+# Pinned to >=2.0.0: mcp_server.py uses `mcp.server.MCPServer`, the current
+# high-level server class -- `mcp.server.fastmcp.FastMCP` was removed in
+# the 2.0.0 release.
+mcp = [
+  "mcp[cli]>=2.0.0",
+]
 
 [project.urls]
 Homepage = "https://github.com/RudrenduPaul/toolgovern"
@@ -52,6 +58,10 @@ Documentation = "https://github.com/RudrenduPaul/toolgovern/blob/main/docs/getti
 
 [project.scripts]
 toolgovern-cli = "toolgovern.cli:main"
+toolgovern-mcp = "toolgovern.mcp_server:main"
+
+[tool.hatch.build]
+exclude = [".venv*/"]
 
 [tool.hatch.build.targets.wheel]
 packages = ["src/toolgovern"]

toolgovern_cli-0.1.4/src/toolgovern/mcp_server.py

@@ -0,0 +1,129 @@
+"""MCP server (Python): exposes the toolgovern-cli command-line tool to agent
+runtimes over stdio.
+
+Requires the `mcp` extra (`pip install "toolgovern-cli[mcp]"`). Started via
+the `toolgovern-mcp` console script (installed by `python/pyproject.toml`'s
+`[project.scripts]`).
+
+This is a generic subprocess wrapper, not a per-subcommand tool set: a
+single `run` tool shells out to `python -m toolgovern.cli <args>` (invoked by
+module rather than by looking up the `toolgovern-cli` binary on PATH, so it
+works the same whether or not the console script entry point is installed)
+and returns the result. Wrapping the CLI this way means the tool stays in
+sync with `validate`, `audit`, and any future subcommand without a matching
+MCP tool hand-written for each one.
+
+Every failure path (the subprocess never starting, timing out, exiting
+non-zero, or printing non-JSON stdout) is caught and returned as a
+`{"error": ...}` dict. This tool handler must never raise -- an uncaught
+exception here would surface as a raw MCP protocol error instead of a
+readable result.
+
+Uses `mcp.server.MCPServer`, the official SDK's current high-level server
+class (`mcp` 2.0.0+) -- earlier `mcp` 1.x releases exposed the same
+`.tool()`/`.run()` pattern under `mcp.server.fastmcp.FastMCP`, which was
+removed in the 2.0.0 release.
+"""
+
+from __future__ import annotations
+
+import json
+import subprocess
+import sys
+from typing import Any
+
+from mcp.server import MCPServer
+
+_TIMEOUT_SECONDS = 60
+
+_STATIC_FALLBACK_DESCRIPTION = (
+    "Run the toolgovern-cli command-line tool with the given argument list "
+    "and return its output. toolgovern-cli validates governance policy "
+    "files and audits signed local trace logs of allow/deny/require-"
+    "approval decisions made by toolgovern's runtime tool-call gate. Pass "
+    "the same arguments you would give the `toolgovern-cli` command on the "
+    'command line, e.g. run(args=["validate", "./toolgovern.policy.yml", '
+    '"--json"]).'
+)
+
+
+def _get_cli_help() -> str:
+    """Runs `python -m toolgovern.cli --help` to source the tool
+    description from the CLI's real, current `--help` text. Returns "" on
+    any failure so the caller can fall back to the static description
+    instead of crashing at import time."""
+    try:
+        result = subprocess.run(
+            [sys.executable, "-m", "toolgovern.cli", "--help"],
+            capture_output=True,
+            text=True,
+            timeout=_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.TimeoutExpired):
+        return ""
+    return (result.stdout or result.stderr).strip()
+
+
+def _build_run_description() -> str:
+    help_text = _get_cli_help()
+    if not help_text:
+        return _STATIC_FALLBACK_DESCRIPTION
+    return (
+        "Run the toolgovern-cli command-line tool with the given argument "
+        f"list and return its output.\n\n{help_text}"
+    )
+
+
+# Populated once at import time from the real, installed CLI -- not
+# hand-maintained, so it can't silently drift from actual `--help` output.
+_RUN_TOOL_DESCRIPTION = _build_run_description()
+
+
+def build_app() -> MCPServer:
+    app = MCPServer("toolgovern")
+
+    @app.tool(description=_RUN_TOOL_DESCRIPTION)
+    def run(args: list[str]) -> dict[str, Any]:
+        try:
+            result = subprocess.run(
+                [sys.executable, "-m", "toolgovern.cli", *args],
+                capture_output=True,
+                text=True,
+                timeout=_TIMEOUT_SECONDS,
+            )
+        except OSError as error:
+            return {"error": f"failed to launch the toolgovern-cli CLI: {error}"}
+        except subprocess.TimeoutExpired:
+            return {"error": f"toolgovern-cli timed out after {_TIMEOUT_SECONDS}s"}
+
+        stdout = result.stdout.strip()
+        stderr = result.stderr.strip()
+
+        if result.returncode != 0:
+            return {
+                "error": stderr or stdout or f"toolgovern-cli exited with code {result.returncode}",
+                "returncode": result.returncode,
+            }
+
+        if not stdout:
+            return {"returncode": result.returncode, "stdout": "", "stderr": stderr}
+
+        try:
+            return {"result": json.loads(stdout)}
+        except json.JSONDecodeError:
+            # Not every subcommand supports --json (or the caller didn't
+            # pass it) -- return the raw text rather than treating this as
+            # an error.
+            return {"returncode": result.returncode, "stdout": stdout, "stderr": stderr}
+
+    return app
+
+
+def main() -> None:
+    """Entry point for the `toolgovern-mcp` console script."""
+    app = build_app()
+    app.run(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()