🛡️ JudgeGuard — Alexa+ MCP Governance Server

JudgeGuard is an autonomous AI governance gatekeeper and safety bridge developed for the Amazon Developer Hackathon 2026 (amazonappdev2026.devpost.com).

It implements a self-hosted Model Context Protocol (MCP) server over Streamable HTTP (MCP Spec 2025-11-25+) to safeguard Alexa+ agentic interactions, prevent unauthorized high-risk operations (e.g. unlocking doors, financial transactions, destructive commands), and provide verifiable policy grounding and deep semantic reasoning via AWS Bedrock.

🏆 Hackathon Tracks & Submission Mapping

Clarifications for Judges:

1. Transport Architecture: The implementation uses Streamable HTTP JSON-RPC POST requests (/mcp) for all MCP protocol operations (initialize, tools/list, tools/call). The GET endpoint provides an SSE event stream for UI telemetry and asynchronous audit events.

2. Policy Grounding Lineage: Google NotebookLM was utilized during the development phase as our research reference environment. For reproducible evaluation, the public server embeds a deterministic, verified local policy corpus derived from official hackathon rules, so judges do not require access to private notebooks or external credentials.

3. AWS Bedrock Dispatch: The repository implements live AWS Bedrock dispatch for Claude 3.5 Sonnet and Amazon Titan Text Express, while automated tests and public evaluation use a deterministic fallback when AWS credentials are unavailable.

4. Alexa+ Web Simulator: The simulator (http://127.0.0.1:8765/simulator) is our custom demonstration web application created to showcase real-time agentic workflows and the JudgeGuard HUD. It is not Amazon's internal simulator.

Related MCP server: Vector Decisions MCP Server

⚡ Quickstart: Running & Testing

1. Clone & Setup Environment

git clone https://github.com/kiza-zmaj/judgeguard-alexa-mcp.git
cd judgeguard-alexa-mcp

python3 -m venv .venv
source .venv/bin/activate

pip install -e .

2. Start the MCP Server & Web Simulator

python3 server.py

The server starts on http://127.0.0.1:8765 and serves both the Streamable HTTP MCP endpoint and the interactive Web Simulator.

3. Run Automated Verification Tests

python3 -m unittest test_server.py test_protocol.py

Test Baseline & Conformance:

• Primary Server Tests: python3 -m unittest test_server.py test_protocol.py (21 passed, 0 failures, 0 errors)

• Companion Schema Tests: pytest tests/ in judgeguard-policy-schema (6 passed, 0 failures)

• Protocol Status: MCP Streamable HTTP implementation with protocol-level regression tests

• Live AWS Bedrock Execution: Optional / environment-dependent (automated tests run against deterministic offline fallback when AWS credentials are not set)

• Environment: Python 3.12.3 on Linux x86_64 (Linux 6.8.0-101-generic)

🔌 MCP Streamable HTTP Protocol (Spec 2025-11-25+)

1. Initialize Handshake

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "initialize",
    "params": {
      "protocolVersion": "2025-11-25",
      "clientInfo": {"name": "AlexaPlusHost", "version": "1.0.0"}
    }
  }'

2. List Available Governance Tools (tools/list)

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/list"}'

3. Execute Pre-Action Verification (tools/call)

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 3,
    "method": "tools/call",
    "params": {
      "name": "judgeguard_verify_action",
      "arguments": {"action": "Unlock front door for delivery driver"}
    }
  }'

4. Evaluate Action with AWS Bedrock (Claude 3.5 Sonnet or Amazon Titan)

curl -X POST http://127.0.0.1:8765/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc": "2.0",
    "id": 4,
    "method": "tools/call",
    "params": {
      "name": "judgeguard_bedrock_evaluate",
      "arguments": {
        "action": "Adjust thermostat to 21 degrees",
        "model_id": "amazon.titan-text-express-v1"
      }
    }
  }'

📑 Hackathon Evidence & Reference Documents

• Master Submission Checklist: MASTER_SUBMISSION_CHECKLIST.md

• AWS Product Feedback: AWS_PRODUCT_FEEDBACK.md — Multi-model evaluation telemetry and feature requests.

• Engineering Friction Logs: HACKATHON_FRICTION_LOG.md — 3 detailed technical logs documenting real challenges and solutions (for the 10% judging bonus).

• Demo Video Script: DEMO_VIDEO_SCRIPT.md — 2:45 walkthrough script formatted for YouTube/Vimeo public submission.

• Open Source Companion Repo: judgeguard-policy-schema — Standalone policy definition library.

📄 License

This project is licensed under the MIT License.