@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.
Files changed (48) hide show
  1. package/dist/cli/index.js +1 -1
  2. package/dist/config.d.ts +6 -0
  3. package/dist/config.d.ts.map +1 -1
  4. package/dist/routes/agents.d.ts.map +1 -1
  5. package/dist/routes/agents.js +14 -29
  6. package/dist/routes/discovery.d.ts +14 -0
  7. package/dist/routes/discovery.d.ts.map +1 -0
  8. package/dist/routes/discovery.js +74 -0
  9. package/dist/routes/mcp.d.ts +26 -0
  10. package/dist/routes/mcp.d.ts.map +1 -0
  11. package/dist/routes/mcp.js +31 -0
  12. package/dist/source.d.ts +1 -1
  13. package/dist/source.d.ts.map +1 -1
  14. package/dist/source.js +4 -1
  15. package/docs/agents.md +44 -0
  16. package/docs/llms.txt +2965 -0
  17. package/docs/manifest.json +194 -0
  18. package/docs/pages/agent-readiness.md +141 -0
  19. package/docs/pages/ask-ai.md +143 -0
  20. package/docs/pages/configuration.md +278 -0
  21. package/docs/pages/deployment.md +53 -0
  22. package/docs/pages/edit-on-github.md +53 -0
  23. package/docs/pages/env.md +62 -0
  24. package/docs/pages/feedback.md +91 -0
  25. package/docs/pages/getting-started.md +116 -0
  26. package/docs/pages/index.md +99 -0
  27. package/docs/pages/internationalization.md +124 -0
  28. package/docs/pages/llms-txt.md +88 -0
  29. package/docs/pages/md.md +84 -0
  30. package/docs/pages/migration.md +376 -0
  31. package/docs/pages/open-in-chat.md +82 -0
  32. package/docs/pages/provider.md +76 -0
  33. package/docs/pages/proxy.md +180 -0
  34. package/docs/pages/rss.md +110 -0
  35. package/docs/pages/syntax.md +413 -0
  36. package/docs/pages/theme-aware-image.md +59 -0
  37. package/docs/pages/versioned-docs.md +230 -0
  38. package/docs/sitemap.md +25 -0
  39. package/package.json +12 -2
  40. package/styles.css +174 -0
  41. package/template/AGENTS.md +10 -3
  42. package/template/app/[lang]/.well-known/mcp.json/route.ts +8 -0
  43. package/template/content/docs/agent-readiness.mdx +44 -8
  44. package/template/content/docs/configuration.mdx +1 -0
  45. package/template/content/docs/index.mdx +1 -1
  46. package/template/content/docs/llms-txt.mdx +1 -1
  47. package/template/content/docs/migration.mdx +12 -2
  48. package/template/package.json +1 -1
@@ -1,23 +1,23 @@
1
1
  ---
2
2
  title: Agent readiness
3
- description: Expose a concise agents.md file that helps AI agents discover and use your docs site
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`, a concise Markdown file that tells AI agents what your product is, where your docs live, and which machine-readable integration surfaces are available.
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 file. Check whether it lists the product description, documentation links, llms.txt, sitemap.md, OpenAPI specs, and MCP servers accurately.">
15
- Review this Geistdocs site's `/agents.md` file. Check whether it lists the product description, documentation links, `llms.txt`, `sitemap.md`, OpenAPI specs, and MCP servers accurately.
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.
@@ -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.3.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",