@vercel/geistdocs 2.5.0 → 2.6.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (44) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +9 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/config.js +13 -0
  5. package/dist/internal/mdx-to-markdown.d.ts.map +1 -1
  6. package/dist/internal/mdx-to-markdown.js +465 -27
  7. package/dist/internal/provider-client.js +1 -1
  8. package/dist/internal/webmcp-client.d.ts +3 -4
  9. package/dist/internal/webmcp-client.d.ts.map +1 -1
  10. package/dist/internal/webmcp-client.js +9 -12
  11. package/dist/internal/webmcp.d.ts +2 -6
  12. package/dist/internal/webmcp.d.ts.map +1 -1
  13. package/dist/internal/webmcp.js +28 -79
  14. package/dist/proxy.d.ts.map +1 -1
  15. package/dist/proxy.js +10 -2
  16. package/dist/routes/agents.d.ts.map +1 -1
  17. package/dist/routes/agents.js +2 -0
  18. package/dist/routes/discovery.d.ts +3 -2
  19. package/dist/routes/discovery.d.ts.map +1 -1
  20. package/dist/routes/discovery.js +49 -1
  21. package/dist/routes/mcp.d.ts +7 -2
  22. package/dist/routes/mcp.d.ts.map +1 -1
  23. package/dist/routes/mcp.js +101 -1
  24. package/dist/routes/openapi.d.ts +64 -0
  25. package/dist/routes/openapi.d.ts.map +1 -0
  26. package/dist/routes/openapi.js +481 -0
  27. package/docs/agents.md +1 -1
  28. package/docs/llms.txt +60 -27
  29. package/docs/manifest.json +1 -1
  30. package/docs/pages/agent-readiness.md +30 -0
  31. package/docs/pages/configuration.md +1 -0
  32. package/docs/pages/migration.md +1 -0
  33. package/docs/pages/webmcp.md +27 -26
  34. package/package.json +9 -3
  35. package/template/AGENTS.md +1 -1
  36. package/template/app/[lang]/openapi.json/route.ts +6 -0
  37. package/template/app/api/mcp/route.ts +7 -0
  38. package/template/content/docs/agent-readiness.mdx +30 -0
  39. package/template/content/docs/configuration.mdx +1 -0
  40. package/template/content/docs/migration.mdx +1 -0
  41. package/template/content/docs/webmcp.mdx +27 -26
  42. package/template/geistdocs.tsx +3 -0
  43. package/template/lib/geistdocs/config.tsx +1 -0
  44. package/template/package.json +1 -1
@@ -0,0 +1,481 @@
1
+ import { stripBasePath, withBasePath } from "../config";
2
+ import { getDiscoveryLanguages, toSiteUrl, validateAgentDiscoveryConfig, } from "./discovery";
3
+ export const DEFAULT_SITE_OPENAPI_PATH = "/openapi.json";
4
+ const OPENAPI_VERSION = "3.1.0";
5
+ const DOCUMENT_VERSION = "1.0.0";
6
+ const TRAILING_SLASH_PATTERN = /\/$/;
7
+ const NON_ALPHANUMERIC_PATTERN = /[^a-zA-Z0-9]+/;
8
+ const markdownResponse = (description) => ({
9
+ description,
10
+ content: { "text/markdown": { schema: { type: "string" } } },
11
+ });
12
+ const jsonResponse = (description, schema) => ({
13
+ description,
14
+ content: { "application/json": { schema } },
15
+ });
16
+ const ref = (name) => ({ $ref: `#/components/schemas/${name}` });
17
+ const getOrigin = (config, request) => config.siteUrl ? new URL(config.siteUrl).origin : request.nextUrl.origin;
18
+ const getServerUrl = (config, origin) => new URL(withBasePath("/", config.basePath), origin)
19
+ .toString()
20
+ .replace(TRAILING_SLASH_PATTERN, "");
21
+ const toPascalCase = (value) => value
22
+ .split(NON_ALPHANUMERIC_PATTERN)
23
+ .filter(Boolean)
24
+ .map((part) => part[0].toUpperCase() + part.slice(1))
25
+ .join("");
26
+ const getContentSections = (config) => {
27
+ const sections = config.content?.length
28
+ ? config.content
29
+ : [{ id: "docs", label: "Documentation", route: "/docs" }];
30
+ // A root-mounted section normalizes to "" so its page template becomes
31
+ // `/{path}.md`; the public route stays "/" in descriptions.
32
+ return sections.map((section) => ({
33
+ ...section,
34
+ route: section.route.replace(TRAILING_SLASH_PATTERN, ""),
35
+ }));
36
+ };
37
+ const present = (parts) => parts.filter((part) => Boolean(part));
38
+ /** "A", "A and B", or "A, B, and C". */
39
+ const joinList = (parts) => parts.length > 2
40
+ ? `${parts.slice(0, -1).join(", ")}, and ${parts.at(-1)}`
41
+ : parts.join(" and ");
42
+ /** Prose for the endpoint families the document actually lists. */
43
+ const describeEndpointFamilies = (endpoints) => {
44
+ const apiPaths = present([
45
+ endpoints.search ? "`/api/search`" : undefined,
46
+ endpoints.chat ? "`/api/chat`" : undefined,
47
+ ]);
48
+ const apiLocaleHints = present([
49
+ endpoints.search ? "the `locale` parameter" : undefined,
50
+ endpoints.chat ? "the `currentRoute` field" : undefined,
51
+ ]);
52
+ return {
53
+ summary: joinList(present([
54
+ endpoints.search ? "Search" : undefined,
55
+ endpoints.chat ? "Ask AI" : undefined,
56
+ "Markdown discovery",
57
+ ])),
58
+ description: joinList(present([
59
+ endpoints.search ? "full-text search" : undefined,
60
+ endpoints.chat ? "the Ask AI assistant" : undefined,
61
+ "Markdown versions of every page",
62
+ ])),
63
+ apiLanguageNote: apiPaths.length > 0
64
+ ? ` ${joinList(apiPaths)} ${apiPaths.length > 1 ? "take" : "takes"} no language prefix; use ${joinList(apiLocaleHints)} instead.`
65
+ : "",
66
+ };
67
+ };
68
+ const buildInfo = (config, endpoints, origin) => {
69
+ const name = config.agent?.product?.name ?? config.title;
70
+ const productApiUrl = config.agent?.api?.openApiUrl;
71
+ const defaultLanguage = config.defaultLanguage ?? "en";
72
+ const otherLanguages = getDiscoveryLanguages(config)
73
+ .filter((lang) => lang !== defaultLanguage)
74
+ .map((lang) => `\`/${lang}\``)
75
+ .join(", ");
76
+ const families = describeEndpointFamilies(endpoints);
77
+ const description = [
78
+ `HTTP endpoints served by the ${name} documentation site: ${families.description}.`,
79
+ `This document describes the documentation site only. It does not describe a ${name} product API.`,
80
+ productApiUrl
81
+ ? `The product API is described separately at ${toSiteUrl(config, origin, productApiUrl)}.`
82
+ : undefined,
83
+ "All endpoints are public and need no authentication.",
84
+ otherLanguages
85
+ ? `Discovery paths are for the default language (\`${defaultLanguage}\`). Prefix a Discovery path with a language code (${otherLanguages}) to read another translation.${families.apiLanguageNote}`
86
+ : undefined,
87
+ ]
88
+ .filter((line) => Boolean(line))
89
+ .join("\n\n");
90
+ return {
91
+ title: `${name} documentation site API`,
92
+ version: DOCUMENT_VERSION,
93
+ summary: `${families.summary} endpoints of the ${name} documentation site.`,
94
+ description,
95
+ ...(config.github
96
+ ? {
97
+ contact: {
98
+ name: `${name} maintainers`,
99
+ url: `https://github.com/${config.github.owner}/${config.github.repo}/issues`,
100
+ },
101
+ }
102
+ : {}),
103
+ };
104
+ };
105
+ const buildSearchPath = (config) => {
106
+ const languages = getDiscoveryLanguages(config);
107
+ return {
108
+ get: {
109
+ operationId: "searchDocs",
110
+ tags: ["Search"],
111
+ summary: "Search the documentation",
112
+ description: "Runs a full-text search over all documentation pages and returns matching pages, headings, and text fragments ranked by relevance. Returns an empty array when `query` is omitted or empty.",
113
+ parameters: [
114
+ {
115
+ name: "query",
116
+ in: "query",
117
+ required: false,
118
+ description: "Search terms.",
119
+ schema: { type: "string" },
120
+ },
121
+ {
122
+ name: "locale",
123
+ in: "query",
124
+ required: false,
125
+ description: `Documentation language. Defaults to \`${config.defaultLanguage ?? "en"}\`.`,
126
+ schema: {
127
+ type: "string",
128
+ enum: languages,
129
+ default: config.defaultLanguage ?? "en",
130
+ },
131
+ },
132
+ ],
133
+ responses: {
134
+ "200": jsonResponse("Ranked search results.", {
135
+ type: "array",
136
+ items: ref("SearchResult"),
137
+ }),
138
+ },
139
+ },
140
+ };
141
+ };
142
+ /** `createChatRoute` accepts `{ prewarm: true }` only for eve agents with prewarming on. */
143
+ const isEveAgentPrewarmEnabled = (config) => Boolean(config.ai?.eveAgent?.url) && config.ai?.eveAgent?.prewarm === true;
144
+ const buildChatPath = (config) => {
145
+ const prewarm = isEveAgentPrewarmEnabled(config);
146
+ return {
147
+ post: {
148
+ operationId: "askDocsAssistant",
149
+ tags: ["Chat"],
150
+ summary: "Ask the documentation assistant",
151
+ description: `Streams an answer from the Ask AI assistant. The assistant searches the documentation before answering and cites the pages it used. The response body is an AI SDK UI message stream sent as server-sent events. This endpoint calls a language model on the site owner's account; use the search endpoint for lookups that do not need an answer written for you.${prewarm ? ' Send `{ "prewarm": true }` instead of a conversation to allocate an assistant session ahead of the first question; the response is the session handle, not an answer.' : ""}`,
152
+ requestBody: {
153
+ required: true,
154
+ content: {
155
+ "application/json": {
156
+ schema: prewarm
157
+ ? { oneOf: [ref("ChatRequest"), ref("ChatPrewarmRequest")] }
158
+ : ref("ChatRequest"),
159
+ },
160
+ },
161
+ },
162
+ responses: {
163
+ "200": {
164
+ description: "AI SDK UI message stream. The stream starts before the assistant answers, so a failure while generating the answer arrives as an `error` part inside this 200 stream rather than as an HTTP error status.",
165
+ content: { "text/event-stream": { schema: { type: "string" } } },
166
+ },
167
+ ...(prewarm
168
+ ? {
169
+ "202": jsonResponse("An assistant session was allocated for a `prewarm` request. Pass the handle back as `eveAgentSession` with the first conversation to reuse it.", ref("ChatSessionHandle")),
170
+ }
171
+ : {}),
172
+ "400": jsonResponse("`messages` is not an array. Sites that route chat to an agent also reject a last message that is not from the user or has no text.", ref("ChatError")),
173
+ "500": jsonResponse("The body is not valid JSON, or the request context could not be prepared before streaming began.", ref("ChatError")),
174
+ },
175
+ },
176
+ };
177
+ };
178
+ const buildDiscoveryPaths = (config, selfPath) => {
179
+ const paths = {
180
+ [selfPath]: {
181
+ get: {
182
+ operationId: "getOpenApiDocument",
183
+ tags: ["Discovery"],
184
+ summary: "Get this OpenAPI document",
185
+ description: "Returns this OpenAPI 3.1 document as JSON.",
186
+ responses: {
187
+ "200": jsonResponse("OpenAPI document.", { type: "object" }),
188
+ },
189
+ },
190
+ },
191
+ "/agents.md": {
192
+ get: {
193
+ operationId: "getAgentsGuide",
194
+ tags: ["Discovery"],
195
+ summary: "Get the agent guide",
196
+ description: "Returns a Markdown guide that states what the product is, when to use it, and which documentation, API, and MCP surfaces exist. Start here.",
197
+ responses: { "200": markdownResponse("Agent guide as Markdown.") },
198
+ },
199
+ },
200
+ "/sitemap.md": {
201
+ get: {
202
+ operationId: "getMarkdownSitemap",
203
+ tags: ["Discovery"],
204
+ summary: "Get the semantic sitemap",
205
+ description: "Returns a Markdown index of every documentation page with its title and description. Use it to pick pages before fetching them.",
206
+ responses: { "200": markdownResponse("Semantic sitemap as Markdown.") },
207
+ },
208
+ },
209
+ "/llms.txt": {
210
+ get: {
211
+ operationId: "getLlmsText",
212
+ tags: ["Discovery"],
213
+ summary: "Get the full documentation as Markdown",
214
+ description: "Returns every documentation page concatenated as one Markdown document, following the llms.txt convention. Large; prefer the sitemap and page-level Markdown for focused questions.",
215
+ responses: {
216
+ "200": markdownResponse("Complete documentation corpus as Markdown."),
217
+ },
218
+ },
219
+ },
220
+ };
221
+ for (const section of getContentSections(config)) {
222
+ const publicRoute = section.route || "/";
223
+ const indexHint = section.route === "" ? " The section index page is `index`." : "";
224
+ paths[`${section.route}/{path}.md`] = {
225
+ get: {
226
+ operationId: `get${toPascalCase(section.id)}PageMarkdown`,
227
+ tags: ["Discovery"],
228
+ summary: `Get one ${section.label} page as Markdown`,
229
+ description: `Returns the Markdown source of a single page in the ${section.label} section. \`path\` is the page path below \`${publicRoute}\` and may contain \`/\`.${indexHint} Requesting the HTML URL with \`Accept: text/markdown\` returns the same content.`,
230
+ parameters: [
231
+ {
232
+ name: "path",
233
+ in: "path",
234
+ required: true,
235
+ description: `Page path below \`${publicRoute}\`, without the \`.md\` suffix.`,
236
+ schema: { type: "string" },
237
+ },
238
+ ],
239
+ responses: {
240
+ "200": markdownResponse("Page content as Markdown."),
241
+ "404": markdownResponse("The page does not exist. The body lists similar pages and links to `/llms.txt`. Sites configured with `notFound.status: 410` and no page-access filter return 410 instead."),
242
+ },
243
+ },
244
+ };
245
+ }
246
+ if (config.agent?.mcp?.servers?.length) {
247
+ paths["/.well-known/mcp.json"] = {
248
+ get: {
249
+ operationId: "getMcpManifest",
250
+ tags: ["Discovery"],
251
+ summary: "Get the MCP manifest",
252
+ description: "Returns the MCP servers the product declares. The documentation site does not run an MCP server itself.",
253
+ responses: {
254
+ "200": jsonResponse("MCP manifest.", ref("McpManifest")),
255
+ },
256
+ },
257
+ };
258
+ }
259
+ return paths;
260
+ };
261
+ const SCHEMAS = {
262
+ SearchResult: {
263
+ type: "object",
264
+ required: ["id", "type", "content", "url"],
265
+ properties: {
266
+ id: { type: "string", description: "Unique result identifier." },
267
+ type: {
268
+ type: "string",
269
+ enum: ["page", "heading", "text"],
270
+ description: "Kind of content that matched.",
271
+ },
272
+ content: { type: "string", description: "Matched text." },
273
+ url: {
274
+ type: "string",
275
+ description: "Path of the page within the documentation app, including a heading anchor for heading and text matches. It omits the site's base path, so append it to the server URL (which carries the base path) rather than resolving it against the origin.",
276
+ },
277
+ breadcrumbs: {
278
+ type: "array",
279
+ items: { type: "string" },
280
+ description: "Section titles from the documentation root to the page.",
281
+ },
282
+ contentWithHighlights: {
283
+ type: "array",
284
+ description: "Matched text split into highlighted fragments.",
285
+ items: {
286
+ type: "object",
287
+ required: ["type", "content"],
288
+ properties: {
289
+ type: { type: "string" },
290
+ content: { type: "string" },
291
+ styles: { type: "object", additionalProperties: true },
292
+ },
293
+ },
294
+ },
295
+ },
296
+ },
297
+ ChatRequest: {
298
+ type: "object",
299
+ required: ["messages"],
300
+ properties: {
301
+ messages: {
302
+ type: "array",
303
+ description: "Conversation history as AI SDK UI messages. The last message must be from the user.",
304
+ items: ref("UIMessage"),
305
+ },
306
+ currentRoute: {
307
+ type: "string",
308
+ description: "Site-relative path of the page the user is viewing. Selects the documentation language and grounds the answer in that page.",
309
+ },
310
+ pageContext: {
311
+ type: "object",
312
+ description: "Content of the current page, used to ground the answer.",
313
+ required: ["title", "url", "content"],
314
+ properties: {
315
+ title: { type: "string" },
316
+ url: { type: "string" },
317
+ content: { type: "string" },
318
+ },
319
+ },
320
+ eveAgentSession: {
321
+ ...ref("ChatSessionHandle"),
322
+ description: "Session handle returned by a `prewarm` request or carried in a previous assistant message's metadata. Honoured on sites whose assistant is an eve agent; ignored otherwise.",
323
+ },
324
+ },
325
+ },
326
+ ChatPrewarmRequest: {
327
+ type: "object",
328
+ required: ["prewarm"],
329
+ properties: {
330
+ prewarm: {
331
+ type: "boolean",
332
+ enum: [true],
333
+ description: "Allocate an assistant session without asking a question.",
334
+ },
335
+ },
336
+ example: { prewarm: true },
337
+ },
338
+ ChatSessionHandle: {
339
+ type: "object",
340
+ required: ["sessionId", "streamIndex"],
341
+ properties: {
342
+ sessionId: { type: "string" },
343
+ streamIndex: {
344
+ type: "integer",
345
+ minimum: 0,
346
+ description: "Number of assistant stream events already consumed.",
347
+ },
348
+ },
349
+ },
350
+ UIMessage: {
351
+ type: "object",
352
+ required: ["id", "role", "parts"],
353
+ properties: {
354
+ id: { type: "string" },
355
+ role: { type: "string", enum: ["user", "assistant", "system"] },
356
+ parts: {
357
+ type: "array",
358
+ items: {
359
+ type: "object",
360
+ required: ["type"],
361
+ properties: {
362
+ type: { type: "string" },
363
+ text: { type: "string" },
364
+ },
365
+ additionalProperties: true,
366
+ },
367
+ },
368
+ },
369
+ example: {
370
+ id: "msg_1",
371
+ role: "user",
372
+ parts: [{ type: "text", text: "How do I get started?" }],
373
+ },
374
+ },
375
+ ChatError: {
376
+ type: "object",
377
+ required: ["error"],
378
+ properties: {
379
+ error: { type: "string", description: "Human-readable error message." },
380
+ },
381
+ example: { error: "Invalid chat request: messages must be an array." },
382
+ },
383
+ McpManifest: {
384
+ type: "object",
385
+ required: ["name", "servers"],
386
+ properties: {
387
+ name: { type: "string" },
388
+ description: { type: "string" },
389
+ servers: {
390
+ type: "array",
391
+ items: {
392
+ type: "object",
393
+ required: ["name", "url"],
394
+ properties: {
395
+ name: { type: "string" },
396
+ url: { type: "string" },
397
+ description: { type: "string" },
398
+ },
399
+ },
400
+ },
401
+ },
402
+ },
403
+ };
404
+ const pickSchemas = (names) => Object.fromEntries(Object.entries(SCHEMAS).filter(([name]) => names.has(name)));
405
+ const buildDocument = ({ config, endpoints, origin, selfPath, }) => {
406
+ const paths = {};
407
+ const schemas = new Set();
408
+ const tags = [];
409
+ if (endpoints.search) {
410
+ paths["/api/search"] = buildSearchPath(config);
411
+ schemas.add("SearchResult");
412
+ tags.push({
413
+ name: "Search",
414
+ description: "Full-text search over the documentation.",
415
+ });
416
+ }
417
+ if (endpoints.chat) {
418
+ paths["/api/chat"] = buildChatPath(config);
419
+ for (const name of [
420
+ "ChatRequest",
421
+ "UIMessage",
422
+ "ChatError",
423
+ "ChatSessionHandle",
424
+ ...(isEveAgentPrewarmEnabled(config) ? ["ChatPrewarmRequest"] : []),
425
+ ]) {
426
+ schemas.add(name);
427
+ }
428
+ tags.push({
429
+ name: "Chat",
430
+ description: "Ask AI assistant grounded in the documentation.",
431
+ });
432
+ }
433
+ Object.assign(paths, buildDiscoveryPaths(config, selfPath));
434
+ if (paths["/.well-known/mcp.json"]) {
435
+ schemas.add("McpManifest");
436
+ }
437
+ tags.push({
438
+ name: "Discovery",
439
+ description: "Machine-readable documentation surfaces for agents.",
440
+ });
441
+ return {
442
+ openapi: OPENAPI_VERSION,
443
+ info: buildInfo(config, endpoints, origin),
444
+ servers: [{ url: getServerUrl(config, origin), description: "This site" }],
445
+ security: [],
446
+ tags,
447
+ paths,
448
+ components: { schemas: pickSchemas(schemas) },
449
+ };
450
+ };
451
+ export const createOpenApiRoute = ({ config, endpoints, transform, }) => {
452
+ validateAgentDiscoveryConfig(config);
453
+ const resolvedEndpoints = {
454
+ search: endpoints?.search ?? config.search?.enabled !== false,
455
+ chat: endpoints?.chat ?? config.ai?.enabled !== false,
456
+ };
457
+ // Document paths are relative to the server URL, which carries the base path.
458
+ const selfPath = stripBasePath(config.agent?.api?.siteOpenApiUrl ?? DEFAULT_SITE_OPENAPI_PATH, config.basePath);
459
+ const GET = async (request) => {
460
+ if (config.agent?.enabled === false) {
461
+ return new Response("Not found", { status: 404 });
462
+ }
463
+ const document = buildDocument({
464
+ config,
465
+ endpoints: resolvedEndpoints,
466
+ origin: getOrigin(config, request),
467
+ selfPath,
468
+ });
469
+ return Response.json(transform ? await transform(document, { request }) : document, {
470
+ headers: {
471
+ "Content-Type": "application/json; charset=utf-8",
472
+ },
473
+ });
474
+ };
475
+ const generateStaticParams = () => getDiscoveryLanguages(config).map((lang) => ({ lang }));
476
+ return {
477
+ GET,
478
+ generateStaticParams,
479
+ revalidate: false,
480
+ };
481
+ };
package/docs/agents.md CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Docs
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 2.5.0 so agents can understand the installed package without web access.
3
+ These docs are bundled with `@vercel/geistdocs` 2.6.1 so agents can understand the installed package without web access.
4
4
  They are generated from `apps/template/content/docs` during the package build.
5
5
 
6
6
  ## How to use these files
package/docs/llms.txt CHANGED
@@ -1,6 +1,6 @@
1
1
  # Geistdocs Package Documentation
2
2
 
3
- These docs are bundled with `@vercel/geistdocs` 2.5.0.
3
+ These docs are bundled with `@vercel/geistdocs` 2.6.1.
4
4
  They describe how to build package-backed Geistdocs sites and how to use the package APIs from generated project adapters.
5
5
 
6
6
  ## Documentation Index
@@ -1014,6 +1014,7 @@ Check these URLs locally:
1014
1014
  - `/sitemap.md`.
1015
1015
  - `/agents.md`.
1016
1016
  - `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
1017
+ - `/openapi.json` if the site mounts `createOpenApiRoute`.
1017
1018
  - A page-level Markdown URL such as `/docs/getting-started.mdx`.
1018
1019
  - A non-docs route that should not be rewritten as Markdown, such as the homepage.
1019
1020
 
@@ -1127,6 +1128,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
1127
1128
  | `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
1128
1129
  | `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
1129
1130
  | `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
1131
+ | `app/[lang]/openapi.json/route.ts` | Serves an OpenAPI document for the site's own search, chat, and Markdown endpoints. |
1130
1132
  | `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
1131
1133
  | `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
1132
1134
  | `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
@@ -3679,6 +3681,36 @@ export const config = defineConfig({
3679
3681
  });
3680
3682
  ```
3681
3683
 
3684
+ ## Describe the documentation site's own API
3685
+
3686
+ `agent.api.openApiUrl` points at your product's API. The documentation site also has HTTP endpoints of its own: `/api/search`, `/api/chat`, and the Markdown discovery routes. Geistdocs owns those implementations, so it can describe them for you. Add the route adapter and tell `/agents.md` where it lives:
3687
+
3688
+ ```ts title="app/[lang]/openapi.json/route.ts"
3689
+ import { createOpenApiRoute } from "@vercel/geistdocs/routes/openapi";
3690
+ import { config } from "@/lib/geistdocs/config";
3691
+
3692
+ export const { GET, generateStaticParams } = createOpenApiRoute({
3693
+ config,
3694
+ });
3695
+ ```
3696
+
3697
+ ```tsx title="geistdocs.tsx"
3698
+ export const agent = {
3699
+ api: {
3700
+ openApiUrl: "https://api.example.com/openapi.json",
3701
+ siteOpenApiUrl: "/openapi.json",
3702
+ },
3703
+ } satisfies GeistdocsAgentReadinessConfig;
3704
+ ```
3705
+
3706
+ The generated OpenAPI 3.1 document states that it describes the documentation site and not the product, links the product spec when `openApiUrl` is set, and lists the languages the site serves. `/agents.md` renders `siteOpenApiUrl` as a separate "Documentation site API" link so agents do not confuse the two.
3707
+
3708
+ The document always lists the Markdown discovery routes (`/agents.md`, `/sitemap.md`, `/llms.txt`, and page-level `.md`), so keep those route files mounted. `/api/search` and `/api/chat` follow `search.enabled` and `ai.enabled`; pass `endpoints: { chat: false }` or `endpoints: { search: false }` to `createOpenApiRoute` when the route files differ from the feature flags. `/.well-known/mcp.json` appears only when `agent.mcp.servers` is configured.
3709
+
3710
+ The server URL comes from `siteUrl` when it is set, and from the request origin otherwise. Set `siteUrl` so the document names your production host.
3711
+
3712
+ Publishing the document makes `/api/chat` discoverable for programmatic use. That endpoint runs a language model on your account and has no built-in rate limit. Set `endpoints: { chat: false }` if that is not acceptable for your site.
3713
+
3682
3714
  ## Keep it honest
3683
3715
 
3684
3716
  Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs validates new `openApiSpecs` entries and MCP servers rendered by `/.well-known/mcp.json` as absolute `http` or `https` URLs or root-relative paths. Existing `/agents.md` URL fields keep the same URL handling as previous versions. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.
@@ -5082,53 +5114,54 @@ source: apps/template/content/docs/webmcp.mdx
5082
5114
 
5083
5115
  # WebMCP
5084
5116
 
5085
- Geistdocs includes experimental WebMCP support. WebMCP is disabled by default. To opt in, add it to the `defineConfig` call in `lib/geistdocs/config.tsx`:
5117
+ Geistdocs uses [mcp-handler's WebMCP bridge](https://github.com/vercel/mcp-handler/blob/main/docs/WEBMCP.md) for search and a browser-local tool for reading the current page. Enable `webmcp: { enabled: true }` in `lib/geistdocs/config.tsx` and add `app/api/mcp/route.ts`:
5086
5118
 
5087
5119
  ```ts
5088
- export const config = defineConfig({
5089
- // ...
5090
- webmcp: { enabled: true },
5091
- });
5120
+ import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
5121
+ import { config } from "@/lib/geistdocs/config";
5122
+ import { GET as search } from "../search/route";
5123
+
5124
+ const handler = createMcpRoute({ config, search });
5125
+
5126
+ export { handler as GET, handler as POST };
5092
5127
  ```
5093
5128
 
5094
- The provider exposes two read-only tools:
5129
+ The canonical template includes this setup. Existing consumers must add the route themselves: `geistdocs update` does not overwrite local adapters. There is no fallback to the old browser search transport.
5130
+
5131
+ ## Tools
5095
5132
 
5096
5133
  | Tool | Input | Result |
5097
5134
  | --- | --- | --- |
5098
- | `search_docs` | `query`, a nonempty string up to 500 characters | Results from the existing search API in the current language |
5099
- | `read_current_page` | None | The current documentation page as Markdown |
5135
+ | `search_docs` | Nonblank `query` up to 500 characters; optional configured `locale` | MCP result containing search results as JSON text |
5136
+ | `read_current_page` | None | Current page as Markdown |
5100
5137
 
5101
- Search respects the existing search visibility rules. Page reading uses the existing Markdown route and fails if the current page does not serve Markdown. Neither tool sends data to an external model or modifies documentation. Returned documentation is marked as untrusted content.
5138
+ The provider loads `/api/mcp?webmcp-script` once through `next/script`. The script discovers the MCP server's tools and registers only `search_docs`. Do not add another copy of the script or register search yourself. Remote MCP clients connect to `/api/mcp` directly. Geistdocs prefixes public paths with `basePath`.
5102
5139
 
5103
- WebMCP requires a compatible browser with the experimental API enabled. Unsupported browsers continue to work normally. This feature uses browser-local tools, independently of the site's remote MCP discovery manifest.
5140
+ Search calls the supplied search handler directly, retaining its visibility filters and request headers/cookies without another network hop. Pass `locale` explicitly for translated results; omitting it selects `defaultLanguage`, even after navigating to another language. Neither tool modifies documentation or sends it to an external model.
5104
5141
 
5105
- ## Verify locally
5142
+ ## Lifecycle and safety
5106
5143
 
5107
- Enable WebMCP testing as described in the [Chrome documentation](https://developer.chrome.com/docs/ai/webmcp). Open a documentation page and inspect its tools:
5144
+ Search follows the upstream bridge contract: MCP result envelopes are returned unchanged, including `isError`; browser-provided cancellation reaches fetch, but there is no additional request deadline. The bridge preserves `readOnlyHint` but does not emit WebMCP's explicit `untrustedContentHint`. Search results are still untrusted documentation, not agent instructions.
5108
5145
 
5109
- ```js
5110
- const tools = await document.modelContext.getTools();
5111
- const search = tools.find((tool) => tool.name === "search_docs");
5112
- await document.modelContext.executeTool(search, JSON.stringify({ query: "configuration" }));
5113
- const read = tools.find((tool) => tool.name === "read_current_page");
5114
- await document.modelContext.executeTool(read, "{}");
5115
- ```
5146
+ Search registration lasts for the document and is not tied to React unmounts. Reload after changing feature configuration. With `webmcp.enabled` disabled, the endpoint returns 404 and new documents do not load the bridge. Unsupported browsers continue to work normally.
5116
5147
 
5117
- Navigate to another documentation page and read it again. Repeat in a translated route and, when configured, under the site's base path. Disable the feature and verify the provider removes its tools.
5148
+ `read_current_page` remains browser-local: it reads the live URL without its query or fragment, requires a Markdown response, and retains its 15-second timeout, cancellation, untrusted-content hint and registration cleanup.
5118
5149
 
5119
- ## agent-browser
5150
+ For protected documentation, authorize the MCP route and supplied search handler. Direct handler reuse does not execute middleware scoped only to `/api/search`. Cross-origin cookie requests are rejected; protocol responses use `Cache-Control: no-store`. Tool allowlists and read-only annotations are not authorization. Never put tokens in client config.
5120
5151
 
5121
- With agent-browser 0.36.0 or newer, WebMCP is enabled by default in managed Chrome sessions:
5152
+ The remote discovery manifest remains independent; configured external servers are not replaced.
5153
+
5154
+ ## Verify locally
5155
+
5156
+ Use a compatible browser with WebMCP enabled. With agent-browser 0.36.0 or newer:
5122
5157
 
5123
5158
  ```bash
5124
5159
  agent-browser --session docs-check open http://localhost:3000/docs
5125
5160
  agent-browser --session docs-check webmcp list
5126
- agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration"}'
5161
+ agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration","locale":"en"}'
5127
5162
  agent-browser --session docs-check webmcp invoke read_current_page --params '{}'
5128
5163
  agent-browser --session docs-check close
5129
5164
  ```
5130
5165
 
5131
- Discovery includes each tool's origin, frame, schema, and read-only annotations. Check the invocation's `status`: a successfully delivered command can still contain a failed tool execution.
5132
-
5133
- Both tools limit network requests to 15 seconds. When the browser supplies an execution signal, cancellation also aborts the request. Some experimental browser versions, including Chrome 152, omit that signal: canceling an invocation in those versions does not immediately abort its underlying fetch, which remains bounded by the request deadline.
5166
+ Check the invocation's `status` and the search result's `isError`, not just command delivery. Navigate to another page and confirm reading follows the new URL; switch language and search with an explicit locale. Repeat under a configured base path. Disable the feature and reload to verify registration and endpoint opt-out.
5134
5167
 
@@ -242,5 +242,5 @@
242
242
  }
243
243
  ],
244
244
  "source": "apps/template/content/docs",
245
- "version": "2.5.0"
245
+ "version": "2.6.1"
246
246
  }