aegis-mcp-server 0.1.11 → 0.1.12

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (4) hide show
  1. package/LICENSE +1 -1
  2. package/README.md +100 -84
  3. package/package.json +3 -2
  4. package/server.json +11 -10
package/LICENSE CHANGED
@@ -1,6 +1,6 @@
1
1
  MIT License
2
2
 
3
- Copyright (c) 2025 Cleburn
3
+ Copyright (c) 2025 MCP Contributors
4
4
 
5
5
  Permission is hereby granted, free of charge, to any person obtaining a copy
6
6
  of this software and associated documentation files (the "Software"), to deal
package/README.md CHANGED
@@ -1,125 +1,141 @@
1
- # aegis-mcp-server
2
- <!-- mcp-name: io.github.cleburn/aegis-mcp -->
3
- **MCP enforcement layer for the [Aegis](https://github.com/cleburn/aegis-spec) agent governance specification.**
1
+ # MCP Registry
4
2
 
5
- The spec writes the law. The CLI generates the law. This enforces the law.
3
+ The MCP registry provides MCP clients with a list of MCP servers, like an app store for MCP servers.
6
4
 
7
- ## What It Does
5
+ [**📤 Publish my MCP server**](docs/guides/publishing/publish-server.md) | [**⚡️ Live API docs**](https://registry.modelcontextprotocol.io/docs) | [**👀 Ecosystem vision**](docs/explanations/ecosystem-vision.md) | 📖 **[Full documentation](./docs)**
8
6
 
9
- `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.
7
+ ## Development Status
10
8
 
11
- 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.
9
+ **2025-09-08 update**: The registry has launched in preview 🎉 ([announcement blog post](https://blog.modelcontextprotocol.io/posts/2025-09-08-mcp-registry-preview/)). While the system is now more stable, this is still a preview release and breaking changes or data resets may occur. A general availability (GA) release will follow later. We'd love your feedback in [GitHub discussions](https://github.com/modelcontextprotocol/registry/discussions/new?category=ideas) or in the [#registry-dev Discord](https://discord.com/channels/1358869848138059966/1369487942862504016) ([joining details here](https://modelcontextprotocol.io/community/communication)).
12
10
 
13
- ## Quick Start
11
+ Current key maintainers:
12
+ - **Adam Jones** (Anthropic) [@domdomegg](https://github.com/domdomegg)
13
+ - **Tadas Antanavicius** (PulseMCP) [@tadasant](https://github.com/tadasant)
14
+ - **Toby Padilla** (GitHub) [@toby](https://github.com/toby)
14
15
 
15
- ```bash
16
- # Install globally
17
- npm install -g aegis-mcp-server
18
- ```
16
+ ## Contributing
19
17
 
20
- 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.
18
+ We use multiple channels for collaboration - see [modelcontextprotocol.io/community/communication](https://modelcontextprotocol.io/community/communication).
21
19
 
22
- ### First Prompt
20
+ Often (but not always) ideas flow through this pipeline:
23
21
 
24
- When starting a new agent session in a governed project, use this as your first prompt:
22
+ - **[Discord](https://modelcontextprotocol.io/community/communication)** - Real-time community discussions
23
+ - **[Discussions](https://github.com/modelcontextprotocol/registry/discussions)** - Propose and discuss product/technical requirements
24
+ - **[Issues](https://github.com/modelcontextprotocol/registry/issues)** - Track well-scoped technical work
25
+ - **[Pull Requests](https://github.com/modelcontextprotocol/registry/pulls)** - Contribute work towards issues
25
26
 
26
- ```
27
- Call aegis_policy_summary now. This is your governance contract — it defines your
28
- role, your boundaries, and which tools to use. Do not read files, do not take any
29
- action, and do not assume your role until you have called this tool.
30
- ```
27
+ ### Quick start:
31
28
 
32
- ## How It Works
29
+ #### Pre-requisites
33
30
 
34
- ### Universal Mode (Default)
31
+ - **Docker**
32
+ - **Go 1.24.x**
33
+ - **golangci-lint v2.4.0**
35
34
 
36
- 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.
35
+ #### Running the server
37
36
 
38
- This is the default behavior — no configuration needed beyond the `.mcp.json` that `aegis init` creates automatically.
37
+ ```bash
38
+ # Start full development environment
39
+ make dev-compose
40
+ ```
39
41
 
40
- ### Fixed Mode
42
+ This starts the registry at [`localhost:8080`](http://localhost:8080) with PostgreSQL and seed data. The database uses ephemeral storage and is reset each time you restart the containers, ensuring a clean state for development and testing.
41
43
 
42
- If you know which role to assign at startup:
44
+ The setup can be configured with environment variables in [docker-compose.yml](./docker-compose.yml) - see [.env.example](./.env.example) for a reference.
43
45
 
44
- ```json
45
- {
46
- "mcpServers": {
47
- "aegis": {
48
- "command": "aegis-mcp",
49
- "args": ["--project", ".", "--role", "backend"]
50
- }
51
- }
52
- }
53
- ```
46
+ <details>
47
+ <summary>Alternative: Running a pre-built Docker image</summary>
48
+
49
+ Pre-built Docker images are automatically published to GitHub Container Registry:
54
50
 
55
- The MCP locks to that role immediately. `aegis_policy_summary` returns the role's boundaries directly, skipping role selection.
51
+ ```bash
52
+ # Run latest stable release
53
+ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest
56
54
 
57
- ## Tools
55
+ # Run latest from main branch (continuous deployment)
56
+ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main
58
57
 
59
- | Tool | What it does | Token cost |
60
- |------|-------------|------------|
61
- | `aegis_policy_summary` | Role boundaries and governance summary (or available roles in universal mode) | ~200 tokens |
62
- | `aegis_select_role` | Select a role in universal mode | Tiny |
63
- | `aegis_check_permissions` | Pre-check if an operation is allowed | Tiny |
64
- | `aegis_write_file` | Governed write with path + content validation | Same as a normal write |
65
- | `aegis_read_file` | Governed read with path validation | Same as a normal read |
66
- | `aegis_delete_file` | Governed delete with path validation | Tiny |
67
- | `aegis_execute` | Governed command execution | Command output only |
68
- | `aegis_complete_task` | Run quality gates before marking done | Gate results only |
69
- | `aegis_request_override` | Execute a blocked action after human confirmation | Tiny |
58
+ # Run specific release version
59
+ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0
70
60
 
71
- ## Zero Token Overhead
61
+ # Run development build from main branch
62
+ docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d
63
+ ```
72
64
 
73
- Traditional approach: load governance files into the agent's context window. Token cost scales with policy complexity.
65
+ **Available tags:**
66
+ - **Releases**: `latest`, `v1.0.0`, `v1.1.0`, etc.
67
+ - **Continuous**: `main` (latest main branch build)
68
+ - **Development**: `main-<date>-<sha>` (specific commit builds)
74
69
 
75
- Aegis MCP approach: the server loads policy into its own process memory. The agent calls tools and gets structured results. A project with 200 lines of governance has the same token cost as one with 20 lines. The complexity is absorbed by the server, not the agent.
70
+ </details>
76
71
 
77
- ## Enforcement
72
+ #### Publishing a server
78
73
 
79
- - **Governance boundaries** — `writable`, `read_only`, `forbidden` path lists
80
- - **Role scoping** — agents confined to their role's writable and readable paths
81
- - **Sensitive pattern detection** — content scanned against governance-defined patterns
82
- - **Cross-domain boundaries** — imports validated against shared interface rules
83
- - **Quality gate validation** — `pre_commit` flags mapped to `build_commands` and executed
84
- - **Override logging** — every blocked action logged to append-only `overrides.jsonl`
85
- - **Immutable policies** — designated rules that cannot be overridden, ever
74
+ To publish a server, we've built a simple CLI. You can use it with:
86
75
 
87
- ## Override Protocol
76
+ ```bash
77
+ # Build the latest CLI
78
+ make publisher
88
79
 
89
- When an action is blocked and the governance override behavior is `warn_confirm_and_log`:
80
+ # Use it!
81
+ ./bin/mcp-publisher --help
82
+ ```
90
83
 
91
- 1. The blocked response includes an `override_token` and the specific policy violated
92
- 2. The agent presents the violation to the user
93
- 3. If the user confirms, the agent calls `aegis_request_override` with the token and the user's rationale
94
- 4. The action proceeds — the override is logged with `human_confirmed: true`
95
- 5. Normal governance resumes immediately — the override is a one-time exception
84
+ See [the publisher guide](./docs/guides/publishing/publish-server.md) for more details.
96
85
 
97
- 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`.
86
+ #### Other commands
98
87
 
99
- ## Consent-Based Governance
88
+ ```bash
89
+ # Run lint, unit tests and integration tests
90
+ make check
91
+ ```
100
92
 
101
- 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.
93
+ There are also a few more helpful commands for development. Run `make help` to learn more, or look in [Makefile](./Makefile).
102
94
 
103
- 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.
95
+ <!--
96
+ For Claude and other AI tools: Always prefer make targets over custom commands where possible.
97
+ -->
104
98
 
105
99
  ## Architecture
106
100
 
101
+ ### Project Structure
102
+
107
103
  ```
108
- Agent ──→ aegis-mcp-server ──→ File System
109
- │
110
- ├── Loads .agentpolicy/ into process memory (once)
111
- ├── Watches for policy changes (auto-reload)
112
- ├── Validates every tool call against policy
113
- ├── Returns success or blocked with override option
114
- └── Logs all enforcement decisions to overrides.jsonl
104
+ ├── cmd/ # Application entry points
105
+ │ └── publisher/ # Server publishing tool
106
+ ├── data/ # Seed data
107
+ ├── deploy/ # Deployment configuration (Pulumi)
108
+ ├── docs/ # Documentation
109
+ ├── internal/ # Private application code
110
+ │ ├── api/ # HTTP handlers and routing
111
+ │ ├── auth/ # Authentication (GitHub OAuth, JWT, namespace blocking)
112
+ │ ├── config/ # Configuration management
113
+ │ ├── database/ # Data persistence (PostgreSQL)
114
+ │ ├── service/ # Business logic
115
+ │ ├── telemetry/ # Metrics and monitoring
116
+ │ └── validators/ # Input validation
117
+ ├── pkg/ # Public packages
118
+ │ ├── api/ # API types and structures
119
+ │ │ └── v0/ # Version 0 API types
120
+ │ └── model/ # Data models for server.json
121
+ ├── scripts/ # Development and testing scripts
122
+ ├── tests/ # Integration tests
123
+ └── tools/ # CLI tools and utilities
124
+ └── validate-*.sh # Schema validation tools
115
125
  ```
116
126
 
117
- Three artifacts, one governance framework:
127
+ ### Authentication
128
+
129
+ Publishing supports multiple authentication methods:
130
+ - **GitHub OAuth** - For publishing by logging into GitHub
131
+ - **GitHub OIDC** - For publishing from GitHub Actions
132
+ - **DNS verification** - For proving ownership of a domain and its subdomains
133
+ - **HTTP verification** - For proving ownership of a domain
118
134
 
119
- - [**aegis-spec**](https://github.com/cleburn/aegis-spec) — Writes the law
120
- - [**aegis-cli**](https://github.com/cleburn/aegis-cli) — Generates the law
121
- - **aegis-mcp-server** — Enforces the law
135
+ The registry validates namespace ownership when publishing. E.g. to publish...:
136
+ - `io.github.domdomegg/my-cool-mcp` you must login to GitHub as `domdomegg`, or be in a GitHub Action on domdomegg's repos
137
+ - `me.adamjones/my-cool-mcp` you must prove ownership of `adamjones.me` via DNS or HTTP challenge
122
138
 
123
- ## License
139
+ ## More documentation
124
140
 
125
- MIT
141
+ See the [documentation](./docs) for more details if your question has not been answered here!
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "aegis-mcp-server",
3
- "version": "0.1.11",
3
+ "version": "0.1.12",
4
4
  "description": "MCP enforcement layer for the Aegis agent governance specification",
5
5
  "type": "module",
6
6
  "bin": {
@@ -38,5 +38,6 @@
38
38
  },
39
39
  "engines": {
40
40
  "node": ">=18.0.0"
41
- }
41
+ },
42
+ "mcpName": "io.github.cleburn/aegis-mcp"
42
43
  }
package/server.json CHANGED
@@ -1,27 +1,28 @@
1
1
  {
2
2
  "$schema": "https://static.modelcontextprotocol.io/schemas/2025-09-16/server.schema.json",
3
3
  "name": "io.github.cleburn/aegis-mcp",
4
- "description": "Runtime enforcement layer for Aegis agent governance. Validates every agent action against .agentpolicy/ files before execution. Zero token overhead.",
5
- "version": "0.1.10",
4
+ "description": "Runtime governance enforcement for AI agents. Zero token overhead.",
6
5
  "repository": {
7
6
  "url": "https://github.com/cleburn/aegis-mcp",
8
7
  "source": "github"
9
8
  },
10
- "icons": [
11
- {
12
- "src": "https://raw.githubusercontent.com/cleburn/aegis-mcp/main/assets/icon.png",
13
- "type": "image/png",
14
- "size": 128
15
- }
16
- ],
9
+ "version": "0.1.11",
17
10
  "packages": [
18
11
  {
19
12
  "registryType": "npm",
13
+ "registryBaseUrl": "https://registry.npmjs.org",
20
14
  "identifier": "aegis-mcp-server",
21
- "version": "0.1.10",
15
+ "version": "0.1.11",
22
16
  "transport": {
23
17
  "type": "stdio"
24
18
  }
25
19
  }
20
+ ],
21
+ "icons": [
22
+ {
23
+ "src": "https://raw.githubusercontent.com/cleburn/aegis-mcp/main/assets/icon.png",
24
+ "type": "image/png",
25
+ "size": 128
26
+ }
26
27
  ]
27
28
  }