feat: llms.txt and llms-full.txt, openapi.json, MCP server

.gitignore

@@ -29,3 +29,7 @@ CLAUDE.md
 AGENTS.md
 codex-workflow.md
 CODING_STANDARDS.md
+
+# Generated LLM docs
+internal/infrastructure/llmdocs/generated/*
+!internal/infrastructure/llmdocs/generated/.gitkeep

Dockerfile

@@ -4,6 +4,10 @@ COPY web/package.json web/bun.lock ./
 RUN bun install --frozen-lockfile
 COPY web/ ./
 RUN bun run build-only
+WORKDIR /src
+COPY docs/ ./docs/
+COPY scripts/generate-llms.ts ./scripts/generate-llms.ts
+RUN bun scripts/generate-llms.ts
 
 FROM golang:1.27.3-alpine AS server
 ARG VERSION=dev
@@ -13,6 +17,7 @@ COPY go.mod go.sum ./
 RUN go mod download
 COPY . .
 COPY --from=web /src/internal/infrastructure/assets/dist ./internal/infrastructure/assets/dist
+COPY --from=web /src/internal/infrastructure/llmdocs/generated ./internal/infrastructure/llmdocs/generated
 RUN go build -trimpath -ldflags "-s -w -X main.version=${VERSION}" -o /out/renewcms ./cmd/server
 
 FROM alpine:3.22

Taskfile.yml

@@ -3,6 +3,7 @@ version: '3'
 vars:
   BINARY: renewcms
   DIST_DIR: internal/infrastructure/assets/dist
+  LLMS_DIR: internal/infrastructure/llmdocs/generated
   VERSION:
     sh: git describe --tags --always --dirty
   LDFLAGS: -s -w -X main.version={{.VERSION}}
@@ -32,6 +33,7 @@ tasks:
 
   dev:api:
     desc: Run the API with hot reload on :8080 (SPA not embedded)
+    deps: [build:llms]
     cmds:
       - air
 
@@ -236,17 +238,31 @@ tasks:
     cmds:
       - bun run build
 
+  build:llms:
+    desc: Generate llms.txt, llms-full.txt and openapi.json from the route catalogue and docs/ → {{.LLMS_DIR}}
+    deps: [web:install]
+    sources: [scripts/generate-llms.ts, web/src/data/apiCatalogue.ts, docs/api.md, docs/api/*.md, docs/llm/*.md, docs/configuration.md]
+    generates: ['{{.LLMS_DIR}}/llms-full.txt']
+    cmds:
+      - bun scripts/generate-llms.ts
+
   build:
     desc: Production binary for this machine → bin/{{.BINARY}}
-    deps: [build:web]
+    deps: [build:web, build:llms]
     cmds:
       - go build -trimpath -ldflags "{{.LDFLAGS}}" -o bin/{{.BINARY}}{{exeExt}} ./cmd/server
 
+  build:mcp:
+    desc: MCP server (stdio) for this machine → bin/{{.BINARY}}-mcp
+    cmds:
+      - go build -trimpath -ldflags "{{.LDFLAGS}}" -o bin/{{.BINARY}}-mcp{{exeExt}} ./cmd/mcp
+
   release:
     desc: Cross-compile and sign production binaries for all release targets → bin/ (needs RELEASE_SIGNING_KEY)
     cmds:
       - task: release:check
       - task: build:web
+      - task: build:llms
       - for: { var: RELEASE_TARGETS }
         task: build:target
         vars:

api/handlers/llms/llmsHandler.go

@@ -0,0 +1,76 @@
+package llms
+
+import (
+	"io/fs"
+	"net/http"
+	"path"
+	"strings"
+
+	"github.com/go-chi/chi/v5"
+)
+
+const (
+	versionPlaceholder = "{{VERSION}}"
+	baseURLPlaceholder = "{{BASE_URL}}"
+	pageSuffix         = ".md"
+	cacheControl       = "public, max-age=300"
+	notBuiltNotice     = "The LLM documentation was not generated for this build. Run `task build:llms`."
+)
+
+type Handler struct {
+	docs    fs.FS
+	version string
+	baseURL string
+}
+
+func NewHandler(docs fs.FS, version string, publicURL string) *Handler {
+	return &Handler{
+		docs:    docs,
+		version: version,
+		baseURL: strings.TrimRight(publicURL, "/"),
+	}
+}
+
+func (h *Handler) Register(r chi.Router) {
+	r.Get("/llms.txt", h.serve("llms.txt", "text/plain; charset=utf-8"))
+	r.Get("/llms-full.txt", h.serve("llms-full.txt", "text/plain; charset=utf-8"))
+	r.Get("/openapi.json", h.serve("openapi.json", "application/json"))
+	r.Get("/llms/{page}", h.page)
+}
+
+func (h *Handler) page(w http.ResponseWriter, r *http.Request) {
+	name := chi.URLParam(r, "page")
+	if !strings.HasSuffix(name, pageSuffix) || strings.ContainsAny(name, "/\\") {
+		h.notFound(w)
+		return
+	}
+	h.write(w, path.Join("llms", name), "text/markdown; charset=utf-8")
+}
+
+func (h *Handler) serve(name string, contentType string) http.HandlerFunc {
+	return func(w http.ResponseWriter, _ *http.Request) {
+		h.write(w, name, contentType)
+	}
+}
+
+func (h *Handler) write(w http.ResponseWriter, name string, contentType string) {
+	if h.docs == nil {
+		h.notFound(w)
+		return
+	}
+	raw, err := fs.ReadFile(h.docs, name)
+	if err != nil {
+		h.notFound(w)
+		return
+	}
+	text := strings.NewReplacer(versionPlaceholder, h.version, baseURLPlaceholder, h.baseURL).Replace(string(raw))
+	w.Header().Set("Content-Type", contentType)
+	w.Header().Set("Cache-Control", cacheControl)
+	_, _ = w.Write([]byte(text))
+}
+
+func (h *Handler) notFound(w http.ResponseWriter) {
+	w.Header().Set("Content-Type", "text/plain; charset=utf-8")
+	w.WriteHeader(http.StatusNotFound)
+	_, _ = w.Write([]byte(notBuiltNotice))
+}

api/router.go

@@ -11,6 +11,7 @@ import (
 	"RenewCMS/api/handlers/entry"
 	"RenewCMS/api/handlers/frontend"
 	"RenewCMS/api/handlers/imagevariant"
+	"RenewCMS/api/handlers/llms"
 	"RenewCMS/api/handlers/media"
 	"RenewCMS/api/handlers/settings"
 	"RenewCMS/api/handlers/site"
@@ -20,6 +21,7 @@ import (
 	"RenewCMS/api/middleware"
 	"RenewCMS/api/pkg/authtoken"
 	"RenewCMS/internal/infrastructure/config"
+	"RenewCMS/internal/infrastructure/llmdocs"
 	"encoding/json"
 	"log"
 	"net/http"
@@ -493,6 +495,7 @@ func InitRoutes(container *UseCases, settings config.Settings) *chi.Mux {
 	apiRouter.Use(middleware.CrossOriginProtection(settings.PublicURL))
 	apiRouter.Use(chimiddleware.GetHead)
 	apiRouter.Get("/healthz", GetHealth)
+	llms.NewHandler(llmdocs.Docs, settings.Version, settings.PublicURL).Register(apiRouter)
 	apiRouter.Mount("/v1", backend)
 	apiRouter.Mount("/static/uploadedImages", staticimages.NewHandler(container.OpenMediaUseCase, container.ServeVariantUseCase))
 	apiRouter.Mount("/", frontend)

cmd/mcp/main.go

@@ -0,0 +1,43 @@
+package main
+
+import (
+	"RenewCMS/internal/infrastructure/mcpserver"
+	"context"
+	"flag"
+	"fmt"
+	"log"
+	"os"
+	"os/signal"
+	"syscall"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+var version = "dev"
+
+func main() {
+	allowDestructive := flag.Bool("allow-destructive", false, "also expose delete_article and delete_media")
+	showVersion := flag.Bool("version", false, "print the version and exit")
+	flag.Parse()
+	if *showVersion {
+		fmt.Println(version)
+		return
+	}
+
+	baseURL := os.Getenv("RENEWCMS_URL")
+	apiKey := os.Getenv("RENEWCMS_API_KEY")
+	if baseURL == "" || apiKey == "" {
+		log.Fatal("RENEWCMS_URL and RENEWCMS_API_KEY must be set")
+	}
+
+	ctx, stop := signal.NotifyContext(context.Background(), os.Interrupt, syscall.SIGTERM)
+	defer stop()
+
+	server := mcpserver.New(mcpserver.NewClient(baseURL, apiKey, nil), mcpserver.Options{
+		Version:          version,
+		AllowDestructive: *allowDestructive,
+	})
+	if err := server.Run(ctx, &mcp.StdioTransport{}); err != nil {
+		log.Fatal(err)
+	}
+}

docs/llm/gotchas.md

@@ -0,0 +1,67 @@
+# Gotchas
+
+> What trips up API clients: session-only routes, error texts, rate limits and draft visibility.
+
+## Session-only routes
+
+An API key cannot call these routes. They answer `403` with a plain-text body and no JSON:
+
+```
+HTTP/1.1 403 Forbidden
+
+This action needs a real session.
+```
+
+- `/v1/api-key/*`, `/v1/system/*`, `POST /v1/auth/verify`, `DELETE /v1/auth/register`.
+- Every activity route under `/v1/activity`.
+- Writes on sites (`POST`, `PATCH`, `DELETE` under `/v1/site`, so a key cannot create a site) and on authors (`POST`, `PATCH`, `DELETE` under `/v1/author`).
+- `PATCH /v1/settings`.
+
+Variant routes under `/v1/media/{id}/variants` answer `401` to a key instead. The sign-in routes (login, logout, register, password reset) ignore a key and give no `403`.
+
+When a task needs one of these routes, stop and tell the user to do it in the app. Do not try to log in with a password.
+
+## Error texts are plain text
+
+Errors are not JSON. The body is one sentence; branch on the status code, and show the sentence to the user.
+
+| Status | Typical text |
+| --- | --- |
+| `400` | `The request cannot be processed due to a mismatch in the format of the body.` |
+| `401` | `You must be logged in to access this resource.` |
+| `403` | `This action needs a real session.`, `Only the owner can do this.`, `Only owners and admins can do this.`, `You must verify your account to access this resource.` |
+| `404` | `Article not found`, `Image not found` |
+| `429` | `Too many requests. Please try again later.` |
+
+An invalid, unknown, expired or revoked key answers `401`, even on public routes. It is never treated as anonymous.
+
+## Rate limit: 429
+
+Each key may make 120 requests per minute. The `429` response carries a `Retry-After` header holding the seconds to wait:
+
+```
+HTTP/1.1 429 Too Many Requests
+Retry-After: 46
+
+Too many requests. Please try again later.
+```
+
+Sleep for `Retry-After` seconds, then retry once. Do not retry in a tight loop. Prefer one list call with `size=100` over many single reads.
+
+## Draft versus online
+
+- Anonymous callers and unverified users only see online articles. A draft answers `404` with `Article not found`, the same as an id that does not exist.
+- A verified session or a key sees drafts as well. In lists, `counts.draft` is `0` for anonymous callers and `status=draft` answers an empty page.
+- `POST /v1/article/` always creates a draft. Publishing is a separate call, `PATCH /v1/article/{id}/publish`.
+- Sitemaps list online articles only.
+
+## Writes
+
+- A title cannot be changed after creation. Create a new article instead.
+- `PATCH /v1/article/{id}` accepts `body`, `site_id`, `author_ids` and the SEO fields only. `{}` and `null` values answer `400`, except `cover_image_id` and `social_image_id`, where `null` removes the image.
+- Request bodies are HTML even though responses default to markdown. Send `<p>` and `<h2>`, not markdown syntax, or it is stored literally.
+- Ids in paths are unsigned integers. Anything else answers `400`.
+
+## Permissions follow the key's creator
+
+A key acts as the user who made it. A key made by a user who is neither owner nor admin cannot do what only owners and admins can, and it answers `403 Only owners and admins can do this.` Check `GET /v1/auth/me` to read the role of the key.

docs/llm/recipe-articles.md

@@ -0,0 +1,81 @@
+# Recipe: create, edit and publish an article
+
+> Create a draft, replace its body, check its SEO, publish it and read it back, with an API key.
+
+Set the key once. Every request below is real output from a running instance; ids and timestamps differ on yours.
+
+```sh
+export RENEWCMS_API_KEY=rcms_...
+```
+
+## 1. Create a draft
+
+Titles are 3 to 200 characters and cannot be changed later. The request body is HTML; the response body is markdown unless you pass `?format=html` or `?format=json`.
+
+```sh
+curl -X POST "{{BASE_URL}}/v1/article/" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"title":"How we price a bathroom renovation","body":"<p>A bathroom renovation is priced by room size, plumbing changes and finish level.</p>"}'
+```
+
+Status `201`:
+
+```json
+{"id":1,"title":"How we price a bathroom renovation","body":"A bathroom renovation is priced by room size, plumbing changes and finish level.","body_format":"markdown","is_online":false,"site_id":1,"authors":[],"created_at":"2026-10-23T01:11:16.767761797+02:00","updated_at":"2026-10-23T01:11:16.767761797+02:00","slug":"how-we-price-a-bathroom-renovation","excerpt":"","seo_title":"","seo_description":"","cover_image_id":null,"cover_image_alt":"","social_title":"","social_description":"","social_image_id":null,"canonical_url":"","noindex":false,"seo_dismissed":[]}
+```
+
+The article starts offline (`is_online: false`) on the default site.
+
+## 2. Replace the body, move it to a site, set the excerpt
+
+`PATCH` takes only `body`, `site_id`, `author_ids` and the SEO fields. At least one is required; `{}` answers `400`. Send `{"body": ""}` to empty a body.
+
+```sh
+curl -X PATCH "{{BASE_URL}}/v1/article/1" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"body":"<h2>What drives the price</h2><p>Room size, plumbing changes and finish level.</p>","site_id":2,"excerpt":"What drives the price of a bathroom renovation."}'
+```
+
+Status `200`:
+
+```json
+{"id":1,"title":"How we price a bathroom renovation","body":"## What drives the price\n\nRoom size, plumbing changes and finish level.","body_format":"markdown","is_online":false,"site_id":2,"authors":[],"created_at":"2026-10-23T01:11:16.767761797+02:00","updated_at":"2026-10-23T01:11:16.771008847+02:00","slug":"how-we-price-a-bathroom-renovation","excerpt":"What drives the price of a bathroom renovation.","seo_title":"","seo_description":"","cover_image_id":null,"cover_image_alt":"","social_title":"","social_description":"","social_image_id":null,"canonical_url":"","noindex":false,"seo_dismissed":[]}
+```
+
+## 3. Check the SEO before publishing
+
+An empty JSON object checks the saved article. Pass any SEO field to check a change without saving it.
+
+```sh
+curl -X POST "{{BASE_URL}}/v1/article/1/seo/check" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{}'
+```
+
+Status `200`:
+
+```json
+{"status":"suggestions","suggestions":[{"code":"desc_short","field":"seo_description","params":{"length":47,"min":70}},{"code":"cover_none","field":"cover_image_id","params":{}},{"code":"no_au","field":"author_ids","params":{}},{"code":"short","field":"body","params":{"length":66,"min":300}}],"slug":{"available":true,"suggestion":null}}
+```
+
+Suggestions never block publishing.
+
+## 4. Publish
+
+```sh
+curl -X PATCH "{{BASE_URL}}/v1/article/1/publish" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY"
+```
+
+Status `200`, same article object with `"is_online":true`. `PATCH /v1/article/{id}/unpublish` reverses it.
+
+## 5. Read it back without credentials
+
+```sh
+curl "{{BASE_URL}}/v1/article/1?format=markdown"
+```
+
+Before step 4 this answers `404` with the text `Article not found`, because anonymous callers only see online articles.

docs/llm/recipe-media.md

@@ -0,0 +1,62 @@
+# Recipe: upload an image and attach it to an article
+
+> Upload a file with multipart form data, find it in the library and use it as an article cover.
+
+## 1. Upload
+
+Send the file in a form field named `file`. PNG, JPEG, WEBP and SVG are accepted.
+
+```sh
+curl -X POST "{{BASE_URL}}/v1/media/" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
+  -F "file=@north-wall.png"
+```
+
+Status `201`:
+
+```json
+{"id":1,"filename":"north-wall.png","url":"/static/uploadedImages/8d9be79c-5db6-4d1d-9f06-b5d1b15cb4f0.png","size":100,"content_type":"image/png","width":32,"height":32,"sha256":"7654144c6e1ee8939fa061fa8129763869fa3c2de55954053a53a965848ef09c","uploaded_by":"florian","created_at":"2026-10-23T01:11:24.228947139+02:00","used_in":0,"duplicate":false,"variant_count":0,"variant_size":0}
+```
+
+`url` is relative to the instance: the public address is `{{BASE_URL}}` followed by `url`. `duplicate: true` means the same bytes were already in the library.
+
+## 2. Find an image
+
+```sh
+curl "{{BASE_URL}}/v1/media/?size=5" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY"
+```
+
+Status `200`:
+
+```json
+{"items":[{"id":1,"filename":"north-wall.png","url":"/static/uploadedImages/8d9be79c-5db6-4d1d-9f06-b5d1b15cb4f0.png","size":100,"content_type":"image/png","width":32,"height":32,"sha256":"7654144c6e1ee8939fa061fa8129763869fa3c2de55954053a53a965848ef09c","uploaded_by":"florian","created_at":"2026-10-23T01:11:24.228947139+02:00","used_in":0,"duplicate":false,"variant_count":0,"variant_size":0}],"total":1,"page":1,"size":5,"counts":{"all":1,"unused":1,"duplicates":0}}
+```
+
+Filter with `q`, `hash`, `filter` (`all`, `unused`, `duplicates`), `sort` and `variants`.
+
+## 3. Attach it as the cover
+
+An image is attached by id. `cover_image_alt` is the alternative text.
+
+```sh
+curl -X PATCH "{{BASE_URL}}/v1/article/1" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"cover_image_id":1,"cover_image_alt":"A tiled bathroom wall"}'
+```
+
+Status `200`, the article object with `"cover_image_id":1` and `"cover_image_alt":"A tiled bathroom wall"`. Use `social_image_id` for the sharing image, and `null` to remove either image.
+
+## 4. See where an image is used
+
+```sh
+curl "{{BASE_URL}}/v1/media/1/usage" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY"
+```
+
+```json
+[{"type":"article","id":1,"title":"How we price a bathroom renovation","published":true,"fields":["cover"]}]
+```
+
+Deleting or merging an image that is in use changes those articles, so read this first.

docs/llm/recipe-pagination.md

@@ -0,0 +1,67 @@
+# Recipe: paginate, filter and choose a body format
+
+> List articles page by page, search and sort them, and read bodies as markdown, HTML or JSON blocks.
+
+`GET /v1/article/` always answers an envelope, never a bare array:
+
+```sh
+curl "{{BASE_URL}}/v1/article/?format=html&size=5&page=1" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY"
+```
+
+```json
+{"items":[{"id":1,"title":"How we price a bathroom renovation","body":"<h2>What drives the price</h2><p>Room size, plumbing changes and finish level.</p>","body_format":"html","is_online":true,"site_id":2,"authors":[],"created_at":"2026-10-23T01:11:16.767761797+02:00","updated_at":"2026-10-23T01:11:24.236138156+02:00","excerpt":"What drives the price of a bathroom renovation.","slug":"how-we-price-a-bathroom-renovation","seo_status":"suggestions","seo_suggestions":3}],"total":1,"page":1,"size":5,"counts":{"all":1,"online":1,"draft":0,"suggestions":1}}
+```
+
+In JSON, `<` and `>` are escaped as `<` and `>`; a JSON parser returns the plain characters.
+
+## Walking every page
+
+1. Request `page=1` with the `size` you want (`5`, `25`, `50` or `100`).
+2. Read `total` and `size`. The number of pages is `ceil(total / size)`.
+3. Request the next pages until `page * size >= total`. A page past the end answers `200` with `items: []`, so an empty `items` also ends the loop.
+
+Ordering is applied to the whole list before slicing and ends with the id, so pages never overlap or skip.
+
+## Filters
+
+Combine them freely.
+
+| Parameter | Example | Effect |
+| --- | --- | --- |
+| `q` | `q=grout` | Title contains the text, ignoring case and accents. Up to 200 characters. |
+| `status` | `status=draft` | `online` or `draft`. |
+| `site` | `site=renew-blog` | Only that site's articles. |
+| `seo` | `seo=suggestions` | `ready`, `suggestions` or `hidden`. |
+| `sort` | `sort=title:asc` | `title`, `status`, `created_at` or `updated_at`, then `:asc` or `:desc`. Default `updated_at:desc`. |
+
+`counts` ignores every filter, so tab totals do not move while searching. `total` follows the filters.
+
+```sh
+curl "{{BASE_URL}}/v1/article/?site=renew-blog&status=draft&sort=title:asc&q=grout" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY"
+```
+
+```json
+{"items":[{"id":2,"title":"Draft about grout","body":"x","body_format":"markdown","is_online":false,"site_id":2,"authors":[],"created_at":"2026-10-23T01:12:24.922895943+02:00","updated_at":"2026-10-23T01:12:24.926728869+02:00","excerpt":"","slug":"draft-about-grout","seo_status":"suggestions","seo_suggestions":4}],"total":1,"page":1,"size":25,"counts":{"all":2,"online":1,"draft":1,"suggestions":2}}
+```
+
+## The `format` parameter
+
+| Value | `body` | `body_format` |
+| --- | --- | --- |
+| absent or `markdown` | markdown string | `markdown` |
+| `html` | the stored HTML | `html` |
+| `json` | array of blocks | `json` |
+
+It applies to every article route, including the writes. Request bodies of `POST` and `PATCH` stay HTML whatever the format. An invalid `format` is reported before any other error.
+
+## Invalid values
+
+A bad `page`, `size`, `status`, `sort` or `seo` answers `400` with a plain-text body:
+
+```
+The request cannot be processed due to a mismatch in the format of the body.
+```
+
+Media lists paginate the same way (`GET /v1/media/?page=2&size=50`) with their own `counts`.

docs/llm/recipe-sites.md

@@ -0,0 +1,66 @@
+# Recipe: sites and sitemaps
+
+> Create a site (session only), move an article onto it and read its public sitemap.
+
+An article belongs to one site. A site has a `key` (a slug used in URLs) and a `base_url` (the public address its pages are served from).
+
+## 1. List the sites
+
+```sh
+curl "{{BASE_URL}}/v1/site/" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY"
+```
+
+```json
+[{"id":1,"name":"Default","key":"default","base_url":"http://localhost:18080","default_social_image_id":null,"default_robots":"index","locale":null,"is_default":true,"article_count":0,"site_name":"","title_template":"%title% | %site%","default_description":""}]
+```
+
+## 2. Create a site: not with a key
+
+Creating, editing, defaulting and deleting a site need a browser session from the owner. A key answers `403`:
+
+```sh
+curl -X POST "{{BASE_URL}}/v1/site/" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"name":"x","key":"x","base_url":"https://x.example"}'
+```
+
+```
+HTTP/1.1 403 Forbidden
+
+This action needs a real session.
+```
+
+Ask the owner to create the site in the app, or send the request with the owner's `jwt` cookie. With a session the same request answers `201`:
+
+```json
+{"id":2,"name":"Renew blog","key":"renew-blog","base_url":"https://blog.renew.example","default_social_image_id":null,"default_robots":"index","locale":null,"is_default":false,"article_count":0,"site_name":"","title_template":"%title% | %site%","default_description":""}
+```
+
+## 3. Put an article on the site
+
+Use the site `id` as `site_id`:
+
+```sh
+curl -X PATCH "{{BASE_URL}}/v1/article/1" \
+  -H "Authorization: Bearer $RENEWCMS_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{"site_id":2}'
+```
+
+## 4. Read the sitemap
+
+The sitemap is public and lists the online articles of one site, by its `key`:
+
+```sh
+curl "{{BASE_URL}}/v1/site/renew-blog/sitemap"
+```
+
+```json
+[{"url":"https://blog.renew.example/how-we-price-a-bathroom-renovation","modified_at":"2026-10-22T23:11:24Z","noindex":false}]
+```
+
+`url` is the site's `base_url` plus the article slug. Drafts are not listed. The response header `X-Total-Count` holds the number of entries. Page with `page` and `size` (`25`, `50`, `100` or `500`, default `100`); any other `size` answers `400`. An unknown key answers `404` with `site_not_found`.
+
+List only one site's articles with `GET /v1/article/?site=renew-blog`.

docs/llms.md

@@ -0,0 +1,22 @@
+# LLM documentation
+
+A running instance serves its own documentation for language models, versioned with the binary:
+
+| URL | Content |
+| --- | --- |
+| `/llms.txt` | Short index with links, following llmstxt.org. |
+| `/llms-full.txt` | Every page below in one file. |
+| `/llms/<page>.md` | One page: `api-reference`, `api`, `articles`, `api-keys`, `gotchas`, `recipe-articles`, `recipe-media`, `recipe-sites`, `recipe-pagination`, `configuration`. |
+| `/openapi.json` | OpenAPI 3.1 description of the routes in the catalogue. |
+
+All of them are public. `{{VERSION}}` and `{{BASE_URL}}` in the sources are replaced by the binary's version and `PUBLIC_URL` when served.
+
+## How it is built
+
+`task build:llms` runs `scripts/generate-llms.ts` (bun) and writes into `internal/infrastructure/llmdocs/generated/`, which is gitignored and embedded in the binary. `task build`, `task release`, `task dev:api` and the Docker image run it first. Without it the routes answer 404 with a notice.
+
+- The API reference and `openapi.json` come from `web/src/data/apiCatalogue.ts`, the same file the Integration page renders. Edit the catalogue, not the output.
+- `docs/api.md`, `docs/api/*.md`, the variables table of `docs/configuration.md` and every `docs/llm/*.md` are included as written. A page in `docs/llm/` starts with `# Title`, then a `> one-line summary` used by `llms.txt`.
+- Recipes in `docs/llm/` hold real responses. Re-capture them when a response shape changes.
+
+`TestRouterRoutesAreInTheCatalogue` fails when a route of `api/router.go` is missing from the catalogue. Routes still undocumented are listed in `routesNotYetInTheCatalogue` in `test/api_catalogue_drift_test.go`; remove an entry once the route is documented.

docs/mcp.md

@@ -0,0 +1,37 @@
+# MCP server
+
+`cmd/mcp` builds `renewcms-mcp`, a stdio [MCP](https://modelcontextprotocol.io) server for Claude Desktop, Claude Code, Cursor and similar clients. It is an HTTP client of the public API: it holds no database access and sends the API key as `Authorization: Bearer`, so what the key's user may do is the limit of what the model may do.
+
+Build it with `task build:mcp` (`bin/renewcms-mcp`).
+
+## Configuration
+
+| Name | Description |
+| --- | --- |
+| `RENEWCMS_URL` | Address of the instance, for example `https://cms.example`. |
+| `RENEWCMS_API_KEY` | An API key created at `/integration/api-keys`. |
+
+They belong to the MCP binary only and are not server variables.
+
+```json
+{
+  "mcpServers": {
+    "renewcms": {
+      "command": "/path/to/renewcms-mcp",
+      "env": { "RENEWCMS_URL": "https://cms.example", "RENEWCMS_API_KEY": "rcms_..." }
+    }
+  }
+}
+```
+
+## Tools
+
+`list_articles`, `get_article`, `create_article` (always a draft), `update_article_body`, `publish_article`, `check_seo`, `list_media`, `upload_media` (local `path`, or `base64` with `filename`), `list_sites`, `get_sitemap`.
+
+`--allow-destructive` adds `delete_article` and `delete_media`.
+
+Routes that need a browser session, such as creating a site, are not exposed. API errors come back as tool errors with the status and the plain-text message.
+
+## Resources and prompts
+
+The resource `renewcms://docs/llms-full.txt` is the instance's own [`/llms-full.txt`](llms.md), so the model reads the documentation of the exact version it talks to. The prompt `write_and_publish_article` drafts, checks the SEO and asks before publishing.

go.mod

@@ -14,6 +14,7 @@ require (
 	github.com/go-sql-driver/mysql v1.10.1
 	github.com/google/uuid v1.6.0
 	github.com/jackc/pgx/v5 v5.11.0
+	github.com/modelcontextprotocol/go-sdk v1.8.0
 	golang.org/x/crypto v0.58.0
 	golang.org/x/image v0.47.0
 	golang.org/x/net v0.61.0
@@ -45,6 +46,7 @@ require (
 	github.com/glebarez/go-sqlite v1.23.0 // indirect
 	github.com/go-playground/locales v0.14.2 // indirect
 	github.com/go-playground/universal-translator v0.18.2 // indirect
+	github.com/google/jsonschema-go v0.4.3 // indirect
 	github.com/jackc/pgpassfile v1.0.0 // indirect
 	github.com/jackc/pgservicefile v0.0.0-20240606120523-5a60cdf6a761 // indirect
 	github.com/jackc/puddle/v2 v2.2.3 // indirect
@@ -54,9 +56,14 @@ require (
 	github.com/mattn/go-isatty v0.0.24 // indirect
 	github.com/ncruces/go-strftime v1.1.0 // indirect
 	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	github.com/segmentio/asm v1.1.3 // indirect
+	github.com/segmentio/encoding v0.5.4 // indirect
 	github.com/stretchr/testify v1.12.1 // indirect
+	github.com/yosida95/uritemplate/v3 v3.0.2 // indirect
+	golang.org/x/oauth2 v0.35.0 // indirect
 	golang.org/x/sync v0.24.0 // indirect
 	golang.org/x/sys v0.49.0 // indirect
+	golang.org/x/time v0.15.0 // indirect
 	modernc.org/libc v1.79.0 // indirect
 	modernc.org/mathutil v1.7.1 // indirect
 	modernc.org/memory v1.12.1 // indirect

go.sum

@@ -61,6 +61,12 @@ github.com/go-playground/validator/v10 v10.30.5 h1:YyCXvVShZbs2Sm3Mb53eNOlhRXctS
 github.com/go-playground/validator/v10 v10.30.5/go.mod h1:wEqiaov48pXX1kjhc3Da8y0M0Dtg/BK7gurFBLgwFrQ=
 github.com/go-sql-driver/mysql v1.10.1 h1:arlSnNLq6a5yxGxV7qg9lF4j0C+KwD6NbQyKr9QL6ME=
 github.com/go-sql-driver/mysql v1.10.1/go.mod h1:M+cqaI7+xxXGG9swrdeUIoPG3Y3KCkF0pZej+SK+nWk=
+github.com/golang-jwt/jwt/v5 v5.3.1 h1:kYf81DTWFe7t+1VvL7eS+jKFVWaUnK9cB1qbwn63YCY=
+github.com/golang-jwt/jwt/v5 v5.3.1/go.mod h1:fxCRLWMO43lRc8nhHWY6LGqRcf+1gQWArsqaEUEa5bE=
+github.com/google/go-cmp v0.7.0 h1:wk8382ETsv4JYUZwIsn6YpYiWiBsYLSJiTsyBybVuN8=
+github.com/google/go-cmp v0.7.0/go.mod h1:pXiqmnSA92OHEEa9HXL2W4E7lf9JzCmGVUdgjX3N/iU=
+github.com/google/jsonschema-go v0.4.3 h1:/DBOLZTfDow7pe2GmaJNhltueGTtDKICi8V8p+DQPd0=
+github.com/google/jsonschema-go v0.4.3/go.mod h1:r5quNTdLOYEz95Ru18zA0ydNbBuYoo9tgaYcxEYhJVE=
 github.com/google/pprof v0.0.0-20261016150608-1facf8f91b50 h1:PlNWJRxu5APSV0pWqfIsZ0qt9OOGHSWfZQ4zvx+WgWs=
 github.com/google/pprof v0.0.0-20261016150608-1facf8f91b50/go.mod h1:yUo1AMMpsPIDFGuwDK8nLcf8+vvAd5l2O6JDZ6hpwrM=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
@@ -85,16 +91,24 @@ github.com/mattn/go-isatty v0.0.24 h1:tGZZoVgT/KiqK1c8ocVLeDS8BSWMRd47J3Lbz7vsRe
 github.com/mattn/go-isatty v0.0.24/go.mod h1:nMCL3Zebbrt45jsMDgnfIwz6ydEQApk5oEI3HqDio6A=
 github.com/mattn/go-sqlite3 v1.14.22 h1:2gZY6PC6kBnID23Tichd1K+Z0oS6nE/XwU+Vz/5o4kU=
 github.com/mattn/go-sqlite3 v1.14.22/go.mod h1:Uh1q+B4BYcTPb+yiD3kU8Ct7aC0hY9fxUwlHK0RXw+Y=
+github.com/modelcontextprotocol/go-sdk v1.8.0 h1:KIvahhYqwtbeniWVPs3TcXEA7b8jEtwfBpOTAI+Urx4=
+github.com/modelcontextprotocol/go-sdk v1.8.0/go.mod h1:dL7u98E/zjJTGzEq+j30jQ8K2k1mb6LeAH4inEcSGts=
 github.com/ncruces/go-strftime v1.1.0 h1:vtPmPWMkb539RGV9WpWT9EwJGvrOCKvMNI4obWL47Hk=
 github.com/ncruces/go-strftime v1.1.0/go.mod h1:yVaq7iwCN09vHRrKBrrflXT0M9tTMG2KmZ9Fj7xeG/g=
 github.com/pmezard/go-difflib v1.0.0/go.mod h1:iKH77koFhYxTK1pcRnkKkqfTogsbg7gZNVY4sRDYZ/4=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
 github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/segmentio/asm v1.1.3 h1:WM03sfUOENvvKexOLp+pCqgb/WDjsi7EK8gIsICtzhc=
+github.com/segmentio/asm v1.1.3/go.mod h1:Ld3L4ZXGNcSLRg4JBsZ3//1+f/TjYl0Mzen/DQy1EJg=
+github.com/segmentio/encoding v0.5.4 h1:OW1VRern8Nw6ITAtwSZ7Idrl3MXCFwXHPgqESYfvNt0=
+github.com/segmentio/encoding v0.5.4/go.mod h1:HS1ZKa3kSN32ZHVZ7ZLPLXWvOVIiZtyJnO1gPH1sKt0=
 github.com/stretchr/objx v0.1.0/go.mod h1:HFkY916IF+rwdDfMAkV7OtwuqBVzrE8GR6GFx+wExME=
 github.com/stretchr/testify v1.3.0/go.mod h1:M5WIy9Dh21IEIfnGCwXGc5bZfKNJtfHm1UVUgZn+9EI=
 github.com/stretchr/testify v1.7.0/go.mod h1:6Fq8oRcR53rry900zMqJjRRixrwX3KX962/h/Wwjteg=
 github.com/stretchr/testify v1.12.1 h1:EuwCh5fleGS7H32xRwO3wRGT7DxrDhLAT6FF8MpWDWE=
 github.com/stretchr/testify v1.12.1/go.mod h1:MDEgiDPPsNp5cuIrHPPCyornHKgEVbtFUmoNlxoYthg=
+github.com/yosida95/uritemplate/v3 v3.0.2 h1:Ed3Oyj9yrmi9087+NczuL5BwkIc4wvTb5zIM+UJPGz4=
+github.com/yosida95/uritemplate/v3 v3.0.2/go.mod h1:ILOh0sOhIJR3+L/8afwt/kE++YT040gmv5BQTMR2HP4=
 go.yaml.in/yaml/v3 v3.0.5 h1:N6y/pJk8buWs9NY5ERU2HSMfm+IuD/OtfdAnq6kESPw=
 go.yaml.in/yaml/v3 v3.0.5/go.mod h1:HVTZu1O7/Vkt2N+BFy8Zza+lnLsABggaTM2ZpNIGuKg=
 golang.org/x/crypto v0.58.0 h1:COkYLr4k7nDI4r6QtMML2AfzeIswWHAJthLS6K/M/54=
@@ -105,12 +119,16 @@ golang.org/x/mod v0.42.0 h1:ICeL3t2L30ljSPHHxDnR4fqVcBt/zR2zJAb9juavmQg=
 golang.org/x/mod v0.42.0/go.mod h1:u5fzIrRInkL8MaO1cbRkUHT64v303YIT5KEqpNr7jRs=
 golang.org/x/net v0.61.0 h1:RR+6j/BTBCrggOLugxa+66R8FvoN6MHlzDlZIbN9YFw=
 golang.org/x/net v0.61.0/go.mod h1:WgDCOTH8iwtB66T4/GfI94AHo/hhdb7Hah9NDseQfiI=
+golang.org/x/oauth2 v0.35.0 h1:Mv2mzuHuZuY2+bkyWXIHMfhNdJAdwW3FuWeCPYN5GVQ=
+golang.org/x/oauth2 v0.35.0/go.mod h1:lzm5WQJQwKZ3nwavOZ3IS5Aulzxi68dUSgRHujetwEA=
 golang.org/x/sync v0.24.0 h1:iqiDrGoDgyuvAKrhLQthUEzU/R378N78gXbBjxed7oA=
 golang.org/x/sync v0.24.0/go.mod h1:sUUOizhqBxiL6pEWpqNLUiaJn1ShEbZ6BBqskPbjZm0=
 golang.org/x/sys v0.49.0 h1:XbzkgYJHdqh/8m2Uu0W/dQv8nktxx4BFHp1M0gROTXA=
 golang.org/x/sys v0.49.0/go.mod h1:hNLxWAXmnKAxqDtdwIYC4bM9oQPEecfsnNMuSxOs3og=
 golang.org/x/text v0.43.0 h1:1QivrlhwAsnMOcqgOdl9my7s9OyZl8O5/UGUTJVXoWc=
 golang.org/x/text v0.43.0/go.mod h1:hbSIYA/amXcRXTFSZqh8tWHEoqRvvbKPJ2uz/KU+a+s=
+golang.org/x/time v0.15.0 h1:bbrp8t3bGUeFOx08pvsMYRTCVSMk89u4tKbNOZbp88U=
+golang.org/x/time v0.15.0/go.mod h1:Y4YMaQmXwGQZoFaVFk4YpCt4FLQMYKZe9oeV/f4MSno=
 golang.org/x/tools v0.52.0 h1:ryxg4U63oaUYk7uOLTF37n43f4qgtGvqV4Ioit1BaEs=
 golang.org/x/tools v0.52.0/go.mod h1:ItcP5UNaVGG+Yc4eIYmaFLNJ4soEopkx5Y2d4lcEurs=
 gopkg.in/check.v1 v0.0.0-20161208181325-20d25e280405/go.mod h1:Co6ibVJAznAaIkqp8huTwlJQCZ016jof/cbN4VW5Yz0=

internal/infrastructure/llmdocs/llmdocs.go

@@ -0,0 +1,19 @@
+package llmdocs
+
+import (
+	"embed"
+	"io/fs"
+)
+
+//go:embed all:generated
+var generatedEmbed embed.FS
+
+var Docs = mustSub(generatedEmbed, "generated")
+
+func mustSub(fsys fs.FS, dir string) fs.FS {
+	sub, err := fs.Sub(fsys, dir)
+	if err != nil {
+		panic("llmdocs: " + err.Error())
+	}
+	return sub
+}

internal/infrastructure/mcpserver/client.go

@@ -0,0 +1,77 @@
+package mcpserver
+
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"io"
+	"net/http"
+	"net/url"
+	"strings"
+	"time"
+)
+
+const (
+	requestTimeout  = 60 * time.Second
+	maxResponseSize = 8 << 20
+)
+
+type Client struct {
+	baseURL string
+	apiKey  string
+	http    *http.Client
+}
+
+type Response struct {
+	Status int
+	Body   string
+}
+
+func NewClient(baseURL string, apiKey string, httpClient *http.Client) *Client {
+	if httpClient == nil {
+		httpClient = &http.Client{Timeout: requestTimeout}
+	}
+	return &Client{baseURL: strings.TrimRight(baseURL, "/"), apiKey: apiKey, http: httpClient}
+}
+
+func (c *Client) Do(ctx context.Context, method string, path string, query url.Values, body []byte, contentType string) (Response, error) {
+	target := c.baseURL + path
+	if len(query) > 0 {
+		target += "?" + query.Encode()
+	}
+	req, err := http.NewRequestWithContext(ctx, method, target, bytes.NewReader(body))
+	if err != nil {
+		return Response{}, err
+	}
+	if c.apiKey != "" {
+		req.Header.Set("Authorization", "Bearer "+c.apiKey)
+	}
+	if contentType != "" {
+		req.Header.Set("Content-Type", contentType)
+	}
+	res, err := c.http.Do(req)
+	if err != nil {
+		return Response{}, err
+	}
+	defer res.Body.Close()
+	raw, err := io.ReadAll(io.LimitReader(res.Body, maxResponseSize))
+	if err != nil {
+		return Response{}, err
+	}
+	return Response{Status: res.StatusCode, Body: string(raw)}, nil
+}
+
+func (r Response) Failed() bool {
+	return r.Status < 200 || r.Status > 299
+}
+
+func (r Response) Describe() string {
+	text := strings.TrimSpace(r.Body)
+	if r.Status == http.StatusNoContent || text == "" {
+		return fmt.Sprintf("HTTP %d", r.Status)
+	}
+	if r.Failed() {
+		return fmt.Sprintf("HTTP %d: %s", r.Status, text)
+	}
+	return text
+}

internal/infrastructure/mcpserver/server.go

@@ -0,0 +1,305 @@
+package mcpserver
+
+import (
+	"bytes"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"fmt"
+	"mime/multipart"
+	"net/http"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strconv"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+const (
+	docsResourceURI = "renewcms://docs/llms-full.txt"
+	jsonType        = "application/json"
+)
+
+type Options struct {
+	Version          string
+	AllowDestructive bool
+}
+
+type server struct {
+	client *Client
+}
+
+type listArticlesInput struct {
+	Page   int    `json:"page,omitempty" jsonschema:"page number from 1"`
+	Size   int    `json:"size,omitempty" jsonschema:"page size: 5, 25, 50 or 100"`
+	Query  string `json:"q,omitempty" jsonschema:"text matched in the title"`
+	Status string `json:"status,omitempty" jsonschema:"online or draft"`
+	Sort   string `json:"sort,omitempty" jsonschema:"field:direction, e.g. title:asc or updated_at:desc"`
+	Site   string `json:"site,omitempty" jsonschema:"site key"`
+	SEO    string `json:"seo,omitempty" jsonschema:"ready, suggestions or hidden"`
+	Format string `json:"format,omitempty" jsonschema:"body format: markdown, html or json"`
+}
+
+type getArticleInput struct {
+	ID     int    `json:"id" jsonschema:"article id"`
+	Format string `json:"format,omitempty" jsonschema:"body format: markdown, html or json"`
+}
+
+type createArticleInput struct {
+	Title string `json:"title" jsonschema:"3 to 200 characters, cannot be changed later"`
+	Body  string `json:"body" jsonschema:"HTML body"`
+}
+
+type updateArticleBodyInput struct {
+	ID   int    `json:"id" jsonschema:"article id"`
+	Body string `json:"body" jsonschema:"new HTML body, replaces the old one"`
+}
+
+type articleIDInput struct {
+	ID int `json:"id" jsonschema:"article id"`
+}
+
+type listMediaInput struct {
+	Query  string `json:"q,omitempty" jsonschema:"search text"`
+	Filter string `json:"filter,omitempty" jsonschema:"all, unused or duplicates"`
+	Sort   string `json:"sort,omitempty" jsonschema:"newest, oldest, name, largest or total_size"`
+	Page   int    `json:"page,omitempty" jsonschema:"page number from 1"`
+	Size   int    `json:"size,omitempty" jsonschema:"page size: 5, 25, 50 or 100"`
+}
+
+type uploadMediaInput struct {
+	Path     string `json:"path,omitempty" jsonschema:"path of a local PNG, JPEG, WEBP or SVG file"`
+	Base64   string `json:"base64,omitempty" jsonschema:"base64 file content, instead of path"`
+	Filename string `json:"filename,omitempty" jsonschema:"file name, required with base64"`
+}
+
+type emptyInput struct{}
+
+type sitemapInput struct {
+	Key  string `json:"key" jsonschema:"site key"`
+	Page int    `json:"page,omitempty" jsonschema:"page number from 1"`
+	Size int    `json:"size,omitempty" jsonschema:"25, 50, 100 or 500"`
+}
+
+type mediaIDInput struct {
+	ID int `json:"id" jsonschema:"image id"`
+}
+
+func New(client *Client, opts Options) *mcp.Server {
+	s := &server{client: client}
+	srv := mcp.NewServer(&mcp.Implementation{Name: "renewcms", Version: opts.Version}, &mcp.ServerOptions{
+		Instructions: "Tools for a RenewCMS instance. Read the renewcms://docs/llms-full.txt resource for the API rules. Articles are created as drafts; ask before publishing.",
+	})
+
+	readOnly := &mcp.ToolAnnotations{ReadOnlyHint: true}
+	additive := &mcp.ToolAnnotations{DestructiveHint: boolPtr(false)}
+
+	mcp.AddTool(srv, &mcp.Tool{Name: "list_articles", Description: "List one page of articles with total and counts.", Annotations: readOnly}, s.listArticles)
+	mcp.AddTool(srv, &mcp.Tool{Name: "get_article", Description: "Get one article.", Annotations: readOnly}, s.getArticle)
+	mcp.AddTool(srv, &mcp.Tool{Name: "create_article", Description: "Create a draft article.", Annotations: additive}, s.createArticle)
+	mcp.AddTool(srv, &mcp.Tool{Name: "update_article_body", Description: "Replace the body of an article. The previous body is overwritten.", Annotations: &mcp.ToolAnnotations{IdempotentHint: true}}, s.updateArticleBody)
+	mcp.AddTool(srv, &mcp.Tool{Name: "publish_article", Description: "Make an article visible to everyone.", Annotations: &mcp.ToolAnnotations{IdempotentHint: true, DestructiveHint: boolPtr(false)}}, s.publishArticle)
+	mcp.AddTool(srv, &mcp.Tool{Name: "check_seo", Description: "Check the SEO of the saved article and list suggestions.", Annotations: readOnly}, s.checkSEO)
+	mcp.AddTool(srv, &mcp.Tool{Name: "list_media", Description: "List one page of the image library.", Annotations: readOnly}, s.listMedia)
+	mcp.AddTool(srv, &mcp.Tool{Name: "upload_media", Description: "Upload an image from a local path or base64 content.", Annotations: additive}, s.uploadMedia)
+	mcp.AddTool(srv, &mcp.Tool{Name: "list_sites", Description: "List the sites.", Annotations: readOnly}, s.listSites)
+	mcp.AddTool(srv, &mcp.Tool{Name: "get_sitemap", Description: "Read the public sitemap of a site.", Annotations: readOnly}, s.getSitemap)
+
+	if opts.AllowDestructive {
+		mcp.AddTool(srv, &mcp.Tool{Name: "delete_article", Description: "Permanently delete an article."}, s.deleteArticle)
+		mcp.AddTool(srv, &mcp.Tool{Name: "delete_media", Description: "Permanently delete an image."}, s.deleteMedia)
+	}
+
+	srv.AddResource(&mcp.Resource{
+		URI:         docsResourceURI,
+		Name:        "llms-full.txt",
+		Description: "The full RenewCMS documentation served by the instance.",
+		MIMEType:    "text/plain",
+	}, s.readDocs)
+
+	srv.AddPrompt(&mcp.Prompt{
+		Name:        "write_and_publish_article",
+		Description: "Draft an article, check its SEO and publish it after confirmation.",
+		Arguments:   []*mcp.PromptArgument{{Name: "topic", Description: "what the article is about", Required: true}},
+	}, writePrompt)
+
+	return srv
+}
+
+func boolPtr(value bool) *bool { return &value }
+
+func intQuery(query url.Values, name string, value int) {
+	if value > 0 {
+		query.Set(name, strconv.Itoa(value))
+	}
+}
+
+func textQuery(query url.Values, name string, value string) {
+	if value != "" {
+		query.Set(name, value)
+	}
+}
+
+func result(res Response, err error) (*mcp.CallToolResult, any, error) {
+	if err != nil {
+		return nil, nil, err
+	}
+	return &mcp.CallToolResult{
+		IsError: res.Failed(),
+		Content: []mcp.Content{&mcp.TextContent{Text: res.Describe()}},
+	}, nil, nil
+}
+
+func (s *server) call(ctx context.Context, method string, path string, query url.Values, body any) (*mcp.CallToolResult, any, error) {
+	var raw []byte
+	contentType := ""
+	if body != nil {
+		encoded, err := json.Marshal(body)
+		if err != nil {
+			return nil, nil, err
+		}
+		raw, contentType = encoded, jsonType
+	}
+	return result(s.client.Do(ctx, method, path, query, raw, contentType))
+}
+
+func articlePath(id int, suffix string) string {
+	return "/v1/article/" + strconv.Itoa(id) + suffix
+}
+
+func (s *server) listArticles(ctx context.Context, _ *mcp.CallToolRequest, in listArticlesInput) (*mcp.CallToolResult, any, error) {
+	query := url.Values{}
+	intQuery(query, "page", in.Page)
+	intQuery(query, "size", in.Size)
+	textQuery(query, "q", in.Query)
+	textQuery(query, "status", in.Status)
+	textQuery(query, "sort", in.Sort)
+	textQuery(query, "site", in.Site)
+	textQuery(query, "seo", in.SEO)
+	textQuery(query, "format", in.Format)
+	return s.call(ctx, http.MethodGet, "/v1/article/", query, nil)
+}
+
+func (s *server) getArticle(ctx context.Context, _ *mcp.CallToolRequest, in getArticleInput) (*mcp.CallToolResult, any, error) {
+	query := url.Values{}
+	textQuery(query, "format", in.Format)
+	return s.call(ctx, http.MethodGet, articlePath(in.ID, ""), query, nil)
+}
+
+func (s *server) createArticle(ctx context.Context, _ *mcp.CallToolRequest, in createArticleInput) (*mcp.CallToolResult, any, error) {
+	return s.call(ctx, http.MethodPost, "/v1/article/", nil, map[string]string{"title": in.Title, "body": in.Body})
+}
+
+func (s *server) updateArticleBody(ctx context.Context, _ *mcp.CallToolRequest, in updateArticleBodyInput) (*mcp.CallToolResult, any, error) {
+	return s.call(ctx, http.MethodPatch, articlePath(in.ID, ""), nil, map[string]string{"body": in.Body})
+}
+
+func (s *server) publishArticle(ctx context.Context, _ *mcp.CallToolRequest, in articleIDInput) (*mcp.CallToolResult, any, error) {
+	return s.call(ctx, http.MethodPatch, articlePath(in.ID, "/publish"), nil, nil)
+}
+
+func (s *server) checkSEO(ctx context.Context, _ *mcp.CallToolRequest, in articleIDInput) (*mcp.CallToolResult, any, error) {
+	return s.call(ctx, http.MethodPost, articlePath(in.ID, "/seo/check"), nil, map[string]string{})
+}
+
+func (s *server) deleteArticle(ctx context.Context, _ *mcp.CallToolRequest, in articleIDInput) (*mcp.CallToolResult, any, error) {
+	return s.call(ctx, http.MethodDelete, articlePath(in.ID, ""), nil, nil)
+}
+
+func (s *server) listMedia(ctx context.Context, _ *mcp.CallToolRequest, in listMediaInput) (*mcp.CallToolResult, any, error) {
+	query := url.Values{}
+	textQuery(query, "q", in.Query)
+	textQuery(query, "filter", in.Filter)
+	textQuery(query, "sort", in.Sort)
+	intQuery(query, "page", in.Page)
+	intQuery(query, "size", in.Size)
+	return s.call(ctx, http.MethodGet, "/v1/media/", query, nil)
+}
+
+func (s *server) deleteMedia(ctx context.Context, _ *mcp.CallToolRequest, in mediaIDInput) (*mcp.CallToolResult, any, error) {
+	return s.call(ctx, http.MethodDelete, "/v1/media/"+strconv.Itoa(in.ID), nil, nil)
+}
+
+func (s *server) uploadMedia(ctx context.Context, _ *mcp.CallToolRequest, in uploadMediaInput) (*mcp.CallToolResult, any, error) {
+	name, content, err := uploadContent(in)
+	if err != nil {
+		return nil, nil, err
+	}
+	var form bytes.Buffer
+	writer := multipart.NewWriter(&form)
+	part, err := writer.CreateFormFile("file", name)
+	if err != nil {
+		return nil, nil, err
+	}
+	if _, err := part.Write(content); err != nil {
+		return nil, nil, err
+	}
+	if err := writer.Close(); err != nil {
+		return nil, nil, err
+	}
+	return result(s.client.Do(ctx, http.MethodPost, "/v1/media/", nil, form.Bytes(), writer.FormDataContentType()))
+}
+
+func uploadContent(in uploadMediaInput) (string, []byte, error) {
+	switch {
+	case in.Path != "" && in.Base64 != "":
+		return "", nil, fmt.Errorf("give either path or base64, not both")
+	case in.Path != "":
+		content, err := os.ReadFile(in.Path)
+		if err != nil {
+			return "", nil, err
+		}
+		name := in.Filename
+		if name == "" {
+			name = filepath.Base(in.Path)
+		}
+		return name, content, nil
+	case in.Base64 != "":
+		if in.Filename == "" {
+			return "", nil, fmt.Errorf("filename is required with base64")
+		}
+		content, err := base64.StdEncoding.DecodeString(in.Base64)
+		if err != nil {
+			return "", nil, fmt.Errorf("base64 content is not valid: %w", err)
+		}
+		return in.Filename, content, nil
+	}
+	return "", nil, fmt.Errorf("give a path or base64 content")
+}
+
+func (s *server) listSites(ctx context.Context, _ *mcp.CallToolRequest, _ emptyInput) (*mcp.CallToolResult, any, error) {
+	return s.call(ctx, http.MethodGet, "/v1/site/", nil, nil)
+}
+
+func (s *server) getSitemap(ctx context.Context, _ *mcp.CallToolRequest, in sitemapInput) (*mcp.CallToolResult, any, error) {
+	query := url.Values{}
+	intQuery(query, "page", in.Page)
+	intQuery(query, "size", in.Size)
+	return s.call(ctx, http.MethodGet, "/v1/site/"+url.PathEscape(in.Key)+"/sitemap", query, nil)
+}
+
+func (s *server) readDocs(ctx context.Context, req *mcp.ReadResourceRequest) (*mcp.ReadResourceResult, error) {
+	res, err := s.client.Do(ctx, http.MethodGet, "/llms-full.txt", nil, nil, "")
+	if err != nil {
+		return nil, err
+	}
+	if res.Failed() {
+		return nil, fmt.Errorf("the instance did not serve its documentation: %s", res.Describe())
+	}
+	return &mcp.ReadResourceResult{Contents: []*mcp.ResourceContents{{
+		URI:      req.Params.URI,
+		MIMEType: "text/plain",
+		Text:     res.Body,
+	}}}, nil
+}
+
+func writePrompt(_ context.Context, req *mcp.GetPromptRequest) (*mcp.GetPromptResult, error) {
+	text := "Write an article about " + req.Params.Arguments["topic"] + " for this RenewCMS instance. " +
+		"Create it as a draft with create_article, run check_seo and fix what is worth fixing with update_article_body, " +
+		"then show me the result and ask before calling publish_article."
+	return &mcp.GetPromptResult{
+		Description: "Draft, check and publish an article",
+		Messages:    []*mcp.PromptMessage{{Role: "user", Content: &mcp.TextContent{Text: text}}},
+	}, nil
+}

scripts/generate-llms.ts

@@ -0,0 +1,321 @@
+import { mkdirSync, readFileSync, readdirSync, rmSync, writeFileSync } from 'node:fs'
+import { basename, dirname, join, resolve } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import {
+	API_GROUPS,
+	ERROR_ROWS,
+	PUBLIC_AUTH_ROWS,
+	SESSION_GROUPS,
+	endpointExamples,
+	type ApiEndpoint,
+	type ApiField,
+} from '../web/src/data/apiCatalogue'
+
+const root = resolve(dirname(fileURLToPath(import.meta.url)), '..')
+const outDir = join(root, 'internal/infrastructure/llmdocs/generated')
+const pagesDir = join(outDir, 'llms')
+
+const VERSION = '{{VERSION}}'
+const BASE_URL = '{{BASE_URL}}'
+
+interface Page {
+	name: string
+	title: string
+	summary: string
+	body: () => string
+}
+
+const read = (relative: string) => readFileSync(join(root, relative), 'utf8')
+
+function section(markdown: string, heading: string) {
+	const lines = markdown.split('\n')
+	const start = lines.findIndex((line) => line.trim() === heading)
+	if (start === -1) throw new Error(`heading not found: ${heading}`)
+	const level = heading.match(/^#+/)![0].length
+	const end = lines.findIndex(
+		(line, index) => index > start && /^#+ /.test(line) && line.match(/^#+/)![0].length <= level,
+	)
+	return lines.slice(start, end === -1 ? undefined : end).join('\n')
+}
+
+const docFiles = (directory: string) =>
+	readdirSync(join(root, directory))
+		.filter((file) => file.endsWith('.md'))
+		.sort()
+		.map((file) => `${directory}/${file}`)
+
+const fieldTable = (fields: ApiField[]) =>
+	[
+		'| Name | Type | Required | Rule |',
+		'| --- | --- | --- | --- |',
+		...fields.map(
+			(field) =>
+				`| \`${field.name}\` | ${field.type} | ${field.required ? 'yes' : 'no'} | ${field.rule.replaceAll('|', '\\|')} |`,
+		),
+	].join('\n')
+
+function endpointMarkdown(item: ApiEndpoint) {
+	const examples = endpointExamples(item, BASE_URL)
+	const parts = [
+		`### ${item.method} ${item.path}`,
+		`Access: ${item.access}. Success status: ${item.status}.${item.rateLimited ? ' Rate limited.' : ''}`,
+		item.description,
+	]
+	if (item.query.length > 0) parts.push(`Query parameters:\n\n${fieldTable(item.query)}`)
+	if (item.body.length > 0) {
+		const kind = item.bodyKind === 'multipart' ? 'multipart/form-data' : 'JSON'
+		parts.push(`Body (${kind}):\n\n${fieldTable(item.body)}`)
+	}
+	parts.push(`Example:\n\n\`\`\`sh\n${examples.curl}\n\`\`\``)
+	parts.push(`Response:\n\n\`\`\`\n${item.response}\n\`\`\``)
+	if (item.errors.length > 0) {
+		parts.push(
+			`Errors:\n\n${item.errors.map((error) => `- ${error.status}: ${error.caption}`).join('\n')}`,
+		)
+	}
+	return parts.join('\n\n')
+}
+
+function apiReference() {
+	const parts = [
+		'# API reference',
+		`Generated from the route catalogue of RenewCMS ${VERSION}. Base URL: ${BASE_URL}. Every path starts with /v1. Send \`Authorization: Bearer rcms_...\` on every route except the public ones.`,
+	]
+	for (const group of API_GROUPS) {
+		parts.push(`## ${group.title}`, group.description)
+		parts.push(...group.endpoints.map(endpointMarkdown))
+	}
+	parts.push(
+		'## Session-only routes',
+		'A key sent to these routes answers 403 "This action needs a real session.", except the sign-in routes, which ignore a key.',
+	)
+	for (const group of SESSION_GROUPS) {
+		parts.push(
+			`### ${group.title}`,
+			group.rows.map((row) => `- ${row.method} ${row.path}: ${row.description}`).join('\n'),
+		)
+	}
+	parts.push(
+		'## Public routes outside the article reads',
+		PUBLIC_AUTH_ROWS.map((row) => `- ${row.method} ${row.path}: ${row.description}`).join('\n'),
+	)
+	parts.push(
+		'## Errors',
+		ERROR_ROWS.map(
+			(row) =>
+				`- ${row.status} ${row.meaning}: ${row.messages.map((message) => `"${message}"`).join(', ')}${row.note ? ` ${row.note}` : ''}`,
+		).join('\n'),
+	)
+	return parts.join('\n\n')
+}
+
+const API_PAGE_SUMMARIES: Record<string, string> = {
+	articles: 'Article reads: pagination, search, counts, the format parameter, SEO status.',
+	'api-keys': 'Creating, listing and revoking API keys, and where a key is accepted.',
+}
+
+const pages: Page[] = [
+	{
+		name: 'api-reference',
+		title: 'API reference',
+		summary: 'Every key-callable route with parameters, bodies, curl examples, responses and errors.',
+		body: apiReference,
+	},
+	{
+		name: 'api',
+		title: 'API overview',
+		summary: 'Base URL, authentication, API key limits, activity log.',
+		body: () => read('docs/api.md'),
+	},
+	...docFiles('docs/api').map((file) => ({
+		name: basename(file, '.md'),
+		title: read(file).match(/^# (.+)$/m)?.[1] ?? basename(file, '.md'),
+		summary: API_PAGE_SUMMARIES[basename(file, '.md')] ?? '',
+		body: () => read(file),
+	})),
+	...docFiles('docs/llm').map((file) => ({
+		name: basename(file, '.md'),
+		title: read(file).match(/^# (.+)$/m)?.[1] ?? basename(file, '.md'),
+		summary: read(file).match(/^> (.+)$/m)?.[1] ?? '',
+		body: () => read(file).replace(/^> .+\n+/m, ''),
+	})),
+	{
+		name: 'configuration',
+		title: 'Configuration',
+		summary: 'Environment variables of the server.',
+		body: () => `# Configuration\n\n${section(read('docs/configuration.md'), '## Variables')}`,
+	},
+]
+
+const pageNames = new Map(pages.map((page) => [page.name, page]))
+
+function rewriteLinks(markdown: string) {
+	return markdown.replace(/\[([^\]]+)\]\(([^)\s]+)\)/g, (whole, text: string, target: string) => {
+		if (/^(https?:|mailto:|#|\{\{)/.test(target)) return whole
+		const [file, anchor] = target.split('#')
+		const page = pageNames.get(basename(file, '.md'))
+		if (!page || !file.endsWith('.md')) return text
+		return `[${text}](${BASE_URL}/llms/${page.name}.md${anchor ? `#${anchor}` : ''})`
+	})
+}
+
+const rendered = pages.map((page) => ({ page, text: rewriteLinks(page.body()).trim() }))
+
+const index = [
+	'# RenewCMS',
+	`> A small self-hosted CMS. A JSON API under /v1 manages articles, media and sites; articles and sitemaps are readable without credentials. Version ${VERSION}, served by ${BASE_URL}.`,
+	'Authenticate with an API key: `Authorization: Bearer rcms_...`. A key acts as its creator, 120 requests per minute. Some routes need a browser session and answer 403 to a key; see the gotchas page.',
+	'## Docs',
+	rendered
+		.map(({ page }) => `- [${page.title}](${BASE_URL}/llms/${page.name}.md): ${page.summary}`)
+		.join('\n'),
+	'## Machine-readable',
+	[
+		`- [llms-full.txt](${BASE_URL}/llms-full.txt): all of the pages above in one file`,
+		`- [openapi.json](${BASE_URL}/openapi.json): OpenAPI 3.1 description of the routes in the API reference`,
+	].join('\n'),
+].join('\n\n')
+
+const full = [
+	`# RenewCMS documentation\n\nVersion ${VERSION}. Served by ${BASE_URL}.`,
+	...rendered.map(({ text }) => text),
+].join('\n\n---\n\n')
+
+const SCALARS: Record<string, object> = {
+	string: { type: 'string' },
+	number: { type: 'number' },
+	boolean: { type: 'boolean' },
+	null: { type: 'null' },
+	file: { type: 'string', format: 'binary' },
+}
+
+function schemaOf(type: string): object {
+	const alternatives = type.split('|').map((part) => part.trim())
+	if (alternatives.length > 1) return { anyOf: alternatives.map(schemaOf) }
+	if (type.endsWith('[]')) return { type: 'array', items: schemaOf(type.slice(0, -2)) }
+	return SCALARS[type] ?? {}
+}
+
+const objectSchema = (fields: ApiField[]) => ({
+	type: 'object',
+	properties: Object.fromEntries(
+		fields.map((field) => [field.name, { ...schemaOf(field.type), description: field.rule }]),
+	),
+	required: fields.filter((field) => field.required).map((field) => field.name),
+})
+
+function parseExample(response: string) {
+	try {
+		return JSON.parse(response)
+	} catch {
+		return undefined
+	}
+}
+
+function operation(item: ApiEndpoint) {
+	const pathParameters = [...item.path.matchAll(/\{(\w+)\}/g)].map((match) => ({
+		name: match[1],
+		in: 'path',
+		required: true,
+		schema: match[1] === 'id' ? { type: 'integer', minimum: 0 } : { type: 'string' },
+	}))
+	const queryParameters = item.query.map((field) => ({
+		name: field.name,
+		in: 'query',
+		required: field.required,
+		description: field.rule,
+		schema: schemaOf(field.type),
+	}))
+	const example = parseExample(item.response)
+	const responses: Record<string, object> = {
+		[String(item.status)]:
+			item.status === 204
+				? { description: 'No content' }
+				: {
+						description: 'Success',
+						content: {
+							'application/json': { schema: {}, ...(example === undefined ? {} : { example }) },
+						},
+					},
+	}
+	for (const error of item.errors) {
+		const key = String(error.status)
+		const previous = (responses[key] as { description?: string } | undefined)?.description
+		responses[key] = {
+			description: previous ? `${previous} / ${error.caption}` : error.caption,
+			content: { 'text/plain': { schema: { type: 'string' } } },
+		}
+	}
+	const result: Record<string, unknown> = {
+		operationId: item.id,
+		summary: item.description,
+		'x-access': item.access,
+		parameters: [...pathParameters, ...queryParameters],
+		responses,
+	}
+	if (item.access !== 'Public') result.security = [{ bearerAuth: [] }, { cookieAuth: [] }]
+	if (item.bodyKind === 'json') {
+		const media = {
+			schema: objectSchema(item.body),
+			...(item.bodySample ? { example: item.bodySample } : {}),
+		}
+		result.requestBody = { required: true, content: { 'application/json': media } }
+	}
+	if (item.bodyKind === 'multipart') {
+		result.requestBody = {
+			required: true,
+			content: { 'multipart/form-data': { schema: objectSchema(item.body) } },
+		}
+	}
+	return result
+}
+
+const paths: Record<string, Record<string, unknown>> = {}
+for (const group of API_GROUPS) {
+	for (const item of group.endpoints) {
+		paths[item.path] ??= {}
+		paths[item.path][item.method.toLowerCase()] = operation(item)
+	}
+}
+for (const group of SESSION_GROUPS) {
+	for (const row of group.rows) {
+		paths[row.path] ??= {}
+		paths[row.path][row.method.toLowerCase()] = {
+			summary: row.description,
+			'x-session-only': row.answers403,
+			security: [{ cookieAuth: [] }],
+			responses: { '200': { description: 'Success' } },
+		}
+	}
+}
+for (const row of PUBLIC_AUTH_ROWS) {
+	paths[row.path] ??= {}
+	paths[row.path][row.method.toLowerCase()] = {
+		summary: row.description,
+		responses: { '200': { description: 'Success' } },
+	}
+}
+
+const openapi = {
+	openapi: '3.1.0',
+	info: {
+		title: 'RenewCMS API',
+		version: VERSION,
+		description: 'Generated from the route catalogue. Routes listed with x-session-only answer 403 to an API key.',
+	},
+	servers: [{ url: BASE_URL }],
+	paths,
+	components: {
+		securitySchemes: {
+			bearerAuth: { type: 'http', scheme: 'bearer', description: 'An API key starting with rcms_' },
+			cookieAuth: { type: 'apiKey', in: 'cookie', name: 'jwt' },
+		},
+	},
+}
+
+rmSync(pagesDir, { recursive: true, force: true })
+mkdirSync(pagesDir, { recursive: true })
+for (const { page, text } of rendered) writeFileSync(join(pagesDir, `${page.name}.md`), `${text}\n`)
+writeFileSync(join(outDir, 'llms.txt'), `${index}\n`)
+writeFileSync(join(outDir, 'llms-full.txt'), `${full}\n`)
+writeFileSync(join(outDir, 'openapi.json'), `${JSON.stringify(openapi, null, 2)}\n`)

test/api_catalogue_drift_test.go

@@ -0,0 +1,120 @@
+package test
+
+import (
+	"RenewCMS/api"
+	"RenewCMS/internal/infrastructure/config"
+	"net/http"
+	"os"
+	"regexp"
+	"sort"
+	"strings"
+	"testing"
+
+	"github.com/go-chi/chi/v5"
+)
+
+var catalogueRoutePatterns = []*regexp.Regexp{
+	regexp.MustCompile(`\w+\(\s*'[^']+',\s*'([A-Z]+)',\s*'([^']+)'`),
+	regexp.MustCompile(`row\(\s*'([A-Z]+)',\s*'([^']+)'`),
+	regexp.MustCompile(`method: '([A-Z]+)',\s*path: '([^']+)'`),
+}
+
+func catalogueRoutes(t *testing.T) map[string]bool {
+	t.Helper()
+	raw, err := os.ReadFile("../web/src/data/apiCatalogue.ts")
+	if err != nil {
+		t.Fatal(err)
+	}
+	routes := map[string]bool{}
+	for _, pattern := range catalogueRoutePatterns {
+		for _, m := range pattern.FindAllStringSubmatch(string(raw), -1) {
+			routes[m[1]+" "+strings.TrimSuffix(m[2], "/")] = true
+		}
+	}
+	return routes
+}
+
+func routerRoutes(t *testing.T) map[string]bool {
+	t.Helper()
+	router := api.InitBackendRoutes(&api.UseCases{}, config.Settings{})
+	routes := map[string]bool{}
+	err := chi.Walk(router, func(method, route string, _ http.Handler, _ ...func(http.Handler) http.Handler) error {
+		route = strings.ReplaceAll(route, "/*", "")
+		routes[method+" /v1"+strings.TrimSuffix(route, "/")] = true
+		return nil
+	})
+	if err != nil {
+		t.Fatal(err)
+	}
+	return routes
+}
+
+var routesNotYetInTheCatalogue = []string{
+	"DELETE /v1/content-type/{key}",
+	"DELETE /v1/content-type/{key}/entry/{id}",
+	"DELETE /v1/image-variants/{name}",
+	"DELETE /v1/media/{id}/variants/{name}",
+	"GET /v1/builtin-type",
+	"GET /v1/builtin-type/{key}",
+	"GET /v1/content-type",
+	"GET /v1/content-type/{key}",
+	"GET /v1/content-type/{key}/entry",
+	"GET /v1/content-type/{key}/entry/{id}",
+	"GET /v1/image-variants",
+	"GET /v1/image-variants/cache",
+	"GET /v1/media/{id}/variants",
+	"GET /v1/user/lookup",
+	"PATCH /v1/image-variants/{name}",
+	"POST /v1/content-type",
+	"POST /v1/content-type/{key}/entry",
+	"POST /v1/image-variants",
+	"POST /v1/image-variants/cache/purge",
+	"POST /v1/image-variants/{name}/purge",
+	"POST /v1/media/{id}/variants",
+	"POST /v1/media/{id}/variants/{name}",
+	"PUT /v1/content-type/{key}",
+	"PUT /v1/content-type/{key}/entry/{id}",
+	"PUT /v1/image-variants/{name}",
+}
+
+func TestRouterRoutesAreInTheCatalogue(t *testing.T) {
+	documented := catalogueRoutes(t)
+	exempt := map[string]bool{}
+	for _, route := range routesNotYetInTheCatalogue {
+		exempt[route] = true
+	}
+	actual := routerRoutes(t)
+	var missing, stale []string
+	for route := range actual {
+		if !documented[route] && !exempt[route] {
+			missing = append(missing, route)
+		}
+	}
+	for route := range exempt {
+		if documented[route] || !actual[route] {
+			stale = append(stale, route)
+		}
+	}
+	sort.Strings(missing)
+	sort.Strings(stale)
+	if len(missing) > 0 {
+		t.Errorf("routes missing from web/src/data/apiCatalogue.ts:\n%s", strings.Join(missing, "\n"))
+	}
+	if len(stale) > 0 {
+		t.Errorf("routes to remove from routesNotYetInTheCatalogue:\n%s", strings.Join(stale, "\n"))
+	}
+}
+
+func TestCatalogueRoutesExistInTheRouter(t *testing.T) {
+	actual := routerRoutes(t)
+	var unknown []string
+	for route := range catalogueRoutes(t) {
+		if strings.Contains(route, " /v1") && !actual[route] {
+			unknown = append(unknown, route)
+		}
+	}
+	sort.Strings(unknown)
+	if len(unknown) > 0 {
+		t.Errorf("catalogue routes the router does not serve:\n%s", strings.Join(unknown, "\n"))
+	}
+}

test/llms_handler_http_test.go

@@ -0,0 +1,76 @@
+package test
+
+import (
+	"RenewCMS/api/handlers/llms"
+	"net/http"
+	"net/http/httptest"
+	"strings"
+	"testing"
+	"testing/fstest"
+
+	"github.com/go-chi/chi/v5"
+)
+
+func llmsRouter(docs fstest.MapFS) http.Handler {
+	r := chi.NewRouter()
+	llms.NewHandler(docs, "v9.9.9", "https://cms.example/").Register(r)
+	return r
+}
+
+func llmsGet(handler http.Handler, target string) *httptest.ResponseRecorder {
+	rec := httptest.NewRecorder()
+	handler.ServeHTTP(rec, httptest.NewRequest(http.MethodGet, target, nil))
+	return rec
+}
+
+func TestLlmsServesGeneratedDocsWithVersionAndBaseURL(t *testing.T) {
+	handler := llmsRouter(fstest.MapFS{
+		"llms.txt":         {Data: []byte("# RenewCMS {{VERSION}}\n{{BASE_URL}}/llms-full.txt")},
+		"llms-full.txt":    {Data: []byte("full {{VERSION}}")},
+		"openapi.json":     {Data: []byte(`{"version":"{{VERSION}}","servers":[{"url":"{{BASE_URL}}"}]}`)},
+		"llms/gotchas.md":  {Data: []byte("# Gotchas {{VERSION}}")},
+		"llms/private.txt": {Data: []byte("not a page")},
+	})
+	cases := []struct {
+		target      string
+		contentType string
+		body        string
+	}{
+		{"/llms.txt", "text/plain; charset=utf-8", "# RenewCMS v9.9.9\nhttps://cms.example/llms-full.txt"},
+		{"/llms-full.txt", "text/plain; charset=utf-8", "full v9.9.9"},
+		{"/openapi.json", "application/json", `{"version":"v9.9.9","servers":[{"url":"https://cms.example"}]}`},
+		{"/llms/gotchas.md", "text/markdown; charset=utf-8", "# Gotchas v9.9.9"},
+	}
+	for _, tc := range cases {
+		rec := llmsGet(handler, tc.target)
+		if rec.Code != http.StatusOK {
+			t.Fatalf("%s answered %d", tc.target, rec.Code)
+		}
+		if got := rec.Header().Get("Content-Type"); got != tc.contentType {
+			t.Errorf("%s content type %q, want %q", tc.target, got, tc.contentType)
+		}
+		if rec.Body.String() != tc.body {
+			t.Errorf("%s body %q, want %q", tc.target, rec.Body.String(), tc.body)
+		}
+	}
+}
+
+func TestLlmsAnswers404WhenNothingWasGenerated(t *testing.T) {
+	handler := llmsRouter(fstest.MapFS{})
+	for _, target := range []string{"/llms.txt", "/llms-full.txt", "/openapi.json", "/llms/gotchas.md", "/llms/private.txt", "/llms/..%2Fllms.txt"} {
+		rec := llmsGet(handler, target)
+		if rec.Code != http.StatusNotFound {
+			t.Errorf("%s answered %d, want 404", target, rec.Code)
+		}
+		if !strings.Contains(rec.Body.String(), "task build:llms") {
+			t.Errorf("%s body %q does not name the task", target, rec.Body.String())
+		}
+	}
+}
+
+func TestLlmsOnlyServesMarkdownPages(t *testing.T) {
+	handler := llmsRouter(fstest.MapFS{"llms/private.txt": {Data: []byte("not a page")}})
+	if rec := llmsGet(handler, "/llms/private.txt"); rec.Code != http.StatusNotFound {
+		t.Fatalf("answered %d, want 404", rec.Code)
+	}
+}

test/mcp_server_test.go

@@ -0,0 +1,189 @@
+package test
+
+import (
+	"RenewCMS/internal/infrastructure/mcpserver"
+	"context"
+	"encoding/base64"
+	"encoding/json"
+	"io"
+	"net/http"
+	"net/http/httptest"
+	"reflect"
+	"strings"
+	"sync"
+	"testing"
+
+	"github.com/modelcontextprotocol/go-sdk/mcp"
+)
+
+type recordedCall struct {
+	method string
+	target string
+	auth   string
+	body   string
+	ctype  string
+}
+
+type mcpFixture struct {
+	session *mcp.ClientSession
+	mu      sync.Mutex
+	calls   []recordedCall
+}
+
+func (f *mcpFixture) last() recordedCall {
+	f.mu.Lock()
+	defer f.mu.Unlock()
+	return f.calls[len(f.calls)-1]
+}
+
+func newMCPFixture(t *testing.T, allowDestructive bool, respond func(w http.ResponseWriter, r *http.Request)) *mcpFixture {
+	t.Helper()
+	f := &mcpFixture{}
+	api := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		raw, _ := io.ReadAll(r.Body)
+		f.mu.Lock()
+		f.calls = append(f.calls, recordedCall{r.Method, r.URL.RequestURI(), r.Header.Get("Authorization"), string(raw), r.Header.Get("Content-Type")})
+		f.mu.Unlock()
+		respond(w, r)
+	}))
+	t.Cleanup(api.Close)
+	server := mcpserver.New(mcpserver.NewClient(api.URL+"/", "rcms_key", nil), mcpserver.Options{Version: "test", AllowDestructive: allowDestructive})
+	ctx := context.Background()
+	serverSide, clientSide := mcp.NewInMemoryTransports()
+	if _, err := server.Connect(ctx, serverSide, nil); err != nil {
+		t.Fatal(err)
+	}
+	session, err := mcp.NewClient(&mcp.Implementation{Name: "test", Version: "0"}, nil).Connect(ctx, clientSide, nil)
+	if err != nil {
+		t.Fatal(err)
+	}
+	t.Cleanup(func() { _ = session.Close() })
+	f.session = session
+	return f
+}
+
+func (f *mcpFixture) callTool(t *testing.T, name string, args map[string]any) *mcp.CallToolResult {
+	t.Helper()
+	res, err := f.session.CallTool(context.Background(), &mcp.CallToolParams{Name: name, Arguments: args})
+	if err != nil {
+		t.Fatalf("%s: %v", name, err)
+	}
+	return res
+}
+
+func toolText(res *mcp.CallToolResult) string {
+	return res.Content[0].(*mcp.TextContent).Text
+}
+
+func echoStatus(status int, body string) func(http.ResponseWriter, *http.Request) {
+	return func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(status)
+		_, _ = io.WriteString(w, body)
+	}
+}
+
+func TestMCPToolsMapToTheAPIWithTheKey(t *testing.T) {
+	f := newMCPFixture(t, false, echoStatus(200, `{"ok":true}`))
+	cases := []struct {
+		tool   string
+		args   map[string]any
+		method string
+		target string
+		body   string
+	}{
+		{"list_articles", map[string]any{"page": 2, "size": 5, "status": "draft", "q": "tile"}, "GET", "/v1/article/?page=2&q=tile&size=5&status=draft", ""},
+		{"get_article", map[string]any{"id": 7, "format": "html"}, "GET", "/v1/article/7?format=html", ""},
+		{"create_article", map[string]any{"title": "Grout tips", "body": "<p>x</p>"}, "POST", "/v1/article/", `{"body":"<p>x</p>","title":"Grout tips"}`},
+		{"update_article_body", map[string]any{"id": 7, "body": "<p>y</p>"}, "PATCH", "/v1/article/7", `{"body":"<p>y</p>"}`},
+		{"publish_article", map[string]any{"id": 7}, "PATCH", "/v1/article/7/publish", ""},
+		{"check_seo", map[string]any{"id": 7}, "POST", "/v1/article/7/seo/check", `{}`},
+		{"list_media", map[string]any{"filter": "unused"}, "GET", "/v1/media/?filter=unused", ""},
+		{"list_sites", map[string]any{}, "GET", "/v1/site/", ""},
+		{"get_sitemap", map[string]any{"key": "renew-blog", "size": 25}, "GET", "/v1/site/renew-blog/sitemap?size=25", ""},
+	}
+	for _, tc := range cases {
+		res := f.callTool(t, tc.tool, tc.args)
+		if res.IsError || toolText(res) != `{"ok":true}` {
+			t.Fatalf("%s: error=%v text=%q", tc.tool, res.IsError, toolText(res))
+		}
+		call := f.last()
+		if call.method != tc.method || call.target != tc.target || !sameJSONBody(call.body, tc.body) || call.auth != "Bearer rcms_key" {
+			t.Errorf("%s sent %q want %q", tc.tool, call.body, tc.body)
+		}
+	}
+}
+
+func TestMCPReportsAPIErrorsAsToolErrors(t *testing.T) {
+	f := newMCPFixture(t, false, echoStatus(403, "This action needs a real session."))
+	res := f.callTool(t, "list_sites", map[string]any{})
+	if !res.IsError || toolText(res) != "HTTP 403: This action needs a real session." {
+		t.Fatalf("error=%v text=%q", res.IsError, toolText(res))
+	}
+}
+
+func TestMCPUploadsMultipartFromBase64(t *testing.T) {
+	f := newMCPFixture(t, false, echoStatus(201, `{"id":1}`))
+	res := f.callTool(t, "upload_media", map[string]any{"base64": base64.StdEncoding.EncodeToString([]byte("PNGDATA")), "filename": "wall.png"})
+	if res.IsError {
+		t.Fatal(toolText(res))
+	}
+	call := f.last()
+	if !strings.HasPrefix(call.ctype, "multipart/form-data") || !strings.Contains(call.body, `name="file"; filename="wall.png"`) || !strings.Contains(call.body, "PNGDATA") {
+		t.Errorf("sent %+v", call)
+	}
+	if res := f.callTool(t, "upload_media", map[string]any{}); !res.IsError {
+		t.Error("an upload without content must fail")
+	}
+}
+
+func TestMCPDestructiveToolsNeedTheFlag(t *testing.T) {
+	names := func(f *mcpFixture) map[string]bool {
+		found := map[string]bool{}
+		for tool, err := range f.session.Tools(context.Background(), nil) {
+			if err != nil {
+				t.Fatal(err)
+			}
+			found[tool.Name] = true
+		}
+		return found
+	}
+	safe := names(newMCPFixture(t, false, echoStatus(200, "")))
+	if safe["delete_article"] || safe["delete_media"] || !safe["publish_article"] || len(safe) != 10 {
+		t.Errorf("default tools: %v", safe)
+	}
+	f := newMCPFixture(t, true, echoStatus(204, ""))
+	if all := names(f); !all["delete_article"] || !all["delete_media"] {
+		t.Errorf("flagged tools: %v", all)
+	}
+	if res := f.callTool(t, "delete_article", map[string]any{"id": 3}); res.IsError || toolText(res) != "HTTP 204" || f.last().method != "DELETE" {
+		t.Errorf("delete: %q %+v", toolText(res), f.last())
+	}
+}
+
+func TestMCPServesTheInstanceDocumentationAsAResource(t *testing.T) {
+	f := newMCPFixture(t, false, func(w http.ResponseWriter, r *http.Request) {
+		if r.URL.Path != "/llms-full.txt" {
+			w.WriteHeader(404)
+			return
+		}
+		_, _ = io.WriteString(w, "# RenewCMS documentation")
+	})
+	res, err := f.session.ReadResource(context.Background(), &mcp.ReadResourceParams{URI: "renewcms://docs/llms-full.txt"})
+	if err != nil {
+		t.Fatal(err)
+	}
+	if res.Contents[0].Text != "# RenewCMS documentation" {
+		t.Errorf("got %q", res.Contents[0].Text)
+	}
+}
+
+func sameJSONBody(got string, want string) bool {
+	if got == want {
+		return true
+	}
+	var a, b any
+	if json.Unmarshal([]byte(got), &a) != nil || json.Unmarshal([]byte(want), &b) != nil {
+		return false
+	}
+	return reflect.DeepEqual(a, b)
+}

web/src/data/apiCatalogue.ts

@@ -28,6 +28,7 @@ export interface ApiEndpoint {
 	bodySample: Record<string, unknown> | null
 	errors: ApiError[]
 	response: string
+	status: number
 	rateLimited: boolean
 }
 
@@ -542,6 +543,7 @@ function endpoint(
 		bodySample: null,
 		errors,
 		response,
+		status: response === NO_CONTENT_RESPONSE ? 204 : 200,
 		rateLimited: false,
 		...extra,
 	}
@@ -638,6 +640,7 @@ export const API_GROUPS: ApiGroup[] = [
 						title: 'Choosing tiles for a small bathroom',
 						body: 'Small rooms show every grout line.',
 					},
+					status: 201,
 				},
 			),
 			endpoint(
@@ -886,6 +889,7 @@ export const API_GROUPS: ApiGroup[] = [
 				json(mediaItem()),
 				{
 					pathId: null,
+					status: 201,
 					bodyKind: 'multipart',
 					body: [
 						{
@@ -1156,6 +1160,7 @@ export const API_GROUPS: ApiGroup[] = [
 				],
 				json(invite()),
 				{
+					status: 201,
 					bodyKind: 'json',
 					body: [
 						{

web/vite.config.ts

@@ -21,6 +21,10 @@ export default defineConfig({
 			'/v1': 'http://localhost:8080',
 			'/healthz': 'http://localhost:8080',
 			'/static': 'http://localhost:8080',
+			'/llms.txt': 'http://localhost:8080',
+			'/llms-full.txt': 'http://localhost:8080',
+			'/llms/': 'http://localhost:8080',
+			'/openapi.json': 'http://localhost:8080',
 		},
 	},
 	plugins: [