docs: replace the typedoc site with VitePress (v2 + v1 reface) (#2395)

docs/.vitepress/config.mts

@@ -0,0 +1,89 @@
+import { existsSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+import { defineConfig, type DefaultTheme } from 'vitepress';
+
+const docsDir = resolve(dirname(fileURLToPath(import.meta.url)), '..');
+
+/**
+ * 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`),
+ * fall back to an empty group with a hint instead of crashing.
+ */
+function apiSidebarItems(): DefaultTheme.SidebarItem[] {
+    const sidebarPath = resolve(docsDir, 'api/typedoc-sidebar.json');
+    if (!existsSync(sidebarPath)) {
+        console.warn(`[docs] ${sidebarPath} not found — run \`pnpm docs:api\` first to populate the API Reference section.`);
+        return [];
+    }
+    return JSON.parse(readFileSync(sidebarPath, 'utf8'));
+}
+
+export default defineConfig({
+    title: 'MCP TypeScript SDK',
+    description: 'The TypeScript SDK implementation of the Model Context Protocol specification.',
+    base: '/v2/',
+    srcExclude: ['v1/**', 'behavior-surface-pins.md'],
+    sitemap: { hostname: 'https://ts.sdk.modelcontextprotocol.io/v2/' },
+    markdown: {
+        config(md) {
+            // Spec-generated JSDoc (packages/core-internal/src/types/spec.types.*.ts) carries
+            // site-root-relative links like /specification/draft/basic/index#meta that are meant
+            // to resolve on modelcontextprotocol.io. Rewrite them at render time so they work on
+            // this site (and so the dead-link check sees them as external).
+            const orig = md.renderer.rules.link_open ?? ((tokens, idx, options, _env, self) => self.renderToken(tokens, idx, options));
+            md.renderer.rules.link_open = (tokens, idx, options, env, self) => {
+                const href = tokens[idx].attrGet('href');
+                if (href?.startsWith('/specification/')) {
+                    tokens[idx].attrSet('href', `https://modelcontextprotocol.io${href}`);
+                }
+                return orig(tokens, idx, options, env, self);
+            };
+        }
+    },
+    themeConfig: {
+        nav: [
+            { text: 'Guide', link: '/server-quickstart', activeMatch: '^/(server|client|faq)' },
+            { text: 'Migration', link: '/migration/', activeMatch: '^/migration/' },
+            { text: 'API Reference', link: '/api/', activeMatch: '^/api/' },
+            { text: 'V1 Docs', link: 'https://ts.sdk.modelcontextprotocol.io/' }
+        ],
+        sidebar: [
+            {
+                text: 'Getting started',
+                items: [
+                    { text: 'Server Quickstart', link: '/server-quickstart' },
+                    { text: 'Client Quickstart', link: '/client-quickstart' }
+                ]
+            },
+            {
+                text: 'Guides',
+                items: [
+                    { text: 'Server', link: '/server' },
+                    { text: 'Client', link: '/client' }
+                ]
+            },
+            {
+                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' }
+                ]
+            },
+            {
+                text: 'FAQ',
+                items: [{ text: 'FAQ', link: '/faq' }]
+            },
+            {
+                text: 'API Reference',
+                collapsed: true,
+                items: apiSidebarItems()
+            }
+        ],
+        outline: { level: [2, 3] },
+        search: { provider: 'local' },
+        socialLinks: [{ icon: 'github', link: 'https://github.com/modelcontextprotocol/typescript-sdk' }]
+    }
+});