@vercel/geistdocs 2.4.2 → 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 (66) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +14 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/config.js +13 -0
  5. package/dist/internal/chat/context.d.ts +1 -0
  6. package/dist/internal/chat/context.d.ts.map +1 -1
  7. package/dist/internal/chat/context.js +1 -0
  8. package/dist/internal/chat/shell.d.ts.map +1 -1
  9. package/dist/internal/chat/shell.js +32 -10
  10. package/dist/internal/eve-agent-session.d.ts +12 -0
  11. package/dist/internal/eve-agent-session.d.ts.map +1 -0
  12. package/dist/internal/eve-agent-session.js +26 -0
  13. package/dist/internal/eve-agent.d.ts +9 -5
  14. package/dist/internal/eve-agent.d.ts.map +1 -1
  15. package/dist/internal/eve-agent.js +63 -15
  16. package/dist/internal/mdx-to-markdown.d.ts.map +1 -1
  17. package/dist/internal/mdx-to-markdown.js +68 -1
  18. package/dist/internal/provider-client.d.ts +13 -1
  19. package/dist/internal/provider-client.d.ts.map +1 -1
  20. package/dist/internal/provider-client.js +1 -1
  21. package/dist/internal/search.d.ts +23 -1
  22. package/dist/internal/search.d.ts.map +1 -1
  23. package/dist/internal/search.js +19 -4
  24. package/dist/internal/webmcp-client.d.ts +3 -4
  25. package/dist/internal/webmcp-client.d.ts.map +1 -1
  26. package/dist/internal/webmcp-client.js +9 -12
  27. package/dist/internal/webmcp.d.ts +2 -6
  28. package/dist/internal/webmcp.d.ts.map +1 -1
  29. package/dist/internal/webmcp.js +28 -79
  30. package/dist/proxy.d.ts.map +1 -1
  31. package/dist/proxy.js +10 -2
  32. package/dist/routes/agents.d.ts.map +1 -1
  33. package/dist/routes/agents.js +2 -0
  34. package/dist/routes/chat.d.ts.map +1 -1
  35. package/dist/routes/chat.js +51 -13
  36. package/dist/routes/discovery.d.ts +3 -2
  37. package/dist/routes/discovery.d.ts.map +1 -1
  38. package/dist/routes/discovery.js +49 -1
  39. package/dist/routes/mcp.d.ts +7 -2
  40. package/dist/routes/mcp.d.ts.map +1 -1
  41. package/dist/routes/mcp.js +101 -1
  42. package/dist/routes/openapi.d.ts +64 -0
  43. package/dist/routes/openapi.d.ts.map +1 -0
  44. package/dist/routes/openapi.js +481 -0
  45. package/docs/agents.md +1 -1
  46. package/docs/llms.txt +95 -29
  47. package/docs/manifest.json +1 -1
  48. package/docs/pages/agent-readiness.md +30 -0
  49. package/docs/pages/ask-ai.md +6 -1
  50. package/docs/pages/configuration.md +7 -1
  51. package/docs/pages/migration.md +1 -0
  52. package/docs/pages/provider.md +23 -0
  53. package/docs/pages/webmcp.md +27 -26
  54. package/package.json +9 -3
  55. package/template/AGENTS.md +2 -2
  56. package/template/app/[lang]/openapi.json/route.ts +6 -0
  57. package/template/app/api/mcp/route.ts +7 -0
  58. package/template/content/docs/agent-readiness.mdx +30 -0
  59. package/template/content/docs/ask-ai.mdx +6 -1
  60. package/template/content/docs/configuration.mdx +7 -1
  61. package/template/content/docs/migration.mdx +1 -0
  62. package/template/content/docs/provider.mdx +23 -0
  63. package/template/content/docs/webmcp.mdx +27 -26
  64. package/template/geistdocs.tsx +3 -0
  65. package/template/lib/geistdocs/config.tsx +1 -0
  66. package/template/package.json +1 -1
@@ -61,6 +61,29 @@ Pass the scope here rather than reading a header or a cookie in the route. The s
61
61
  `createSearchRoute` indexes pages without a `tag` field, and tagged queries match with `containsAll`, so a tag passed to the built-in route matches nothing.
62
62
  </Callout>
63
63
 
64
+ ### Let readers change the scope
65
+
66
+ `tag` alone fixes the scope: it follows the page and a reader cannot override it. Pass `tags` as well to render the alternatives as pills under the results:
67
+
68
+ ```tsx title="app/layout.tsx"
69
+ <GeistdocsProvider
70
+ config={config}
71
+ search={{
72
+ options: {
73
+ tag: "v5",
74
+ tags: [
75
+ { name: "v4", value: "v4" },
76
+ { name: "v5", value: "v5" },
77
+ ],
78
+ allowClear: true,
79
+ onTagChange: (value) => persist(value),
80
+ },
81
+ }}
82
+ >
83
+ ```
84
+
85
+ The selection starts at `tag` and follows it when the page changes, so navigating still re-scopes the dialog. `allowClear` adds a pill that searches everything, and `onTagChange` reports each pick for sites that remember it across sessions.
86
+
64
87
  ## AI Sidebar
65
88
 
66
89
  When users open the AI chat on desktop, the provider automatically adds padding to prevent content from being hidden behind the sidebar. On mobile, the chat opens as a drawer instead, so no padding is needed.
@@ -3,52 +3,53 @@ title: WebMCP
3
3
  description: Expose documentation search and page reading to browser agents.
4
4
  ---
5
5
 
6
- Geistdocs includes experimental WebMCP support. WebMCP is disabled by default. To opt in, add it to the `defineConfig` call in `lib/geistdocs/config.tsx`:
6
+ 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`:
7
7
 
8
8
  ```ts
9
- export const config = defineConfig({
10
- // ...
11
- webmcp: { enabled: true },
12
- });
9
+ import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
10
+ import { config } from "@/lib/geistdocs/config";
11
+ import { GET as search } from "../search/route";
12
+
13
+ const handler = createMcpRoute({ config, search });
14
+
15
+ export { handler as GET, handler as POST };
13
16
  ```
14
17
 
15
- The provider exposes two read-only tools:
18
+ 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.
19
+
20
+ ## Tools
16
21
 
17
22
  | Tool | Input | Result |
18
23
  | --- | --- | --- |
19
- | `search_docs` | `query`, a nonempty string up to 500 characters | Results from the existing search API in the current language |
20
- | `read_current_page` | None | The current documentation page as Markdown |
24
+ | `search_docs` | Nonblank `query` up to 500 characters; optional configured `locale` | MCP result containing search results as JSON text |
25
+ | `read_current_page` | None | Current page as Markdown |
21
26
 
22
- Search respects the existing search visibility rules. Page reading uses the existing Markdown route and fails if the current page does not serve Markdown. Neither tool sends data to an external model or modifies documentation. Returned documentation is marked as untrusted content.
27
+ 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`.
23
28
 
24
- WebMCP requires a compatible browser with the experimental API enabled. Unsupported browsers continue to work normally. This feature uses browser-local tools, independently of the site's remote MCP discovery manifest.
29
+ 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.
25
30
 
26
- ## Verify locally
31
+ ## Lifecycle and safety
27
32
 
28
- Enable WebMCP testing as described in the [Chrome documentation](https://developer.chrome.com/docs/ai/webmcp). Open a documentation page and inspect its tools:
33
+ 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.
29
34
 
30
- ```js
31
- const tools = await document.modelContext.getTools();
32
- const search = tools.find((tool) => tool.name === "search_docs");
33
- await document.modelContext.executeTool(search, JSON.stringify({ query: "configuration" }));
34
- const read = tools.find((tool) => tool.name === "read_current_page");
35
- await document.modelContext.executeTool(read, "{}");
36
- ```
35
+ 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.
37
36
 
38
- Navigate to another documentation page and read it again. Repeat in a translated route and, when configured, under the site's base path. Disable the feature and verify the provider removes its tools.
37
+ `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.
39
38
 
40
- ## agent-browser
39
+ 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.
41
40
 
42
- With agent-browser 0.36.0 or newer, WebMCP is enabled by default in managed Chrome sessions:
41
+ The remote discovery manifest remains independent; configured external servers are not replaced.
42
+
43
+ ## Verify locally
44
+
45
+ Use a compatible browser with WebMCP enabled. With agent-browser 0.36.0 or newer:
43
46
 
44
47
  ```bash
45
48
  agent-browser --session docs-check open http://localhost:3000/docs
46
49
  agent-browser --session docs-check webmcp list
47
- agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration"}'
50
+ agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration","locale":"en"}'
48
51
  agent-browser --session docs-check webmcp invoke read_current_page --params '{}'
49
52
  agent-browser --session docs-check close
50
53
  ```
51
54
 
52
- Discovery includes each tool's origin, frame, schema, and read-only annotations. Check the invocation's `status`: a successfully delivered command can still contain a failed tool execution.
53
-
54
- 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.
55
+ 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.
@@ -63,6 +63,9 @@ export const agent = {
63
63
  "Share Vercel docs UI and runtime behavior across projects",
64
64
  ],
65
65
  },
66
+ api: {
67
+ siteOpenApiUrl: "/openapi.json",
68
+ },
66
69
  links: [
67
70
  {
68
71
  label: "Geistdocs source",
@@ -27,6 +27,7 @@ export const config = defineConfig({
27
27
  siteId,
28
28
  siteUrl: isSiteUrlConfigured ? siteUrl.toString() : undefined,
29
29
  translations,
30
+ webmcp: { enabled: true },
30
31
  content: [{ id: "docs", label: "Docs", dir: "content/docs", route: "/docs" }],
31
32
  ai: {
32
33
  prompt,
@@ -17,7 +17,7 @@
17
17
  "@streamdown/code": "^1.0.1",
18
18
  "@vercel/agent-readability": "^0.7.0",
19
19
  "@vercel/analytics": "^1.6.1",
20
- "@vercel/geistdocs": "2.4.2",
20
+ "@vercel/geistdocs": "2.6.0",
21
21
  "@vercel/speed-insights": "^1.3.1",
22
22
  "ai": "^6.0.132",
23
23
  "clsx": "^2.1.1",