docs: generate llms.txt, llms-full.txt, and markdown page renditions (#2407)
This commit is contained in:
Felix Weinberger
GitHub
parent
f172626a8e
commit
ebca273a3c
7 changed files with 313 additions and 78 deletions
|
|
@ -4,8 +4,14 @@ import { fileURLToPath } from 'node:url';
|
|||
|
||||
import { defineConfig, type DefaultTheme } from 'vitepress';
|
||||
|
||||
import { generateLlmsArtifacts } from './llms';
|
||||
import { guideSidebar } from './nav';
|
||||
|
||||
const docsDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
|
||||
|
||||
/** Absolute site URL (origin + base), the single copy every consumer derives from. */
|
||||
const siteUrl = 'https://ts.sdk.modelcontextprotocol.io/v2';
|
||||
|
||||
/**
|
||||
* The API Reference sidebar is generated by `pnpm docs:api` (typedoc + typedoc-vitepress-theme)
|
||||
* into docs/api/typedoc-sidebar.json. When it is missing (e.g. `docs:dev` before `docs:api`),
|
||||
|
|
@ -25,7 +31,7 @@ export default defineConfig({
|
|||
description: 'The TypeScript SDK implementation of the Model Context Protocol specification.',
|
||||
base: '/v2/',
|
||||
srcExclude: ['v1/**', '_meta/**', 'behavior-surface-pins.md'],
|
||||
sitemap: { hostname: 'https://ts.sdk.modelcontextprotocol.io/v2/' },
|
||||
sitemap: { hostname: `${siteUrl}/` },
|
||||
markdown: {
|
||||
config(md) {
|
||||
// Spec-generated JSDoc (packages/core-internal/src/types/spec.types.*.ts) carries
|
||||
|
|
@ -42,6 +48,9 @@ export default defineConfig({
|
|||
};
|
||||
}
|
||||
},
|
||||
buildEnd(siteConfig) {
|
||||
generateLlmsArtifacts(docsDir, siteConfig.outDir, siteUrl);
|
||||
},
|
||||
themeConfig: {
|
||||
nav: [
|
||||
{ text: 'Get started', link: '/get-started/first-server', activeMatch: '^/get-started/' },
|
||||
|
|
@ -52,82 +61,7 @@ export default defineConfig({
|
|||
{ text: 'V1 Docs', link: 'https://ts.sdk.modelcontextprotocol.io/' }
|
||||
],
|
||||
sidebar: [
|
||||
{
|
||||
text: 'Get started',
|
||||
items: [
|
||||
{ text: 'Build a server', link: '/get-started/first-server' },
|
||||
{ text: 'Plug into a real host', link: '/get-started/real-host' },
|
||||
{ text: 'Build a client', link: '/get-started/first-client' },
|
||||
{ text: 'Packages', link: '/get-started/packages' },
|
||||
{ text: 'Examples', link: '/get-started/examples' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Servers',
|
||||
items: [
|
||||
{ text: 'Tools', link: '/servers/tools' },
|
||||
{ text: 'Resources', link: '/servers/resources' },
|
||||
{ text: 'Prompts', link: '/servers/prompts' },
|
||||
{ text: 'Completion', link: '/servers/completion' },
|
||||
{ text: 'Logging, progress, cancellation', link: '/servers/logging-progress-cancellation' },
|
||||
{ text: 'Elicitation', link: '/servers/elicitation' },
|
||||
{ text: 'Sampling (sunset)', link: '/servers/sampling' },
|
||||
{ text: 'Input required', link: '/servers/input-required' },
|
||||
{ text: 'Notifications', link: '/servers/notifications' },
|
||||
{ text: 'Errors', link: '/servers/errors' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Serving',
|
||||
items: [
|
||||
{ text: 'stdio', link: '/serving/stdio' },
|
||||
{ text: 'HTTP', link: '/serving/http' },
|
||||
{ text: 'Express', link: '/serving/express' },
|
||||
{ text: 'Hono', link: '/serving/hono' },
|
||||
{ text: 'Fastify', link: '/serving/fastify' },
|
||||
{ text: 'Web-standard runtimes', link: '/serving/web-standard' },
|
||||
{ text: 'Sessions, state, scaling', link: '/serving/sessions-state-scaling' },
|
||||
{ text: 'Authorization', link: '/serving/authorization' },
|
||||
{ text: 'Legacy clients', link: '/serving/legacy-clients' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Clients',
|
||||
items: [
|
||||
{ text: 'Connect', link: '/clients/connect' },
|
||||
{ text: 'Calling', link: '/clients/calling' },
|
||||
{ text: 'Handle server requests', link: '/clients/server-requests' },
|
||||
{ text: 'Roots (sunset)', link: '/clients/roots' },
|
||||
{ text: 'Subscriptions', link: '/clients/subscriptions' },
|
||||
{ text: 'OAuth', link: '/clients/oauth' },
|
||||
{ text: 'Machine auth', link: '/clients/machine-auth' },
|
||||
{ text: 'Middleware', link: '/clients/middleware' },
|
||||
{ text: 'Caching', link: '/clients/caching' }
|
||||
]
|
||||
},
|
||||
{ text: 'Protocol versions', link: '/protocol-versions' },
|
||||
{
|
||||
text: 'Advanced',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Low-level server', link: '/advanced/low-level-server' },
|
||||
{ text: 'Custom methods', link: '/advanced/custom-methods' },
|
||||
{ text: 'Schema libraries', link: '/advanced/schema-libraries' },
|
||||
{ text: 'Custom transports', link: '/advanced/custom-transports' },
|
||||
{ text: 'Wire schemas', link: '/advanced/wire-schemas' },
|
||||
{ text: 'Gateway', link: '/advanced/gateway' }
|
||||
]
|
||||
},
|
||||
{ text: 'Testing', link: '/testing' },
|
||||
{ text: 'Troubleshooting', link: '/troubleshooting' },
|
||||
{
|
||||
text: 'Migration',
|
||||
items: [
|
||||
{ text: 'Overview', link: '/migration/' },
|
||||
{ text: 'Upgrade to v2', link: '/migration/upgrade-to-v2' },
|
||||
{ text: '2026-07-28 protocol support', link: '/migration/support-2026-07-28' }
|
||||
]
|
||||
},
|
||||
...guideSidebar,
|
||||
{
|
||||
text: 'API Reference',
|
||||
collapsed: true,
|
||||
|
|
|
|||
213
docs/.vitepress/llms.ts
Normal file
213
docs/.vitepress/llms.ts
Normal file
|
|
@ -0,0 +1,213 @@
|
|||
import { mkdirSync, readFileSync, writeFileSync } from 'node:fs';
|
||||
import { dirname, join, posix } from 'node:path';
|
||||
|
||||
import type { DefaultTheme } from 'vitepress';
|
||||
|
||||
import { guideSidebar } from './nav';
|
||||
|
||||
/**
|
||||
* LLM-facing renditions of the docs, generated into the site output at build
|
||||
* time (wired into `buildEnd` in config.mts), following https://llmstxt.org
|
||||
* and the Python SDK's equivalent:
|
||||
*
|
||||
* - `<page>.md` next to every guide page's HTML — the page as plain markdown,
|
||||
* frontmatter stripped, links absolutized (cross-page links point at the
|
||||
* `.md` renditions so an agent can keep fetching markdown).
|
||||
* - `llms.txt` — the index: one line per page, grouped like the sidebar.
|
||||
* - `llms-full.txt` — every guide page concatenated in sidebar order.
|
||||
*
|
||||
* The generated API reference stays out of all three (linked, not inlined):
|
||||
* it would swamp the prose that answers most questions.
|
||||
*/
|
||||
|
||||
interface Page {
|
||||
/** Sidebar title. */
|
||||
title: string;
|
||||
/** Path of the markdown source relative to the docs dir, e.g. `servers/tools.md`. */
|
||||
sourcePath: string;
|
||||
/** Absolute URL of the markdown rendition. */
|
||||
mdUrl: string;
|
||||
}
|
||||
|
||||
interface Section {
|
||||
title: string;
|
||||
pages: Page[];
|
||||
}
|
||||
|
||||
function toPage(site: string, title: string, route: string): Page {
|
||||
const sourcePath = route === '/' ? 'index.md' : route.endsWith('/') ? `${route.slice(1)}index.md` : `${route.slice(1)}.md`;
|
||||
return { title, sourcePath, mdUrl: `${site}/${sourcePath}` };
|
||||
}
|
||||
|
||||
/** Flatten the sidebar into ordered sections, preserving sidebar order exactly. */
|
||||
function sections(site: string): Section[] {
|
||||
const out: Section[] = [{ title: 'Overview', pages: [toPage(site, 'MCP TypeScript SDK', '/')] }];
|
||||
for (const entry of guideSidebar as (DefaultTheme.SidebarItem & { items?: DefaultTheme.SidebarItem[] })[]) {
|
||||
if (entry.items) {
|
||||
out.push({ title: entry.text!, pages: entry.items.map(i => toPage(site, i.text!, i.link!)) });
|
||||
} else {
|
||||
out.push({ title: entry.text!, pages: [toPage(site, entry.text!, entry.link!)] });
|
||||
}
|
||||
}
|
||||
return out;
|
||||
}
|
||||
|
||||
/** Read a `description:` frontmatter value, if present. */
|
||||
function frontmatterDescription(markdown: string): string | undefined {
|
||||
if (!markdown.startsWith('---\n')) return undefined;
|
||||
const end = markdown.indexOf('\n---\n', 4);
|
||||
if (end === -1) return undefined;
|
||||
const match = /^description:\s*(.+)$/m.exec(markdown.slice(4, end));
|
||||
return match?.[1].trim().replace(/^(['"])(.*)\1$/, '$2');
|
||||
}
|
||||
|
||||
/** Strip `--- ... ---` frontmatter. */
|
||||
function stripFrontmatter(markdown: string): string {
|
||||
if (!markdown.startsWith('---\n')) return markdown;
|
||||
const end = markdown.indexOf('\n---\n', 4);
|
||||
return end === -1 ? markdown : markdown.slice(end + 5).replace(/^\n+/, '');
|
||||
}
|
||||
|
||||
/** Drop the `source="…"` wiring attribute from fence info lines. */
|
||||
function stripFenceAttributes(markdown: string): string {
|
||||
return markdown.replace(/^```(\w+)\s+source="[^"]*"\s*$/gm, '```$1');
|
||||
}
|
||||
|
||||
/**
|
||||
* Absolutize every link for a page living at `pageDir` (docs-relative, '' for
|
||||
* the root). Relative `.md` links stay `.md` so they resolve to the markdown
|
||||
* renditions; `/specification/…` goes to modelcontextprotocol.io, mirroring
|
||||
* the render-time rewrite in config.mts.
|
||||
*/
|
||||
function absolutizeLinks(markdown: string, pageDir: string, site: string, sourcePath: string): string {
|
||||
// Runs over the raw markdown, code fences included — fine while no code
|
||||
// sample contains a relative markdown link (none do; a false rewrite would
|
||||
// show up in review of the rendition).
|
||||
return markdown.replace(/\]\(([^)\s]+)\)/g, (match, target: string) => {
|
||||
if (/^(https?:|mailto:|#)/.test(target)) return match;
|
||||
if (target.startsWith('/specification/')) return `](https://modelcontextprotocol.io${target})`;
|
||||
if (target.startsWith('/')) return `](${site}${target})`;
|
||||
const hashIndex = target.indexOf('#');
|
||||
const path = hashIndex === -1 ? target : target.slice(0, hashIndex);
|
||||
const hash = hashIndex === -1 ? '' : target.slice(hashIndex);
|
||||
let resolved = posix.normalize(posix.join(pageDir, path));
|
||||
if (resolved.startsWith('..')) {
|
||||
throw new Error(`${sourcePath}: relative link escapes the docs root: ${target} — use the site URL or a GitHub URL`);
|
||||
}
|
||||
if (resolved.startsWith('api/')) {
|
||||
// The generated API reference has no markdown renditions — link its HTML.
|
||||
resolved = resolved.replace(/\.md$/, '.html');
|
||||
}
|
||||
return `](${site}/${resolved}${hash})`;
|
||||
});
|
||||
}
|
||||
|
||||
function renderPage(docsDir: string, page: Page, site: string): { markdown: string; description?: string } {
|
||||
const raw = readFileSync(join(docsDir, page.sourcePath), 'utf8');
|
||||
const pageDir = posix.dirname(page.sourcePath);
|
||||
return {
|
||||
markdown: absolutizeLinks(stripFenceAttributes(stripFrontmatter(raw)), pageDir === '.' ? '' : pageDir, site, page.sourcePath),
|
||||
description: frontmatterDescription(raw)
|
||||
};
|
||||
}
|
||||
|
||||
/** First prose sentence after the H1, markdown stripped, for the llms.txt index line. */
|
||||
function describe(rendered: string): string {
|
||||
const lines = rendered.split('\n');
|
||||
let inFence = false;
|
||||
let inContainer = false;
|
||||
let past = false;
|
||||
const paragraph: string[] = [];
|
||||
for (const line of lines) {
|
||||
if (line.startsWith('```')) {
|
||||
inFence = !inFence;
|
||||
continue;
|
||||
}
|
||||
if (inFence) continue;
|
||||
if (line.startsWith(':::')) {
|
||||
inContainer = line.trim() !== ':::';
|
||||
continue;
|
||||
}
|
||||
if (inContainer) continue;
|
||||
if (line.startsWith('# ')) {
|
||||
past = true;
|
||||
continue;
|
||||
}
|
||||
if (!past) continue;
|
||||
if (line.trim() === '' || /^[#>|]|^[-*] /.test(line)) {
|
||||
if (paragraph.length > 0) break;
|
||||
continue;
|
||||
}
|
||||
paragraph.push(line.trim());
|
||||
}
|
||||
const plain = paragraph
|
||||
.join(' ')
|
||||
.replace(/\[([^\]]*)\]\([^)]*\)/g, '$1')
|
||||
.replace(/[*`]/g, '')
|
||||
.trim();
|
||||
const sentence = /^(.*?[.!?])(\s|$)/.exec(plain);
|
||||
const blurb = sentence ? sentence[1] : plain;
|
||||
return blurb.length > 220 ? `${blurb.slice(0, 217).replace(/\s+\S*$/, '')}…` : blurb;
|
||||
}
|
||||
|
||||
/**
|
||||
* Generate llms.txt, llms-full.txt, and the per-page markdown renditions into
|
||||
* `outDir`. `site` is the absolute site URL without a trailing slash
|
||||
* (origin + base), owned by config.mts.
|
||||
*/
|
||||
export function generateLlmsArtifacts(docsDir: string, outDir: string, site: string): void {
|
||||
const groups = sections(site);
|
||||
const rendered = new Map<string, { markdown: string; blurb: string }>();
|
||||
|
||||
for (const section of groups) {
|
||||
for (const page of section.pages) {
|
||||
const { markdown, description } = renderPage(docsDir, page, site);
|
||||
rendered.set(page.sourcePath, { markdown, blurb: description ?? describe(markdown) });
|
||||
const outPath = join(outDir, page.sourcePath);
|
||||
mkdirSync(dirname(outPath), { recursive: true });
|
||||
writeFileSync(outPath, markdown);
|
||||
}
|
||||
}
|
||||
|
||||
const header = [
|
||||
'# MCP TypeScript SDK',
|
||||
'',
|
||||
'> The official TypeScript SDK for the Model Context Protocol (MCP): build MCP servers and clients on Node.js, Bun, Deno, and Workers. This is the v2 beta documentation, tracking the 2026-07-28 spec revision.',
|
||||
'',
|
||||
'Every page below is also served as plain markdown at its `.md` URL — fetch any page directly.',
|
||||
''
|
||||
];
|
||||
|
||||
const index = [...header];
|
||||
for (const section of groups) {
|
||||
index.push(`## ${section.title}`, '');
|
||||
for (const page of section.pages) {
|
||||
const blurb = rendered.get(page.sourcePath)!.blurb;
|
||||
index.push(`- [${page.title}](${page.mdUrl})${blurb ? `: ${blurb}` : ''}`);
|
||||
}
|
||||
index.push('');
|
||||
}
|
||||
index.push(
|
||||
'## Optional',
|
||||
'',
|
||||
`- [llms-full.txt](${site}/llms-full.txt): every page above concatenated into one file`,
|
||||
`- [API reference](${site}/api/): generated per-package API reference`,
|
||||
'- [MCP specification](https://modelcontextprotocol.io/specification/latest)',
|
||||
'- [v1 documentation](https://ts.sdk.modelcontextprotocol.io/)',
|
||||
''
|
||||
);
|
||||
writeFileSync(join(outDir, 'llms.txt'), index.join('\n'));
|
||||
|
||||
// A separator no page body contains ('---' appears in the guides as a
|
||||
// thematic break, so it cannot delimit pages unambiguously).
|
||||
const separator = '='.repeat(80);
|
||||
const full = [...header];
|
||||
for (const section of groups) {
|
||||
for (const page of section.pages) {
|
||||
full.push(separator, `Source: ${page.mdUrl}`, separator, '', rendered.get(page.sourcePath)!.markdown.trimEnd(), '');
|
||||
}
|
||||
}
|
||||
writeFileSync(join(outDir, 'llms-full.txt'), full.join('\n'));
|
||||
|
||||
console.log(`[docs] llms.txt, llms-full.txt, and ${rendered.size} markdown renditions written`);
|
||||
}
|
||||
85
docs/.vitepress/nav.ts
Normal file
85
docs/.vitepress/nav.ts
Normal file
|
|
@ -0,0 +1,85 @@
|
|||
import type { DefaultTheme } from 'vitepress';
|
||||
|
||||
/**
|
||||
* The guide sidebar: every hand-written page, in reading order. Shared by the
|
||||
* site config (which appends the generated API Reference group) and the
|
||||
* llms.txt generator (which mirrors these groups and this order).
|
||||
*/
|
||||
export const guideSidebar: DefaultTheme.SidebarItem[] = [
|
||||
{
|
||||
text: 'Get started',
|
||||
items: [
|
||||
{ text: 'Build a server', link: '/get-started/first-server' },
|
||||
{ text: 'Plug into a real host', link: '/get-started/real-host' },
|
||||
{ text: 'Build a client', link: '/get-started/first-client' },
|
||||
{ text: 'Packages', link: '/get-started/packages' },
|
||||
{ text: 'Examples', link: '/get-started/examples' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Servers',
|
||||
items: [
|
||||
{ text: 'Tools', link: '/servers/tools' },
|
||||
{ text: 'Resources', link: '/servers/resources' },
|
||||
{ text: 'Prompts', link: '/servers/prompts' },
|
||||
{ text: 'Completion', link: '/servers/completion' },
|
||||
{ text: 'Logging, progress, cancellation', link: '/servers/logging-progress-cancellation' },
|
||||
{ text: 'Elicitation', link: '/servers/elicitation' },
|
||||
{ text: 'Sampling (sunset)', link: '/servers/sampling' },
|
||||
{ text: 'Input required', link: '/servers/input-required' },
|
||||
{ text: 'Notifications', link: '/servers/notifications' },
|
||||
{ text: 'Errors', link: '/servers/errors' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Serving',
|
||||
items: [
|
||||
{ text: 'stdio', link: '/serving/stdio' },
|
||||
{ text: 'HTTP', link: '/serving/http' },
|
||||
{ text: 'Express', link: '/serving/express' },
|
||||
{ text: 'Hono', link: '/serving/hono' },
|
||||
{ text: 'Fastify', link: '/serving/fastify' },
|
||||
{ text: 'Web-standard runtimes', link: '/serving/web-standard' },
|
||||
{ text: 'Sessions, state, scaling', link: '/serving/sessions-state-scaling' },
|
||||
{ text: 'Authorization', link: '/serving/authorization' },
|
||||
{ text: 'Legacy clients', link: '/serving/legacy-clients' }
|
||||
]
|
||||
},
|
||||
{
|
||||
text: 'Clients',
|
||||
items: [
|
||||
{ text: 'Connect', link: '/clients/connect' },
|
||||
{ text: 'Calling', link: '/clients/calling' },
|
||||
{ text: 'Handle server requests', link: '/clients/server-requests' },
|
||||
{ text: 'Roots (sunset)', link: '/clients/roots' },
|
||||
{ text: 'Subscriptions', link: '/clients/subscriptions' },
|
||||
{ text: 'OAuth', link: '/clients/oauth' },
|
||||
{ text: 'Machine auth', link: '/clients/machine-auth' },
|
||||
{ text: 'Middleware', link: '/clients/middleware' },
|
||||
{ text: 'Caching', link: '/clients/caching' }
|
||||
]
|
||||
},
|
||||
{ text: 'Protocol versions', link: '/protocol-versions' },
|
||||
{
|
||||
text: 'Advanced',
|
||||
collapsed: true,
|
||||
items: [
|
||||
{ text: 'Low-level server', link: '/advanced/low-level-server' },
|
||||
{ text: 'Custom methods', link: '/advanced/custom-methods' },
|
||||
{ text: 'Schema libraries', link: '/advanced/schema-libraries' },
|
||||
{ text: 'Custom transports', link: '/advanced/custom-transports' },
|
||||
{ text: 'Wire schemas', link: '/advanced/wire-schemas' },
|
||||
{ text: 'Gateway', link: '/advanced/gateway' }
|
||||
]
|
||||
},
|
||||
{ text: 'Testing', link: '/testing' },
|
||||
{ text: 'Troubleshooting', link: '/troubleshooting' },
|
||||
{
|
||||
text: 'Migration',
|
||||
items: [
|
||||
{ text: 'Overview', link: '/migration/' },
|
||||
{ text: 'Upgrade to v2', link: '/migration/upgrade-to-v2' },
|
||||
{ text: '2026-07-28 protocol support', link: '/migration/support-2026-07-28' }
|
||||
]
|
||||
}
|
||||
];
|
||||
|
|
@ -1,5 +1,6 @@
|
|||
---
|
||||
shape: how-to
|
||||
description: 'Authenticate a client with no user present: client credentials, private-key JWT, and cross-app access.'
|
||||
---
|
||||
# Authenticate without a user
|
||||
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
---
|
||||
shape: how-to
|
||||
description: 'Sign an end user in from a client you build with the OAuth authorization-code flow.'
|
||||
---
|
||||
# Authenticate a user with OAuth
|
||||
|
||||
|
|
|
|||
|
|
@ -202,7 +202,7 @@ per-member declarations; per-member is recommended, since the v2 package split m
|
|||
actual needs explicit. To answer "which packages does this member need" directly, run
|
||||
the codemod against that member's directory with `--dry-run`: the manifest summary is
|
||||
computed from that member's own imports. (The authoritative import-path routing lives
|
||||
in the codemod's [mapping file](../../packages/codemod/src/migrations/v1-to-v2/mappings/importMap.ts).)
|
||||
in the codemod's [mapping file](https://github.com/modelcontextprotocol/typescript-sdk/blob/main/packages/codemod/src/migrations/v1-to-v2/mappings/importMap.ts).)
|
||||
|
||||
The framework adapter packages declare their framework as a **peer dependency**
|
||||
(`express`, `hono`, `fastify`); v1 shipped them as direct deps. The codemod adds the
|
||||
|
|
|
|||
|
|
@ -1,5 +1,6 @@
|
|||
---
|
||||
shape: how-to
|
||||
description: 'Require a bearer token on a server you run: verification, protected-resource metadata, and per-tool scopes.'
|
||||
---
|
||||
# Require authorization
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue