Aletheia-MCP 🛡️🔍

Aletheia-MCP (named after Aletheia, the Greek goddess/concept of truth and disclosure) is an advanced multi-agent runtime validation and execution engine. Inspired by Google DeepMind's AI Control Roadmap (June 2026), it establishes a dual-agent boundary system designed to secure autonomous LLMs executing terminal commands, modifying files, and running code.

It exposes execution capabilities through the Model Context Protocol (MCP), running untrusted agent-generated code inside a secure, containerized Docker sandbox while a real-time Supervisor Agent audits the worker's reasoning process and intercepts tool parameters before they execute.

---

Key Features

• Dual-Agent A2A Collaboration: Implements stateful worker-supervisor interaction protocols via LangGraph.
• DeepMind AI Control Audit: Intercepts the Worker's thinking trace and proposed tool arguments out-of-band, validating actions against security rules.
• Secure Dockerized Sandbox: Executes terminal instructions and script tasks in ephemeral, resource-constrained containers.
• Dynamic Security Dashboard: Built with FastAPI and real-time streaming to visualize agent reasoning, decision logs, and manual approval gates.
• OKF (Open Knowledge Format) RAG: Pulls target environment parameters and security runbooks dynamically using semantic search to guide the supervisor.

---

System Architecture

                     +---------------------------------------+
                     |            User Request               |
                     +-------------------+-------------------+
                                         |
                                         v
                     +-------------------+-------------------+
                     |           Worker Agent                |
                     |  (Generates code, runs terminal cmds)  |
                     +-------------------+-------------------+
                                         |
                                         | [Intercepts Tool Calls]
                                         v
+----------------------------------------+---------------------------------------+
|                                  Supervisor Agent                              |
|  - Reasoning Trace Auditor                                                     |
|  - Tool Call Validator (Checks payloads, paths, code safety)                   |
|  - Security Guardrail (OWASP Agentic Top 10 Scanner)                           |
+----------------------------------------+---------------------------------------+
                                         |
                       [Approved]        |        [Rejected]
                    +--------------------+--------------------+
                    |                                         |
                    v                                         v
+-------------------+-------------------+           +---------+---------+
|        Sandboxed MCP Server           |           |  Force Rollback   |
| (Dockerized execution of bash/python) |           |  & Re-planning    |
+---------------------------------------+           +-------------------+

---

Getting Started

Prerequisites

• Python 3.10+
• Docker (for containerized execution)
• Gemini API Key (set as GEMINI_API_KEY)

Setup & Run

1. Clone the repository:

   git clone https://github.com/xenoroses/aletheia-mcp.git
   cd aletheia-mcp
   

2. Install dependencies:

   pip install uv
   uv pip install -e .
   

3. Start the FastAPI dashboard and safety orchestrator:

   python -m aletheia.app
   

4. Open http://localhost:8000 to interact with the UI.

---

License

MIT License.