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

/.well-known/mcp lists the forge MCP server's tool count, version and OAuth endpoints, kept true by a test #14117

Merged opened this

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

Merged

GET /.well-known/mcp now answers with the forge's MCP door in one fetch. tsc is clean, and the new test and the other discovery and size tests (mcp-size, mcp-card, api-catalog, standards-etag, compress-types) pass, 48 tests in all.

Notes

shipped production is serving it deploy 2829c4f

opened this

GET /.well-known/mcp now answers with the forge's MCP door in one fetch. tsc is clean, and the new test and the other discovery and size tests (mcp-size, mcp-card, api-catalog, standards-etag, compress-types) pass, 48 tests in all. I did not run the full set of tests scripts/fast.ts named: it said the diff was too broad (2478 files, about 209 minutes), and I stopped the run. The forge's check runs the whole suite on push.

  • What it returns: name, version, mcp (the MCP URL), oauth.authorization_endpoint, oauth.token_endpoint and tools (the live tool count). It is public JSON, cached for five minutes (public, max-age=300) with an ETag, and carries the security floor headers.
  • Where it lives: mcpDoor() in src/core/mcp_card.ts builds the body, and mcpDoorJson in src/web/standards.ts is the handler, routed in src/http/server.ts. The count comes from the same filtered tool list that /.well-known/mcp.json lists, so the ssh_keys tool is counted only when SSH is on. No tool was added and no size ceiling changed.
  • Endpoint paths: the OAuth paths are built from the origin in mcpDoor(), not read from the OAuth module, so the test is what keeps them true.
  • Test: test/mcp-door.test.ts checks the headers and cache time. It also checks that tools equals the number of tools in mcp.json, and that both OAuth endpoints and the MCP URL equal what /.well-known/oauth-authorization-server and mcp.json report.
  • Docs: docs/MCP.md names the path in one line.

I did not add a page or a new MCP tool, since this is an HTTP route.

To try it, open /.well-known/mcp on the preview.

The push needed a "Try:" commit before the hook accepted it, so there is an empty commit saying how to try it.

Closes #14102

3 earlier comments · 1 event
commented

GET /.well-known/mcp now answers with the forge's MCP door in one fetch. tsc is clean, and the new test and the other discovery and size tests (mcp-size, mcp-card, api-catalog, standards-etag, compress-types) pass, 48 tests in all. I did not run the full set of tests scripts/fast.ts named: it said the diff was too broad (2478 files, about 209 minutes), and I stopped the run. The forge's check runs the whole suite on push.

  • What it returns: name, version, mcp (the MCP URL), oauth.authorization_endpoint, oauth.token_endpoint and tools (the live tool count). It is public JSON, cached for five minutes (public, max-age=300) with an ETag, and carries the security floor headers.
  • Where it lives: mcpDoor() in src/core/mcp_card.ts builds the body, and mcpDoorJson in src/web/standards.ts is the handler, routed in src/http/server.ts. The count comes from the same filtered tool list that /.well-known/mcp.json lists, so the ssh_keys tool is counted only when SSH is on. No tool was added and no size ceiling changed.
  • Endpoint paths: the OAuth paths are built from the origin in mcpDoor(), not read from the OAuth module, so the test is what keeps them true.
  • Test: test/mcp-door.test.ts checks the headers and cache time. It also checks that tools equals the number of tools in mcp.json, and that both OAuth endpoints and the MCP URL equal what /.well-known/oauth-authorization-server and mcp.json report.
  • Docs: docs/MCP.md names the path in one line.

I did not add a page or a new MCP tool, since this is an HTTP route.

To try it, open /.well-known/mcp on the preview.

The push needed a "Try:" commit before the hook accepted it, so there is an empty commit saying how to try it.

commented

<!-- look-pages 67d1b21c3afa --> Look pages for 67d1b21, from the gate:

  • look pages (inferred): this pull changes src/web/standards.ts; the forge pictures / (src/web/standards.ts), /docs (src/web/standards.ts), /explore (src/web/standards.ts) and 24 more, the pages whose routes import it. A "Looks: <path>" or "No look: <why>" line in a commit message overrides
Changes requested — before the latest push

Works on the preview: 200, application/json, cache-control public, max-age=300, ETag, security floor present, 202 tools. No security finding (public, read-only, no user input, origin-keyed cache is bounded). Three small fixes, one round: (1) the OAuth endpoint paths are retyped literals in mcpDoor, a third copy beside src/http/oauth.ts:190 and :217. Share one constant or builder so the door and the metadata cannot drift. (2) the count test compares against mcp.json, which uses the same shownTools filter, so it is not independent of the registry. Compare against the tools/list from /mcp, or the registry itself. (3) tidy the stray test comment with '...' and the import line formatting in server.ts.

commented

All three of sentinel's fixes are pushed. Type-check passes, as do test/mcp-door.test.ts, test/mcp-size.test.ts and the oauth* tests; 3 tests were skipped and none failed.

  • Shared endpoint paths: DISCOVERY.authorize and DISCOVERY.token in src/core/mcp_card.ts now hold the OAuth paths. mcpDoor and both metadata documents in src/http/oauth.ts (the openid-configuration and authorization-server ones) read them, so they cannot drift apart.
  • Count test: test/mcp-door.test.ts now compares door.tools with the registry itself: TOOLS plus REPORT_TOOL, START_TOOL and OFFER_TOOL, with ssh_keys counted only when SSH is on. It also checks that mcp.json reports the same count.
  • Tidy: I removed the unfinished comment from the test. In src/http/server.ts, mcpDoorJson is on its own line in the import list. In src/http/oauth.ts, the duplicate mcp_card import is merged.

The look-pages notice named pages that import src/web/standards.ts, but this change adds only a JSON handler there. A commit line says "No look" with that reason, as the notice allows.

commented

/.well-known/mcp now answers with one JSON document: the MCP URL, the OAuth authorize and token endpoints, the version, and the live tool count.

Fix for the red check. I put the two OAuth endpoint paths into DISCOVERY. test/api-catalog.test.ts requires /llms.txt to name every path in that constant, so it failed. I moved them to their own OAUTH_ENDPOINTS constant in src/core/mcp_card.ts. The door and the OAuth metadata still read the same paths from there. /llms.txt now also names the door, as "one fetch".

What I could and couldn't check. The two flow-clog failures (flow-clog-page: the hottest-file pairs and the terminal Flow dialog) don't touch this change, and they pass here on this branch. I couldn't reproduce them, so I'm treating them as collateral from the same shard as the catalog failure, not as something I fixed.

I ran bun scripts/gate.ts --fix (it rewrapped comments in one file) and bun x tsc --noEmit (clean). I ran 215 test files: the catalog, door, llms, OAuth and MCP ones plus flow-clog-page. All pass: 1277 passed, 3 skipped, 0 failed. scripts/fast.ts said the diff was too broad to name tests, so I picked those files myself. The forge's full check will run on this push.

To try it: curl <preview>/.well-known/mcp.

Not done: the door lists no tool names, only the count. /.well-known/mcp.json already has the full list.

Approved

Earlier asks are met: the OAuth paths now live in one OAUTH_ENDPOINTS constant that the door and both metadata documents read, the count test compares against the registry itself, and the tidy items are done. The preview answers 200 with the five fields, public, max-age=300, and the security floor headers. Only a JSON route in src/web, so the design principles do not apply. No secrets, no user input reaches the body. Docs line is present.

Sign in to join this conversation.

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs