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

scout/forge:scout/14102-well-known-mcp-lists-the-forge-mcp-serve → main 5 commits fork 3 threads · 3 unresolved

  • Merged. scout/14102-well-known-mcp-lists-the-forge-mcp-serve was merged into main as e266eee.

Review

Sign in to review this change.
6 files changed +99 −7
docs/MCP.md +2
@@ -483,6 +483,8 @@ Any MCP client that can send a header works the same way.
483483
484484 `/.well-known/mcp/server-card.json` is the small one (the MCP server-card draft, SEP-1649; its names may change): `name`, `version`, `endpoint`, `transport`, `authorization` (read from `/.well-known/oauth-protected-resource`), and only the tools a stranger may call. Public, cached an hour, linked from `/llms.txt` and `mcp` in `/api/v1/here`.
485485
486 `/.well-known/mcp` is the one-fetch door: `name`, `version`, `mcp` (the URL), `oauth.authorization_endpoint`, `oauth.token_endpoint` and `tools` (the live count); public, cached five minutes.
487
486488 `/.well-known/mcp.json` names the server (`name`, `version`, `endpoint`,
487489 `transport`, `protectedResourceMetadata`, `documentation`, `openapi`,
488490 `tokenFreeTools`)
src/core/mcp_card.ts +25
@@ -47,9 +47,16 @@ export const DISCOVERY = {
4747 agentCard: "/.well-known/agent-card.json",
4848 catalog: "/.well-known/api-catalog",
4949 mcp: "/mcp",
50 mcpDoor: "/.well-known/mcp",
5051 api: "/api/v1",
5152 } as const;
5253
54 /**
55 * The OAuth endpoints the metadata documents and the door name; not discovery documents, so
56 * /llms.txt need not list them.
57 */
58 export const OAUTH_ENDPOINTS = { authorize: "/oauth/authorize", token: "/oauth/token" } as const;
59
5360 /**
5461 * The OAuth metadata documents the catalog names (llms.txt names the resource one by its own line).
5562 */
@@ -278,6 +285,24 @@ export function mcpCard(origin: string, repo: string | undefined, ssh: boolean,
278285 };
279286 }
280287
288 /**
289 * The one-fetch door at /.well-known/mcp: the server, where it is, where to sign in and how many
290 * tools it has. The count is the live registry's, the endpoints are the ones the OAuth metadata
291 * documents name (both read the paths from `DISCOVERY`).
292 */
293 export function mcpDoor(origin: string, ssh: boolean, now: Running = running()) {
294 return {
outdated

Endpoint paths are typed here and again in src/http/oauth.ts. Export them from one place and use that in both, so the door is true by construction, not only by the test.

295 name: "forge",
296 version: now.version,
297 mcp: mcpPointers(origin).url,
298 oauth: {
299 authorization_endpoint: `${origin}${OAUTH_ENDPOINTS.authorize}`,
300 token_endpoint: `${origin}${OAUTH_ENDPOINTS.token}`,
301 },
302 tools: shownTools(ssh).length,
303 };
304 }
305
281306 /**
282307 * The small server card at /.well-known/mcp/server-card.json. It follows the
283308 * MCP server-card draft (SEP-1649, a draft: field names may change), keeping
src/http/oauth.ts +5 −5
@@ -9,7 +9,7 @@
99 * checked on its POST.
1010 */
1111 import type { App } from "../app.ts";
12 import { protectedResource } from "../core/mcp_card.ts";
12 import { OAUTH_ENDPOINTS, protectedResource } from "../core/mcp_card.ts";
1313 import {
1414 createClient,
1515 OAUTH_SCOPES,
@@ -187,8 +187,8 @@ export function oauthRoutes(router: Router<Handler>): void {
187187 json(
188188 {
189189 issuer: ctx.url.origin,
190 authorization_endpoint: `${ctx.url.origin}/oauth/authorize`,
191 token_endpoint: `${ctx.url.origin}/oauth/token`,
190 authorization_endpoint: `${ctx.url.origin}${OAUTH_ENDPOINTS.authorize}`,
191 token_endpoint: `${ctx.url.origin}${OAUTH_ENDPOINTS.token}`,
192192 revocation_endpoint: `${ctx.url.origin}/oauth/revoke`,
193193 userinfo_endpoint: `${ctx.url.origin}/oauth/userinfo`,
194194 jwks_uri: `${ctx.url.origin}/oauth/jwks`,
@@ -214,8 +214,8 @@ export function oauthRoutes(router: Router<Handler>): void {
214214 json(
215215 {
216216 issuer: ctx.url.origin,
217 authorization_endpoint: `${ctx.url.origin}/oauth/authorize`,
218 token_endpoint: `${ctx.url.origin}/oauth/token`,
217 authorization_endpoint: `${ctx.url.origin}${OAUTH_ENDPOINTS.authorize}`,
218 token_endpoint: `${ctx.url.origin}${OAUTH_ENDPOINTS.token}`,
219219 revocation_endpoint: `${ctx.url.origin}/oauth/revoke`,
220220 registration_endpoint: `${ctx.url.origin}/oauth/register`,
221221 scopes_supported: [...OAUTH_SCOPES],
src/http/server.ts +2
@@ -219,6 +219,7 @@ import {
219219 securityTxt,
220220 apiCatalogJson,
221221 mcpJson,
outdated

Put mcpDoorJson on its own line, as the rest of this import list does.

222 mcpDoorJson,
222223 serverCardJson,
223224 agentCardJson,
224225 forgeJson,
@@ -859,6 +860,7 @@ export function buildRouter(): Router<Handler> {
859860 });
860861 // What the open web expects of a site, from the forge's own facts.
861862 router.add("GET", "/.well-known/security.txt", securityTxt);
863 router.add("GET", "/.well-known/mcp", mcpDoorJson);
862864 router.add("GET", "/.well-known/mcp.json", mcpJson);
863865 router.add("GET", "/.well-known/mcp/server-card.json", serverCardJson);
864866 router.add("GET", "/.well-known/agent-card.json", agentCardJson);
src/web/standards.ts +12 −2
@@ -54,7 +54,7 @@ import { holds } from "./feeds.ts";
5454 import { mcpToolsSection, mcpToolsVersion, readerKey, type Reader } from "./llms_tools.ts";
5555 import { threeDoors } from "./doors_words.ts";
5656 import { OAUTH_SCOPES } from "../core/oauth.ts";
57 import { agentCard, serverCard, toolsKey, apiCatalog, cardsLine, DISCOVERY, mcpCard, offeredPlugins, mcpPointers, offeredPluginRepo, pluginSource } from "../core/mcp_card.ts";
57 import { agentCard, serverCard, toolsKey, apiCatalog, cardsLine, DISCOVERY, mcpCard, mcpDoor, offeredPlugins, mcpPointers, offeredPluginRepo, pluginSource } from "../core/mcp_card.ts";
5858 import { forgeDocument } from "../core/standards_index.ts";
5959 import { TAGS } from "../contract/served.ts";
6060 import { running, shortOf, UNSTAMPED } from "../kernel/version.ts";
@@ -174,6 +174,16 @@ export async function mcpJson(ctx: Ctx): Promise<Response> {
174174 return discovery(ctx, "mcp", JSON.stringify([repo, now.version, now.commit, toolsKey(ssh)]), () => mcpCard(ctx.url.origin, repo, ssh, now), "application/json", "public, max-age=3600", true);
175175 }
176176
177 /**
178 * GET /.well-known/mcp — the one-fetch door: name, version, MCP URL, OAuth endpoints, tool count.
179 */
180 export async function mcpDoorJson(ctx: Ctx): Promise<Response> {
181 await loadMcp();
182 const now = running();
183 const ssh = sshOn(ctx.app.db);
184 return discovery(ctx, "mcp-door", JSON.stringify([now.version, toolsKey(ssh)]), () => mcpDoor(ctx.url.origin, ssh, now), "application/json", "public, max-age=300");
185 }
186
177187 /** GET /.well-known/mcp/server-card.json — the small server card (a draft; see `serverCard`).
178188 * Public, the same for every reader. */
179189 export function serverCardJson(ctx: Ctx): Response {
@@ -601,7 +611,7 @@ function renderLlmsTxt(ctx: Ctx, o: string, tell: string | undefined, running: s
601611 "",
602612 "## For agents with an account",
603613 "",
604 `- MCP: ${mcp.url} (OAuth discovery: ${mcp.oauth}; server card, a draft format: ${o}${DISCOVERY.serverCard} (fuller: ${o}${DISCOVERY.card}); A2A agent card: ${o}${DISCOVERY.agentCard})`,
614 `- MCP: ${mcp.url} (OAuth discovery: ${mcp.oauth}; server card, a draft format: ${o}${DISCOVERY.serverCard} (fuller: ${o}${DISCOVERY.card}; one fetch: ${o}${DISCOVERY.mcpDoor}); A2A agent card: ${o}${DISCOVERY.agentCard})`,
605615 `- API: ${o}${DISCOVERY.api} (the root lists the other URLs), Authorization: Bearer <token>`,
606616 `- API catalog (RFC 9727, one linkset of the above): ${o}${DISCOVERY.catalog}`,
607617 `- OpenAPI: GET ${o}${DISCOVERY.openapi}, or one slice with ?tag= (${TAGS.join(", ")})`,
test/mcp-door.test.ts added +53
@@ -0,0 +1,53 @@
1 /** /.well-known/mcp: the count and endpoints are the registry's and the OAuth metadata's. */
2 import { afterAll, beforeAll, expect, test } from "bun:test";
3 import { mkdtemp, rm } from "node:fs/promises";
4 import { tmpdir } from "node:os";
5 import { join } from "node:path";
6 import { createApp } from "../src/app.ts";
7 import { serve, type Servers } from "../src/http/server.ts";
8 import { TOOLS } from "../src/http/mcp/tools.ts";
9 import { OFFER_TOOL, REPORT_TOOL, START_TOOL } from "../src/http/mcp.ts";
10 import { sshOn } from "../src/settings/ssh.ts";
11 import { running } from "../src/kernel/version.ts";
12
13 let dataDir: string;
14 let servers: Servers;
15 let app: ReturnType<typeof createApp>;
16 let base: string;
17 beforeAll(async () => {
18 dataDir = await mkdtemp(join(tmpdir(), "forge-mcp-door-"));
19 app = createApp({ dataDir, port: 0 });
20 servers = await serve(app);
21 base = servers.url;
22 });
23 afterAll(async () => {
24 await servers.stop?.();
25 await rm(dataDir, { recursive: true, force: true });
26 });
27
28 test("answers the door, cached five minutes, with the security floor", async () => {
29 const res = await fetch(`${base}/.well-known/mcp`);
30 expect(res.status).toBe(200);
31 expect(res.headers.get("content-type")).toContain("application/json");
32 expect(res.headers.get("cache-control")).toBe("public, max-age=300");
33 expect(res.headers.get("x-content-type-options")).toBe("nosniff");
34 expect(res.headers.get("referrer-policy")).toBeTruthy();
35 expect(res.headers.get("content-security-policy")).toBeTruthy();
36 const door = (await res.json()) as any;
37 expect(door.name).toBe("forge");
38 expect(door.version).toBe(running().version);
39 expect(door.mcp).toBe(`${base}/mcp`);
40 });
41
42 test("the count equals the tools mcp.json lists and the endpoints equal the OAuth metadata", async () => {
43 const door = (await (await fetch(`${base}/.well-known/mcp`)).json()) as any;
44 const card = (await (await fetch(`${base}/.well-known/mcp.json`)).json()) as any;
outdated

Compare door.tools with the live registry (tools/list on /mcp, or the registry import) rather than mcp.json, which shares the same filter. Also drop this comment; it ends in '...' and reads as unfinished.

45 const live = [...TOOLS, REPORT_TOOL, START_TOOL, OFFER_TOOL].filter((t) => t.name !== "ssh_keys" || sshOn(app.db));
46 expect(door.tools).toBe(live.length);
47 expect(card.tools.length).toBe(live.length);
48 expect(door.tools).toBeGreaterThan(0);
49 const as = (await (await fetch(`${base}/.well-known/oauth-authorization-server`)).json()) as any;
50 expect(door.oauth.authorization_endpoint).toBe(as.authorization_endpoint);
51 expect(door.oauth.token_endpoint).toBe(as.token_endpoint);
52 expect(door.mcp).toBe(card.endpoint);
53 });

↑↓ navigate ↵ open ⌘↵ its app esc close

Keyboard shortcuts

Docs