aigp-mcp 1.0.0__tar.gz

aigp_mcp-1.0.0/.gitignore

@@ -0,0 +1,56 @@
+# Python
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.venv/
+.eggs/
+
+# Node
+node_modules/
+dist/
+
+# Go
+bin/
+
+# Rust
+target/
+
+# .NET
+bin/
+obj/
+
+# Java
+*.class
+out/
+
+# IDE
+.idea/
+.vscode/
+.kiro/
+*.swp
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Secrets (never commit)
+.env
+*.pem
+*.key
+*.pdf
+BACKLOG/
+patent/
+docs/.archive/
+review/
+
+# Generated navigable spec split — derived from the monoliths by
+# specification/tools/spec_split.py; the manifest + monoliths are the
+# source of truth, not this output. Same convention as Mars (spec/*/*/).
+specification/*/*/
+specification/split-index.md
+
+# Local rendering/preview site — self-contained, not part of the
+# published specification, never pushed.
+site/

aigp_mcp-1.0.0/PKG-INFO

@@ -0,0 +1,76 @@
+Metadata-Version: 2.5
+Name: aigp-mcp
+Version: 1.0.0
+Summary: AIGP governance adapter for MCP tool invocations — policy, scope, consent, evidence
+Requires-Python: >=3.10
+Provides-Extra: all
+Requires-Dist: boto3; extra == 'all'
+Provides-Extra: aws
+Requires-Dist: boto3; extra == 'aws'
+Provides-Extra: dynamodb
+Requires-Dist: boto3; extra == 'dynamodb'
+Provides-Extra: s3
+Requires-Dist: boto3; extra == 's3'
+Description-Content-Type: text/markdown
+
+# aigp-mcp
+
+AIGP governance for MCP (Model Context Protocol) tool invocations.
+
+Part of **MAIGP** — the Mediated AI Governance Protocol: a runtime consent / scope / evidence layer for AI systems. Every governed call is **CHECK**ed before it runs (policy, scope, jurisdiction, circuit-breaker) and **RECORD**ed + **TRACE**d as tamper-evident evidence after.
+
+## What it governs
+
+Governs MCP tool calls — policy, scope, consent, classification, and evidence.
+
+## Governance model
+
+This adapter maps the framework's lifecycle onto the AIGP agent-governance loop provided by [`maigp-agent-core`](https://pypi.org/project/maigp-agent-core/):
+
+| Framework event | AIGP action |
+|---|---|
+| run / invocation start | **CHECK** (`pre_invoke`) — allowed? under what authority? |
+| each model reply | token accounting (`on_model_call`) |
+| each tool / function call | tool governance (`on_tool_call`) |
+| run complete | **RECORD** + **TRACE** (`post_invoke`) |
+| failure | `on_error` (recorded, then re-raised) |
+
+
+## Install
+
+```bash
+pip install aigp-mcp
+```
+
+Pulls in [`maigp-agent-core`](https://pypi.org/project/maigp-agent-core/) (shared lifecycle) and, transitively, [`maigp-client`](https://pypi.org/project/maigp-client/).
+
+## Quick start
+
+```python
+from aigp_mcp import GovernedMCPClient, MCPGovernanceConfig
+
+config = MCPGovernanceConfig(
+    mode="ENFORCE",
+    gov_url="https://gov.example.com",
+    app_id="mcp-gateway",
+    hmac_secret="...",
+)
+governed = GovernedMCPClient(mcp_client, config)
+
+# Pre-check → execute only if allowed → post-record evidence
+result = await governed.call_tool("wiz", "listVulnerabilities",
+                                  {"severity": "HIGH"})
+```
+
+## Modes & exports
+
+`mode="ENFORCE"` blocks disallowed calls (raising `GovernanceDenied`); monitor-only modes record without blocking. Exports include `AccessDecision`, `GovernanceDenied`, and `ToolEvidence`.
+
+## Links
+
+- Protocol, specs & full adapter catalog: https://github.com/owner-spec/aigp-protocol
+- Issues: https://github.com/owner-spec/aigp-protocol/issues
+
+---
+
+License: Proprietary. © Kanjani AI Research & Causum.

aigp_mcp-1.0.0/README.md

@@ -0,0 +1,61 @@
+# aigp-mcp
+
+AIGP governance for MCP (Model Context Protocol) tool invocations.
+
+Part of **MAIGP** — the Mediated AI Governance Protocol: a runtime consent / scope / evidence layer for AI systems. Every governed call is **CHECK**ed before it runs (policy, scope, jurisdiction, circuit-breaker) and **RECORD**ed + **TRACE**d as tamper-evident evidence after.
+
+## What it governs
+
+Governs MCP tool calls — policy, scope, consent, classification, and evidence.
+
+## Governance model
+
+This adapter maps the framework's lifecycle onto the AIGP agent-governance loop provided by [`maigp-agent-core`](https://pypi.org/project/maigp-agent-core/):
+
+| Framework event | AIGP action |
+|---|---|
+| run / invocation start | **CHECK** (`pre_invoke`) — allowed? under what authority? |
+| each model reply | token accounting (`on_model_call`) |
+| each tool / function call | tool governance (`on_tool_call`) |
+| run complete | **RECORD** + **TRACE** (`post_invoke`) |
+| failure | `on_error` (recorded, then re-raised) |
+
+
+## Install
+
+```bash
+pip install aigp-mcp
+```
+
+Pulls in [`maigp-agent-core`](https://pypi.org/project/maigp-agent-core/) (shared lifecycle) and, transitively, [`maigp-client`](https://pypi.org/project/maigp-client/).
+
+## Quick start
+
+```python
+from aigp_mcp import GovernedMCPClient, MCPGovernanceConfig
+
+config = MCPGovernanceConfig(
+    mode="ENFORCE",
+    gov_url="https://gov.example.com",
+    app_id="mcp-gateway",
+    hmac_secret="...",
+)
+governed = GovernedMCPClient(mcp_client, config)
+
+# Pre-check → execute only if allowed → post-record evidence
+result = await governed.call_tool("wiz", "listVulnerabilities",
+                                  {"severity": "HIGH"})
+```
+
+## Modes & exports
+
+`mode="ENFORCE"` blocks disallowed calls (raising `GovernanceDenied`); monitor-only modes record without blocking. Exports include `AccessDecision`, `GovernanceDenied`, and `ToolEvidence`.
+
+## Links
+
+- Protocol, specs & full adapter catalog: https://github.com/owner-spec/aigp-protocol
+- Issues: https://github.com/owner-spec/aigp-protocol/issues
+
+---
+
+License: Proprietary. © Kanjani AI Research & Causum.

aigp_mcp-1.0.0/SPEC.md

@@ -0,0 +1,340 @@
+# SPEC: aigp_mcp — AIGP Adapter for MCP Tool Governance
+
+**Date:** 2026-07-09  
+**Status:** Spec  
+**Location:** `aigp-protocol/sdks/python/adapters/mcp/`  
+**Purpose:** Govern MCP tool invocations with AIGP — policy enforcement, consent gating, evidence recording.
+
+---
+
+## 1. What It Does
+
+Wraps any MCP tool call with AIGP governance:
+
+```python
+from aigp_mcp import GovernedMCPClient
+
+# Without governance (current):
+result = await mcp_client.call_tool("listVulnerabilities", {"severity": "HIGH"})
+
+# With governance (aigp_mcp):
+governed = GovernedMCPClient(mcp_client, aigp_config)
+result = await governed.call_tool("wiz", "listVulnerabilities", {"severity": "HIGH"})
+# → PRE: checks policy (is this agent allowed to call wiz tools?)
+# → PRE: checks consent (does TIER_2 consent exist for this data?)
+# → PRE: checks scope (is read:vulnerabilities in the allowed scope?)
+# → EXECUTE: calls the MCP tool
+# → POST: records AIGP evidence (who, what, when, under what authority)
+# → POST: hashes input/output for tamper detection
+# → RETURNS: result (or GovernanceDenied exception)
+```
+
+---
+
+## 2. Architecture
+
+```
+Agent
+  │
+  ▼
+aigp_mcp.GovernedMCPClient
+  │
+  ├── PRE-CHECK ──────────────────────────┐
+  │   • Policy evaluation (GOV_APP)       │
+  │   • Scope enforcement (allowed tools) │  ← AIGP governance
+  │   • Consent verification (tier check) │
+  │   • Data classification match         │
+  ├───────────────────────────────────────┘
+  │
+  ├── EXECUTE ────────────────────────────┐
+  │   • MCP Helper call_tool()            │  ← Actual tool invocation
+  ├───────────────────────────────────────┘
+  │
+  ├── POST-RECORD ────────────────────────┐
+  │   • Evidence record (trace store)     │
+  │   • Input/output hash                 │  ← AIGP evidence
+  │   • Duration, status, errors          │
+  │   • Evidence chain linkage            │
+  ├───────────────────────────────────────┘
+  │
+  ▼
+Result (or GovernanceDenied)
+```
+
+---
+
+## 3. Module Structure
+
+```
+aigp-protocol/sdks/python/adapters/mcp/
+├── pyproject.toml
+├── aigp_mcp/
+│   ├── __init__.py          # Exports: GovernedMCPClient, MCPGovernanceConfig
+│   ├── client.py            # GovernedMCPClient — wraps MCP calls
+│   ├── policy.py            # Policy evaluation (calls GOV_APP or local rules)
+│   ├── consent.py           # Consent tier verification
+│   ├── scope.py             # Scope enforcement (which tools are allowed)
+│   ├── evidence.py          # AIGP evidence recording
+│   ├── models.py            # Pydantic models (ToolInvocation, Evidence, Decision)
+│   └── config.py            # MCPGovernanceConfig
+└── tests/
+    ├── test_client.py
+    ├── test_policy.py
+    └── test_evidence.py
+```
+
+---
+
+## 4. Core API
+
+### 4.1 GovernedMCPClient
+
+```python
+class GovernedMCPClient:
+    """Wraps MCP tool calls with AIGP governance."""
+    
+    def __init__(
+        self,
+        mcp_client,                    # The actual MCP client/helper
+        config: MCPGovernanceConfig,    # Governance configuration
+    ):
+        ...
+    
+    async def call_tool(
+        self,
+        server_id: str,                # Which MCP server (e.g. "wiz")
+        tool_name: str,                # Which tool (e.g. "listVulnerabilities")
+        arguments: dict,               # Tool arguments
+        *,
+        agent_id: str = "",            # Calling agent identity
+        session_id: str = "",          # AIGP session ID (for chaining)
+        consent_reference: str = "",   # Consent record ID (if pre-obtained)
+    ) -> ToolResult:
+        """Call an MCP tool with full AIGP governance."""
+        ...
+    
+    async def list_tools(
+        self,
+        agent_id: str = "",
+        classification: str = "",
+    ) -> list[GovernedTool]:
+        """List available tools filtered by agent's permissions."""
+        ...
+    
+    async def check_access(
+        self,
+        server_id: str,
+        tool_name: str,
+        agent_id: str,
+    ) -> AccessDecision:
+        """Pre-check if an agent can call a specific tool (without calling it)."""
+        ...
+```
+
+### 4.2 MCPGovernanceConfig
+
+```python
+class MCPGovernanceConfig:
+    """Configuration for MCP governance."""
+    
+    # Governance mode
+    mode: str = "REPORT"              # REPORT | ENFORCE | TRACE
+    
+    # Policy source
+    gov_url: str = ""                 # GOV_APP URL for policy evaluation
+    local_policy: dict = {}           # Or: inline policy rules (for offline)
+    
+    # Evidence store
+    evidence_store: str = "s3"        # s3 | dynamodb | local
+    evidence_bucket: str = ""         # S3 bucket for evidence
+    
+    # Scope rules (which agents can use which servers/tools)
+    scope_rules: dict = {}
+    # Example:
+    # {
+    #   "cpg_agent_v2": {"allowed_servers": ["wiz", "aws-security-agent"], "denied_tools": []},
+    #   "graph_query_agent": {"allowed_servers": ["aws-documentation", "oscal"], "denied_tools": ["*__delete*"]},
+    #   "*": {"allowed_servers": ["aws-documentation"], "denied_tools": ["*__write*", "*__delete*"]}
+    # }
+    
+    # Classification requirements
+    classification_rules: dict = {}
+    # Example:
+    # {
+    #   "wiz": "HIGH",
+    #   "aws-documentation": "LOW",
+    #   "servicenow": "HIGH",
+    # }
+    
+    # Consent tiers
+    consent_tiers: dict = {}
+    # Example:
+    # {
+    #   "HIGH": "TIER_2",    # HIGH-classified tools need TIER_2 consent
+    #   "MEDIUM": "TIER_1",  # MEDIUM needs TIER_1
+    #   "LOW": "NONE",       # LOW needs no consent
+    # }
+```
+
+---
+
+## 5. Governance Modes
+
+| Mode | PRE-CHECK | EXECUTE | POST-RECORD | On Denial |
+|---|---|---|---|---|
+| **TRACE** | Log only (no block) | Always execute | Always record | Log warning, proceed |
+| **REPORT** | Evaluate + log | Always execute | Always record | Log violation, proceed |
+| **ENFORCE** | Evaluate + block | Only if allowed | Always record | Raise GovernanceDenied |
+
+Start with REPORT for visibility, move to ENFORCE once policies are tuned.
+
+---
+
+## 6. Evidence Record
+
+Every governed tool call produces an evidence record:
+
+```json
+{
+  "evidence_type": "MCP_TOOL_INVOCATION",
+  "evidence_id": "EVD-MCP-20260709-150000-001",
+  "timestamp": "2026-07-09T15:00:00Z",
+  
+  "identity": {
+    "agent_id": "cpg_agent_v2",
+    "session_id": "sess-abc123",
+    "delegation_chain": ["user:admin@org.com", "agent:cpg_agent_v2"]
+  },
+  
+  "action": {
+    "server_id": "wiz",
+    "tool_name": "listVulnerabilities",
+    "arguments_hash": "sha256:abc...",
+    "result_hash": "sha256:def...",
+    "status": "SUCCESS",
+    "duration_ms": 342
+  },
+  
+  "governance": {
+    "mode": "ENFORCE",
+    "policy_id": "POL-MCP-001",
+    "decision": "ALLOW",
+    "scope_check": "PASSED",
+    "classification": "HIGH",
+    "consent_tier": "TIER_2",
+    "consent_reference": "CONSENT-2026-001",
+    "data_residency": "us-east-1"
+  },
+  
+  "provenance": {
+    "aigp_version": "5.1.0",
+    "adapter": "aigp_mcp",
+    "evidence_chain_id": "CHAIN-MCP-WIZ-001",
+    "parent_evidence_id": "EVD-AGENT-20260709-145959-001"
+  }
+}
+```
+
+---
+
+## 7. Scope Enforcement Examples
+
+### Allow: CPG agent calling Wiz for vulnerability scan
+```
+Agent: cpg_agent_v2
+Server: wiz
+Tool: listVulnerabilities
+Rule: cpg_agent_v2 → allowed_servers: ["wiz"]
+Decision: ALLOW
+```
+
+### Deny: Query agent trying to write to ServiceNow
+```
+Agent: graph_query_agent
+Server: servicenow
+Tool: createIncident
+Rule: graph_query_agent → denied_tools: ["*__create*", "*__write*", "*__delete*"]
+Decision: DENY (scope violation: write operation not permitted for read-only agent)
+```
+
+### Deny: Unregistered agent calling HIGH tool
+```
+Agent: unknown_agent
+Server: wiz
+Tool: deleteAsset
+Rule: * → denied_tools: ["*__delete*"]
+Decision: DENY (destructive operation blocked by default policy)
+```
+
+---
+
+## 8. Integration with Managed/Unmanaged MCP
+
+```python
+# Unmanaged MCP (current — no governance):
+result = await mcp_helper.call_tool("wiz", "listVulnerabilities", args)
+
+# Managed MCP (with aigp_mcp):
+governed = GovernedMCPClient(mcp_helper, config)
+result = await governed.call_tool("wiz", "listVulnerabilities", args, agent_id="cpg_agent")
+```
+
+The `GovernedMCPClient` is a **drop-in wrapper**. Existing code continues to work — you just wrap the client. No changes to MCP Helper internals.
+
+For the AgentCore bridge, the wrapper sits at the bridge layer:
+
+```
+Agent → AgentCore → MCP Bridge → aigp_mcp (governance) → MCP Helper → MCP Server
+```
+
+---
+
+## 9. Package Definition
+
+```toml
+# pyproject.toml
+[project]
+name = "aigp-mcp"
+version = "1.0.0"
+description = "AIGP adapter for governed MCP tool invocations"
+requires-python = ">=3.10"
+dependencies = [
+    "maigp-client>=5.0.0",
+    "pydantic>=2.0",
+    "httpx>=0.24",
+]
+
+[project.optional-dependencies]
+s3 = ["boto3"]
+```
+
+---
+
+## 10. Implementation Estimate
+
+| Task | Effort |
+|---|---|
+| `client.py` (GovernedMCPClient) | 1 day |
+| `policy.py` (GOV_APP integration + local rules) | 1 day |
+| `scope.py` (agent → server/tool permission matrix) | 0.5 day |
+| `consent.py` (tier verification) | 0.5 day |
+| `evidence.py` (S3/DynamoDB evidence writer) | 1 day |
+| `config.py` + `models.py` | 0.5 day |
+| Tests | 1 day |
+| Integration with MCP Helper bridge | 1 day |
+
+**Total: ~6.5 days**
+
+---
+
+## 11. Relationship to Other Adapters
+
+| Adapter | What It Governs | Where It Sits |
+|---|---|---|
+| `aigp_strands` | Strands agent actions | Inside agent code |
+| `aigp_langchain` | LangChain tool calls | Inside agent code |
+| `aigp_agentcore` | AgentCore invocations | AgentCore middleware |
+| **`aigp_mcp`** | **MCP tool calls** | **MCP Helper bridge** |
+| `aigp_a2a` *(also missing)* | Agent-to-agent delegation | AgentCore routing |
+
+`aigp_mcp` is the **tool-layer governance** — it doesn't care about which framework called it. Whether a Strands agent, LangChain agent, or direct API call invokes an MCP tool, `aigp_mcp` governs it at the MCP Helper level.

aigp_mcp-1.0.0/aigp_mcp/__init__.py

@@ -0,0 +1,33 @@
+"""AIGP-MCP — Governance adapter for MCP tool invocations.
+
+Wraps MCP tool calls with AIGP governance:
+- Pre-check: policy, scope, consent, classification
+- Execute: only if allowed (ENFORCE mode)
+- Post-record: evidence (who, what, when, under what authority)
+
+Usage:
+    from aigp_mcp import GovernedMCPClient, MCPGovernanceConfig
+
+    config = MCPGovernanceConfig(
+        mode="ENFORCE",
+        gov_url="https://www.cyber-ai-gov.com",
+        app_id="mcp-gateway",
+        hmac_secret="...",
+    )
+    governed = GovernedMCPClient(mcp_client, config)
+    result = await governed.call_tool("wiz", "listVulnerabilities", {"severity": "HIGH"})
+"""
+
+__version__ = "1.0.0"
+
+from .client import GovernedMCPClient
+from .config import MCPGovernanceConfig
+from .models import AccessDecision, GovernanceDenied, ToolEvidence
+
+__all__ = [
+    "GovernedMCPClient",
+    "MCPGovernanceConfig",
+    "AccessDecision",
+    "GovernanceDenied",
+    "ToolEvidence",
+]

aigp_mcp-1.0.0/aigp_mcp/client.py

@@ -0,0 +1,222 @@
+"""GovernedMCPClient — wraps MCP tool calls with AIGP governance."""
+
+from __future__ import annotations
+
+import hashlib
+import logging
+import time
+import uuid
+from typing import Any, Protocol
+
+from .config import MCPGovernanceConfig
+from .evidence import EvidenceWriter
+from .models import AccessDecision, GovernanceDenied, ToolEvidence
+from .scope import check_scope
+
+logger = logging.getLogger(__name__)
+
+
+class MCPClientProtocol(Protocol):
+    """Protocol for any MCP client that can call tools."""
+
+    async def call_tool(self, server_id: str, tool_name: str, arguments: dict) -> Any: ...
+
+
+class GovernedMCPClient:
+    """Wraps an MCP client with AIGP governance.
+
+    Every tool call goes through:
+      1. PRE: scope check, classification check, consent check
+      2. EXECUTE: actual tool call (only if allowed in ENFORCE mode)
+      3. POST: evidence record
+
+    Usage:
+        from aigp_mcp import GovernedMCPClient, MCPGovernanceConfig
+
+        config = MCPGovernanceConfig(mode="ENFORCE", evidence_store="local")
+        governed = GovernedMCPClient(mcp_client, config)
+        result = await governed.call_tool("wiz", "listVulnerabilities", {}, agent_id="cpg_agent")
+    """
+
+    def __init__(self, mcp_client: Any, config: MCPGovernanceConfig):
+        self._client = mcp_client
+        self._config = config
+        self._evidence_writer = EvidenceWriter.from_config(
+            config.evidence_store,
+            bucket=config.evidence_bucket,
+            path=config.evidence_path,
+        )
+
+    async def call_tool(
+        self,
+        server_id: str,
+        tool_name: str,
+        arguments: dict | None = None,
+        *,
+        agent_id: str = "",
+        session_id: str = "",
+        consent_reference: str = "",
+        parent_evidence_id: str = "",
+    ) -> Any:
+        """Call an MCP tool with full AIGP governance.
+
+        Args:
+            server_id: MCP server ID (e.g. "wiz")
+            tool_name: Tool name (e.g. "listVulnerabilities")
+            arguments: Tool arguments
+            agent_id: Calling agent's identity
+            session_id: AIGP session ID for chaining
+            consent_reference: Pre-obtained consent record ID
+            parent_evidence_id: Link to parent evidence (delegation chain)
+
+        Returns:
+            Tool result (passthrough from MCP server)
+
+        Raises:
+            GovernanceDenied: If ENFORCE mode and policy denies the call
+        """
+        arguments = arguments or {}
+        t0 = time.time()
+        evidence_id = f"EVD-MCP-{uuid.uuid4().hex[:12]}"
+
+        # ─── PRE-CHECK ─────────────────────────────────────────────
+        decision = self._pre_check(agent_id, server_id, tool_name, consent_reference)
+
+        if decision.decision == "DENY" and self._config.mode == "ENFORCE":
+            # Record denied evidence
+            await self._record_evidence(
+                evidence_id, agent_id, session_id, server_id, tool_name,
+                arguments, None, decision, 0, "DENIED", parent_evidence_id,
+            )
+            raise GovernanceDenied(
+                reason=decision.reason,
+                server_id=server_id,
+                tool_name=tool_name,
+                policy_id=decision.policy_id,
+            )
+
+        if decision.decision == "DENY" and self._config.mode in ("REPORT", "TRACE"):
+            logger.warning(
+                "GOVERNANCE VIOLATION (mode=%s, not blocking): %s.%s by %s — %s",
+                self._config.mode, server_id, tool_name, agent_id, decision.reason,
+            )
+
+        # ─── EXECUTE ───────────────────────────────────────────────
+        result = None
+        status = "SUCCESS"
+        try:
+            result = await self._client.call_tool(server_id, tool_name, arguments)
+        except Exception as e:
+            status = "ERROR"
+            duration_ms = int((time.time() - t0) * 1000)
+            await self._record_evidence(
+                evidence_id, agent_id, session_id, server_id, tool_name,
+                arguments, None, decision, duration_ms, status, parent_evidence_id,
+            )
+            raise
+
+        # ─── POST-RECORD ──────────────────────────────────────────
+        duration_ms = int((time.time() - t0) * 1000)
+        await self._record_evidence(
+            evidence_id, agent_id, session_id, server_id, tool_name,
+            arguments, result, decision, duration_ms, status, parent_evidence_id,
+        )
+
+        return result
+
+    async def check_access(
+        self, server_id: str, tool_name: str, agent_id: str
+    ) -> AccessDecision:
+        """Pre-check if an agent can call a tool (without calling it)."""
+        return self._pre_check(agent_id, server_id, tool_name)
+
+    def _pre_check(
+        self, agent_id: str, server_id: str, tool_name: str, consent_reference: str = ""
+    ) -> AccessDecision:
+        """Evaluate governance rules. Returns AccessDecision."""
+
+        # 1. Scope check
+        allowed, reason = check_scope(self._config, agent_id, server_id, tool_name)
+        if not allowed:
+            return AccessDecision(
+                decision="DENY", reason=reason, scope_check="FAILED",
+                classification=self._config.classification_rules.get(server_id, ""),
+            )
+
+        # 2. Classification check
+        classification = self._config.classification_rules.get(server_id, "LOW")
+        required_tier = self._config.consent_tiers.get(classification, "NONE")
+
+        # 3. Consent check (if required)
+        consent_verified = True
+        if required_tier != "NONE" and not consent_reference:
+            # In ENFORCE mode, missing consent = deny
+            if self._config.mode == "ENFORCE":
+                consent_verified = False
+                return AccessDecision(
+                    decision="DENY",
+                    reason=f"Consent tier {required_tier} required for {classification} server '{server_id}' — no consent_reference provided",
+                    scope_check="PASSED",
+                    classification=classification,
+                    consent_tier=required_tier,
+                    consent_verified=False,
+                )
+            else:
+                # REPORT/TRACE: log but allow
+                logger.warning("Consent %s required for %s but not provided (mode=%s)",
+                               required_tier, server_id, self._config.mode)
+
+        return AccessDecision(
+            decision="ALLOW",
+            scope_check="PASSED",
+            classification=classification,
+            consent_tier=required_tier,
+            consent_verified=consent_verified,
+        )
+
+    async def _record_evidence(
+        self,
+        evidence_id: str,
+        agent_id: str,
+        session_id: str,
+        server_id: str,
+        tool_name: str,
+        arguments: dict | None,
+        result: Any,
+        decision: AccessDecision,
+        duration_ms: int,
+        status: str,
+        parent_evidence_id: str,
+    ) -> None:
+        """Write evidence record."""
+        try:
+            evidence = ToolEvidence(
+                evidence_id=evidence_id,
+                agent_id=agent_id,
+                session_id=session_id,
+                server_id=server_id,
+                tool_name=tool_name,
+                arguments_hash=self._hash(arguments) if arguments else "",
+                result_hash=self._hash(result) if result else "",
+                status=status,
+                duration_ms=duration_ms,
+                mode=self._config.mode,
+                decision=decision.decision,
+                policy_id=decision.policy_id,
+                scope_check=decision.scope_check,
+                classification=decision.classification,
+                consent_tier=decision.consent_tier,
+                parent_evidence_id=parent_evidence_id,
+            )
+            await self._evidence_writer.write(evidence)
+        except Exception as e:
+            logger.warning("Evidence write failed (non-fatal): %s", e)
+
+    @staticmethod
+    def _hash(data: Any) -> str:
+        """SHA-256 hash of data for tamper detection."""
+        try:
+            serialized = str(data).encode()
+            return f"sha256:{hashlib.sha256(serialized).hexdigest()[:16]}"
+        except Exception:
+            return ""

aigp_mcp-1.0.0/aigp_mcp/config.py

@@ -0,0 +1,59 @@
+"""MCPGovernanceConfig — configuration for governed MCP tool calls."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+
+
+@dataclass
+class MCPGovernanceConfig:
+    """Configuration for MCP tool governance.
+
+    Attributes:
+        mode: Governance mode — TRACE (log only), REPORT (log + evaluate), ENFORCE (block on deny)
+        gov_url: GOV_APP URL for policy evaluation (empty = local-only)
+        app_id: AIGP application ID for this gateway
+        hmac_secret: HMAC secret for AIGP authentication
+        scope_rules: Per-agent scope rules {agent_id: {allowed_servers: [...], denied_tools: [...]}}
+        classification_rules: Per-server data classification {server_id: "HIGH"|"MEDIUM"|"LOW"}
+        consent_tiers: Classification → required consent tier mapping
+        evidence_store: Where to write evidence — "s3", "dynamodb", "local", "none"
+        evidence_bucket: S3 bucket (if evidence_store=s3)
+        evidence_path: Local path (if evidence_store=local)
+    """
+
+    # Governance mode
+    mode: str = "REPORT"  # TRACE | REPORT | ENFORCE
+
+    # AIGP connection
+    gov_url: str = ""
+    app_id: str = "mcp-gateway"
+    hmac_secret: str = ""
+
+    # Scope enforcement
+    scope_rules: dict = field(default_factory=lambda: {
+        "*": {"allowed_servers": ["*"], "denied_tools": ["*__delete*"]},
+    })
+
+    # Data classification per server
+    classification_rules: dict = field(default_factory=lambda: {
+        "wiz": "HIGH",
+        "servicenow": "HIGH",
+        "aws-security-agent": "HIGH",
+        "aws-cloudtrail": "HIGH",
+        "cribl": "MEDIUM",
+        "aws-documentation": "LOW",
+        "oscal": "LOW",
+    })
+
+    # Consent tier requirements
+    consent_tiers: dict = field(default_factory=lambda: {
+        "HIGH": "TIER_2",
+        "MEDIUM": "TIER_1",
+        "LOW": "NONE",
+    })
+
+    # Evidence storage (cloud-agnostic)
+    evidence_store: str = "none"  # s3 | dynamodb | local | none
+    evidence_bucket: str = ""
+    evidence_path: str = "./evidence"

aigp_mcp-1.0.0/aigp_mcp/evidence.py

@@ -0,0 +1,267 @@
+"""Evidence Writer — factory pattern with pluggable storage backends.
+
+Cloud-agnostic: register any storage backend. Ships with:
+  - LocalFileBackend (default, no dependencies)
+  - S3Backend (optional: pip install aigp-mcp[s3])
+  - DynamoDBBackend (optional: pip install aigp-mcp[dynamodb])
+  - LogOnlyBackend (no persistence, just logs)
+
+Extend with custom backends:
+    from aigp_mcp.evidence import EvidenceWriterFactory, EvidenceBackend
+
+    class MyCustomBackend(EvidenceBackend):
+        async def write(self, evidence_id, record): ...
+
+    EvidenceWriterFactory.register("custom", MyCustomBackend)
+    writer = EvidenceWriterFactory.create("custom", **kwargs)
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+import os
+from abc import ABC, abstractmethod
+from dataclasses import asdict
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+from .models import ToolEvidence
+
+logger = logging.getLogger(__name__)
+
+
+# ─── Abstract Base ─────────────────────────────────────────────────
+
+
+class EvidenceBackend(ABC):
+    """Abstract base for evidence storage backends."""
+
+    @abstractmethod
+    async def write(self, evidence_id: str, record: dict) -> str:
+        """Write an evidence record. Returns storage location/key."""
+        ...
+
+    @abstractmethod
+    async def read(self, evidence_id: str) -> dict | None:
+        """Read an evidence record by ID. Returns None if not found."""
+        ...
+
+
+# ─── Built-in Backends ─────────────────────────────────────────────
+
+
+class LogOnlyBackend(EvidenceBackend):
+    """No persistence — logs evidence at INFO level."""
+
+    async def write(self, evidence_id: str, record: dict) -> str:
+        logger.info("Evidence [%s]: %s.%s → %s",
+                    evidence_id, record.get("server_id"), record.get("tool_name"), record.get("decision"))
+        return evidence_id
+
+    async def read(self, evidence_id: str) -> dict | None:
+        return None
+
+
+class LocalFileBackend(EvidenceBackend):
+    """Write evidence as JSON files to local filesystem."""
+
+    def __init__(self, path: str = "./evidence"):
+        self._path = Path(path)
+        self._path.mkdir(parents=True, exist_ok=True)
+
+    async def write(self, evidence_id: str, record: dict) -> str:
+        file_path = self._path / f"{evidence_id}.json"
+        file_path.write_text(json.dumps(record, indent=2, default=str))
+        logger.info("Evidence → %s", file_path)
+        return str(file_path)
+
+    async def read(self, evidence_id: str) -> dict | None:
+        file_path = self._path / f"{evidence_id}.json"
+        if file_path.exists():
+            return json.loads(file_path.read_text())
+        return None
+
+
+class S3Backend(EvidenceBackend):
+    """Write evidence to S3. Requires: pip install aigp-mcp[s3]"""
+
+    def __init__(self, bucket: str, prefix: str = "aigp-evidence/mcp", region: str = ""):
+        self._bucket = bucket
+        self._prefix = prefix
+        self._region = region
+
+    async def write(self, evidence_id: str, record: dict) -> str:
+        import asyncio
+        import boto3
+
+        key = f"{self._prefix}/{evidence_id}.json"
+
+        def _upload():
+            kwargs = {"region_name": self._region} if self._region else {}
+            s3 = boto3.client("s3", **kwargs)
+            s3.put_object(
+                Bucket=self._bucket, Key=key,
+                Body=json.dumps(record, indent=2, default=str).encode(),
+                ContentType="application/json",
+            )
+
+        await asyncio.to_thread(_upload)
+        logger.info("Evidence → s3://%s/%s", self._bucket, key)
+        return f"s3://{self._bucket}/{key}"
+
+    async def read(self, evidence_id: str) -> dict | None:
+        import asyncio
+        import boto3
+
+        key = f"{self._prefix}/{evidence_id}.json"
+
+        def _get():
+            kwargs = {"region_name": self._region} if self._region else {}
+            s3 = boto3.client("s3", **kwargs)
+            try:
+                resp = s3.get_object(Bucket=self._bucket, Key=key)
+                return json.loads(resp["Body"].read())
+            except Exception:
+                return None
+
+        return await asyncio.to_thread(_get)
+
+
+class DynamoDBBackend(EvidenceBackend):
+    """Write evidence to DynamoDB. Requires: pip install aigp-mcp[dynamodb]"""
+
+    def __init__(self, table_name: str = "aigp-evidence", region: str = ""):
+        self._table_name = table_name
+        self._region = region
+
+    async def write(self, evidence_id: str, record: dict) -> str:
+        import asyncio
+        import boto3
+
+        def _put():
+            kwargs = {"region_name": self._region} if self._region else {}
+            ddb = boto3.resource("dynamodb", **kwargs)
+            table = ddb.Table(self._table_name)
+            table.put_item(Item={
+                "PK": f"EVIDENCE#{evidence_id}",
+                "SK": "META",
+                **{k: v for k, v in record.items() if v is not None and v != "" and v != []},
+            })
+
+        await asyncio.to_thread(_put)
+        logger.info("Evidence → DynamoDB:%s/%s", self._table_name, evidence_id)
+        return f"dynamodb://{self._table_name}/{evidence_id}"
+
+    async def read(self, evidence_id: str) -> dict | None:
+        import asyncio
+        import boto3
+
+        def _get():
+            kwargs = {"region_name": self._region} if self._region else {}
+            ddb = boto3.resource("dynamodb", **kwargs)
+            table = ddb.Table(self._table_name)
+            resp = table.get_item(Key={"PK": f"EVIDENCE#{evidence_id}", "SK": "META"})
+            return resp.get("Item")
+
+        return await asyncio.to_thread(_get)
+
+
+# ─── Factory ───────────────────────────────────────────────────────
+
+
+class EvidenceWriterFactory:
+    """Factory for creating evidence storage backends.
+
+    Built-in backends: none, local, s3, dynamodb
+    Register custom backends with: EvidenceWriterFactory.register("name", MyBackend)
+    """
+
+    _registry: dict[str, type[EvidenceBackend]] = {
+        "none": LogOnlyBackend,
+        "local": LocalFileBackend,
+        "s3": S3Backend,
+        "dynamodb": DynamoDBBackend,
+    }
+
+    @classmethod
+    def register(cls, name: str, backend_class: type[EvidenceBackend]) -> None:
+        """Register a custom evidence backend.
+
+        Example:
+            class AzureBlobBackend(EvidenceBackend): ...
+            EvidenceWriterFactory.register("azure_blob", AzureBlobBackend)
+        """
+        cls._registry[name] = backend_class
+        logger.info("Registered evidence backend: %s", name)
+
+    @classmethod
+    def create(cls, backend_type: str, **kwargs) -> EvidenceBackend:
+        """Create an evidence backend by type.
+
+        Args:
+            backend_type: One of "none", "local", "s3", "dynamodb", or any registered name.
+            **kwargs: Backend-specific configuration (bucket, path, table_name, region, etc.)
+
+        Returns:
+            An EvidenceBackend instance.
+
+        Raises:
+            ValueError: If backend_type is not registered.
+        """
+        if backend_type not in cls._registry:
+            available = list(cls._registry.keys())
+            raise ValueError(
+                f"Unknown evidence backend: '{backend_type}'. "
+                f"Available: {available}. Register custom with EvidenceWriterFactory.register()"
+            )
+
+        backend_class = cls._registry[backend_type]
+
+        # Filter kwargs to only those the backend accepts
+        import inspect
+        sig = inspect.signature(backend_class.__init__)
+        valid_params = set(sig.parameters.keys()) - {"self"}
+        filtered_kwargs = {k: v for k, v in kwargs.items() if k in valid_params}
+
+        return backend_class(**filtered_kwargs)
+
+    @classmethod
+    def available(cls) -> list[str]:
+        """List all registered backend types."""
+        return list(cls._registry.keys())
+
+
+# ─── Convenience: EvidenceWriter wraps backend + serialization ─────
+
+
+class EvidenceWriter:
+    """High-level evidence writer — serializes ToolEvidence and delegates to backend."""
+
+    def __init__(self, backend: EvidenceBackend):
+        self._backend = backend
+
+    @classmethod
+    def from_config(cls, evidence_store: str, **kwargs) -> "EvidenceWriter":
+        """Create from config values.
+
+        Example:
+            writer = EvidenceWriter.from_config("s3", bucket="my-bucket", region="us-east-1")
+        """
+        backend = EvidenceWriterFactory.create(evidence_store, **kwargs)
+        return cls(backend)
+
+    async def write(self, evidence: ToolEvidence) -> str:
+        """Serialize and write evidence. Returns storage location."""
+        record = asdict(evidence)
+        return await self._backend.write(evidence.evidence_id, record)
+
+    async def read(self, evidence_id: str) -> ToolEvidence | None:
+        """Read evidence by ID."""
+        record = await self._backend.read(evidence_id)
+        if record:
+            record.pop("PK", None)
+            record.pop("SK", None)
+            return ToolEvidence(**{k: v for k, v in record.items() if hasattr(ToolEvidence, k)})
+        return None

aigp_mcp-1.0.0/aigp_mcp/models.py

@@ -0,0 +1,66 @@
+"""Models for MCP governance — decisions, evidence, errors."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+
+
+class GovernanceDenied(Exception):
+    """Raised when a tool call is blocked by governance (ENFORCE mode)."""
+
+    def __init__(self, reason: str, server_id: str = "", tool_name: str = "", policy_id: str = ""):
+        self.reason = reason
+        self.server_id = server_id
+        self.tool_name = tool_name
+        self.policy_id = policy_id
+        super().__init__(f"Tool '{server_id}.{tool_name}' denied: {reason}")
+
+
+@dataclass
+class AccessDecision:
+    """Result of a governance pre-check."""
+
+    decision: str = "ALLOW"  # ALLOW | DENY | WARN
+    reason: str = ""
+    policy_id: str = ""
+    scope_check: str = "PASSED"  # PASSED | FAILED | SKIPPED
+    classification: str = ""
+    consent_tier: str = ""
+    consent_verified: bool = True
+
+
+@dataclass
+class ToolEvidence:
+    """AIGP evidence record for a single MCP tool invocation."""
+
+    evidence_id: str = ""
+    timestamp: str = field(default_factory=lambda: datetime.now(timezone.utc).isoformat())
+
+    # Identity
+    agent_id: str = ""
+    session_id: str = ""
+    delegation_chain: list[str] = field(default_factory=list)
+
+    # Action
+    server_id: str = ""
+    tool_name: str = ""
+    arguments_hash: str = ""
+    result_hash: str = ""
+    status: str = "SUCCESS"  # SUCCESS | ERROR | DENIED
+    duration_ms: int = 0
+
+    # Governance
+    mode: str = "REPORT"
+    decision: str = "ALLOW"
+    policy_id: str = ""
+    scope_check: str = "PASSED"
+    classification: str = ""
+    consent_tier: str = ""
+    consent_reference: str = ""
+
+    # Provenance
+    aigp_version: str = "5.1.0"
+    adapter: str = "aigp_mcp"
+    evidence_chain_id: str = ""
+    parent_evidence_id: str = ""

aigp_mcp-1.0.0/aigp_mcp/scope.py

@@ -0,0 +1,46 @@
+"""Scope enforcement — determines if an agent can call a specific tool."""
+
+from __future__ import annotations
+
+import fnmatch
+
+from .config import MCPGovernanceConfig
+
+
+def check_scope(
+    config: MCPGovernanceConfig,
+    agent_id: str,
+    server_id: str,
+    tool_name: str,
+) -> tuple[bool, str]:
+    """Check if agent_id is allowed to call server_id.tool_name.
+
+    Returns:
+        (allowed: bool, reason: str)
+    """
+    # Find matching rule (specific agent first, then wildcard)
+    rule = config.scope_rules.get(agent_id) or config.scope_rules.get("*", {})
+
+    if not rule:
+        return True, "No scope rules configured (default allow)"
+
+    allowed_servers = rule.get("allowed_servers", ["*"])
+    denied_tools = rule.get("denied_tools", [])
+
+    # Check server allowlist
+    server_allowed = False
+    for pattern in allowed_servers:
+        if pattern == "*" or fnmatch.fnmatch(server_id, pattern):
+            server_allowed = True
+            break
+
+    if not server_allowed:
+        return False, f"Agent '{agent_id}' not authorized for server '{server_id}'"
+
+    # Check tool denylist
+    full_tool_name = f"{server_id}__{tool_name}"
+    for pattern in denied_tools:
+        if fnmatch.fnmatch(full_tool_name, pattern):
+            return False, f"Tool '{full_tool_name}' matches deny pattern '{pattern}'"
+
+    return True, "Scope check passed"

aigp_mcp-1.0.0/pyproject.toml

@@ -0,0 +1,20 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "aigp-mcp"
+version = "1.0.0"
+description = "AIGP governance adapter for MCP tool invocations — policy, scope, consent, evidence"
+readme = "README.md"
+requires-python = ">=3.10"
+dependencies = []
+
+[project.optional-dependencies]
+s3 = ["boto3"]
+dynamodb = ["boto3"]
+aws = ["boto3"]
+all = ["boto3"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["aigp_mcp"]

aigp_mcp-1.0.0/tests/test_scope.py

@@ -0,0 +1,53 @@
+"""Tests for the AIGP MCP adapter — scope enforcement + config (pure logic, no MCP install)."""
+
+import pytest
+
+from aigp_mcp.config import MCPGovernanceConfig
+from aigp_mcp.scope import check_scope
+
+
+def test_default_config_denies_delete_tools():
+    cfg = MCPGovernanceConfig()
+    # default wildcard rule denies *__delete*
+    allowed, reason = check_scope(cfg, "agent-1", "wiz", "delete_finding")
+    assert allowed is False
+    assert "deny pattern" in reason
+
+
+def test_default_config_allows_read_tools():
+    cfg = MCPGovernanceConfig()
+    allowed, reason = check_scope(cfg, "agent-1", "wiz", "list_findings")
+    assert allowed is True
+
+
+def test_server_allowlist_enforced():
+    cfg = MCPGovernanceConfig(scope_rules={
+        "agent-2": {"allowed_servers": ["aws-*"], "denied_tools": []},
+    })
+    ok_allowed, _ = check_scope(cfg, "agent-2", "aws-cloudtrail", "lookup")
+    bad_allowed, reason = check_scope(cfg, "agent-2", "servicenow", "create")
+    assert ok_allowed is True
+    assert bad_allowed is False and "not authorized" in reason
+
+
+def test_specific_agent_rule_overrides_wildcard():
+    cfg = MCPGovernanceConfig(scope_rules={
+        "*": {"allowed_servers": ["*"], "denied_tools": ["*__delete*"]},
+        "restricted": {"allowed_servers": ["aws-documentation"], "denied_tools": []},
+    })
+    # restricted agent may only reach aws-documentation
+    allowed, _ = check_scope(cfg, "restricted", "wiz", "list_findings")
+    assert allowed is False
+
+
+def test_no_rules_default_allow():
+    cfg = MCPGovernanceConfig(scope_rules={})
+    allowed, reason = check_scope(cfg, "any", "any-server", "any_tool")
+    assert allowed is True and "default allow" in reason
+
+
+def test_classification_defaults():
+    cfg = MCPGovernanceConfig()
+    assert cfg.classification_rules["wiz"] == "HIGH"
+    assert cfg.consent_tiers["HIGH"] == "TIER_2"
+    assert cfg.mode == "REPORT"