# Hugo MCP Remote Server

Streamable HTTP MCP server that wraps the [Hugo Generator API](http://localhost:8080/swagger). Use it from Cursor (or any MCP remote client) to add and manage page schemas, records, generate markdown, build, and publish.

## Prerequisites

- Node.js 22+
- A running Hugo Generator API (`HUGO_API_BASE_URL`)

## Local development

```bash
cp .env.example .env
# edit HUGO_API_BASE_URL if needed

npm install
npm run dev
```

Server listens on `http://localhost:3100/mcp` by default.

```bash
npm run build && npm start
```

## Docker

```bash
docker compose up --build -d
```

Defaults:

| Variable | Default |
|----------|---------|
| `PORT` | `3100` |
| `HUGO_API_BASE_URL` | `http://host.docker.internal:8080` |
| `MCP_API_KEY` | _(empty — auth disabled)_ |

`extra_hosts: host.docker.internal:host-gateway` lets the container reach an API on the host machine. If the API runs in the same Compose network, set `HUGO_API_BASE_URL` to that service URL instead (e.g. `http://hugo-generator:8080`).

## Cursor MCP config

Add a remote server entry (path may vary by Cursor version):

```json
{
  "mcpServers": {
    "hugo": {
      "url": "http://localhost:3100/mcp"
    }
  }
}
```

With optional bearer auth (`MCP_API_KEY` set on the server):

```json
{
  "mcpServers": {
    "hugo": {
      "url": "http://localhost:3100/mcp",
      "headers": {
        "Authorization": "Bearer change-me"
      }
    }
  }
}
```

## Tools

| Tool | Purpose |
|------|---------|
| `health` | Upstream API health |
| `list_schemas` / `get_schema` / `upsert_schema` / `delete_schema` / `import_schema` | Schema CRUD |
| `list_records` / `get_record` / `create_record` / `list_registry` | Page records |
| `generate_page` / `generate_from_records` | Write Hugo markdown |
| `build_site` | Run Hugo CLI |
| `publish_site` | Sync `public/` to R2 via publisher |
| `list_themes` / `get_theme` / `get_selected_theme` / `import_theme` / `select_theme` / `delete_theme` | Theme library |
| `scan_theme_signals` / `suggest_theme_schemas` / `apply_theme_schemas` | Theme → schema helpers |

Typical content workflow: `list_schemas` → `create_record` → `generate_from_records` → `build_site` → `publish_site`.

**Note:** The upstream Records API supports create/list/get only (no update/delete).

## Environment

| Variable | Required | Description |
|----------|----------|-------------|
| `HUGO_API_BASE_URL` | yes | Hugo Generator API base URL (no trailing slash) |
| `PORT` | no | Listen port (default `3100`) |
| `MCP_API_KEY` | no | When set, `/mcp` requires `Authorization: Bearer <key>` |

`GET /health` on this server is always unauthenticated (for Docker healthchecks).