Skip to content

Home

Jump to bottom
Jm Rohmer edited this page Jul 5, 2026 · 13 revisions

mcp-hugo-server-go Wiki

This wiki is the operational notebook for mcp-hugo-server-go, the canonical unified MCP server for the Arleo Hugo site.

The repository contains the Go MCP/OAuth server. The live public setup also depends on the Hugo VM, OpenResty vhosts, and static discovery files served by www.arleo.eu.

What This Repository Is For

mcp-hugo-server-go exposes a Hugo site through the Model Context Protocol with strict scope separation:

  • anonymous: safe public discovery and limited read-only access
  • content.read: authenticated read tools
  • content.write: content creation and update tools
  • site.admin: build, validation, and site operation tools
  • system.admin: sensitive system diagnostics
  • mcp: deprecated compatibility alias for content.read only

The server is intended to be compatible with:

  • Claude Desktop and Claude.ai remote MCP connectors
  • ChatGPT MCP/custom connector flows
  • OAuth/OIDC discovery
  • MCP server cards
  • IsItAgentReady Agent-Native discovery checks

Live Endpoints

Purpose URL
Public site https://www.arleo.eu
MCP endpoint https://mcp.arleo.eu/mcp
OAuth issuer https://mcp.arleo.eu
Authorization metadata https://mcp.arleo.eu/.well-known/oauth-authorization-server
Protected resource metadata https://mcp.arleo.eu/.well-known/oauth-protected-resource
MCP server card https://mcp.arleo.eu/.well-known/mcp/server-card.json
Auth guide https://www.arleo.eu/auth.md and https://mcp.arleo.eu/auth.md

Production Topology

The live setup uses two hostnames with different responsibilities:

  • www.arleo.eu is the Hugo site and static AgentReady discovery surface.
  • mcp.arleo.eu is the MCP/OAuth server.

Traffic path:

Cloudflare
  -> host OpenResty
    -> www.arleo.eu -> Hugo VM Nginx -> Hugo static files
    -> mcp.arleo.eu -> Hugo VM mcp-hugo-server-go service

The current reference config examples live in the repository:

  • docs/examples/agent-ready/openresty-www.arleo.eu.conf
  • docs/examples/agent-ready/openresty-mcp.arleo.eu.conf
  • docs/examples/agent-ready/nginx-hugo-vm.conf
  • docs/examples/agent-ready/static/auth.md
  • docs/examples/agent-ready/static/.well-known/oauth-protected-resource
  • docs/examples/agent-ready/static/llms.txt
  • docs/examples/agent-ready/static/robots.txt

Important Pages

Release Rule

Do not tag or release if any of these fail:

go test ./...
go test -race ./...
go vet ./...
staticcheck ./...
govulncheck ./...
gitleaks detect --no-banner --redact --source .
SMOKE_LIVE=1 ./scripts/check-agent-ready.sh
SMOKE_LIVE=1 ./scripts/smoke-agent-interop.sh

For AgentReady releases, also scan https://www.arleo.eu on IsItAgentReady and require API/Auth/MCP/Skill Discovery to stay at 7/7, unless the release explicitly documents why that external score changed.

Security Notes

  • Never publish OAuth client secrets, bearer tokens, Cloudflare tokens, or private host config containing credentials.
  • Docs and wiki pages must use redacted examples only.
  • Write/admin tools must never become anonymous.
  • Discovery can be public; authorization must still be enforced on both tools/list and tools/call.

Clone this wiki locally