sage-governance 1.0.0

package/sage/mcp_server.py

@@ -0,0 +1,459 @@
+"""
+mcp_server.py — SAGE MCP Server
+═════════════════════════════════
+Exposes 5 tools to any MCP-compatible coding agent:
+
+  1. sage_evaluate         — classify intent + full ethics evaluation
+  2. security_scan         — deterministic code security scan
+  3. intercept_file_write  — PRE-WRITE interception (the key differentiator)
+  4. audit_write           — append-only audit trail entry
+  5. report_generate       — model card generation from audit trail
+
+TRANSPORT: stdio (persistent process — NOT respawned per tool call)
+DISTRIBUTION: npm install -g sage-governance (see bin/sage.js)
+COMPATIBLE WITH: OpenCode, Cline, Claude Code, Continue, Cursor, Zed
+
+ARGUMENT 2 CLARIFICATION (for team reference)
+──────────────────────────────────────────────
+The concern "FastMCP spawns a new process per call" is INCORRECT for
+stdio transport. The host (e.g. OpenCode) launches this process ONCE
+when the MCP connection is established. It stays alive for the session.
+startup.py preloading is still correct practice — it eliminates first-
+call latency from heavy imports inside tool functions.
+
+Author: SAGE Team — Beunec Technologies, Inc. / Team SAGE (Hackathon)
+License: MIT
+"""
+
+from __future__ import annotations
+
+import hashlib
+import json
+import sys
+from datetime import datetime, timezone
+from pathlib import Path
+
+# ── startup MUST be the first import — preloads all globals ──────────────────
+from startup import AUDIT_FILE, LOGS_FILE, LOCAL_MEMORY, write_audit_entry
+
+import sage_agent
+import security_agent
+import report_gen
+
+try:
+    from mcp.server.fastmcp import FastMCP
+except ImportError:
+    print(
+        "[SAGE] FATAL: 'mcp' package not found.\n"
+        "  Run: pip install mcp\n"
+        "  Or:  pip install 'mcp[cli]'",
+        file=sys.stderr,
+    )
+    sys.exit(1)
+
+# ══════════════════════════════════════════════════════════════════════════════
+# SERVER INITIALISATION
+# ══════════════════════════════════════════════════════════════════════════════
+
+mcp = FastMCP(
+    "sage-governance",
+    instructions=(
+        "SAGE (Supervisory Agentic Governance Engine) — governance layer for agentic coding. "
+        "Always call sage_evaluate BEFORE acting on any request involving data, ML models, "
+        "or automated decisions. Always call intercept_file_write BEFORE writing any file. "
+        "Call audit_write to record developer decisions. Call report_generate to produce "
+        "a human-readable governance report."
+    ),
+)
+
+# ══════════════════════════════════════════════════════════════════════════════
+# AUDIT TRAIL STATE  (module-level, persists for the process lifetime)
+# ══════════════════════════════════════════════════════════════════════════════
+
+_session_id: str  = datetime.now(timezone.utc).strftime("%Y%m%d_%H%M%S")
+
+
+def _write_audit(entry: dict) -> str:
+    """
+    Append one JSON line to decisions.jsonl with SHA-256 chain link.
+    Delegates to write_audit_entry in startup.py to support multi-process chaining.
+    """
+    if "session_id" not in entry:
+        entry["session_id"] = _session_id
+    return write_audit_entry(entry)
+
+
+def _write_log(summary: str) -> None:
+    """Append human-readable summary to LOGS.md (append-only)."""
+    ts = datetime.now(timezone.utc).strftime("%Y-%m-%d %H:%M UTC")
+    with open(LOGS_FILE, "a", encoding="utf-8") as fh:
+        fh.write(f"\n## {ts}\n\n{summary}\n\n---\n")
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# TOOL 1 — sage_evaluate
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+@mcp.tool()
+async def sage_evaluate(
+    prompt:  str,
+    code:    str = "",
+    context: str = "",
+) -> dict:
+    """
+    SAGE primary evaluation tool.
+
+    Call this BEFORE the coding agent acts on ANY request involving:
+      • machine learning models or classifiers
+      • predictions about people (recidivism, credit, hiring, health)
+      • datasets with demographic or behavioral signals
+      • automated decision-making systems
+
+    Returns a Pydantic-validated response (always parseable):
+      • risk_level          : LOW | MEDIUM | HIGH | CRITICAL
+      • eu_ai_act_annex     : applicable EU AI Act classification or null
+      • protected_attributes: attributes detected directly
+      • proxy_attributes    : known proxy features detected
+      • fairness_options    : 3 concrete options with pros/cons/API
+      • compliance_flags    : actionable regulatory issues
+      • immediate_actions   : ordered list of required next steps
+      • requires_human_review: true when risk is HIGH or CRITICAL
+      • sage_reasoning      : 2-3 sentence explanation (LLM or fallback)
+
+    Args:
+        prompt:  The developer's original request (required)
+        code:    Optional code snippet already written
+        context: Optional dataset description or additional context
+    """
+    result      = sage_agent.evaluate(prompt=prompt, code=code, context=context)
+    result_dict = result.model_dump()
+
+    entry_hash = _write_audit({
+        "event_type":           "sage_evaluate",
+        "intent_summary":       result.intent_summary,
+        "domain":               result.detected_domain,
+        "risk_level":           result.risk_level,
+        "eu_ai_act_annex":      result.eu_ai_act_annex,
+        "protected_attributes": result.protected_attributes,
+        "proxy_attributes":     result.proxy_attributes,
+        "compliance_flags":     result.compliance_flags,
+        "regulations":          result.regulations,
+        "udhr_articles":        result.udhr_articles,
+        "requires_human_review": result.requires_human_review,
+        "fairness_impossibility": result.fairness_impossibility,
+    })
+    result_dict["audit_entry_hash"] = entry_hash
+
+    _write_log(
+        f"**SAGE Evaluate** — Risk: `{result.risk_level}` | "
+        f"Domain: `{result.detected_domain}`\n\n"
+        f"**Prompt:** {prompt[:200]}\n\n"
+        f"**EU AI Act:** {result.eu_ai_act_annex or 'Not classified as high-risk'}\n\n"
+        f"**Protected attributes:** "
+        f"{', '.join(f'`{a}`' for a in result.protected_attributes) or 'none detected'}\n\n"
+        f"**SAGE reasoning:** {result.sage_reasoning}"
+    )
+
+    return result_dict
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# TOOL 2 — security_scan
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+@mcp.tool()
+async def security_scan(
+    code:     str,
+    filepath: str = "",
+    context:  str = "",
+) -> dict:
+    """
+    Full deterministic security scan of generated code.
+
+    Detects (in severity order P0–P4):
+      P0 — API keys / secrets hardcoded; biometric/medical PII; protected attrs
+      P1 — Government ID PII; geolocation; major compliance gaps
+      P2 — Proxy discrimination risk; black-box model; missing fairness metrics
+      P3 — Encoding choices; data quality; model serialization gaps
+
+    Returns:
+      • passed          : true only when zero P0/P1 findings
+      • highest_severity: P0|P1|P2|P3|P4|PASS
+      • findings        : list of findings sorted by severity
+      • summary         : human-readable verdict string
+
+    Args:
+        code:     Code content to scan
+        filepath: Optional path for audit trail reference
+        context:  Optional context (framework, dataset, purpose)
+    """
+    report = security_agent.scan(code)
+
+    findings_dicts = [f.to_dict() for f in report.findings]
+    top = report.top_finding()
+
+    _write_audit({
+        "event_type":               "security_scan",
+        "filepath":                 filepath,
+        "total_findings":           report.total_findings,
+        "highest_severity":         report.highest_severity,
+        "protected_attributes_found": report.protected_attributes_found,
+        "secrets_found_count":      len(report.secrets_found),
+        "passed":                   report.passed,
+        "highest_risk_finding": {
+            "severity":    top.severity,
+            "category":    top.category,
+            "description": top.description,
+        } if top else None,
+    })
+
+    verdict = "✅ PASSED" if report.passed else "❌ BLOCKED"
+    return {
+        "passed":           report.passed,
+        "total_findings":   report.total_findings,
+        "highest_severity": report.highest_severity,
+        "protected_attributes_found": report.protected_attributes_found,
+        "findings":         findings_dicts,
+        "summary": (
+            f"{verdict} — {report.total_findings} finding(s), "
+            f"highest severity: {report.highest_severity}"
+        ),
+    }
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# TOOL 3 — intercept_file_write  (THE KEY DIFFERENTIATOR)
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+@mcp.tool()
+async def intercept_file_write(
+    filepath: str,
+    code:     str,
+    context:  str = "",
+) -> dict:
+    """
+    CRITICAL — Call this BEFORE writing ANY file to disk.
+
+    SAGE scans the code before it touches the filesystem.
+    This is the only governance tool that blocks at the point of action,
+    not after the fact.
+
+    Behaviour:
+      • Zero P0/P1 findings → auto-approves, logs silently, returns approved=true
+      • P0/P1 found → BLOCKS write, surfaces the single highest-risk finding,
+        returns approved=false with 3 explicit developer choices
+
+    Developer choices (pass back via audit_write):
+      • "accept_as_is"      — write file unchanged; risk accepted and logged
+      • "apply_suggestion"  — apply SAGE's recommended fix before writing
+      • "reject"            — discard this code; revise the approach
+
+    Args:
+        filepath: Target file path being written
+        code:     Complete code content about to be written
+        context:  Optional context (framework, dataset purpose)
+    """
+    report = security_agent.scan(code)
+
+    # ── Auto-approve path ────────────────────────────────────────────────────
+    if report.passed:
+        _write_audit({
+            "event_type":     "file_write_intercepted",
+            "filepath":       filepath,
+            "decision":       "auto_approved",
+            "total_findings": report.total_findings,
+            "highest_severity": report.highest_severity,
+        })
+        return {
+            "approved": True,
+            "decision": "auto_approved",
+            "findings": [f.to_dict() for f in report.findings],
+            "message":  f"✅ SAGE approved write to `{filepath}` — no P0/P1 issues detected.",
+        }
+
+    # ── Block path ───────────────────────────────────────────────────────────
+    top = report.top_finding()
+
+    audit_data = {
+        "event_type":     "file_write_intercepted",
+        "filepath":       filepath,
+        "decision":       "blocked_pending_developer_action",
+        "total_findings": report.total_findings,
+        "highest_risk_finding": {
+            "severity":    top.severity,
+            "category":    top.category,
+            "line_number": top.line_number,
+            "snippet":     top.snippet,
+            "description": top.description,
+            "fix":         top.fix,
+            "regulation":  top.regulation,
+        } if top else None,
+        "audit_pending": True,
+    }
+    _write_audit(audit_data)
+
+    _write_log(
+        f"**⛔ File Write Intercepted:** `{filepath}`\n\n"
+        f"- Severity: `{top.severity}`\n"
+        f"- Category: `{top.category}`\n"
+        f"- Line {top.line_number}: `{top.snippet[:80]}`\n"
+        f"- Issue: {top.description}\n"
+        f"- Regulation: {top.regulation}"
+    )
+
+    return {
+        "approved":        False,
+        "requires_action": True,
+        "filepath":        filepath,
+        "total_findings":  report.total_findings,
+        "highest_risk": {
+            "severity":       top.severity,
+            "category":       top.category,
+            "line_number":    top.line_number,
+            "code_snippet":   top.snippet,
+            "risk_description": top.description,
+            "suggested_fix":  top.fix,
+            "regulation":     top.regulation,
+        },
+        "developer_choices": [
+            "accept_as_is — write file unchanged (risk accepted and logged in audit trail)",
+            "apply_suggestion — apply SAGE's suggested fix before writing",
+            "reject — discard this code and revise the approach",
+        ],
+        "instruction": (
+            f"⛔ SAGE has BLOCKED write to `{filepath}`. "
+            f"Severity: {top.severity}. "
+            f"You MUST call audit_write with your developer_choice before proceeding. "
+            f"Total findings: {report.total_findings}."
+        ),
+        "audit_pending": True,
+    }
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# TOOL 4 — audit_write
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+@mcp.tool()
+async def audit_write(
+    event_type:       str,
+    developer_choice: str = "",
+    choice_reasoning: str = "",
+    filepath:         str = "",
+    extra_data:       dict = {},
+) -> dict:
+    """
+    Records a developer decision in the append-only audit trail.
+
+    Required after intercept_file_write when approved=false.
+    Also use to record any governance decision (fairness option selection,
+    DPIA acknowledgement, human review escalation).
+
+    The audit trail is append-only — entries can be added but never deleted
+    or modified via this tool.
+
+    Args:
+        event_type:       Type of event (e.g. "fairness_option_selected",
+                          "file_write_decision", "human_review_escalated")
+        developer_choice: What the developer chose
+        choice_reasoning: Optional explanation of the choice
+        filepath:         Optional file path reference
+        extra_data:       Optional additional structured data
+    """
+    entry = {
+        "event_type":       event_type,
+        "developer_choice": developer_choice,
+        "choice_reasoning": choice_reasoning,
+        "filepath":         filepath,
+        **extra_data,
+    }
+    entry_hash = _write_audit(entry)
+
+    _write_log(
+        f"**Developer Decision** — `{event_type}`\n\n"
+        f"- Choice: `{developer_choice or 'N/A'}`\n"
+        f"- File: {filepath or 'N/A'}\n"
+        f"- Reasoning: {choice_reasoning or '_Not provided_'}"
+    )
+
+    return {
+        "recorded":         True,
+        "event_type":       event_type,
+        "developer_choice": developer_choice,
+        "entry_hash":       entry_hash,
+        "session_id":       _session_id,
+        "message": (
+            f"✅ Decision recorded in audit trail "
+            f"(hash: {entry_hash[:12]}...)"
+        ),
+    }
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# TOOL 5 — report_generate
+# ══════════════════════════════════════════════════════════════════════════════
+
+
+@mcp.tool()
+async def report_generate(
+    session_id:    str = "",
+    output_format: str = "markdown",
+) -> dict:
+    """
+    Generates a human-readable governance report from the audit trail.
+
+    Output formats:
+      • "markdown"  (default) — full model card written to reports/governance_report_*.md
+      • "summary"   — short terminal-friendly summary (no file written)
+
+    The model card follows Google Model Cards spec (Mitchell et al., 2019)
+    and covers: intended use, regulatory classification, fairness analysis,
+    security findings, compliance flags, audit integrity, and limitations.
+
+    Args:
+        session_id:    Filter to a specific session (empty = current session)
+        output_format: "markdown" or "summary"
+    """
+    sid = session_id or _session_id
+
+    if output_format == "summary":
+        content     = report_gen.generate_terminal_summary(sid)
+        report_path = None
+    else:
+        content     = report_gen.generate_model_card(sid)
+        saved_path  = report_gen.save_report(content, sid)
+        report_path = str(saved_path)
+
+    _write_audit({
+        "event_type":    "report_generated",
+        "output_format": output_format,
+        "report_path":   report_path,
+        "session_id":    sid,
+    })
+
+    return {
+        "generated":   True,
+        "session_id":  sid,
+        "report_path": report_path,
+        "content":     content,
+        "message": (
+            f"✅ Governance report generated ({output_format})"
+            + (f" → {report_path}" if report_path else "")
+        ),
+    }
+
+
+# ══════════════════════════════════════════════════════════════════════════════
+# ENTRY POINT
+# ══════════════════════════════════════════════════════════════════════════════
+
+if __name__ == "__main__":
+    print(
+        f"[SAGE] MCP server starting — session {_session_id}",
+        file=sys.stderr,
+    )
+    mcp.run(transport="stdio")