@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.
- package/dist/cli/index.js +1 -1
- package/dist/config.d.ts +9 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/config.js +13 -0
- package/dist/internal/mdx-to-markdown.d.ts.map +1 -1
- package/dist/internal/mdx-to-markdown.js +465 -27
- package/dist/internal/provider-client.js +1 -1
- package/dist/internal/webmcp-client.d.ts +3 -4
- package/dist/internal/webmcp-client.d.ts.map +1 -1
- package/dist/internal/webmcp-client.js +9 -12
- package/dist/internal/webmcp.d.ts +2 -6
- package/dist/internal/webmcp.d.ts.map +1 -1
- package/dist/internal/webmcp.js +28 -79
- package/dist/proxy.d.ts.map +1 -1
- package/dist/proxy.js +10 -2
- package/dist/routes/agents.d.ts.map +1 -1
- package/dist/routes/agents.js +2 -0
- package/dist/routes/discovery.d.ts +3 -2
- package/dist/routes/discovery.d.ts.map +1 -1
- package/dist/routes/discovery.js +49 -1
- package/dist/routes/mcp.d.ts +7 -2
- package/dist/routes/mcp.d.ts.map +1 -1
- package/dist/routes/mcp.js +101 -1
- package/dist/routes/openapi.d.ts +64 -0
- package/dist/routes/openapi.d.ts.map +1 -0
- package/dist/routes/openapi.js +481 -0
- package/docs/agents.md +1 -1
- package/docs/llms.txt +60 -27
- package/docs/manifest.json +1 -1
- package/docs/pages/agent-readiness.md +30 -0
- package/docs/pages/configuration.md +1 -0
- package/docs/pages/migration.md +1 -0
- package/docs/pages/webmcp.md +27 -26
- package/package.json +9 -3
- package/template/AGENTS.md +1 -1
- package/template/app/[lang]/openapi.json/route.ts +6 -0
- package/template/app/api/mcp/route.ts +7 -0
- package/template/content/docs/agent-readiness.mdx +30 -0
- package/template/content/docs/configuration.mdx +1 -0
- package/template/content/docs/migration.mdx +1 -0
- package/template/content/docs/webmcp.mdx +27 -26
- package/template/geistdocs.tsx +3 -0
- package/template/lib/geistdocs/config.tsx +1 -0
- 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.
|
|
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.
|
|
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
|
|
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
|
-
|
|
5089
|
-
|
|
5090
|
-
|
|
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
|
|
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
|
|
5099
|
-
| `read_current_page` | None |
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
5142
|
+
## Lifecycle and safety
|
|
5106
5143
|
|
|
5107
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
|
package/docs/manifest.json
CHANGED