# outline-rbac-mcp

Role-based access plugin for [Outline](https://www.getoutline.com), built as a standalone MCP server over the Outline REST API. No changes to the Outline server required.

Each person connects with **their own Outline API key**. The plugin resolves who the key belongs to and their workspace role, then only exposes the operations that role is entitled to.

## How access is decided — the role graph

Roles are nodes in a directed graph; each role inherits every capability of the roles below it:

```
admin ──▶ member ──▶ viewer ──▶ guest
```

| Role | Adds capabilities |
|---|---|
| **guest** | view own account, read shared docs |
| **viewer** | read/search docs, list users, read comments |
| **member** | update own account, create/update/delete docs, write comments |
| **admin** | invite/remove/suspend/activate users, change roles, update any account, read audit log |

Effective permissions are resolved by walking the inheritance edges (BFS) and unioning capabilities.

## The workflow pipeline

Every tool call flows through a staged workflow — a failure at any node short-circuits the call:

```
authenticate ─▶ resolve_role ─▶ authorize ─▶ execute ─▶ audit
```

- **authenticate** — verifies the API key against `auth.info`
- **resolve_role** — reads the caller's role, resolves capabilities from the graph
- **authorize** — rejects the call if the role lacks the tool's required capability
- **execute** — proxies to the Outline REST API
- **audit** — records actor, role, tool, outcome, and per-stage timing (admins can read it via `audit_log`)

## Tools

| Tool | Requires |
|---|---|
| `whoami`, `access_graph` | `account.view_self` (all roles) |
| `search_docs`, `read_doc`, `list_users` | viewer+ |
| `update_my_account`, `create_doc`, `update_doc`, `delete_doc` | member+ |
| `invite_user`, `remove_user`, `suspend_user`, `activate_user`, `change_user_role`, `audit_log` | admin |

Denied calls return `DENIED: role "<role>" lacks capability "<capability>"`.

## Install (per user)

1. Create your API key in Outline: **Settings → API & Apps → New API key**
2. Install from the packaged tarball (or from npm once published):

```bash
npm install -g ./outline-rbac-mcp-1.0.0.tgz   # or: npm install -g outline-rbac-mcp

claude mcp add outline-rbac \
  --env OUTLINE_URL=https://outline.knowaiclub.com \
  --env OUTLINE_API_KEY=<your-personal-api-key> \
  -- outline-rbac-mcp
```

The package also ships a Claude Code plugin manifest (`.claude-plugin/plugin.json` + `.mcp.json`), so the repo can be installed as a Claude Code plugin from a marketplace; set `OUTLINE_URL` and `OUTLINE_API_KEY` in your shell environment and the plugin's MCP server picks them up.

### From source

```bash
cd outline_test && npm install

claude mcp add outline-rbac \
  --env OUTLINE_URL=https://outline.knowaiclub.com \
  --env OUTLINE_API_KEY=<your-personal-api-key> \
  -- node /path/to/outline_test/src/server.js
```

Works the same in Claude Desktop / Cursor as a stdio MCP server:

```json
{
  "mcpServers": {
    "outline-rbac": {
      "command": "node",
      "args": ["/path/to/outline_test/src/server.js"],
      "env": {
        "OUTLINE_URL": "https://outline.knowaiclub.com",
        "OUTLINE_API_KEY": "<your-personal-api-key>"
      }
    }
  }
}
```

## Smoke test

```bash
TEST_KEY=<api-key> node test/smoke.js whoami access_graph 'list_users={}'
```