mcp-hugo-server-go

Canonical unified MCP server for Hugo sites.

Public endpoint: https://mcp.arleo.eu/mcp

This MCP is far more than a remote Markdown editor for Hugo: it's an intelligent content-management interface. It gives AI agents structured understanding and safe operations on a Hugo site. Example site using this MCP: www.arleo.eu.

Ce MCP est bien plus qu'un éditeur à distance de Markdown pour Hugo : il est une interface de gestion intelligente du contenu. Il donne aux agents IA une compréhension structurée et des opérations sûres sur un site Hugo. Exemple de site utilisant ce MCP : www.arleo.eu.

Content mostly written with Claude Code and Codex. / Contenu majoritairement codé avec Claude Code et Codex.

What it does

mcp-hugo-server-go exposes a Hugo site through the Model Context Protocol with public discovery, OAuth-backed scopes, and strict separation between read, write, and admin operations.

It is the unified successor of:

• hugo-public-mcp for public discovery, OAuth, and auth.md
• hugo-mcp-go for content and administration tools
• mcp-runtime-go for MCP transport/runtime behavior

Access model

The server enforces exactly two internal scopes (#450):

• read: full visibility, including drafts and other source-only/pre-publication content. Requires no secret and is auto-registrable (self-service, the same mechanism the old reader profile used).
• write: requires a registered OAuth client (client_id + client_secret). Implies read — a write token gets everything, including build/site/integrity/ diagnostic operations that used to require a separate site.admin scope.

Legacy clients may still send any scope string from the pre-#450 four-tier model (reader, content.read, content.write, site.admin, system.admin, ...) or the original mcp alias. The server accepts all of them as deprecated compatibility aliases, resolved to read/write via oauth.CanonicalScope, but only read and write are ever advertised as canonical scopes. See docs/mcp-contract.md §6.12 for the full mapping and rationale.

Tool inventory

The current tool inventory is documented in docs/tools.md and should be treated as the source of truth for scope mapping and tool naming.

Slug formats: slug vs source_key

Tool payloads use two different shapes for the same page identity, and mixing them up is a recurring source of confusion (#610):

• slug on read-tool outputs (list_pages, search_pages, get_recent_posts, get_sitemap, get_feed, get_page, etc.) is the canonical public URL form, e.g. /posts/my-article/ (or /en/posts/my-article/ for a non-default language).
• slug on write-tool inputs (create_page, update_page, delete_page, upload_page_asset, delete_page_asset) expects the source-relative source_key form, e.g. posts/my-article — no leading/trailing slashes, no language prefix. (suggest_links, a read-scoped tool, is the exception: its slug input takes the public URL form, matching read-tool outputs.)
• To avoid reformatting by hand, every read tool that returns slug also returns source_key alongside it, in exactly the form the write tools' slug input expects. Feed source_key from a read-tool result straight into a write tool's slug parameter.

See docs/mcp-contract.md for the full per-tool field reference.

Recommended authoring workflow

For a fresh article, the suggested call order is:

1. list_content_types — confirm the content type and required front matter.
2. suggest_links(tags, categories, body) — run against your draft tags/body before writing, to surface internal-linking candidates while the content is still easy to adjust (#623).
3. create_page — write the page (create_page's own description also cross-references suggest_links as a pre-write step).
4. verify_publication — confirm the change actually went live after a build.

Multi-page editorial changes

When a single logical change spans several pages (e.g. renaming a category across an entire series, or a coordinated cross-linking pass), don't call publish_changes after each page — it triggers a full site build, so publishing once per page instead of once for the whole batch costs a build per page for no benefit and makes a half-applied batch briefly visible on the live site between builds.

The recommended shape (#631):

1. For each page: plan_content_change → review the returned preview/diff → if it looks right, apply_content_plan immediately. Apply each plan right after previewing it rather than collecting previews for the whole batch first — plan_content_change's plan_id is a single-use preview with a 5-minute TTL (data.plan_expires_at), so a plan-everything-then-apply-everything ordering risks the earliest plans expiring before you get to them on a large batch.
2. Track the plan_id/revision returned for each page as you go — apply_content_plan fails closed with revision_conflict if a page changed since its plan was made, and rollback_change (per page, using the tracked revision) is how you undo any single page in the batch if something downstream turns out wrong.
3. Once every page in the batch has been applied, call publish_changes once for the whole site.

No new orchestration tool is needed for this — apply_content_plan's existing per-page revision pinning and rollback_change's per-page undo already compose into this pattern; a batch-level primitive would just be a wrapper around the same three calls.

Security model

• Anonymous callers and read-scoped callers see the same tool set — read carries no additional visibility restriction (#450).
• Reader-facing discovery is provider-neutral: capability differences depend on token trust, not on whether the client is ChatGPT, Claude, Gemini, Le Chat, Copilot, or another MCP consumer.
• An OAuth bearer token with write scope is required for mutating and operational tools.
• write is never exposed to anonymous or read-scoped callers.
• Legacy scope aliases (mcp, reader, content.read, content.write, site.admin, system.admin, ...) are accepted for compatibility, but only read/write are advertised as canonical.

Claude and MCP

Claude Desktop and Claude.ai can connect directly to the public MCP endpoint above.

The server card and OAuth discovery advertise canonical internal scopes only:

• read
• write

They also publish additive reader / operator access-profile metadata so clients can understand the simplified external contract without treating those profile names as direct OAuth scope strings. (reader's internal_scopes is now ["read"] and operator's is ["read", "write"].)

Public compatibility discovery for external scanners lives on the website surface as well:

• https://www.arleo.eu/auth.md
• https://www.arleo.eu/.well-known/oauth-protected-resource

That www surface is served through Hugo static files plus OpenResty, not only through the Go MCP runtime. The operator recovery notes live in docs/agent-ready-howto.md.

Validation

The repository is expected to pass:

go test ./...
go test -race ./...
go vet ./...
staticcheck ./...
go build ./...
govulncheck ./...
gitleaks detect --no-banner --redact --source .

Release flow

Production promotion is intentionally split into three explicit stages:

1. Merge to main and wait for CI to go green.
2. Run Deploy to Production for the exact main commit you want live.
3. Run Release only after production deployment succeeds. The release workflow refuses to publish unless:
   • the requested ref resolves to the current origin/main HEAD;
   • CHANGELOG.md contains the requested version;
   • README.md still uses dynamic latest-release metadata;
   • the target SHA already has a successful production deployment record.

Project lineage

• hugo-public-mcp - public agent-ready discovery, OAuth, and auth.md
• hugo-mcp-go - Hugo content and administration tools
• mcp-runtime-go - MCP runtime and transport foundation

mcp-hugo-server-go is the canonical unified successor of those repositories.

Architecture

mcp.arleo.eu
├── read (anonymous or self-service token)   full content visibility, including drafts
└── write (registered OAuth client only)     content creation/editing plus build, site, integrity, and diagnostic operations

The MCP transport is streamable HTTP at /mcp.

Security contact

To report a vulnerability, set security_contact in your server config (e.g., security_contact: "mailto:security@example.com"). This populates /.well-known/security.txt per RFC 9116. The server requires Contact and Expires — Canonical is set automatically from site_url (or oauth.issuer if site_url is blank).

Agent identity flow

Agents authenticate via the identity assertion flow:

1. Agent POSTs to /agent/identity with {"type":"anonymous"}.
2. If oauth.allow_reader_self_registration is enabled, the response is immediately exchangeable at /token (grant_type=urn:ietf:params:oauth:grant-type:jwt-bearer) for a read Bearer token.
3. If self-registration is disabled, the response includes claim_token + verification_uri; the agent POSTs to /agent/identity/claim, then an operator visits the verification_uri (or POSTs to /agent/identity/verify) with a write Bearer token and the claim_token to approve.
4. The approved assertion then exchanges at /token for the configured read token.

This flow yields the internal read scope. The published reader / operator profile language is an external contract layer over the same underlying read/write scope strings, not a separate mechanism.

The POST to /agent/identity/verify requires operator authentication via the Authorization: Bearer <admin-token> header (or admin_token form field for browser submissions).

API reference

Documentation

• Operator guide
• AgentReady 100% HowTo
• MCP contract
• Agent tool matrix
• Invariant matrix
• Release checklist
• Staging runbook
• Tool inventory
• Contributing guide
• Code of conduct
• Security policy
• Operations wiki