@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
|
@@ -134,6 +134,36 @@ export const config = defineConfig({
|
|
|
134
134
|
});
|
|
135
135
|
```
|
|
136
136
|
|
|
137
|
+
## Describe the documentation site's own API
|
|
138
|
+
|
|
139
|
+
`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:
|
|
140
|
+
|
|
141
|
+
```ts title="app/[lang]/openapi.json/route.ts"
|
|
142
|
+
import { createOpenApiRoute } from "@vercel/geistdocs/routes/openapi";
|
|
143
|
+
import { config } from "@/lib/geistdocs/config";
|
|
144
|
+
|
|
145
|
+
export const { GET, generateStaticParams } = createOpenApiRoute({
|
|
146
|
+
config,
|
|
147
|
+
});
|
|
148
|
+
```
|
|
149
|
+
|
|
150
|
+
```tsx title="geistdocs.tsx"
|
|
151
|
+
export const agent = {
|
|
152
|
+
api: {
|
|
153
|
+
openApiUrl: "https://api.example.com/openapi.json",
|
|
154
|
+
siteOpenApiUrl: "/openapi.json",
|
|
155
|
+
},
|
|
156
|
+
} satisfies GeistdocsAgentReadinessConfig;
|
|
157
|
+
```
|
|
158
|
+
|
|
159
|
+
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.
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
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.
|
|
164
|
+
|
|
165
|
+
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.
|
|
166
|
+
|
|
137
167
|
## Keep it honest
|
|
138
168
|
|
|
139
169
|
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.
|
|
@@ -37,6 +37,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
|
|
|
37
37
|
| `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
|
|
38
38
|
| `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
|
|
39
39
|
| `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
|
|
40
|
+
| `app/[lang]/openapi.json/route.ts` | Serves an OpenAPI document for the site's own search, chat, and Markdown endpoints. |
|
|
40
41
|
| `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
|
|
41
42
|
| `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
|
|
42
43
|
| `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
|
package/docs/pages/migration.md
CHANGED
|
@@ -553,6 +553,7 @@ Check these URLs locally:
|
|
|
553
553
|
- `/sitemap.md`.
|
|
554
554
|
- `/agents.md`.
|
|
555
555
|
- `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
|
|
556
|
+
- `/openapi.json` if the site mounts `createOpenApiRoute`.
|
|
556
557
|
- A page-level Markdown URL such as `/docs/getting-started.mdx`.
|
|
557
558
|
- A non-docs route that should not be rewritten as Markdown, such as the homepage.
|
|
558
559
|
|
package/docs/pages/webmcp.md
CHANGED
|
@@ -7,52 +7,53 @@ source: apps/template/content/docs/webmcp.mdx
|
|
|
7
7
|
|
|
8
8
|
# WebMCP
|
|
9
9
|
|
|
10
|
-
Geistdocs
|
|
10
|
+
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`:
|
|
11
11
|
|
|
12
12
|
```ts
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
13
|
+
import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
|
|
14
|
+
import { config } from "@/lib/geistdocs/config";
|
|
15
|
+
import { GET as search } from "../search/route";
|
|
16
|
+
|
|
17
|
+
const handler = createMcpRoute({ config, search });
|
|
18
|
+
|
|
19
|
+
export { handler as GET, handler as POST };
|
|
17
20
|
```
|
|
18
21
|
|
|
19
|
-
The
|
|
22
|
+
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.
|
|
23
|
+
|
|
24
|
+
## Tools
|
|
20
25
|
|
|
21
26
|
| Tool | Input | Result |
|
|
22
27
|
| --- | --- | --- |
|
|
23
|
-
| `search_docs` | `query
|
|
24
|
-
| `read_current_page` | None |
|
|
28
|
+
| `search_docs` | Nonblank `query` up to 500 characters; optional configured `locale` | MCP result containing search results as JSON text |
|
|
29
|
+
| `read_current_page` | None | Current page as Markdown |
|
|
25
30
|
|
|
26
|
-
|
|
31
|
+
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`.
|
|
27
32
|
|
|
28
|
-
|
|
33
|
+
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.
|
|
29
34
|
|
|
30
|
-
##
|
|
35
|
+
## Lifecycle and safety
|
|
31
36
|
|
|
32
|
-
|
|
37
|
+
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.
|
|
33
38
|
|
|
34
|
-
|
|
35
|
-
const tools = await document.modelContext.getTools();
|
|
36
|
-
const search = tools.find((tool) => tool.name === "search_docs");
|
|
37
|
-
await document.modelContext.executeTool(search, JSON.stringify({ query: "configuration" }));
|
|
38
|
-
const read = tools.find((tool) => tool.name === "read_current_page");
|
|
39
|
-
await document.modelContext.executeTool(read, "{}");
|
|
40
|
-
```
|
|
39
|
+
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.
|
|
41
40
|
|
|
42
|
-
|
|
41
|
+
`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.
|
|
43
42
|
|
|
44
|
-
|
|
43
|
+
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.
|
|
45
44
|
|
|
46
|
-
|
|
45
|
+
The remote discovery manifest remains independent; configured external servers are not replaced.
|
|
46
|
+
|
|
47
|
+
## Verify locally
|
|
48
|
+
|
|
49
|
+
Use a compatible browser with WebMCP enabled. With agent-browser 0.36.0 or newer:
|
|
47
50
|
|
|
48
51
|
```bash
|
|
49
52
|
agent-browser --session docs-check open http://localhost:3000/docs
|
|
50
53
|
agent-browser --session docs-check webmcp list
|
|
51
|
-
agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration"}'
|
|
54
|
+
agent-browser --session docs-check webmcp invoke search_docs --params '{"query":"configuration","locale":"en"}'
|
|
52
55
|
agent-browser --session docs-check webmcp invoke read_current_page --params '{}'
|
|
53
56
|
agent-browser --session docs-check close
|
|
54
57
|
```
|
|
55
58
|
|
|
56
|
-
|
|
57
|
-
|
|
58
|
-
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.
|
|
59
|
+
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.
|
package/package.json
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
{
|
|
2
2
|
"name": "@vercel/geistdocs",
|
|
3
3
|
"description": "Runtime and CLI for Geistdocs projects.",
|
|
4
|
-
"version": "2.
|
|
4
|
+
"version": "2.6.1",
|
|
5
5
|
"license": "Apache-2.0",
|
|
6
6
|
"repository": {
|
|
7
7
|
"type": "git",
|
|
@@ -127,6 +127,10 @@
|
|
|
127
127
|
"types": "./dist/routes/mcp.d.ts",
|
|
128
128
|
"default": "./dist/routes/mcp.js"
|
|
129
129
|
},
|
|
130
|
+
"./routes/openapi": {
|
|
131
|
+
"types": "./dist/routes/openapi.d.ts",
|
|
132
|
+
"default": "./dist/routes/openapi.js"
|
|
133
|
+
},
|
|
130
134
|
"./routes/not-found": {
|
|
131
135
|
"types": "./dist/routes/not-found.d.ts",
|
|
132
136
|
"default": "./dist/routes/not-found.js"
|
|
@@ -255,6 +259,7 @@
|
|
|
255
259
|
"dependencies": {
|
|
256
260
|
"@ai-sdk/react": "^3.0.134",
|
|
257
261
|
"@clack/prompts": "^0.11.0",
|
|
262
|
+
"@modelcontextprotocol/server": "^2.0.0",
|
|
258
263
|
"@next/env": "16.3.3",
|
|
259
264
|
"@orama/tokenizers": "^3.1.16",
|
|
260
265
|
"@streamdown/cjk": "^1.0.1",
|
|
@@ -273,6 +278,7 @@
|
|
|
273
278
|
"fumadocs-ui": "16.2.2",
|
|
274
279
|
"geist": "1.7.1",
|
|
275
280
|
"glob": "^11.0.0",
|
|
281
|
+
"mcp-handler": "2.2.0",
|
|
276
282
|
"mermaid": "^11.12.2",
|
|
277
283
|
"motion": "^12.23.25",
|
|
278
284
|
"next-themes": "^0.4.6",
|
|
@@ -287,14 +293,14 @@
|
|
|
287
293
|
"remark-stringify": "^11.0.0",
|
|
288
294
|
"sonner": "^2.0.7",
|
|
289
295
|
"streamdown": "^2.1.0",
|
|
290
|
-
"ts-morph": "^27.0.2",
|
|
291
296
|
"tailwind-merge": "^3.4.0",
|
|
297
|
+
"ts-morph": "^27.0.2",
|
|
292
298
|
"tw-animate-css": "^1.4.0",
|
|
293
299
|
"unified": "^11.0.5",
|
|
294
300
|
"unist-util-visit": "^5.1.0",
|
|
295
301
|
"use-stick-to-bottom": "^1.1.1",
|
|
296
302
|
"vaul": "^1.1.2",
|
|
297
|
-
"zod": "^4.
|
|
303
|
+
"zod": "^4.6.5"
|
|
298
304
|
},
|
|
299
305
|
"peerDependencies": {
|
|
300
306
|
"next": "^16.3.3",
|
package/template/AGENTS.md
CHANGED
|
@@ -35,7 +35,7 @@ Use these instructions when an AI coding agent edits this project.
|
|
|
35
35
|
| Configure the Fumadocs source adapter or versioned docs | `lib/geistdocs/source.ts` |
|
|
36
36
|
| Configure Fumadocs collections and source-safe MDX processing | `source.config.ts` |
|
|
37
37
|
| Configure the docs page renderer | `app/[lang]/docs/[[...slug]]/page.tsx` |
|
|
38
|
-
| Configure AI-readable markdown output and recovery | `app/[lang]/agents.md/route.ts`, `app/[lang]/.well-known/mcp.json/route.ts`, `app/[lang]/llms.txt/route.ts`, `app/[lang]/llms.mdx/[[...slug]]/route.ts`, `app/[lang]/sitemap.md/route.ts` |
|
|
38
|
+
| Configure AI-readable markdown output and recovery | `app/[lang]/agents.md/route.ts`, `app/[lang]/.well-known/mcp.json/route.ts`, `app/[lang]/openapi.json/route.ts`, `app/[lang]/llms.txt/route.ts`, `app/[lang]/llms.mdx/[[...slug]]/route.ts`, `app/[lang]/sitemap.md/route.ts` |
|
|
39
39
|
| Configure chat or search APIs | `app/api/chat/route.ts`, `app/api/search/route.ts`, `app/api/search/export/route.ts` |
|
|
40
40
|
| Add request handling before or after Geistdocs routing | `proxy.ts` |
|
|
41
41
|
| Edit the marketing home page | `app/[lang]/(home)/**` |
|
|
@@ -0,0 +1,7 @@
|
|
|
1
|
+
import { createMcpRoute } from "@vercel/geistdocs/routes/mcp";
|
|
2
|
+
import { config } from "@/lib/geistdocs/config";
|
|
3
|
+
import { GET as search } from "../search/route";
|
|
4
|
+
|
|
5
|
+
const handler = createMcpRoute({ config, search });
|
|
6
|
+
|
|
7
|
+
export { handler as GET, handler as POST };
|
|
@@ -132,6 +132,36 @@ export const config = defineConfig({
|
|
|
132
132
|
});
|
|
133
133
|
```
|
|
134
134
|
|
|
135
|
+
## Describe the documentation site's own API
|
|
136
|
+
|
|
137
|
+
`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:
|
|
138
|
+
|
|
139
|
+
```ts title="app/[lang]/openapi.json/route.ts"
|
|
140
|
+
import { createOpenApiRoute } from "@vercel/geistdocs/routes/openapi";
|
|
141
|
+
import { config } from "@/lib/geistdocs/config";
|
|
142
|
+
|
|
143
|
+
export const { GET, generateStaticParams } = createOpenApiRoute({
|
|
144
|
+
config,
|
|
145
|
+
});
|
|
146
|
+
```
|
|
147
|
+
|
|
148
|
+
```tsx title="geistdocs.tsx"
|
|
149
|
+
export const agent = {
|
|
150
|
+
api: {
|
|
151
|
+
openApiUrl: "https://api.example.com/openapi.json",
|
|
152
|
+
siteOpenApiUrl: "/openapi.json",
|
|
153
|
+
},
|
|
154
|
+
} satisfies GeistdocsAgentReadinessConfig;
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
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.
|
|
158
|
+
|
|
159
|
+
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.
|
|
160
|
+
|
|
161
|
+
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.
|
|
162
|
+
|
|
163
|
+
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.
|
|
164
|
+
|
|
135
165
|
## Keep it honest
|
|
136
166
|
|
|
137
167
|
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.
|
|
@@ -35,6 +35,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
|
|
|
35
35
|
| `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
|
|
36
36
|
| `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
|
|
37
37
|
| `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
|
|
38
|
+
| `app/[lang]/openapi.json/route.ts` | Serves an OpenAPI document for the site's own search, chat, and Markdown endpoints. |
|
|
38
39
|
| `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
|
|
39
40
|
| `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
|
|
40
41
|
| `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
|
|
@@ -552,6 +552,7 @@ Check these URLs locally:
|
|
|
552
552
|
- `/sitemap.md`.
|
|
553
553
|
- `/agents.md`.
|
|
554
554
|
- `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
|
|
555
|
+
- `/openapi.json` if the site mounts `createOpenApiRoute`.
|
|
555
556
|
- A page-level Markdown URL such as `/docs/getting-started.mdx`.
|
|
556
557
|
- A non-docs route that should not be rewritten as Markdown, such as the homepage.
|
|
557
558
|
|
|
@@ -3,52 +3,53 @@ title: WebMCP
|
|
|
3
3
|
description: Expose documentation search and page reading to browser agents.
|
|
4
4
|
---
|
|
5
5
|
|
|
6
|
-
Geistdocs
|
|
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
|
-
|
|
10
|
-
|
|
11
|
-
|
|
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
|
|
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
|
|
20
|
-
| `read_current_page` | None |
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
##
|
|
31
|
+
## Lifecycle and safety
|
|
27
32
|
|
|
28
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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
|
-
|
|
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.
|
package/template/geistdocs.tsx
CHANGED
|
@@ -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,
|
package/template/package.json
CHANGED