feat: agent readiness for maple.dev — OpenAPI, MCP manifest, Accept-aware 404s, trust pages

[Makisuo]

Summary

Raises maple.dev's machine-readability for agents (audit baseline 73/100). Product behaviour and visual design are unchanged for browsers.

Landing (apps/landing)

• src/worker.ts: 404 representation follows Accept — HTML for browsers, a short markdown note with recovery links (llms.txt, sitemap, docs, OpenAPI, MCP manifest, about/contact) for everything else, and the v2 JSON error envelope under /api, /v1, /v2, /rpc, /mcp. / gets a markdown twin (/index.md); HTML pages with a twin send Vary: Accept + Link: <…md>; rel="alternate"; type="text/markdown".
• New endpoints: /openapi.json (OpenAPI 3.1 from MapleApiV2), /.well-known/mcp.json + /.well-known/mcp/server.json (MCP registry server.json, validated against the 2025-12-11 schema), /about, /contact (+ .md twins), docs /docs/api and /docs/mcp (the API's OAuth metadata already linked /docs/mcp).
• Organization JSON-LD: legalName, email, contactPoint[], address; llms.txt: API / MCP server / Company sections, Homebrew + releases for the CLI; robots.txt names the machine-readable entry points; small "where to look next" row on the HTML 404.

API (apps/api)

• routes/discovery.http.ts: /openapi.json, /v2/openapi.json, /.well-known/mcp.json, JSON index at /, and a wildcard catch-all answering unmatched routes with the v2 RouteNotFound envelope instead of an empty 404.

Domain (packages/domain)

• @maple/domain/mcp-manifest (single source of the server.json; McpServer version reads the same constant) and V2RouteNotFound.

Test plan

• apps/landing: new vitest suite (worker negotiation/404s, OpenAPI + MCP endpoints, trust pages) — 22 passing
• packages/domain: mcp-manifest.test.ts + existing openapi.test.ts — 43 passing
• apps/api: discovery.http.test.ts (spec, manifest, catch-all precedence) + mcp/app.test.ts — passing; tsc --noEmit clean
• astro build ok; built site run under the real worker locally and curl-verified every endpoint (404 markdown/HTML/JSON by Accept, Vary/Link headers, twins, manifests)

Open decisions (not in this PR)

• Postal address in the Organization schema is country-level only (US).
• Support contact uses support@maple.dev (already in the OpenAPI info.contact); privacy/legal stay on @getmaple.dev.
• Registering dev.maple/maple in the MCP registry and publishing the CLI to npm need account access.

---

^{Need help on this PR? Tag @codesmith-bot with what you need. Autofix is disabled.}

[github-actions]

🍁 Maple PR preview

Note

Preview resources were removed when this pull request closed.

Final commit c7c34c0 · View workflow run