# ATLAS-GATE MCP (VS Code Edition)

### The Single-IDE Brokered Security Gateway for Agentic AI

[![Version](https://img.shields.io/badge/version-2.1.0-blue.svg)](https://github.com/dylanmarriner/ATLAS-GATE-MCP/releases)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org)
[![MCP](https://img.shields.io/badge/MCP-compatible-blueviolet.svg)](https://modelcontextprotocol.io)
[![License](https://img.shields.io/badge/license-MIT-green.svg)](LICENSE)

ATLAS-GATE is a Zero-Trust security gateway that enforces **"Plans are Laws"** for AI agents. This version is optimized for **VS Code**, consolidating the former dual-agent (Antigravity/Windsurf) model into a single, high-performance **MCP Broker**.

---

## 🔐 The Problem: Agentic Chaos
AI agents can write arbitrary code to any file — no pre-authorization, no audit trail, no quality enforcement. ATLAS-GATE fixes this by requiring every file write to pass through a five-gate cryptographic pipeline before a single byte reaches disk.

## 🏗️ The Solution: Brokered Architecture
Instead of managing two separate agents and servers, ATLAS-GATE now runs as a **single MCP server** that internally manages the lifecycle of your changes.

- **One Server**: `atlas-gate` handles both planning and execution.
- **One Session**: The broker maintains state, active plans, and audit logs.
- **One Config**: Simple `.vscode/mcp.json` setup.

### How it works (The Five-Gate Pipeline)
Every `write_file` call passes through five sequential gates:
1. **Schema**: Validates input structure.
2. **Plan Authority**: Ensures an active, signed plan exists in the broker session.
3. **Intent**: Requires a companion `.intent.md` explaining *why* the change is happening.
4. **Stub Detection**: AST-level blocks on `TODO`, `mock`, empty `catch`, etc.
5. **Audit Commit**: Writes to disk and appends to the hash-chained audit log.

---

## 🚀 Quickstart (VS Code)

### 1. Installation
```bash
git clone https://github.com/dylanmarriner/ATLAS-GATE-MCP.git
cd ATLAS-GATE-MCP
npm install
```

### 2. Automated Setup
Run the setup script to generate your VS Code MCP configuration:
```bash
npm run setup:vscode
```
This creates `.vscode/mcp.json` pointing to the local broker.

### 3. Verify Environment
Run the doctor script to ensure everything is ready:
```bash
npm run doctor:vscode
```

---

## 🔌 MCP Client Configuration
VS Code (with Copilot/MCP support) will now see a single server:

```json
{
  "servers": {
    "atlas-gate": {
      "command": "node",
      "args": ["/path/to/bin/atlas-gate-vscode.js"],
      "env": {
        "ATLAS_WORKSPACE_ROOT": "${workspaceFolder}",
        "ATLAS_HOST_IDE": "vscode"
      }
    }
  }
}
```

---

## ⚡ The Brokered Workflow

1. **Initialize**: Call `begin_session` with your workspace root.
2. **Plan**: Draft your plan and call `lint_plan`.
3. **Authorize**: Call `save_plan`. The broker signs the plan and locks it into the current session.
4. **Execute**: Call `write_file`. The broker automatically validates against the session-locked plan.
5. **Verify**: Call `verify_phase` to confirm the integrity of your changes.

---

## ⚙️ Key Scripts
| Command | Description |
|---|---|
| `npm run start:vscode` | Manually start the VS Code Broker |
| `npm run setup:vscode` | Generate VS Code MCP configuration |
| `npm run doctor:vscode` | Run diagnostic checks on the broker |
| `npm run test:all` | Run the full security and integration test suite |

---

## 🛡️ Governance Invariants
ATLAS-GATE enforces eight mechanical invariants (I1–I8) to ensure total auditability and code quality. From **Path Confinement** (I3) to **Zero-Stub Enforcement** (I4), the broker ensures that your AI agents remain within the guardrails you define.

---

## 🤝 Contributing
The quality bar is mechanically enforced. PRs containing `TODO`, stub implementations, or empty error handlers will be rejected by the same pipeline that governs the AI agents.

**Author**: Dylan Marriner · **Version**: 2.1.0 · **License**: MIT