@vercel/geistdocs 2.5.0 → 2.6.0

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 (42) 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/provider-client.js +1 -1
  6. package/dist/internal/webmcp-client.d.ts +3 -4
  7. package/dist/internal/webmcp-client.d.ts.map +1 -1
  8. package/dist/internal/webmcp-client.js +9 -12
  9. package/dist/internal/webmcp.d.ts +2 -6
  10. package/dist/internal/webmcp.d.ts.map +1 -1
  11. package/dist/internal/webmcp.js +28 -79
  12. package/dist/proxy.d.ts.map +1 -1
  13. package/dist/proxy.js +10 -2
  14. package/dist/routes/agents.d.ts.map +1 -1
  15. package/dist/routes/agents.js +2 -0
  16. package/dist/routes/discovery.d.ts +3 -2
  17. package/dist/routes/discovery.d.ts.map +1 -1
  18. package/dist/routes/discovery.js +49 -1
  19. package/dist/routes/mcp.d.ts +7 -2
  20. package/dist/routes/mcp.d.ts.map +1 -1
  21. package/dist/routes/mcp.js +101 -1
  22. package/dist/routes/openapi.d.ts +64 -0
  23. package/dist/routes/openapi.d.ts.map +1 -0
  24. package/dist/routes/openapi.js +481 -0
  25. package/docs/agents.md +1 -1
  26. package/docs/llms.txt +60 -27
  27. package/docs/manifest.json +1 -1
  28. package/docs/pages/agent-readiness.md +30 -0
  29. package/docs/pages/configuration.md +1 -0
  30. package/docs/pages/migration.md +1 -0
  31. package/docs/pages/webmcp.md +27 -26
  32. package/package.json +9 -3
  33. package/template/AGENTS.md +1 -1
  34. package/template/app/[lang]/openapi.json/route.ts +6 -0
  35. package/template/app/api/mcp/route.ts +7 -0
  36. package/template/content/docs/agent-readiness.mdx +30 -0
  37. package/template/content/docs/configuration.mdx +1 -0
  38. package/template/content/docs/migration.mdx +1 -0
  39. package/template/content/docs/webmcp.mdx +27 -26
  40. package/template/geistdocs.tsx +3 -0
  41. package/template/lib/geistdocs/config.tsx +1 -0
  42. package/template/package.json +1 -1
@@ -1,4 +1,104 @@
1
- import { getDiscoveryLanguages, toSiteUrl, validateMcpManifestConfig, } from "./discovery";
1
+ import { createMcpHandler } from "mcp-handler";
2
+ import { NextRequest } from "next/server.js";
3
+ import { z } from "zod";
4
+ import { getPublicPath, withBasePath, } from "../config.js";
5
+ import { getDiscoveryLanguages, toSiteUrl, validateMcpManifestConfig, } from "./discovery.js";
6
+ const withoutCache = (response) => {
7
+ const headers = new Headers(response.headers);
8
+ headers.set("cache-control", "no-store");
9
+ return new Response(response.body, {
10
+ status: response.status,
11
+ statusText: response.statusText,
12
+ headers,
13
+ });
14
+ };
15
+ const isCrossOriginCookieRequest = (request) => {
16
+ if (!request.headers.has("cookie")) {
17
+ return false;
18
+ }
19
+ const origin = request.headers.get("origin");
20
+ const site = request.headers.get("sec-fetch-site");
21
+ return ((origin !== null && origin !== new URL(request.url).origin) ||
22
+ (site !== null && site !== "same-origin" && site !== "none"));
23
+ };
24
+ export const createMcpRoute = ({ config, search }) => {
25
+ const inputSchema = z.object({
26
+ query: z.string().min(1).max(500).trim().min(1),
27
+ locale: z
28
+ .enum(getDiscoveryLanguages(config))
29
+ .default(config.defaultLanguage ?? "en"),
30
+ });
31
+ return async (request) => {
32
+ if (!config.webmcp?.enabled) {
33
+ return withoutCache(new Response("Not found", { status: 404 }));
34
+ }
35
+ if (isCrossOriginCookieRequest(request)) {
36
+ return withoutCache(new Response("Forbidden", { status: 403 }));
37
+ }
38
+ const handler = createMcpHandler((server) => {
39
+ server.registerTool("search_docs", {
40
+ description: `Search ${config.title} documentation. Returns matching titles, excerpts, and page URLs in the requested language.`,
41
+ inputSchema,
42
+ annotations: { readOnlyHint: true },
43
+ }, async ({ query, locale }) => {
44
+ try {
45
+ request.signal.throwIfAborted();
46
+ const url = new URL(getPublicPath("/api/search", config.basePath), request.url);
47
+ url.searchParams.set("query", query);
48
+ url.searchParams.set("locale", locale);
49
+ const response = await search(new NextRequest(url, {
50
+ method: "GET",
51
+ headers: request.headers,
52
+ signal: request.signal,
53
+ redirect: "error",
54
+ }));
55
+ request.signal.throwIfAborted();
56
+ if (!response.ok || response.redirected) {
57
+ throw new Error("Documentation search failed.");
58
+ }
59
+ const results = z
60
+ .array(z.object({ url: z.string() }).passthrough())
61
+ .parse(await response.json());
62
+ request.signal.throwIfAborted();
63
+ const normalized = results.map((result) => ({
64
+ ...result,
65
+ url: withBasePath(result.url, config.basePath),
66
+ }));
67
+ return {
68
+ content: [{ type: "text", text: JSON.stringify(normalized) }],
69
+ };
70
+ }
71
+ catch {
72
+ return {
73
+ isError: true,
74
+ content: [
75
+ {
76
+ type: "text",
77
+ text: request.signal.aborted
78
+ ? "Documentation search was cancelled."
79
+ : "Documentation search failed.",
80
+ },
81
+ ],
82
+ };
83
+ }
84
+ });
85
+ }, {
86
+ serverInfo: { name: config.title, version: "1.0.0" },
87
+ maxSubscriptions: 0,
88
+ experimental_webMcp: {
89
+ tools: ["search_docs"],
90
+ credentials: "same-origin",
91
+ cacheControl: "no-store",
92
+ },
93
+ });
94
+ try {
95
+ return withoutCache(await handler(request));
96
+ }
97
+ catch {
98
+ return withoutCache(new Response("MCP request failed.", { status: 500 }));
99
+ }
100
+ };
101
+ };
2
102
  const renderManifest = (config, request) => {
3
103
  const product = config.agent?.product ?? {};
4
104
  const origin = request.nextUrl.origin;
@@ -0,0 +1,64 @@
1
+ import type { NextRequest } from "next/server";
2
+ import { type GeistdocsConfig } from "../config";
3
+ export declare const DEFAULT_SITE_OPENAPI_PATH = "/openapi.json";
4
+ export interface CreateOpenApiRouteOptions {
5
+ config: Pick<GeistdocsConfig, "agent" | "ai" | "basePath" | "content" | "defaultLanguage" | "github" | "search" | "siteUrl" | "title" | "translations">;
6
+ /**
7
+ * Which package-owned API routes the site mounts. Defaults follow
8
+ * `config.search.enabled` and `config.ai.enabled`; override when the route
9
+ * files differ from the feature flags. The Markdown discovery routes are
10
+ * always listed.
11
+ */
12
+ endpoints?: {
13
+ chat?: boolean;
14
+ search?: boolean;
15
+ };
16
+ transform?: (document: GeistdocsOpenApiDocument, context: {
17
+ request: NextRequest;
18
+ }) => Promise<GeistdocsOpenApiDocument> | GeistdocsOpenApiDocument;
19
+ }
20
+ type JsonSchema = Record<string, unknown>;
21
+ interface OpenApiOperation {
22
+ description: string;
23
+ operationId: string;
24
+ parameters?: Record<string, unknown>[];
25
+ requestBody?: Record<string, unknown>;
26
+ responses: Record<string, unknown>;
27
+ summary: string;
28
+ tags: string[];
29
+ }
30
+ export interface GeistdocsOpenApiDocument {
31
+ components: {
32
+ schemas: Record<string, JsonSchema>;
33
+ };
34
+ info: {
35
+ contact?: {
36
+ name: string;
37
+ url: string;
38
+ };
39
+ description: string;
40
+ summary: string;
41
+ title: string;
42
+ version: string;
43
+ };
44
+ openapi: "3.1.0";
45
+ paths: Record<string, Record<string, OpenApiOperation>>;
46
+ security: never[];
47
+ servers: {
48
+ description: string;
49
+ url: string;
50
+ }[];
51
+ tags: {
52
+ description: string;
53
+ name: string;
54
+ }[];
55
+ }
56
+ export declare const createOpenApiRoute: ({ config, endpoints, transform, }: CreateOpenApiRouteOptions) => {
57
+ GET: (request: NextRequest) => Promise<Response>;
58
+ generateStaticParams: () => {
59
+ lang: string;
60
+ }[];
61
+ revalidate: false;
62
+ };
63
+ export {};
64
+ //# sourceMappingURL=openapi.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"openapi.d.ts","sourceRoot":"","sources":["../../src/routes/openapi.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EAAE,KAAK,eAAe,EAA+B,MAAM,WAAW,CAAC;AAO9E,eAAO,MAAM,yBAAyB,kBAAkB,CAAC;AAEzD,MAAM,WAAW,yBAAyB;IACxC,MAAM,EAAE,IAAI,CACV,eAAe,EACb,OAAO,GACP,IAAI,GACJ,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,QAAQ,GACR,QAAQ,GACR,SAAS,GACT,OAAO,GACP,cAAc,CACjB,CAAC;IACF;;;;;OAKG;IACH,SAAS,CAAC,EAAE;QACV,IAAI,CAAC,EAAE,OAAO,CAAC;QACf,MAAM,CAAC,EAAE,OAAO,CAAC;KAClB,CAAC;IACF,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,wBAAwB,EAClC,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,KAC9B,OAAO,CAAC,wBAAwB,CAAC,GAAG,wBAAwB,CAAC;CACnE;AAID,KAAK,UAAU,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;AAE1C,UAAU,gBAAgB;IACxB,WAAW,EAAE,MAAM,CAAC;IACpB,WAAW,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAAE,CAAC;IACvC,WAAW,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACtC,SAAS,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,IAAI,EAAE,MAAM,EAAE,CAAC;CAChB;AAED,MAAM,WAAW,wBAAwB;IACvC,UAAU,EAAE;QACV,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,UAAU,CAAC,CAAC;KACrC,CAAC;IACF,IAAI,EAAE;QACJ,OAAO,CAAC,EAAE;YAAE,IAAI,EAAE,MAAM,CAAC;YAAC,GAAG,EAAE,MAAM,CAAA;SAAE,CAAC;QACxC,WAAW,EAAE,MAAM,CAAC;QACpB,OAAO,EAAE,MAAM,CAAC;QAChB,KAAK,EAAE,MAAM,CAAC;QACd,OAAO,EAAE,MAAM,CAAC;KACjB,CAAC;IACF,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,gBAAgB,CAAC,CAAC,CAAC;IACxD,QAAQ,EAAE,KAAK,EAAE,CAAC;IAClB,OAAO,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IAChD,IAAI,EAAE;QAAE,WAAW,EAAE,MAAM,CAAC;QAAC,IAAI,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;CAC/C;AAgiBD,eAAO,MAAM,kBAAkB,GAAI,mCAIhC,yBAAyB;mBAaE,WAAW;;;;;CA8BxC,CAAC"}
@@ -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.0 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