# cockpit-mcp

A small, **read-only** [MCP](https://modelcontextprotocol.io) server for [Cockpit CMS](https://getcockpit.com). It lets an AI agent understand *the content behind a page* — the models, fields, and types — by asking tools, instead of fetching the whole REST API or reading docs.

Generic and reusable: point it at any Cockpit v2 instance (Core or Pro) via env vars. **Write it once, reuse in every project** — the code is generic; only `COCKPIT_URL` + `COCKPIT_TOKEN` change per project.

## Run with npx (no install)

It runs straight from GitHub — no clone, no registry:

```bash
npx -y github:Avanxo-Technology/cockpit-mcp          # latest main
npx -y github:Avanxo-Technology/cockpit-mcp#v0.1.0   # pinned to a tag
```

## Tools

| Tool | What it does |
|------|--------------|
| `list_models` | List all content models (collections & singletons) with a one-line summary. Start here. |
| `describe_model` | Field schema for one model — names, types, required, choices, linked models, nested fields. The "understand this quickly" tool. |
| `list_items` | List items for a model (Mongo-style `filter`, `sort`, `fields`, `limit`). |
| `get_item` | Fetch one item by `_id`. |
| `search` | Case-insensitive substring match on a text field. |

All tools are GET-only; the server never mutates content.

## Setup

```bash
cd cockpit-mcp
npm install
cp .env.example .env   # then fill in COCKPIT_URL and COCKPIT_TOKEN
```

Create the token in Cockpit admin: **Settings → API → add token** (a read scope is enough).

## Register with opencode / Claude (stdio)

Example MCP client config:

```json
{
  "mcpServers": {
    "cockpit": {
      "command": "npx",
      "args": ["-y", "github:Avanxo-Technology/cockpit-mcp"],
      "env": {
        "COCKPIT_URL": "http://localhost:8080",
        "COCKPIT_TOKEN": "your-token-here"
      }
    }
  }
}
```

Each project registers the same package and supplies its **own** `COCKPIT_URL` / `COCKPIT_TOKEN` — one package, reused everywhere. (For local dev against a checkout, swap `command` to `node` with the path to `src/index.js`.)

The server logs a connection/health line to **stderr** on startup (never to stdout, which carries the JSON-RPC stream).

## Compatibility

Targets **Cockpit v2 (Core & Pro)** REST API: `GET /api/content/models`, `/api/content/items/{model}`, `/api/content/item/{model}/{id}`, auth via the `api-key` header. On startup it probes `list_models`; if the URL/token is wrong it warns (auth failures surface as a clear message) and tools return errors until fixed — the server itself still starts.