# Open Automation Platform MCP Server

A Model Context Protocol (MCP) server that exposes open automation platform
capabilities to AI agents and assistants. It is the open implementation of the
AAP 2.7 **MCP server**.

Every tool call is governed the same way a human action is:

1. **Gateway auth** — platform data is read/written only through the gateway
   origin, using the caller's token.
2. **RBAC scope** — each tool requires a scope; a caller lacking it gets an
   explicit error, never a silent allow.
3. **Policy** — mutating tools (e.g. `launch_job_template`) build a
   `PolicyContext` and call the policy service first; a denial blocks the action
   before it reaches the gateway. Fail-closed if the policy service is
   unreachable.

So an agent can never exceed the caller's RBAC or bypass policy.

## Tools

| Tool | Scope | Action |
| --- | --- | --- |
| `list_job_templates` | `controller:read` | List controller job templates. |
| `list_inventories` | `controller:read` | List inventories. |
| `list_collections` | `hub:read` | List hub collections. |
| `list_eda_activations` | `eda:read` | List EDA activations. |
| `read_audit_events` | `audit:read` | Read normalized audit events. |
| `policy_dry_run` | `policy:read` | Evaluate a PolicyContext with no side effect. |
| `launch_job_template` | `controller:launch` | Launch a job template (policy-checked). |

`platform:admin` satisfies any scope.

## Protocol

Conformant JSON-RPC 2.0 MCP core — `initialize`, `tools/list`, `tools/call`,
`ping` — implemented dependency-free so the server is self-contained. It can be
swapped for the official MCP SDK without changing the tool or client layers.

Transports: newline-delimited JSON-RPC over **stdio** (the standard local MCP
transport) and an **HTTP** JSON-RPC endpoint (`POST /`, `GET /healthz`) for the
platform.

## Run

```sh
# stdio (per-agent), identity/scopes from env
GATEWAY_URL=http://awx-gateway:8080 POLICY_URL=http://policy:8181 \
MCP_AUTH_USER=agent MCP_AUTH_TEAMS=sre MCP_AUTH_SCOPES=controller:read,controller:launch,policy:read \
MCP_AUTH_TOKEN=... node src/index.mjs

# http (platform service)
MCP_TRANSPORT=http MCP_ADDR=0.0.0.0:8765 node src/index.mjs
```

## Validate

```sh
scripts/local-validation   # node --check every module + node --test
```

Zero runtime dependencies (Node 20+ built-in `fetch`, `http`, `readline`,
`node:test`). Container base and all images are public/community; no
authenticated Red Hat registry.