Add MCP blast radius analyzer CLI

Author: dinpd

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## Unreleased
+
+- Added `agentid mcp analyze` for scoring saved MCP `tools/list` output.
+- Added `agentid mcp diff` for detecting newly exposed tools and tool schema drift.
+- Added a sample MCP `tools/list` response for analyzer testing.
+
 ## 0.1.2
 
 - Added first-class just-in-time authorization support.

README.md

@@ -135,13 +135,21 @@ agentid explain examples/provider-mcp-support-agent.yaml
 agentid risk-score examples/provider-mcp-support-agent.yaml
 agentid generate-policy examples/provider-mcp-support-agent.yaml --target opa
 agentid audit examples/sample-tool-log.json --manifest examples/customer-support-refund-agent.yaml
+agentid mcp analyze examples/mcp-tools-list-risky.json
+agentid mcp analyze examples/mcp-tools-list-risky.json --json
+agentid mcp diff old-tools-list.json new-tools-list.json
 agentid schema > schema/agentid.schema.json
 agentid config-ui --output agentid-policy-builder.html
 agentid gateway examples/provider-mcp-support-agent.yaml --host 127.0.0.1 --port 8787
 ```
 
 `config-ui` writes a self-contained browser UI for building an AgentID manifest and starter OPA policy.
 
+`mcp analyze` scores a saved MCP `tools/list` response for tool capability
+risk, sensitive arguments, likely blast radius, and remediation steps. `mcp
+diff` compares two saved `tools/list` responses to detect newly exposed tools,
+schema changes, and increased tool risk.
+
 The JSON Schema is available at [`schema/agentid.schema.json`](schema/agentid.schema.json)
 and can be emitted with `agentid schema`. Add this to a manifest for editor
 validation:
@@ -321,6 +329,8 @@ Implemented:
 - TypeScript gateway client helper
 - Reference MCP gateway adapter for `tools/list` and `tools/call`
 - MCP gateway adapter demo with mock provider server
+- MCP blast-radius analyzer CLI for saved `tools/list` output
+- MCP tool drift diff for newly exposed tools and schema changes
 - MCP gateway integration guide and enterprise/provider MCP example manifest
 - Hosted gateway-control demo with SaaS and MCP flows
 - CI checks for tests, schema validation, manifest risk, and TypeScript SDK
@@ -330,9 +340,8 @@ Next:
 - More ecommerce manifests and audit-log examples
 - MCP tool metadata import/export and tool drift detection for `tools/list`
   changes, schema changes, and newly exposed write/admin tools
-- MCP blast-radius analyzer for scoring tool capability risk, authorization
-  posture, sensitive arguments, data-flow exposure, and remediation steps from
-  saved `tools/list` output or live gateway metadata
+- MCP blast-radius analyzer improvements for authorization posture, data-flow
+  exposure, manifest snippet generation, and live gateway metadata
 - Browser/local UI for MCP analysis with scorecards, tool tables, drift views,
   blast-radius summaries, remediation checklists, and generated AgentID
   manifest snippets

agentid/cli.py

@@ -1,6 +1,7 @@
 from __future__ import annotations
 
 import argparse
+import json
 import os
 import sys
 
@@ -9,6 +10,15 @@
 from agentid.explain import explain_manifest
 from agentid.gateway import serve
 from agentid.manifest import ManifestError, load_manifest, validate_manifest
+from agentid.mcp import (
+    analysis_to_dict,
+    analyze_tools,
+    diff_to_dict,
+    diff_tools,
+    format_analysis,
+    format_diff,
+    load_tools_list,
+)
 from agentid.policy import generate_policy
 from agentid.risk import risk_label, risk_score
 from agentid.schema import schema_json
@@ -49,6 +59,16 @@ def main(argv: list[str] | None = None) -> int:
     audit_parser.add_argument("audit_log")
     audit_parser.add_argument("--manifest", required=True)
 
+    mcp_parser = subparsers.add_parser("mcp", help="Analyze MCP tool surfaces.")
+    mcp_subparsers = mcp_parser.add_subparsers(dest="mcp_command", required=True)
+    mcp_analyze_parser = mcp_subparsers.add_parser("analyze", help="Score an MCP tools/list response.")
+    mcp_analyze_parser.add_argument("tools_list")
+    mcp_analyze_parser.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+    mcp_diff_parser = mcp_subparsers.add_parser("diff", help="Compare two MCP tools/list responses for drift.")
+    mcp_diff_parser.add_argument("before")
+    mcp_diff_parser.add_argument("after")
+    mcp_diff_parser.add_argument("--json", action="store_true", help="Print machine-readable JSON.")
+
     args = parser.parse_args(argv)
 
     if args.command == "schema":
@@ -68,6 +88,26 @@ def main(argv: list[str] | None = None) -> int:
             return 2
         return 0
 
+    if args.command == "mcp":
+        try:
+            if args.mcp_command == "analyze":
+                analysis = analyze_tools(load_tools_list(args.tools_list))
+                if args.json:
+                    print(json.dumps(analysis_to_dict(analysis), indent=2))
+                else:
+                    print(format_analysis(analysis), end="")
+                return 0
+            if args.mcp_command == "diff":
+                diff = diff_tools(load_tools_list(args.before), load_tools_list(args.after))
+                if args.json:
+                    print(json.dumps(diff_to_dict(diff), indent=2))
+                else:
+                    print(format_diff(diff), end="")
+                return 0
+        except Exception as exc:
+            print(f"ERROR: failed to analyze MCP tools: {exc}", file=sys.stderr)
+            return 2
+
     try:
         manifest = load_manifest(args.manifest)
     except ManifestError as exc: