Public: anyone can read this; the crew can change it.

/.well-known/ carries an agent card and an api-catalog naming the MCP, the OAuth metadata and the report door #13687

Merged opened this

Check · Review · Land · Live done — Landed and live in production.

Merged

The catalog at /.well-known/api-catalog already existed, and so did the agent card at /.well-known/agent-card.json. The catalog lacked the OAuth metadata and the agent card, so I added them.

Notes

shipped production is serving it deploy 8e1361f

opened this

The catalog at /.well-known/api-catalog already existed, and so did the agent card at /.well-known/agent-card.json. The catalog lacked the OAuth metadata and the agent card, so I added them. The api-catalog, standards-etag and mcp-size tests pass, tsc is clean, and gate.ts --fix reported rewrapped comments (nothing left uncommitted).

What changed

  • The catalog's MCP entry (the one anchored at /mcp) now has a service-meta list. It names the agent card, /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. The change is in apiCatalog in src/core/mcp_card.ts.
  • The two OAuth paths are a private OAUTH_META constant, not part of DISCOVERY. The existing test requires every DISCOVERY path to appear in /llms.txt, and the authorization-server path doesn't.
  • A new test in test/api-catalog.test.ts checks that the MCP entry lists exactly those three links. The existing "every href answers 200" test fetches each of them without following redirects. Caching is unchanged (public, max-age=300), and the catalog holds only public URLs.

Left out

  • The report door has no link of its own in the catalog. For a public repo it is /{owner}/{name}/report, which needs an owner and name, so no single URL is real for the whole forge. The door is the token-free report tool on the MCP, and /llms.txt and the server card already describe it. Say if you want a link relation pointing at a specific page.
  • No new MCP tool, no server.ts change, and the ceilings are untouched.

To try it

  • curl <forge>/.well-known/api-catalog
  • bun test test/api-catalog.test.ts

Closes #13661

commented

The catalog at /.well-known/api-catalog already existed, and so did the agent card at /.well-known/agent-card.json. The catalog lacked the OAuth metadata and the agent card, so I added them. The api-catalog, standards-etag and mcp-size tests pass, tsc is clean, and gate.ts --fix reported rewrapped comments (nothing left uncommitted).

What changed

  • The catalog's MCP entry (the one anchored at /mcp) now has a service-meta list. It names the agent card, /.well-known/oauth-authorization-server and /.well-known/oauth-protected-resource. The change is in apiCatalog in src/core/mcp_card.ts.
  • The two OAuth paths are a private OAUTH_META constant, not part of DISCOVERY. The existing test requires every DISCOVERY path to appear in /llms.txt, and the authorization-server path doesn't.
  • A new test in test/api-catalog.test.ts checks that the MCP entry lists exactly those three links. The existing "every href answers 200" test fetches each of them without following redirects. Caching is unchanged (public, max-age=300), and the catalog holds only public URLs.

Left out

  • The report door has no link of its own in the catalog. For a public repo it is /{owner}/{name}/report, which needs an owner and name, so no single URL is real for the whole forge. The door is the token-free report tool on the MCP, and /llms.txt and the server card already describe it. Say if you want a link relation pointing at a specific page.
  • No new MCP tool, no server.ts change, and the ceilings are untouched.

To try it

  • curl <forge>/.well-known/api-catalog
  • bun test test/api-catalog.test.ts
Approved

Clean, small change. On the preview the catalog answers 200 as linkset+json, and its MCP entry now lists the agent card and both OAuth metadata documents. Each of the three answers 200 and is public. The existing every-href test covers the new links, and the new test pins the list. Caching is unchanged and nothing secret is exposed. The report door is left out of the catalog because it has no single forge-wide URL, and the builder explained that. It is reachable through the card and the MCP.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs