Class: AgentDiscoveryController

Inherits:
ActionController::Base
  • Object
show all
Defined in:
app/controllers/agent_discovery_controller.rb

Overview

Serves the agent-facing discovery surface that complements the RFC 9727 API
catalog (ApiCatalogController) and the OAuth discovery metadata
(OauthDiscoveryController): a human/agent-readable auth guide, the MCP
server card, and an Agent Skills discovery index. Together with /robots.txt,
/llms.txt, and the OAuth/api-catalog well-knowns, these are what
isitagentready.com (and other agent crawlers) probe.

Four sibling endpoints, all mounted at the top level (ahead of the
subdomain-scoped draws and the locale scope) so they answer on every
WarmlyYours origin without the /en-US/ locale redirect — mirroring /up,
/robots.txt, and /.well-known/api-catalog:

  1. Auth guide — GET /auth.md
    Markdown (auth.md) describing how an
    agent authenticates: OAuth 2.1 (authorization code + PKCE) against the MCP
    gateway, with RFC 7591 dynamic client registration. Points at the existing
    OAuth discovery metadata rather than restating it.

  2. MCP Server Card (SEP-1649) — GET /.well-known/mcp/server-card.json
    serverInfo, transport endpoint, and capabilities for the gateway at
    MCP_URL. The name/version/protocolVersion mirror the live server
    built in config.ru — keep them in sync if that server's identity changes.

  3. Agent Skills index (RFC v0.2.0) — GET /.well-known/agent-skills/index.json
    A $schema + skills array. Each entry's digest is the SHA-256 of the
    served artifact; here that artifact is PRODUCT_DISCOVERY_SKILL, served by
    endpoint (4), so the digest is computed over the exact bytes we return.

  4. Skill artifact — GET /.well-known/agent-skills/warmlyyours-product-discovery/SKILL.md
    The single SKILL.md the index references.

Inherits from ActionController::Base (not ApplicationController) so no
auth/locale/session filters run — the surface must be reachable
unauthenticated and locale-free on every host, exactly like
ApiCatalogController and RobotsController.

See Also:

Constant Summary collapse

CACHE_TTL =

Edge/browser cache TTL shared by all documents. They change only on deploy
and are cheap to regenerate, so a modest public TTL is plenty.

1.hour
MCP_SERVER_NAME =

MCP gateway identity — MUST match the MCP::Server.new(...) built in
config.ru (the server card is the static advertisement of that live
server's initialize response).

'heatwave'
MCP_SERVER_VERSION =

Version reported in the server card's serverInfo — mirrors the live
MCP::Server.new(...) in config.ru.

'1.0.0'
MCP_PROTOCOL_VERSION =

MCP protocol version the gateway speaks — mirrors the live
MCP::Server.new(...) in config.ru.

'2025-06-18'
PRODUCT_DISCOVERY_SKILL =

Identifier of the one skill the discovery index advertises. Lowercase
alphanumeric + hyphens per the Agent Skills Discovery RFC.

'warmlyyours-product-discovery'
PRODUCT_DISCOVERY_SKILL_MD =

The SKILL.md artifact, verbatim. Served by #skill and digested by
#agent_skills — the digest is computed over this exact string, so the
sha256: in the index always matches the bytes we return. Edit the body
and the digest updates automatically; no second copy to keep in sync.

<<~MARKDOWN
  ---
  name: warmlyyours-product-discovery
  description: >-
    Discover and reason about WarmlyYours radiant-heating products, content,
    and tools. Use the Markdown/llms.txt content surface for catalog and
    article text, the RFC 9727 API catalog for machine endpoints, and the
    authenticated MCP gateway for live tools (content search, etc.).
  license: Proprietary
  ---

  # WarmlyYours Product Discovery

  WarmlyYours (https://www.warmlyyours.com) sells radiant floor heating,
  snow melting, towel warmers, and related controls. This skill tells an
  agent where the machine-readable surfaces live.

  ## Content (read)

  - `GET /llms.txt` — llmstxt.org manifest of the primary pages and articles.
  - Append `.md` (or send `Accept: text/markdown`) to most marketing/content
    URLs to receive a clean Markdown rendering instead of HTML.
  - `GET /en-US/sitemap.xml` and `GET /en-CA/sitemap.xml` — full URL inventory.

  ## API (read)

  - `GET /.well-known/api-catalog` — RFC 9727 linkset of public APIs.
  - `GET /openapi.json` — OpenAPI 3.1 description (`service-desc`).
  - `GET /api-docs` — human-readable API documentation (`service-doc`).

  ## Tools (MCP)

  The Model Context Protocol gateway at `https://mcp.warmlyyours.com` speaks
  Streamable HTTP with OAuth 2.1 auth (see `/auth.md`). It currently serves
  internal WarmlyYours tooling only; public agent tools are planned. Check the
  `access` block in `/.well-known/mcp/server-card.json` for current availability.

  ## Quotes

  Project/quote builders are linked from the product pages (e.g.
  `/en-US/floor-heating/quote-builder`). A public quote API is planned but not
  yet published; until then, drive the on-page builder.
MARKDOWN

Instance Method Summary collapse

Instance Method Details

#agent_skills ⇒ void

This method returns an undefined value.

Agent Skills Discovery index (RFC v0.2.0).



134
135
136
 
# File 'app/controllers/agent_discovery_controller.rb', line 134

def agent_skills
  render_document agent_skills_document
end

#auth_md ⇒ void

This method returns an undefined value.

auth.md agent registration guide. Markdown with an H1 containing
"auth.md", and a fenced agent_auth block (skill / register_uri /
registration methods) for machine parsing.



120
121
122
 
# File 'app/controllers/agent_discovery_controller.rb', line 120

def auth_md
  render_markdown auth_md_document
end

#mcp_server_card ⇒ void

This method returns an undefined value.

MCP Server Card (SEP-1649): serverInfo, transport endpoint, capabilities.



127
128
129
 
# File 'app/controllers/agent_discovery_controller.rb', line 127

def mcp_server_card
  render_document mcp_server_card_document
end

#skill ⇒ void

This method returns an undefined value.

The single SKILL.md artifact the index references and digests.



141
142
143
 
# File 'app/controllers/agent_discovery_controller.rb', line 141

def skill
  render_markdown PRODUCT_DISCOVERY_SKILL_MD
end