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

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: toolgovern-cli
-Version: 0.1.2
+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
@@ -12,7 +12,7 @@ Project-URL: Author - Sourav Nandy, https://github.com/Sourav-nandy-ai
 Author: Rudrendu Paul, Sourav Nandy
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: agent-governance,ai-agents,audit-trail,cli,mcp,runtime-security,security,tool-calling
+Keywords: agent-governance,ai-agents,audit-trail,cli,mcp,policy-enforcement,runtime-security,scope-narrowing,security,tool-calling
 Classifier: Development Status :: 3 - Alpha
 Classifier: Environment :: Console
 Classifier: Intended Audience :: Developers
@@ -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
@@ -259,6 +262,35 @@ from toolgovern import (
 )
 ```
 
+## How it compares to other agent governance projects
+
+Same facts as the [project README's full comparison
+table](https://github.com/RudrenduPaul/toolgovern#how-it-compares-to-other-agent-governance-projects)
+-- condensed here to the rows that matter most for picking a package, not re-derived. The "Rules
+out of the box" row below is 36, not 35, because this Python port folds the DNS-resolution check
+(`TG03-dns-resolves-private`) directly into its one synchronous `classify()` instead of needing a
+separate async entry point -- see [What it does](#what-it-does) above. Every other row applies
+equally to both the TypeScript and Python distributions.
+
+|                            | **toolgovern**                                                      | [Microsoft Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit)     | [NVIDIA NeMo Relay](https://github.com/NVIDIA/NeMo-Relay)                     | [LangGraph human-in-the-loop](https://docs.langchain.com/oss/python/langchain/human-in-the-loop) |
+| -------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| What it actually gates     | Tool calls, pre-execution, against a built-in rule set              | Tool calls, messages, and delegation, pre-execution, against policy you author (YAML/OPA/Cedar) | Tool and LLM calls via pre-tool hooks -- coverage depends on the host agent   | A single tool call, paused for a human decision -- no automated risk classification              |
+| Rules out of the box       | 36 (this Python port), across 6 categories, zero config             | None shipped -- you write the policy                                                            | None shipped -- pre-tool hooks call your own logic, not a built-in classifier | None -- you decide per call                                                                      |
+| Per-agent scope narrowing  | Yes -- a sub-agent can never exceed its coordinator's granted scope | Yes -- documented delegation-chain narrowing and a 4-ring privilege model                       | Not publicly documented                                                       | No                                                                                               |
+| Tamper-evident audit trail | Yes -- signed, hash-chained local JSONL                             | Yes -- Merkle-audit-backed, 157 conformance tests just for the audit layer                      | No -- raw JSONL trajectory export (ATOF/ATIF format), not signed              | No                                                                                               |
+| Hosted component required  | No, never                                                           | No -- self-hosted by design, Azure integration is optional                                      | No -- local CLI gateway                                                       | No for the OSS library; LangGraph's own hosted server runtime is separately licensed             |
+| License                    | Apache 2.0                                                          | MIT                                                                                             | Apache 2.0                                                                    | MIT                                                                                              |
+
+Two things worth repeating from the full narrative rather than leaving implicit: Microsoft's
+Agent Governance Toolkit already matches or exceeds this project on scoping and audit-trail
+maturity (a formal delegation-chain spec, 157 conformance tests just for its audit layer) -- this
+table is not a claim that toolgovern beats AGT. And NeMo Relay / LangGraph HITL are doing a
+genuinely different job, not a weaker version of the same one -- listing them here is about scope,
+not a claim of superiority at the task each of them is actually built for. Read the [full
+comparison and both honest
+caveats](https://github.com/RudrenduPaul/toolgovern#how-it-compares-to-other-agent-governance-projects)
+in the project README before deciding what you need.
+
 ## CLI
 
 ```bash
@@ -273,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
@@ -322,6 +391,56 @@ pytest
 
 Report a vulnerability per the project's [`SECURITY.md`](https://github.com/RudrenduPaul/toolgovern/blob/main/SECURITY.md); please don't open a public issue for one.
 
+## FAQ
+
+**What does toolgovern do?**
+It's a runtime gate that checks every tool call an AI agent makes -- shell, filesystem, network,
+credential access -- against a 36-rule classifier before the call executes, not after.
+`govern_tool()` wraps any `ToolDefinition(name, execute)` you already have and runs each call
+through the classifier, the per-agent scope registry, and (if wired in) the signed trace writer
+before your real `execute()` ever fires. See [Why this exists](#why-this-exists) and [What it
+does](#what-it-does) above for the full case.
+
+**How does this Python package differ from the npm package, if at all?**
+Functionally, barely. It ships the same 36-rule classifier (the npm/TypeScript package runs 35
+rules synchronously plus one additional async-only DNS-resolution rule, landing at 36 checks total
+through its `classifyAsync()` path; this Python port folds that same DNS check into its one
+synchronous `classify()` instead, so it's 36 either way), the same intersection-only scope
+registry, the same durable approval registry, the same MCP-server trust boundary, and the same
+signed trace format -- a genuine Python port, not a wrapper around the Node binary. Two real gaps
+today: `toolgovern-cli init [oma|langgraph]` (the npm CLI's TypeScript integration-file scaffolder)
+isn't ported, since it generates a `.ts` file importing JS/TS-only packages; and the two npm-only
+integration packages (`toolgovern-integration-oma`, `toolgovern-integration-langgraph` for
+LangGraph.js) have no Python equivalent by design -- wire `govern_tool()` directly into your
+Python framework's own call site instead. See [CLI](#cli) and [Framework
+integrations](#framework-integrations) above.
+
+**Does it need API keys or an account?**
+No. Nothing in this package calls out to a hosted service. No call payload, argument, trace
+content, or policy leaves your process unless code you write sends it somewhere -- there's no
+server dependency, no account, and nothing to sign up for.
+
+**Is it safe to run -- does an `allow` decision mean a tool call is safe?**
+Running the package itself is safe: it's a local, in-process classifier that makes no network
+calls of its own (the one exception, `TG03-dns-resolves-private`, only performs a DNS lookup of an
+argument value your own tool call passes it). But an `allow` decision is not a safety guarantee --
+it means the call was checked against the current 36-rule set and nothing fired.
+[`docs/security-model.md`](https://github.com/RudrenduPaul/toolgovern/blob/main/docs/security-model.md)
+in the main repo documents exactly what the classifier does and doesn't catch, including disclosed
+obfuscation techniques it can still miss.
+
+**How do I use it from an agent?**
+Five real Python framework integrations exist in the main repo -- LangGraph (using the real
+`wrap_tool_call` `ToolNode` parameter), CrewAI, AutoGen, Microsoft Agent Framework, and the Claude
+Agent SDK (using its real `PreToolUse` hook) -- each installable from source (none are published to
+PyPI yet). For a framework without a dedicated integration, wrap your own tool definitions with
+`govern_tool()` directly at whatever call site your framework dispatches tool calls from. See
+[Framework integrations](#framework-integrations) above for install commands and worked examples.
+
+**Is there a hosted version of toolgovern?**
+No. Everything that exists today is in the GitHub repository, Apache 2.0, self-hosted only, for
+both the Python and TypeScript distributions.
+
 ## Links
 
 - [GitHub repository](https://github.com/RudrenduPaul/toolgovern)
@@ -335,4 +454,3 @@ Report a vulnerability per the project's [`SECURITY.md`](https://github.com/Rudr
 ## License
 
 Apache 2.0 -- see [LICENSE](../LICENSE).
-

{toolgovern_cli-0.1.2 → 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
@@ -222,6 +223,35 @@ from toolgovern import (
 )
 ```
 
+## How it compares to other agent governance projects
+
+Same facts as the [project README's full comparison
+table](https://github.com/RudrenduPaul/toolgovern#how-it-compares-to-other-agent-governance-projects)
+-- condensed here to the rows that matter most for picking a package, not re-derived. The "Rules
+out of the box" row below is 36, not 35, because this Python port folds the DNS-resolution check
+(`TG03-dns-resolves-private`) directly into its one synchronous `classify()` instead of needing a
+separate async entry point -- see [What it does](#what-it-does) above. Every other row applies
+equally to both the TypeScript and Python distributions.
+
+|                            | **toolgovern**                                                      | [Microsoft Agent Governance Toolkit](https://github.com/microsoft/agent-governance-toolkit)     | [NVIDIA NeMo Relay](https://github.com/NVIDIA/NeMo-Relay)                     | [LangGraph human-in-the-loop](https://docs.langchain.com/oss/python/langchain/human-in-the-loop) |
+| -------------------------- | ------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
+| What it actually gates     | Tool calls, pre-execution, against a built-in rule set              | Tool calls, messages, and delegation, pre-execution, against policy you author (YAML/OPA/Cedar) | Tool and LLM calls via pre-tool hooks -- coverage depends on the host agent   | A single tool call, paused for a human decision -- no automated risk classification              |
+| Rules out of the box       | 36 (this Python port), across 6 categories, zero config             | None shipped -- you write the policy                                                            | None shipped -- pre-tool hooks call your own logic, not a built-in classifier | None -- you decide per call                                                                      |
+| Per-agent scope narrowing  | Yes -- a sub-agent can never exceed its coordinator's granted scope | Yes -- documented delegation-chain narrowing and a 4-ring privilege model                       | Not publicly documented                                                       | No                                                                                               |
+| Tamper-evident audit trail | Yes -- signed, hash-chained local JSONL                             | Yes -- Merkle-audit-backed, 157 conformance tests just for the audit layer                      | No -- raw JSONL trajectory export (ATOF/ATIF format), not signed              | No                                                                                               |
+| Hosted component required  | No, never                                                           | No -- self-hosted by design, Azure integration is optional                                      | No -- local CLI gateway                                                       | No for the OSS library; LangGraph's own hosted server runtime is separately licensed             |
+| License                    | Apache 2.0                                                          | MIT                                                                                             | Apache 2.0                                                                    | MIT                                                                                              |
+
+Two things worth repeating from the full narrative rather than leaving implicit: Microsoft's
+Agent Governance Toolkit already matches or exceeds this project on scoping and audit-trail
+maturity (a formal delegation-chain spec, 157 conformance tests just for its audit layer) -- this
+table is not a claim that toolgovern beats AGT. And NeMo Relay / LangGraph HITL are doing a
+genuinely different job, not a weaker version of the same one -- listing them here is about scope,
+not a claim of superiority at the task each of them is actually built for. Read the [full
+comparison and both honest
+caveats](https://github.com/RudrenduPaul/toolgovern#how-it-compares-to-other-agent-governance-projects)
+in the project README before deciding what you need.
+
 ## CLI
 
 ```bash
@@ -236,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
@@ -285,6 +352,56 @@ pytest
 
 Report a vulnerability per the project's [`SECURITY.md`](https://github.com/RudrenduPaul/toolgovern/blob/main/SECURITY.md); please don't open a public issue for one.
 
+## FAQ
+
+**What does toolgovern do?**
+It's a runtime gate that checks every tool call an AI agent makes -- shell, filesystem, network,
+credential access -- against a 36-rule classifier before the call executes, not after.
+`govern_tool()` wraps any `ToolDefinition(name, execute)` you already have and runs each call
+through the classifier, the per-agent scope registry, and (if wired in) the signed trace writer
+before your real `execute()` ever fires. See [Why this exists](#why-this-exists) and [What it
+does](#what-it-does) above for the full case.
+
+**How does this Python package differ from the npm package, if at all?**
+Functionally, barely. It ships the same 36-rule classifier (the npm/TypeScript package runs 35
+rules synchronously plus one additional async-only DNS-resolution rule, landing at 36 checks total
+through its `classifyAsync()` path; this Python port folds that same DNS check into its one
+synchronous `classify()` instead, so it's 36 either way), the same intersection-only scope
+registry, the same durable approval registry, the same MCP-server trust boundary, and the same
+signed trace format -- a genuine Python port, not a wrapper around the Node binary. Two real gaps
+today: `toolgovern-cli init [oma|langgraph]` (the npm CLI's TypeScript integration-file scaffolder)
+isn't ported, since it generates a `.ts` file importing JS/TS-only packages; and the two npm-only
+integration packages (`toolgovern-integration-oma`, `toolgovern-integration-langgraph` for
+LangGraph.js) have no Python equivalent by design -- wire `govern_tool()` directly into your
+Python framework's own call site instead. See [CLI](#cli) and [Framework
+integrations](#framework-integrations) above.
+
+**Does it need API keys or an account?**
+No. Nothing in this package calls out to a hosted service. No call payload, argument, trace
+content, or policy leaves your process unless code you write sends it somewhere -- there's no
+server dependency, no account, and nothing to sign up for.
+
+**Is it safe to run -- does an `allow` decision mean a tool call is safe?**
+Running the package itself is safe: it's a local, in-process classifier that makes no network
+calls of its own (the one exception, `TG03-dns-resolves-private`, only performs a DNS lookup of an
+argument value your own tool call passes it). But an `allow` decision is not a safety guarantee --
+it means the call was checked against the current 36-rule set and nothing fired.
+[`docs/security-model.md`](https://github.com/RudrenduPaul/toolgovern/blob/main/docs/security-model.md)
+in the main repo documents exactly what the classifier does and doesn't catch, including disclosed
+obfuscation techniques it can still miss.
+
+**How do I use it from an agent?**
+Five real Python framework integrations exist in the main repo -- LangGraph (using the real
+`wrap_tool_call` `ToolNode` parameter), CrewAI, AutoGen, Microsoft Agent Framework, and the Claude
+Agent SDK (using its real `PreToolUse` hook) -- each installable from source (none are published to
+PyPI yet). For a framework without a dedicated integration, wrap your own tool definitions with
+`govern_tool()` directly at whatever call site your framework dispatches tool calls from. See
+[Framework integrations](#framework-integrations) above for install commands and worked examples.
+
+**Is there a hosted version of toolgovern?**
+No. Everything that exists today is in the GitHub repository, Apache 2.0, self-hosted only, for
+both the Python and TypeScript distributions.
+
 ## Links
 
 - [GitHub repository](https://github.com/RudrenduPaul/toolgovern)
@@ -298,4 +415,3 @@ Report a vulnerability per the project's [`SECURITY.md`](https://github.com/Rudr
 ## License
 
 Apache 2.0 -- see [LICENSE](../LICENSE).
-

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

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "toolgovern-cli"
-version = "0.1.2"
+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"
@@ -13,7 +13,7 @@ authors = [
   { name = "Rudrendu Paul" },
   { name = "Sourav Nandy" },
 ]
-keywords = ["security", "ai-agents", "agent-governance", "tool-calling", "runtime-security", "audit-trail", "cli", "mcp"]
+keywords = ["security", "ai-agents", "agent-governance", "tool-calling", "runtime-security", "audit-trail", "cli", "mcp", "policy-enforcement", "scope-narrowing"]
 classifiers = [
   "Development Status :: 3 - Alpha",
   "Environment :: Console",
@@ -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()