Everything an agent or script needs to work with Seamus Roche's site. The machine-readable spec is openapi.json; the MCP server card is /mcp/server-card.
Quickstart
- List MCP tools:
curl -X POST https://seamus.ninja/api/mcp -H 'content-type: application/json' -H 'accept: application/json, text/event-stream' -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}' - Request a token: call the
request_accesstool with a name. The reply includes the secret once. An admin approves it at /admin/tokens. - Use the token:
Authorization: Bearer <token>on https://seamus.ninja/api/mcp, or POST to https://seamus.ninja/api/mcp/<token>./mcpis an alias of/api/mcp. - Read the site as Markdown: send
Accept: text/markdownto any public page, or fetch llms-full.txt.
Authentication
- Tokens are static bearer secrets (
pls_<site>_<random>) created byrequest_accessand stored hashed. They start pending; until an admin approves, every other tool answers with an explanation instead of acting. - Tokens can be revoked by an admin at any time. There is no OAuth flow and no self-service key page; the MCP tool is the key request.
- The admin UI at /admin uses HTTP Basic Auth for family members only.
MCP tools
request_access(name)— create a pending token (no auth).check_access()— token status.create_upload_link(maxFiles?, note?)— 24-hour drag-and-drop upload page URL.submit_media_from_url(url, caption?, tags?, gameId?)— import a public image or video.list_my_submissions(),update_submission(id, caption?, tags?, gameId?)— manage pending submissions.list_games(season?)— game ids for tagging media.- Site editing (immediate):
get_site_profile,update_site_profile,reset_site_profile,set_hero_image. - Games and stats:
add_game,update_game,delete_game. Times:list_measurables,add_measurable,update_measurable,delete_measurable. - Published media:
list_media,update_media,delete_media.
REST endpoints
POST /api/v1/mcpandPOST /api/v1/mcp/{token}— JSON-RPC 2.0 over Streamable HTTP (operationIdsmcpRequest,mcpRequestWithPathToken)./api/mcpand/mcpare aliases.POST /api/v1/upload— client upload token handshake for the upload page (issueUploadToken).POST /api/v1/upload/complete— record an uploaded file as a pending submission (completeUpload).GET /llms.txt,/llms-full.txt,/agents.md,/mcp/server-card,/server.json,/.well-known/ai-catalog.json,/.well-known/api-catalog,/.well-known/agent-skills/index.json— discovery documents.
Every operation in the OpenAPI spec has an operationId, a description, typed parameters and typed response schemas, so it can be loaded directly as function-calling tools.
Errors
All errors are RFC 9457 problem documents with Content-Type: application/problem+json: { "type", "title", "status", "code", "detail" }. code is stable and machine-readable (for example upload_link_not_valid, endpoint_not_found); detail says how to recover. Unknown /api/* paths return a 404 problem, never an HTML page. MCP tool failures come back as JSON-RPC results with isError: true and a plain-language message.
Rate limits
Every API response carries RateLimit-Policy and RateLimit headers (draft-ietf-httpapi-ratelimit-headers). Defaults: 120 requests per minute per client; request_access 20 per hour. A 429 response includes Retry-After. Reuse tokens instead of requesting new ones.
Versioning and deprecation
Paths are versioned under /api/v1/; unversioned /api/ paths are aliases of v1. Every response carries the API-Version: 1 header and info.version in openapi.json matches. Additive changes (new optional fields, new tools) do not change the version. A breaking change ships as /api/v2/...; the previous version keeps working for at least 90 days and its responses carry Deprecation and Sunset headers with the retirement date. Changes are listed on this page.
Changelog
- 1.1.0 — site customization, games, measurables and media tools on the MCP server; admin "Site profile" page.
- 1.0.0 — initial release: MCP server, upload handshake, discovery documents, Markdown negotiation.
SDK documentation
There is no SDK or CLI to install; the surface is small enough to call directly, and any MCP client can connect. There is no sandbox: use a pending token to exercise the flow without publishing anything, since nothing goes live before an admin approves it.