@vercel/geistdocs 1.3.1 → 1.4.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 +6 -0
- package/dist/config.d.ts.map +1 -1
- package/dist/routes/agents.d.ts.map +1 -1
- package/dist/routes/agents.js +14 -29
- package/dist/routes/discovery.d.ts +14 -0
- package/dist/routes/discovery.d.ts.map +1 -0
- package/dist/routes/discovery.js +74 -0
- package/dist/routes/mcp.d.ts +26 -0
- package/dist/routes/mcp.d.ts.map +1 -0
- package/dist/routes/mcp.js +31 -0
- package/dist/source.d.ts +1 -1
- package/dist/source.d.ts.map +1 -1
- package/dist/source.js +4 -1
- package/docs/agents.md +44 -0
- package/docs/llms.txt +2965 -0
- package/docs/manifest.json +194 -0
- package/docs/pages/agent-readiness.md +141 -0
- package/docs/pages/ask-ai.md +143 -0
- package/docs/pages/configuration.md +278 -0
- package/docs/pages/deployment.md +53 -0
- package/docs/pages/edit-on-github.md +53 -0
- package/docs/pages/env.md +62 -0
- package/docs/pages/feedback.md +91 -0
- package/docs/pages/getting-started.md +116 -0
- package/docs/pages/index.md +99 -0
- package/docs/pages/internationalization.md +124 -0
- package/docs/pages/llms-txt.md +88 -0
- package/docs/pages/md.md +84 -0
- package/docs/pages/migration.md +376 -0
- package/docs/pages/open-in-chat.md +82 -0
- package/docs/pages/provider.md +76 -0
- package/docs/pages/proxy.md +180 -0
- package/docs/pages/rss.md +110 -0
- package/docs/pages/syntax.md +413 -0
- package/docs/pages/theme-aware-image.md +59 -0
- package/docs/pages/versioned-docs.md +230 -0
- package/docs/sitemap.md +25 -0
- package/package.json +12 -2
- package/styles.css +174 -0
- package/template/AGENTS.md +10 -3
- package/template/app/[lang]/.well-known/mcp.json/route.ts +8 -0
- package/template/content/docs/agent-readiness.mdx +44 -8
- package/template/content/docs/configuration.mdx +1 -0
- package/template/content/docs/index.mdx +1 -1
- package/template/content/docs/llms-txt.mdx +1 -1
- package/template/content/docs/migration.mdx +12 -2
- package/template/package.json +1 -1
|
@@ -1,23 +1,23 @@
|
|
|
1
1
|
---
|
|
2
2
|
title: Agent readiness
|
|
3
|
-
description: Expose
|
|
3
|
+
description: Expose agents.md and MCP discovery files that help AI agents discover and use your docs site
|
|
4
4
|
type: guide
|
|
5
|
-
summary: Generate /agents.md from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
|
|
5
|
+
summary: Generate /agents.md and /.well-known/mcp.json from Geistdocs config so agents can find docs, Markdown surfaces, API specs, and MCP endpoints.
|
|
6
6
|
related:
|
|
7
7
|
- /docs/llms-txt
|
|
8
8
|
- /docs/md
|
|
9
9
|
- /docs/proxy
|
|
10
10
|
---
|
|
11
11
|
|
|
12
|
-
Geistdocs can generate `/agents.md
|
|
12
|
+
Geistdocs can generate `/agents.md` and `/.well-known/mcp.json` discovery files from your site config. These files tell AI agents where your docs live and which machine-readable integration surfaces your product declares.
|
|
13
13
|
|
|
14
|
-
<CopyPrompt text="Review this Geistdocs site's /agents.md
|
|
15
|
-
Review this Geistdocs site's `/agents.md`
|
|
14
|
+
<CopyPrompt text="Review this Geistdocs site's /agents.md and /.well-known/mcp.json files. Check whether they list the product description, documentation links, llms.txt, sitemap.md, OpenAPI specs, and MCP servers accurately.">
|
|
15
|
+
Review this Geistdocs site's `/agents.md` and `/.well-known/mcp.json` files. Check whether they list the product description, documentation links, `llms.txt`, `sitemap.md`, OpenAPI specs, and MCP servers accurately.
|
|
16
16
|
</CopyPrompt>
|
|
17
17
|
|
|
18
18
|
## What it provides
|
|
19
19
|
|
|
20
|
-
The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation.
|
|
20
|
+
The generated `/agents.md` file gives agents a stable starting point before they crawl the rest of your documentation. The optional `/.well-known/mcp.json` route advertises configured MCP servers without running an MCP server inside Geistdocs.
|
|
21
21
|
|
|
22
22
|
It can include:
|
|
23
23
|
|
|
@@ -45,6 +45,35 @@ export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
|
|
|
45
45
|
|
|
46
46
|
Because the route is under `[lang]`, the Geistdocs proxy can serve `/agents.md` through the default language route.
|
|
47
47
|
|
|
48
|
+
Generated projects also include a thin adapter for MCP discovery:
|
|
49
|
+
|
|
50
|
+
```ts title="app/[lang]/.well-known/mcp.json/route.ts"
|
|
51
|
+
import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
|
|
52
|
+
import { config } from "@/lib/geistdocs/config";
|
|
53
|
+
|
|
54
|
+
export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
|
|
55
|
+
config,
|
|
56
|
+
});
|
|
57
|
+
```
|
|
58
|
+
|
|
59
|
+
The MCP discovery route returns `404` until you configure `agent.mcp.servers`, so generated sites do not claim MCP support by default.
|
|
60
|
+
|
|
61
|
+
When configured, `/.well-known/mcp.json` returns the declared MCP servers:
|
|
62
|
+
|
|
63
|
+
```json
|
|
64
|
+
{
|
|
65
|
+
"name": "My Product",
|
|
66
|
+
"description": "My Product helps teams build and deploy applications.",
|
|
67
|
+
"servers": [
|
|
68
|
+
{
|
|
69
|
+
"name": "My Product MCP",
|
|
70
|
+
"url": "https://example.com/api/mcp",
|
|
71
|
+
"description": "Use product tools through MCP."
|
|
72
|
+
}
|
|
73
|
+
]
|
|
74
|
+
}
|
|
75
|
+
```
|
|
76
|
+
|
|
48
77
|
## Configure agent metadata
|
|
49
78
|
|
|
50
79
|
Add agent-readiness metadata in `geistdocs.tsx`, then pass it through `defineConfig` in `lib/geistdocs/config.tsx`.
|
|
@@ -62,6 +91,13 @@ export const agent = {
|
|
|
62
91
|
},
|
|
63
92
|
api: {
|
|
64
93
|
openApiUrl: "https://api.example.com/openapi.json",
|
|
94
|
+
openApiSpecs: [
|
|
95
|
+
{
|
|
96
|
+
label: "Admin API OpenAPI specification",
|
|
97
|
+
url: "https://api.example.com/admin/openapi.json",
|
|
98
|
+
description: "Administrative API operations.",
|
|
99
|
+
},
|
|
100
|
+
],
|
|
65
101
|
authDocsUrl: "/docs/authentication",
|
|
66
102
|
scopesDocsUrl: "/docs/scopes",
|
|
67
103
|
rateLimitsUrl: "/docs/rate-limits",
|
|
@@ -98,6 +134,6 @@ export const config = defineConfig({
|
|
|
98
134
|
|
|
99
135
|
## Keep it honest
|
|
100
136
|
|
|
101
|
-
Only list OpenAPI specs, authentication flows, or MCP servers that actually exist. Geistdocs makes product capabilities discoverable, but it does not create APIs or MCP tools for you.
|
|
137
|
+
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.
|
|
102
138
|
|
|
103
|
-
Use `/agents.md` with [llms.txt](/docs/llms-txt), [.md extension](/docs/md), and [Proxy and markdown routes](/docs/proxy) to give agents a complete discovery path.
|
|
139
|
+
Use `/agents.md` and `/.well-known/mcp.json` with [llms.txt](/docs/llms-txt), [.md extension](/docs/md), and [Proxy and markdown routes](/docs/proxy) to give agents a complete discovery path.
|
|
@@ -32,6 +32,7 @@ Configure Geistdocs through user-owned files in the generated project. Runtime f
|
|
|
32
32
|
| `components/geistdocs/docs-layout.tsx` | Customizes the package-backed docs layout, including optional sidebar content. |
|
|
33
33
|
| `app/[lang]/docs/[[...slug]]/page.tsx` | Configures the package docs page renderer. |
|
|
34
34
|
| `app/[lang]/agents.md/route.ts` | Configures the agent-readiness entry point. |
|
|
35
|
+
| `app/[lang]/.well-known/mcp.json/route.ts` | Configures MCP server discovery. |
|
|
35
36
|
| `app/[lang]/llms.txt/route.ts` | Configures the all-docs Markdown endpoint. |
|
|
36
37
|
| `app/[lang]/llms.mdx/[[...slug]]/route.ts` | Configures single-page Markdown responses. |
|
|
37
38
|
| `proxy.ts` | Configures markdown negotiation, AI-agent rewrites, request tracking, and custom request hooks. |
|
|
@@ -77,7 +77,7 @@ Advanced projects can use package APIs for versioned docs, multiple content sour
|
|
|
77
77
|
- Local content in `content/docs`
|
|
78
78
|
- Search and Ask AI
|
|
79
79
|
- Page actions, including feedback, copy page, open in chat, and edit on GitHub
|
|
80
|
-
- Agent-readiness metadata with `/agents.md`
|
|
80
|
+
- Agent-readiness metadata with `/agents.md` and `/.well-known/mcp.json`
|
|
81
81
|
- Raw Markdown routes for AI tools
|
|
82
82
|
- `llms.txt`
|
|
83
83
|
- Versioned docs and multiple content sources
|
|
@@ -18,7 +18,7 @@ Geistdocs implements the [llms.txt standard](https://llmstxt.org/), a convention
|
|
|
18
18
|
|
|
19
19
|
## What it is
|
|
20
20
|
|
|
21
|
-
The `/llms.txt` endpoint returns all configured documentation pages as Markdown in a single response. Each page is separated by blank lines so AI tools can parse the complete documentation set.
|
|
21
|
+
The `/llms.txt` endpoint returns all configured documentation pages as Markdown in a single response. Each page is separated by blank lines so AI tools can parse the complete documentation set. When agent metadata is configured, page-level Markdown also links agents to `/agents.md` for API and MCP discovery.
|
|
22
22
|
|
|
23
23
|
### Access
|
|
24
24
|
|
|
@@ -26,7 +26,7 @@ Create a working branch and inventory the current site before replacing code:
|
|
|
26
26
|
- Public route families, such as `/docs`, `/api-reference`, `/guides`, or `/`.
|
|
27
27
|
- Existing `middleware.ts` or `proxy.ts` behavior.
|
|
28
28
|
- Static files that overlap package routes, such as `public/llms.txt`.
|
|
29
|
-
- Search, chat, `llms.txt`, page-level Markdown, `sitemap.md`, `agents.md`, RSS, and Open Graph routes.
|
|
29
|
+
- Search, chat, `llms.txt`, page-level Markdown, `sitemap.md`, `agents.md`, `/.well-known/mcp.json`, RSS, and Open Graph routes.
|
|
30
30
|
- Tailwind CSS version and custom plugins.
|
|
31
31
|
- Direct app usage of `ai` or `@ai-sdk/react` outside Geistdocs.
|
|
32
32
|
- Environment variables required by the homepage, docs routes, or API routes.
|
|
@@ -213,6 +213,15 @@ export const { GET, generateStaticParams, revalidate } = createAgentsRoute({
|
|
|
213
213
|
});
|
|
214
214
|
```
|
|
215
215
|
|
|
216
|
+
```ts title="app/[lang]/.well-known/mcp.json/route.ts"
|
|
217
|
+
import { createMcpManifestRoute } from "@vercel/geistdocs/routes/mcp";
|
|
218
|
+
import { config } from "@/lib/geistdocs/config";
|
|
219
|
+
|
|
220
|
+
export const { GET, generateStaticParams, revalidate } = createMcpManifestRoute({
|
|
221
|
+
config,
|
|
222
|
+
});
|
|
223
|
+
```
|
|
224
|
+
|
|
216
225
|
Delete `public/llms.txt` after adding `createLlmsRoute`. Static files in `public` can mask App Router route behavior.
|
|
217
226
|
|
|
218
227
|
## Add search and Ask AI routes
|
|
@@ -354,6 +363,7 @@ Check these URLs locally:
|
|
|
354
363
|
- `/llms.txt`.
|
|
355
364
|
- `/sitemap.md`.
|
|
356
365
|
- `/agents.md`.
|
|
366
|
+
- `/.well-known/mcp.json` if `agent.mcp.servers` is configured.
|
|
357
367
|
- A page-level Markdown URL such as `/docs/getting-started.mdx`.
|
|
358
368
|
- A non-docs route that should not be rewritten as Markdown, such as the homepage.
|
|
359
369
|
|
|
@@ -361,4 +371,4 @@ Check these URLs locally:
|
|
|
361
371
|
|
|
362
372
|
- Read [Configuration](/docs/configuration) to review package config options.
|
|
363
373
|
- Read [Proxy and markdown routes](/docs/proxy) to tune request handling.
|
|
364
|
-
- Read [Agent readiness](/docs/agent-readiness) to configure `/agents.md` for AI agents.
|
|
374
|
+
- Read [Agent readiness](/docs/agent-readiness) to configure `/agents.md` and `/.well-known/mcp.json` for AI agents.
|
package/template/package.json
CHANGED
|
@@ -18,7 +18,7 @@
|
|
|
18
18
|
"@streamdown/code": "^1.0.1",
|
|
19
19
|
"@vercel/agent-readability": "^0.2.1",
|
|
20
20
|
"@vercel/analytics": "^1.6.1",
|
|
21
|
-
"@vercel/geistdocs": "1.
|
|
21
|
+
"@vercel/geistdocs": "1.4.1",
|
|
22
22
|
"@vercel/speed-insights": "^1.3.1",
|
|
23
23
|
"ai": "^6.0.132",
|
|
24
24
|
"class-variance-authority": "^0.7.1",
|