@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
@@ -1,84 +1,33 @@
1
- import { getPublicPath, withBasePath, } from "../config.js";
2
- export const createWebMCPTools = ({ config, fetcher = fetch, lang, location, requestTimeoutMs = 15_000, }) => {
3
- const getRequestSignal = (signal) => {
4
- const deadline = AbortSignal.timeout(requestTimeoutMs);
5
- return signal ? AbortSignal.any([signal, deadline]) : deadline;
6
- };
7
- const annotations = { readOnlyHint: true, untrustedContentHint: true };
8
- return [
9
- {
10
- name: "search_docs",
11
- description: `Search ${config.title} documentation in the current language. Returns matching titles, excerpts, and page URLs.`,
12
- annotations,
13
- inputSchema: {
14
- type: "object",
15
- properties: { query: { type: "string", minLength: 1, maxLength: 500 } },
16
- required: ["query"],
17
- additionalProperties: false,
18
- },
19
- execute: async (input, { signal } = {}) => {
20
- if (typeof input.query !== "string" ||
21
- !input.query.trim() ||
22
- input.query.length > 500) {
23
- throw new Error("query must contain between 1 and 500 characters.");
24
- }
25
- const url = new URL(getPublicPath("/api/search", config.basePath), location.href);
26
- url.searchParams.set("query", input.query.trim());
27
- url.searchParams.set("locale", lang ?? config.defaultLanguage ?? "en");
28
- const response = await fetcher(url, {
29
- signal: getRequestSignal(signal),
30
- redirect: "error",
31
- });
32
- if (!response.ok) {
33
- throw new Error(`Documentation search failed (${response.status}).`);
34
- }
35
- const results = await response.json();
36
- if (!Array.isArray(results)) {
37
- throw new Error("Documentation search returned an invalid response.");
38
- }
39
- return JSON.stringify(results.map((result) => {
40
- if (typeof result !== "object" ||
41
- result === null ||
42
- !("url" in result) ||
43
- typeof result.url !== "string") {
44
- throw new Error("Documentation search returned an invalid result.");
45
- }
46
- return {
47
- ...result,
48
- url: withBasePath(result.url, config.basePath),
49
- };
50
- }));
51
- },
1
+ export const createWebMCPTools = ({ fetcher = fetch, location, requestTimeoutMs = 15_000, }) => [
2
+ {
3
+ name: "read_current_page",
4
+ description: "Read the current documentation page as Markdown. Navigate to a documentation page before calling this tool.",
5
+ annotations: { readOnlyHint: true, untrustedContentHint: true },
6
+ inputSchema: {
7
+ type: "object",
8
+ properties: {},
9
+ additionalProperties: false,
52
10
  },
53
- {
54
- name: "read_current_page",
55
- description: "Read the current documentation page as Markdown. Navigate to a documentation page before calling this tool.",
56
- annotations,
57
- inputSchema: {
58
- type: "object",
59
- properties: {},
60
- additionalProperties: false,
61
- },
62
- execute: async (_input, { signal } = {}) => {
63
- const url = new URL(location.href);
64
- url.hash = "";
65
- url.search = "";
66
- const response = await fetcher(url, {
67
- headers: { Accept: "text/markdown" },
68
- redirect: "error",
69
- signal: getRequestSignal(signal),
70
- });
71
- if (!response.ok) {
72
- throw new Error(`Documentation page could not be read (${response.status}).`);
73
- }
74
- if (!response.headers.get("content-type")?.includes("text/markdown")) {
75
- throw new Error("The current page does not provide documentation Markdown.");
76
- }
77
- return response.text();
78
- },
11
+ execute: async (_input, { signal } = {}) => {
12
+ const url = new URL(location.href);
13
+ url.hash = "";
14
+ url.search = "";
15
+ const deadline = AbortSignal.timeout(requestTimeoutMs);
16
+ const response = await fetcher(url, {
17
+ headers: { Accept: "text/markdown" },
18
+ redirect: "error",
19
+ signal: signal ? AbortSignal.any([signal, deadline]) : deadline,
20
+ });
21
+ if (!response.ok) {
22
+ throw new Error(`Documentation page could not be read (${response.status}).`);
23
+ }
24
+ if (!response.headers.get("content-type")?.includes("text/markdown")) {
25
+ throw new Error("The current page does not provide documentation Markdown.");
26
+ }
27
+ return response.text();
79
28
  },
80
- ];
81
- };
29
+ },
30
+ ];
82
31
  export const registerWebMCPTools = (context, tools, onError) => {
83
32
  const controller = new AbortController();
84
33
  const register = async () => {
@@ -1 +1 @@
1
- {"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,UAAU,CAAC;AASlB,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,iBAAiB,GACjB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,GAAG,mBAAmB,GAAG,eAAe,CAAC;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,KAAK,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAEhD,MAAM,MAAM,yBAAyB,GAAG,CACtC,QAAQ,EAAE,IAAI,MAAM,EAAE,EACtB,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC,GAAG,IAAI,MAAM,EAAE,CAAC;AAE1C,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;IACnB,EAAE,EACE,IAAI,MAAM,EAAE,GACZ,CAAC,CAAC,OAAO,EAAE;QACT,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,IAAI,MAAM,EAAE,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,wBAAwB,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACpD,KAAK,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IAClD,MAAM,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IACnD,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,iBAAiB,GAAG,cAAc,CACtE,CAAC;IACF,sFAAsF;IACtF,gBAAgB,CAAC,EACb,OAAO,GACP,CAAC,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC;IACnE,cAAc,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC1C,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAoKD,eAAO,MAAM,WAAW,GAAI,gIASzB,kBAAkB,MAsVL,SAAS,WAAW,EAAE,SAAS,cAAc,sBA0D5D,CAAC"}
1
+ {"version":3,"file":"proxy.d.ts","sourceRoot":"","sources":["../src/proxy.ts"],"names":[],"mappings":"AAMA,OAAO,EACL,KAAK,cAAc,EACnB,KAAK,WAAW,EAEjB,MAAM,aAAa,CAAC;AACrB,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,UAAU,CAAC;AASlB,MAAM,MAAM,eAAe,GACvB,UAAU,GACV,iBAAiB,GACjB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,WAAW,yBAAyB;IACxC,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,eAAe,CAAC,EAAE,eAAe,CAAC;IAClC,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,MAAM,GAAG,IAAI,CAAC;IACvB,WAAW,CAAC,EAAE,QAAQ,GAAG,mBAAmB,GAAG,eAAe,CAAC;IAC/D,SAAS,EAAE,MAAM,GAAG,IAAI,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,OAAO,EAAE,cAAc,CAAC;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,OAAO,EAAE,WAAW,CAAC;CACtB;AAED,KAAK,eAAe,GAAG,QAAQ,GAAG,SAAS,GAAG,IAAI,CAAC;AAEnD,MAAM,MAAM,kBAAkB,GAAG,CAC/B,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,eAAe,CAAC,GAAG,eAAe,CAAC;AAEhD,MAAM,MAAM,yBAAyB,GAAG,CACtC,QAAQ,EAAE,IAAI,MAAM,EAAE,EACtB,OAAO,EAAE,qBAAqB,KAC3B,OAAO,CAAC,IAAI,MAAM,EAAE,CAAC,GAAG,IAAI,MAAM,EAAE,CAAC;AAE1C,MAAM,WAAW,sBAAsB;IACrC,IAAI,EAAE,IAAI,MAAM,EAAE,CAAC;IACnB,EAAE,EACE,IAAI,MAAM,EAAE,GACZ,CAAC,CAAC,OAAO,EAAE;QACT,eAAe,EAAE,MAAM,CAAC;QACxB,QAAQ,EAAE,MAAM,CAAC;QACjB,IAAI,EAAE,MAAM,EAAE,CAAC;QACf,QAAQ,EAAE,MAAM,CAAC;KAClB,KAAK,IAAI,MAAM,EAAE,CAAC,CAAC;CACzB;AAED,MAAM,WAAW,kBAAkB;IACjC,4EAA4E;IAC5E,wBAAwB,CAAC,EAAE,sBAAsB,EAAE,CAAC;IACpD,KAAK,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IAClD,MAAM,CAAC,EAAE,kBAAkB,GAAG,kBAAkB,EAAE,CAAC;IACnD,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,SAAS,GAAG,iBAAiB,GAAG,cAAc,CACtE,CAAC;IACF,sFAAsF;IACtF,gBAAgB,CAAC,EACb,OAAO,GACP,CAAC,CAAC,OAAO,EAAE;QAAE,QAAQ,EAAE,MAAM,CAAC;QAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,KAAK,OAAO,CAAC,CAAC;IACnE,cAAc,CAAC,EAAE,sBAAsB,EAAE,CAAC;IAC1C,oBAAoB,CAAC,EAAE,CACrB,KAAK,EAAE,yBAAyB,KAC7B,OAAO,CAAC,IAAI,CAAC,GAAG,IAAI,CAAC;IAC1B,8EAA8E;IAC9E,gBAAgB,CAAC,EAAE,yBAAyB,CAAC;CAC9C;AAqKD,eAAO,MAAM,WAAW,GAAI,gIASzB,kBAAkB,MA6VL,SAAS,WAAW,EAAE,SAAS,cAAc,sBA0D5D,CAAC"}
package/dist/proxy.js CHANGED
@@ -2,7 +2,7 @@ import { applyMarkdownHeaders, createNotFoundResponse, } from "@vercel/agent-rea
2
2
  import { defineI18n } from "fumadocs-core/i18n";
3
3
  import { createI18nMiddleware } from "fumadocs-core/i18n/middleware";
4
4
  import { NextResponse, } from "next/server";
5
- import { getPublicPath, normalizeBasePath, } from "./config";
5
+ import { getPublicPath, normalizeBasePath, stripBasePath, } from "./config";
6
6
  import { matchesAppRoute, parseAppRouteManifest, } from "./internal/app-route-manifest";
7
7
  import { getMarkdownDecision } from "./internal/markdown-negotiation";
8
8
  import { renderNotFoundMarkdown } from "./internal/not-found";
@@ -23,6 +23,7 @@ const PACKAGE_ROUTE_PATHS = new Set([
23
23
  "/.well-known/mcp.json",
24
24
  "/agents.md",
25
25
  "/llms.txt",
26
+ "/openapi.json",
26
27
  "/rss.xml",
27
28
  "/sitemap.md",
28
29
  ]);
@@ -139,6 +140,13 @@ export const createProxy = ({ additionalMarkdownRoutes, after, before, config, m
139
140
  hideLocale: "default-locale",
140
141
  });
141
142
  const configuredBasePath = normalizeBasePath(config.basePath);
143
+ // The site OpenAPI document can be mounted at a custom path; like the other
144
+ // package routes it must never be captured by a Markdown mapping.
145
+ const packageRoutePaths = new Set(PACKAGE_ROUTE_PATHS);
146
+ const siteOpenApiPath = config.agent?.api?.siteOpenApiUrl;
147
+ if (siteOpenApiPath) {
148
+ packageRoutePaths.add(stripBasePath(siteOpenApiPath, configuredBasePath));
149
+ }
142
150
  const internationalizer = createI18nMiddleware({
143
151
  ...i18n,
144
152
  format: (locale, path) => getPublicPath(`/${locale}${path}`, configuredBasePath),
@@ -249,7 +257,7 @@ export const createProxy = ({ additionalMarkdownRoutes, after, before, config, m
249
257
  }
250
258
  const localized = getLocalizedPathname(pathname, languages, defaultLanguage);
251
259
  if ((localized.hasLanguagePrefix && localized.language === defaultLanguage) ||
252
- PACKAGE_ROUTE_PATHS.has(localized.pathname)) {
260
+ packageRoutePaths.has(localized.pathname)) {
253
261
  return null;
254
262
  }
255
263
  const extensionResponse = await handleMarkdownExtensionRequest(request, context, proxyContext, localized.pathname, localized.language, pathname);
@@ -1 +1 @@
1
- {"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/routes/agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,WAAW,CAAC;AASnB,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,IAAI,CACV,eAAe,EACb,OAAO,GACP,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,QAAQ,GACR,KAAK,GACL,OAAO,GACP,cAAc,GACd,UAAU,CACb,CAAC;IACF,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,KAC7C,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CAC/B;AAsTD,eAAO,MAAM,iBAAiB,GAAI,wBAG/B,wBAAwB;mBAId,WAAW,eACR;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;;;;;CA2BtD,CAAC"}
1
+ {"version":3,"file":"agents.d.ts","sourceRoot":"","sources":["../../src/routes/agents.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,WAAW,CAAC;AASnB,MAAM,WAAW,wBAAwB;IACvC,MAAM,EAAE,IAAI,CACV,eAAe,EACb,OAAO,GACP,UAAU,GACV,SAAS,GACT,iBAAiB,GACjB,QAAQ,GACR,KAAK,GACL,OAAO,GACP,cAAc,GACd,UAAU,CACb,CAAC;IACF,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,MAAM,EAChB,OAAO,EAAE;QAAE,IAAI,CAAC,EAAE,MAAM,CAAC;QAAC,OAAO,EAAE,WAAW,CAAA;KAAE,KAC7C,OAAO,CAAC,MAAM,CAAC,GAAG,MAAM,CAAC;CAC/B;AA4TD,eAAO,MAAM,iBAAiB,GAAI,wBAG/B,wBAAwB;mBAId,WAAW,eACR;QAAE,MAAM,CAAC,EAAE,OAAO,CAAC;YAAE,IAAI,CAAC,EAAE,MAAM,CAAA;SAAE,CAAC,CAAA;KAAE;;;;;CA2BtD,CAAC"}
@@ -95,6 +95,8 @@ const getApiLinks = (api, config, origin) => [
95
95
  renderLink("Rate limits", toSiteUrl(config, origin, api.rateLimitsUrl)),
96
96
  api?.errorsUrl &&
97
97
  renderLink("Error handling", toSiteUrl(config, origin, api.errorsUrl)),
98
+ api?.siteOpenApiUrl &&
99
+ renderLink("Documentation site API (OpenAPI)", toSiteUrl(config, origin, api.siteOpenApiUrl), "HTTP endpoints of this documentation site itself, not the product API"),
98
100
  ].filter((link) => Boolean(link));
99
101
  const renderApiSection = (api, config, origin) => {
100
102
  const links = getApiLinks(api, config, origin);
@@ -1,4 +1,4 @@
1
- import { type GeistdocsConfig } from "../config";
1
+ import { type GeistdocsConfig } from "../config.js";
2
2
  type DiscoveryConfig = Pick<GeistdocsConfig, "agent">;
3
3
  export declare const getDiscoveryLanguages: (config: Pick<GeistdocsConfig, "defaultLanguage" | "translations">) => string[];
4
4
  export declare const toAbsoluteUrl: ({ basePath, href, origin, }: {
@@ -12,7 +12,8 @@ export declare const toPublicUrl: ({ basePath, href, origin, }: {
12
12
  origin: string;
13
13
  }) => string;
14
14
  export declare const toSiteUrl: (config: Pick<GeistdocsConfig, "basePath">, origin: string, href: string) => string;
15
- export declare const validateAgentDiscoveryConfig: (config: DiscoveryConfig) => void;
15
+ type SiteOpenApiPathConfig = Pick<GeistdocsConfig, "basePath" | "defaultLanguage" | "translations">;
16
+ export declare const validateAgentDiscoveryConfig: (config: DiscoveryConfig & SiteOpenApiPathConfig) => void;
16
17
  export declare const validateMcpManifestConfig: (config: DiscoveryConfig) => void;
17
18
  export {};
18
19
  //# sourceMappingURL=discovery.d.ts.map
@@ -1 +1 @@
1
- {"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/routes/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,eAAe,EAA+B,MAAM,WAAW,CAAC;AAE9E,KAAK,eAAe,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAItD,eAAO,MAAM,qBAAqB,GAChC,QAAQ,IAAI,CAAC,eAAe,EAAE,iBAAiB,GAAG,cAAc,CAAC,aAMlE,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,6BAI3B;IACD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,WAMA,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,6BAIzB;IACD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,WAMA,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,QAAQ,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,EACzC,QAAQ,MAAM,EACd,MAAM,MAAM,WACiD,CAAC;AAiChE,eAAO,MAAM,4BAA4B,GAAI,QAAQ,eAAe,SAenE,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,QAAQ,eAAe,SAahE,CAAC"}
1
+ {"version":3,"file":"discovery.d.ts","sourceRoot":"","sources":["../../src/routes/discovery.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,eAAe,EAIrB,MAAM,cAAc,CAAC;AAEtB,KAAK,eAAe,GAAG,IAAI,CAAC,eAAe,EAAE,OAAO,CAAC,CAAC;AAgBtD,eAAO,MAAM,qBAAqB,GAChC,QAAQ,IAAI,CAAC,eAAe,EAAE,iBAAiB,GAAG,cAAc,CAAC,aAMlE,CAAC;AAEF,eAAO,MAAM,aAAa,GAAI,6BAI3B;IACD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,WAMA,CAAC;AAEF,eAAO,MAAM,WAAW,GAAI,6BAIzB;IACD,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;CAChB,WAMA,CAAC;AAEF,eAAO,MAAM,SAAS,GACpB,QAAQ,IAAI,CAAC,eAAe,EAAE,UAAU,CAAC,EACzC,QAAQ,MAAM,EACd,MAAM,MAAM,WACiD,CAAC;AAiChE,KAAK,qBAAqB,GAAG,IAAI,CAC/B,eAAe,EACf,UAAU,GAAG,iBAAiB,GAAG,cAAc,CAChD,CAAC;AA4CF,eAAO,MAAM,4BAA4B,GACvC,QAAQ,eAAe,GAAG,qBAAqB,SAmBhD,CAAC;AAEF,eAAO,MAAM,yBAAyB,GAAI,QAAQ,eAAe,SAahE,CAAC"}
@@ -1,5 +1,17 @@
1
- import { getPublicPath, withBasePath } from "../config";
1
+ import { getPublicPath, stripBasePath, withBasePath, } from "../config.js";
2
2
  const ABSOLUTE_URL_PATTERN = /^[a-z][a-z\d+.-]*:/i;
3
+ const QUERY_OR_FRAGMENT_PATTERN = /[?#]/;
4
+ const TRAILING_SLASH_PATTERN = /\/$/;
5
+ const MARKDOWN_EXTENSION_PATTERN = /\.mdx?$/i;
6
+ /** Paths the OpenAPI document already describes; the document cannot live at one of them. */
7
+ const RESERVED_SITE_PATHS = new Set([
8
+ "/.well-known/mcp.json",
9
+ "/agents.md",
10
+ "/api/chat",
11
+ "/api/search",
12
+ "/llms.txt",
13
+ "/sitemap.md",
14
+ ]);
3
15
  export const getDiscoveryLanguages = (config) => {
4
16
  const defaultLanguage = config.defaultLanguage ?? "en";
5
17
  const languages = Object.keys(config.translations ?? {});
@@ -42,11 +54,47 @@ const assertDiscoveryUrl = (value, field) => {
42
54
  throw new Error(`${field} must use http or https.`);
43
55
  }
44
56
  };
57
+ /**
58
+ * The site OpenAPI path is matched against language-stripped request
59
+ * pathnames by the proxy and echoed as the document's own path, so only a
60
+ * plain, language-neutral route path that a request can carry is accepted.
61
+ */
62
+ const assertSiteOpenApiPath = (value, { basePath, ...languagesConfig }) => {
63
+ const field = "agent.api.siteOpenApiUrl";
64
+ if (ABSOLUTE_URL_PATTERN.test(value)) {
65
+ throw new Error(`${field} must be a root-relative path.`);
66
+ }
67
+ assertDiscoveryUrl(value, field);
68
+ if (QUERY_OR_FRAGMENT_PATTERN.test(value)) {
69
+ throw new Error(`${field} must not include a query string or fragment.`);
70
+ }
71
+ const appLocalPath = stripBasePath(value, basePath);
72
+ if (appLocalPath === "/") {
73
+ throw new Error(`${field} must not be the site root.`);
74
+ }
75
+ if (TRAILING_SLASH_PATTERN.test(value)) {
76
+ throw new Error(`${field} must not end with a slash.`);
77
+ }
78
+ if (RESERVED_SITE_PATHS.has(appLocalPath)) {
79
+ throw new Error(`${field} must not be a path the document already describes (${appLocalPath}).`);
80
+ }
81
+ // `.md` and `.mdx` URLs are page-level Markdown everywhere else on the site.
82
+ if (MARKDOWN_EXTENSION_PATTERN.test(appLocalPath)) {
83
+ throw new Error(`${field} must not end with .md or .mdx.`);
84
+ }
85
+ const firstSegment = appLocalPath.split("/")[1];
86
+ if (getDiscoveryLanguages(languagesConfig).includes(firstSegment)) {
87
+ throw new Error(`${field} must not start with a language prefix (/${firstSegment}); the document is served for every language.`);
88
+ }
89
+ };
45
90
  export const validateAgentDiscoveryConfig = (config) => {
46
91
  if (!config.agent || config.agent.enabled === false) {
47
92
  return;
48
93
  }
49
94
  const api = config.agent?.api;
95
+ if (api?.siteOpenApiUrl !== undefined) {
96
+ assertSiteOpenApiPath(api.siteOpenApiUrl, config);
97
+ }
50
98
  api?.openApiSpecs?.forEach((spec, index) => {
51
99
  if (spec.label.trim() === "") {
52
100
  throw new Error(`agent.api.openApiSpecs[${index}].label must not be empty.`);
@@ -1,5 +1,10 @@
1
- import type { NextRequest } from "next/server";
2
- import type { GeistdocsConfig } from "../config";
1
+ import { NextRequest } from "next/server.js";
2
+ import { type GeistdocsConfig } from "../config.js";
3
+ export interface CreateMcpRouteOptions {
4
+ config: Pick<GeistdocsConfig, "title" | "basePath" | "defaultLanguage" | "translations" | "webmcp">;
5
+ search: (request: NextRequest) => Response | Promise<Response>;
6
+ }
7
+ export declare const createMcpRoute: ({ config, search }: CreateMcpRouteOptions) => (request: Request) => Promise<Response>;
3
8
  export interface GeistdocsMcpManifestServer {
4
9
  description?: string;
5
10
  name: string;
@@ -1 +1 @@
1
- {"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/routes/mcp.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,aAAa,CAAC;AAC/C,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,WAAW,CAAC;AAOjD,MAAM,WAAW,0BAA0B;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,0BAA0B,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,iBAAiB,GAAG,OAAO,GAAG,cAAc,CACpE,CAAC;IACF,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,KAC9B,OAAO,CAAC,oBAAoB,CAAC,GAAG,oBAAoB,CAAC;CAC3D;AAoBD,eAAO,MAAM,sBAAsB,GAAI,wBAGpC,6BAA6B;mBAGF,WAAW;;;;;CAuBxC,CAAC"}
1
+ {"version":3,"file":"mcp.d.ts","sourceRoot":"","sources":["../../src/routes/mcp.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AAE7C,OAAO,EACL,KAAK,eAAe,EAGrB,MAAM,cAAc,CAAC;AAOtB,MAAM,WAAW,qBAAqB;IACpC,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,iBAAiB,GAAG,cAAc,GAAG,QAAQ,CACrE,CAAC;IACF,MAAM,EAAE,CAAC,OAAO,EAAE,WAAW,KAAK,QAAQ,GAAG,OAAO,CAAC,QAAQ,CAAC,CAAC;CAChE;AAyBD,eAAO,MAAM,cAAc,GAAI,oBAAoB,qBAAqB,MAQxD,SAAS,OAAO,KAAG,OAAO,CAAC,QAAQ,CAmFlD,CAAC;AAEF,MAAM,WAAW,0BAA0B;IACzC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;CACb;AAED,MAAM,WAAW,oBAAoB;IACnC,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,EAAE,0BAA0B,EAAE,CAAC;CACvC;AAED,MAAM,WAAW,6BAA6B;IAC5C,MAAM,EAAE,IAAI,CACV,eAAe,EACf,OAAO,GAAG,UAAU,GAAG,iBAAiB,GAAG,OAAO,GAAG,cAAc,CACpE,CAAC;IACF,SAAS,CAAC,EAAE,CACV,QAAQ,EAAE,oBAAoB,EAC9B,OAAO,EAAE;QAAE,OAAO,EAAE,WAAW,CAAA;KAAE,KAC9B,OAAO,CAAC,oBAAoB,CAAC,GAAG,oBAAoB,CAAC;CAC3D;AAoBD,eAAO,MAAM,sBAAsB,GAAI,wBAGpC,6BAA6B;mBAGF,WAAW;;;;;CAuBxC,CAAC"}
@@ -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"}