aegis-mcp-server 0.1.10 → 0.1.11

package/README.md

@@ -1,5 +1,5 @@
 # aegis-mcp-server
-
+<!-- mcp-name: io.github.cleburn/aegis-mcp -->
 **MCP enforcement layer for the [Aegis](https://github.com/cleburn/aegis-spec) agent governance specification.**
 
 The spec writes the law. The CLI generates the law. This enforces the law.
@@ -8,54 +8,65 @@ The spec writes the law. The CLI generates the law. This enforces the law.
 
 `aegis-mcp-server` is an MCP server that validates every agent action against your `.agentpolicy/` files **before** it happens. Path permissions, content scanning, role boundaries, quality gates — all enforced at runtime with zero token overhead to the agent.
 
-The agent never loads your governance files. The MCP server reads them into its own process memory and validates silently. The agent calls governed tools (`aegis_write_file`, `aegis_read_file`, etc.) and gets back either a success or a blocked response with the specific reason.
+The agent never loads your governance files. The MCP server reads them into its own process memory and validates silently. The agent calls governed tools and gets back either a success or a blocked response with the specific reason.
 
 ## Quick Start
 
 ```bash
+# Install globally
 npm install -g aegis-mcp-server
-
-# Or use npx
-npx aegis-mcp-server --project . --role default
 ```
 
-### Claude Code Configuration
+If you generated your policy with [aegis-cli](https://github.com/cleburn/aegis-cli), the `.mcp.json` connection config is already in your project root. Just install the MCP and open your agent — it connects automatically.
 
-```json
-{
-  "mcpServers": {
-    "aegis": {
-      "command": "npx",
-      "args": ["aegis-mcp-server", "--project", ".", "--role", "default"]
-    }
-  }
-}
+### First Prompt
+
+When starting a new agent session in a governed project, use this as your first prompt:
+
+```
+Call aegis_policy_summary now. This is your governance contract — it defines your
+role, your boundaries, and which tools to use. Do not read files, do not take any
+action, and do not assume your role until you have called this tool.
 ```
 
-For role-specific enforcement:
+## How It Works
+
+### Universal Mode (Default)
+
+The MCP starts without a pre-assigned role. When the agent calls `aegis_policy_summary`, it receives the list of available roles from `.agentpolicy/roles/`. The agent presents them to the user, the user picks, and the agent calls `aegis_select_role` to lock in. All enforcement uses the selected role for the rest of the session.
+
+This is the default behavior — no configuration needed beyond the `.mcp.json` that `aegis init` creates automatically.
+
+### Fixed Mode
+
+If you know which role to assign at startup:
 
 ```json
 {
   "mcpServers": {
     "aegis": {
-      "command": "npx",
-      "args": ["aegis-mcp-server", "--project", ".", "--role", "backend"]
+      "command": "aegis-mcp",
+      "args": ["--project", ".", "--role", "backend"]
     }
   }
 }
 ```
 
+The MCP locks to that role immediately. `aegis_policy_summary` returns the role's boundaries directly, skipping role selection.
+
 ## Tools
 
 | Tool | What it does | Token cost |
 |------|-------------|------------|
-| `aegis_check_permissions` | Pre-check if an operation is allowed | Tiny — just the verdict |
-| `aegis_write_file` | Write with path + content validation | Same as a normal write |
-| `aegis_read_file` | Read with path validation | Same as a normal read |
-| `aegis_delete_file` | Delete with path validation | Tiny — just the verdict |
-| `aegis_execute` | Execute a command in project root | Command output only |
+| `aegis_policy_summary` | Role boundaries and governance summary (or available roles in universal mode) | ~200 tokens |
+| `aegis_select_role` | Select a role in universal mode | Tiny |
+| `aegis_check_permissions` | Pre-check if an operation is allowed | Tiny |
+| `aegis_write_file` | Governed write with path + content validation | Same as a normal write |
+| `aegis_read_file` | Governed read with path validation | Same as a normal read |
+| `aegis_delete_file` | Governed delete with path validation | Tiny |
+| `aegis_execute` | Governed command execution | Command output only |
 | `aegis_complete_task` | Run quality gates before marking done | Gate results only |
-| `aegis_policy_summary` | Minimal role + permissions summary | ~200 tokens |
+| `aegis_request_override` | Execute a blocked action after human confirmation | Tiny |
 
 ## Zero Token Overhead
 
@@ -65,13 +76,31 @@ Aegis MCP approach: the server loads policy into its own process memory. The age
 
 ## Enforcement
 
-- **Governance boundaries** — `writable`, `read_only`, `forbidden` path lists from governance.json
+- **Governance boundaries** — `writable`, `read_only`, `forbidden` path lists
 - **Role scoping** — agents confined to their role's writable and readable paths
 - **Sensitive pattern detection** — content scanned against governance-defined patterns
-- **Cross-domain boundaries** — imports validated against shared interface rules (when configured)
+- **Cross-domain boundaries** — imports validated against shared interface rules
 - **Quality gate validation** — `pre_commit` flags mapped to `build_commands` and executed
-- **Override logging** — violations logged to append-only `overrides.jsonl`
-- **Immutable policies** — designated rules that cannot be overridden, even with human confirmation
+- **Override logging** — every blocked action logged to append-only `overrides.jsonl`
+- **Immutable policies** — designated rules that cannot be overridden, ever
+
+## Override Protocol
+
+When an action is blocked and the governance override behavior is `warn_confirm_and_log`:
+
+1. The blocked response includes an `override_token` and the specific policy violated
+2. The agent presents the violation to the user
+3. If the user confirms, the agent calls `aegis_request_override` with the token and the user's rationale
+4. The action proceeds — the override is logged with `human_confirmed: true`
+5. Normal governance resumes immediately — the override is a one-time exception
+
+Immutable policies (e.g., HIPAA compliance, audit completeness) return `override_available: false` and cannot be overridden. The user must modify the governance through `aegis init`.
+
+## Consent-Based Governance
+
+The Aegis MCP does not override the agent's native directives. It introduces itself through tool descriptions, explains why governance is active, and asks the agent to seek user permission to route write operations through Aegis tools. The user's authority is the enforcement mechanism.
+
+Native tools for reading, searching, and exploring the codebase work fine without governance gating. Only write, delete, and execute operations benefit from routing through Aegis.
 
 ## Architecture
 
@@ -81,7 +110,8 @@ Agent ──→ aegis-mcp-server ──→ File System
               ├── Loads .agentpolicy/ into process memory (once)
               ├── Watches for policy changes (auto-reload)
               ├── Validates every tool call against policy
-              └── Returns success or blocked with reason
+              ├── Returns success or blocked with override option
+              └── Logs all enforcement decisions to overrides.jsonl
 ```
 
 Three artifacts, one governance framework:

package/assets/icon.svg

@@ -0,0 +1,54 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 512 512" width="512" height="512">
+  <defs>
+    <linearGradient id="shieldGrad" x1="0%" y1="0%" x2="0%" y2="100%">
+      <stop offset="0%" stop-color="#79c0ff"/>
+      <stop offset="35%" stop-color="#58a6ff"/>
+      <stop offset="100%" stop-color="#1f6feb"/>
+    </linearGradient>
+    <clipPath id="roundedBg">
+      <rect width="512" height="512" rx="80"/>
+    </clipPath>
+  </defs>
+
+  <!-- Rounded rectangle background -->
+  <rect width="512" height="512" rx="80" fill="#0d1117"/>
+
+  <!-- Outer shield (blue filled) -->
+  <path d="
+    M 256 56
+    L 120 116
+    L 120 248
+    C 120 348 178 432 256 472
+    C 334 432 392 348 392 248
+    L 392 116
+    Z
+  " fill="url(#shieldGrad)"/>
+
+  <!-- Inner shield cutout (dark) -->
+  <path d="
+    M 256 96
+    L 152 142
+    L 152 248
+    C 152 332 200 404 256 438
+    C 312 404 360 332 360 248
+    L 360 142
+    Z
+  " fill="#0d1117" opacity="0.87"/>
+
+  <!-- Policy line 1 (top, faintest) -->
+  <line x1="196" y1="212" x2="316" y2="212" 
+        stroke="#58a6ff" stroke-width="9" stroke-linecap="round" opacity="0.45"/>
+
+  <!-- Policy line 2 (middle) -->
+  <line x1="196" y1="252" x2="316" y2="252" 
+        stroke="#58a6ff" stroke-width="9" stroke-linecap="round" opacity="0.7"/>
+
+  <!-- Policy line 3 (shorter, full) -->
+  <line x1="196" y1="292" x2="288" y2="292" 
+        stroke="#58a6ff" stroke-width="9" stroke-linecap="round" opacity="1.0"/>
+
+  <!-- Checkmark -->
+  <polyline points="270,332 290,352 330,304" 
+            fill="none" stroke="#58a6ff" stroke-width="10" 
+            stroke-linecap="round" stroke-linejoin="round"/>
+</svg>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "aegis-mcp-server",
-  "version": "0.1.10",
+  "version": "0.1.11",
   "description": "MCP enforcement layer for the Aegis agent governance specification",
   "type": "module",
   "bin": {

package/server.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
+  "name": "io.github.cleburn/aegis-mcp",
+  "description": "Runtime enforcement layer for Aegis agent governance. Validates every agent action against .agentpolicy/ files before execution. Zero token overhead.",
+  "version": "0.1.10",
+  "repository": {
+    "url": "https://github.com/cleburn/aegis-mcp",
+    "source": "github"
+  },
+  "icons": [
+    {
+      "src": "https://raw.githubusercontent.com/cleburn/aegis-mcp/main/assets/icon.png",
+      "type": "image/png",
+      "size": 128
+    }
+  ],
+  "packages": [
+    {
+      "registryType": "npm",
+      "identifier": "aegis-mcp-server",
+      "version": "0.1.10",
+      "transport": {
+        "type": "stdio"
+      }
+    }
+  ]
+}