@docsector/docsector-reader 1.4.0 → 1.6.0

package/README.md

@@ -30,6 +30,8 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🤖 **AI-Friendly robots.txt** — Scaffold includes a `robots.txt` explicitly allowing 23 AI crawlers (GPTBot, ClaudeBot, PerplexityBot, GrokBot, etc.)
 - 🧭 **Content Signals** — Optional `Content-Signal` directive for declaring AI usage policy (`ai-train`, `search`, `ai-input`) in `robots.txt`
 - 🧩 **Agent Skills Discovery Index** — Optional `/.well-known/agent-skills/index.json` with RFC v0.2.0 schema and SHA-256 digests
+- 🪪 **MCP Server Card** — Optional `/.well-known/mcp/server-card.json` for MCP server discovery before connection
+- 🌐 **WebMCP Browser Tools** — Optional registration of in-page tools via `navigator.modelContext` for browser agents
 - 🔗 **Homepage Link Headers** — Auto-generated `Link` response headers for agent discovery (`api-catalog`, `service-doc`, `service-desc`, `describedby`) per RFC 8288 / RFC 9727
 - 🔌 **MCP Server** — Auto-generated [MCP](https://modelcontextprotocol.io) server at `/mcp` for AI assistant integration (Claude Desktop, VS Code, etc.)
 - 📄 **llms.txt / llms-full.txt** — Auto-generated [llms.txt](https://llmstxt.org) index and full-content file for LLM discovery (requires `siteUrl` in config)
@@ -45,6 +47,7 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🌗 **Dark/Light Mode** — Automatic theme switching with Quasar Dark Plugin
 - 🔗 **Anchor Navigation** — Right-side Table of Contents tree with scroll tracking and auto-scroll to active section
 - 🔎 **Search** — Menu search across all documentation content and tags
+- 🌐 **WebMCP Browser Tools** — Registers in-page tools for browser agents with `registerTool` and optional `provideContext` fallback
 - 📱 **Responsive** — Mobile-friendly with collapsible sidebar and drawers
 - 🏷️ **Status Badges** — Mark pages as `done`, `draft`, or `empty` with visual indicators
 - ✏️ **Edit on GitHub** — Direct links to edit pages on your repository
@@ -141,6 +144,126 @@ curl -X POST http://localhost:8788/mcp \
 
 ---
 
+## 🪪 MCP Server Card Discovery
+
+Docsector Reader can publish an MCP Server Card at:
+
+- `/.well-known/mcp/server-card.json`
+
+This supports pre-connection MCP discovery, exposing:
+
+- `serverInfo` (`name`, `version`)
+- MCP transport endpoint (defaults to `/mcp`)
+- `capabilities` for tools/resources/prompts
+
+When MCP is enabled, tool capabilities are derived from the generated server:
+
+- `search_{toolSuffix}`
+- `get_page_{toolSuffix}`
+
+### Configure
+
+```javascript
+export default {
+  // ...other config
+
+  mcp: {
+    serverName: 'my-docs',
+    toolSuffix: 'my_docs'
+  },
+
+  mcpServerCard: {
+    enabled: true,
+    path: '/.well-known/mcp/server-card.json',
+    transportEndpoint: '/mcp',
+    transportType: 'streamable-http',
+    protocolVersion: '2025-03-26',
+    capabilities: {
+      tools: { supported: true },
+      resources: { supported: false },
+      prompts: { supported: false }
+    }
+  }
+}
+```
+
+### Validate
+
+```bash
+npx docsector build
+cat dist/spa/.well-known/mcp/server-card.json
+cat dist/spa/_headers
+```
+
+External validation:
+
+```bash
+curl -X POST https://isitagentready.com/api/scan \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://YOUR-SITE.com"}'
+```
+
+Check `checks.discovery.mcpServerCard.status` equals `"pass"`.
+
+---
+
+## 🌐 WebMCP Browser Tools
+
+Docsector Reader can register browser-side tools for agents when
+`navigator.modelContext` is available (secure context required).
+
+Default tools:
+
+- `docs.search_docs` (bridges to MCP `search_{toolSuffix}`)
+- `docs.get_page` (bridges to MCP `get_page_{toolSuffix}`)
+- `docs.navigate_to` (SPA navigation)
+- `docs.copy_current_page` (current page markdown URL/content)
+
+### WebMCP Configure
+
+```javascript
+export default {
+  // ...other config
+
+  mcp: {
+    serverName: 'my-docs',
+    toolSuffix: 'my_docs'
+  },
+
+  webMcp: {
+    enabled: true,
+    apiMode: 'dual', // 'registerTool' | 'dual'
+    toolPrefix: 'docs',
+    bridgeEndpoint: '/mcp',
+    bridgeToMcp: true,
+    tools: {
+      searchDocs: true,
+      getPage: true,
+      navigateTo: true,
+      copyCurrentPage: true
+    }
+  }
+}
+```
+
+Notes:
+
+- `apiMode: 'registerTool'` uses only `navigator.modelContext.registerTool()`.
+- `apiMode: 'dual'` also attempts `provideContext` fallback when available.
+- Registration happens on page load and is automatically cleaned up on unmount.
+
+### WebMCP Validate
+
+```bash
+curl -X POST https://isitagentready.com/api/scan \
+  -H 'Content-Type: application/json' \
+  -d '{"url":"https://YOUR-SITE.com"}'
+```
+
+Check `checks.discovery.webMcp.status` equals `"pass"`.
+
+---
+
 ## � llms.txt (LLM Discovery)
 
 Docsector Reader automatically generates [llms.txt](https://llmstxt.org) files at build time when `siteUrl` is configured (same requirement as sitemap.xml).
@@ -550,6 +673,14 @@ export default {
     agentFallback: true
   },
 
+  mcpServerCard: {
+    enabled: true,
+    path: '/.well-known/mcp/server-card.json',
+    transportEndpoint: '/mcp',
+    transportType: 'streamable-http',
+    protocolVersion: '2025-03-26'
+  },
+
   contentSignals: {
     enabled: true,
     aiTrain: 'yes',

package/bin/docsector.js

@@ -23,7 +23,7 @@ const packageRoot = resolve(__dirname, '..')
 const args = process.argv.slice(2)
 const command = args[0]
 
-const VERSION = '1.4.0'
+const VERSION = '1.6.0'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -133,6 +133,38 @@ export default {
   //   toolSuffix: 'my_docs'
   // },
 
+  // @ MCP Server Card discovery (optional)
+  // Publishes /.well-known/mcp/server-card.json for pre-connection discovery.
+  // mcpServerCard: {
+  //   enabled: true,
+  //   path: '/.well-known/mcp/server-card.json',
+  //   transportEndpoint: '/mcp',
+  //   transportType: 'streamable-http',
+  //   protocolVersion: '2025-03-26',
+  //   capabilities: {
+  //     tools: { supported: true },
+  //     resources: { supported: false },
+  //     prompts: { supported: false }
+  //   }
+  // },
+
+  // @ WebMCP browser tools (optional)
+  // Registers tools in browser contexts that expose navigator.modelContext.
+  // Uses registerTool when available, with optional provideContext fallback.
+  // webMcp: {
+  //   enabled: true,
+  //   apiMode: 'dual', // 'registerTool' | 'dual'
+  //   toolPrefix: 'docs',
+  //   bridgeEndpoint: '/mcp',
+  //   bridgeToMcp: true,
+  //   tools: {
+  //     searchDocs: true,
+  //     getPage: true,
+  //     navigateTo: true,
+  //     copyCurrentPage: true
+  //   }
+  // },
+
   // @ Homepage Link headers for agent discovery (optional)
   // linkHeaders: {
   //   enabled: true,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "1.4.0",
+  "version": "1.6.0",
   "description": "A documentation rendering engine built with Vue 3, Quasar v2 and Vite. Transform Markdown into beautiful, navigable documentation sites.",
   "productName": "Docsector Reader",
   "author": "Rodrigo de Araujo Vieira",

package/src/App.vue

@@ -114,20 +114,24 @@
 </template>
 
 <script setup>
-import { reactive, computed, onMounted } from 'vue'
+import { reactive, computed, onMounted, onBeforeUnmount } from 'vue'
 import { useQuasar } from 'quasar'
 import { useStore } from 'vuex'
 import { useI18n } from 'vue-i18n'
-import { useRouter } from 'vue-router'
+import { useRouter, useRoute } from 'vue-router'
 
 import docsectorConfig from 'docsector.config.js'
+import { setupWebMcp } from './composables/useWebMcp'
 
 defineOptions({ name: 'App' })
 
 const $q = useQuasar()
 const store = useStore()
-const { locale } = useI18n()
+const { locale, t } = useI18n()
 const router = useRouter()
+const route = useRoute()
+
+let cleanupWebMcp = null
 
 const settings = reactive({
   general: {
@@ -213,6 +217,21 @@ onMounted(() => {
     settings.appearance.background.default = dark
   }
   $q.dark.set(dark)
+
+  cleanupWebMcp = setupWebMcp({
+    router,
+    route,
+    store,
+    translate: t,
+    locale
+  })
+})
+
+onBeforeUnmount(() => {
+  if (typeof cleanupWebMcp === 'function') {
+    cleanupWebMcp()
+    cleanupWebMcp = null
+  }
 })
 </script>
 

package/src/composables/useWebMcp.js

@@ -0,0 +1,398 @@
+import docsectorConfig from 'docsector.config.js'
+
+let activeCleanup = null
+
+function toSafeToolPrefix (prefix) {
+  const value = String(prefix || 'docs')
+    .trim()
+    .replace(/[^A-Za-z0-9_.-]/g, '_')
+
+  if (!value) {
+    return 'docs'
+  }
+
+  return value.slice(0, 48)
+}
+
+function decodeMarkdownSource (source) {
+  return String(source || '')
+    .replace(/{/g, '{')
+    .replace(/}/g, '}')
+    .replace(/\{'([^']+)'\}/g, '$1')
+    .replace(/&/g, '&')
+}
+
+function isSecurePageContext () {
+  if (typeof window === 'undefined') return false
+
+  if (window.isSecureContext) return true
+
+  const protocol = window.location?.protocol || ''
+  const host = window.location?.hostname || ''
+  return protocol === 'https:' || host === 'localhost' || host === '127.0.0.1'
+}
+
+function buildMcpEndpoint (bridgeEndpoint) {
+  if (typeof window === 'undefined') return '/mcp'
+
+  const endpoint = bridgeEndpoint || '/mcp'
+  try {
+    return new URL(endpoint, window.location.origin).toString()
+  } catch {
+    return `${window.location.origin}/mcp`
+  }
+}
+
+async function callMcpTool ({ endpoint, toolName, args }) {
+  const requestId = `${toolName}:${Date.now()}`
+  const response = await fetch(endpoint, {
+    method: 'POST',
+    headers: { 'Content-Type': 'application/json' },
+    body: JSON.stringify({
+      jsonrpc: '2.0',
+      id: requestId,
+      method: 'tools/call',
+      params: {
+        name: toolName,
+        arguments: args || {}
+      }
+    })
+  })
+
+  if (!response.ok) {
+    throw new Error(`MCP endpoint responded with ${response.status}`)
+  }
+
+  const payload = await response.json()
+  if (payload.error) {
+    throw new Error(payload.error.message || 'MCP tool call failed')
+  }
+
+  return payload.result || null
+}
+
+function normalizePath (inputPath) {
+  const value = String(inputPath || '').trim()
+  if (!value) return '/'
+
+  if (value.startsWith('http://') || value.startsWith('https://')) {
+    try {
+      const url = new URL(value)
+      return `${url.pathname}${url.search}${url.hash}`
+    } catch {
+      return '/'
+    }
+  }
+
+  if (value.startsWith('/')) {
+    return value
+  }
+
+  return `/${value}`
+}
+
+function createToolDefinitions ({
+  prefix,
+  mcpToolSuffix,
+  bridgeEndpoint,
+  bridgeToMcp,
+  tools,
+  router,
+  getCurrentPath,
+  getCurrentHash,
+  getLocale,
+  getAbsoluteI18nPath,
+  translate
+}) {
+  const endpoint = buildMcpEndpoint(bridgeEndpoint)
+
+  const maybeCallMcp = async (toolName, args) => {
+    if (!bridgeToMcp) {
+      throw new Error('MCP bridge disabled in webMcp configuration')
+    }
+
+    return callMcpTool({ endpoint, toolName, args })
+  }
+
+  const definitions = []
+
+  if (tools.searchDocs) {
+    definitions.push({
+      name: `${prefix}.search_docs`,
+      description: 'Search documentation pages by keyword and return top matches.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          query: {
+            type: 'string',
+            description: 'Search term or phrase.'
+          }
+        },
+        required: ['query']
+      },
+      annotations: { readOnlyHint: true },
+      execute: async (input) => {
+        const query = String(input?.query || '').trim()
+        if (!query) {
+          return {
+            ok: false,
+            error: 'Missing required field: query'
+          }
+        }
+
+        const toolName = `search_${mcpToolSuffix}`
+        const result = await maybeCallMcp(toolName, { query })
+
+        return {
+          ok: true,
+          query,
+          mcpTool: toolName,
+          endpoint,
+          result
+        }
+      }
+    })
+  }
+
+  if (tools.getPage) {
+    definitions.push({
+      name: `${prefix}.get_page`,
+      description: 'Fetch a documentation page in markdown format by its path.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Documentation page path without trailing .md.'
+          }
+        },
+        required: ['path']
+      },
+      annotations: { readOnlyHint: true },
+      execute: async (input) => {
+        const path = String(input?.path || '').trim()
+        if (!path) {
+          return {
+            ok: false,
+            error: 'Missing required field: path'
+          }
+        }
+
+        const toolName = `get_page_${mcpToolSuffix}`
+        const result = await maybeCallMcp(toolName, { path })
+
+        return {
+          ok: true,
+          path,
+          mcpTool: toolName,
+          endpoint,
+          result
+        }
+      }
+    })
+  }
+
+  if (tools.navigateTo) {
+    definitions.push({
+      name: `${prefix}.navigate_to`,
+      description: 'Navigate to a docs route and optional anchor hash in the current session.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          path: {
+            type: 'string',
+            description: 'Target path (absolute or relative).'
+          },
+          hash: {
+            type: 'string',
+            description: 'Optional hash fragment, with or without leading #.'
+          }
+        }
+      },
+      annotations: { readOnlyHint: false },
+      execute: async (input) => {
+        const path = normalizePath(input?.path || getCurrentPath())
+        const hashInput = String(input?.hash || '').trim()
+        const hash = hashInput ? (hashInput.startsWith('#') ? hashInput : `#${hashInput}`) : ''
+
+        await router.push({ path, hash })
+
+        return {
+          ok: true,
+          path,
+          hash,
+          currentPath: getCurrentPath(),
+          currentHash: getCurrentHash()
+        }
+      }
+    })
+  }
+
+  if (tools.copyCurrentPage) {
+    definitions.push({
+      name: `${prefix}.copy_current_page`,
+      description: 'Return markdown URL and markdown source for the current page context.',
+      inputSchema: {
+        type: 'object',
+        properties: {
+          includeContent: {
+            type: 'boolean',
+            description: 'When false, return metadata and URL only.'
+          }
+        }
+      },
+      annotations: { readOnlyHint: true },
+      execute: async (input) => {
+        const locale = getLocale() || 'en-US'
+        const currentPath = getCurrentPath()
+        const path = currentPath === '/' ? '/Homepage' : currentPath.replace(/\/+$/, '')
+        const markdownUrl = `${window.location.origin}${path}.md`
+
+        const includeContent = input?.includeContent !== false
+        const absolute = getAbsoluteI18nPath()
+
+        let content = ''
+        if (includeContent && absolute) {
+          const source = translate(`_.${absolute}.source`)
+          if (source) {
+            content = decodeMarkdownSource(source)
+          }
+        }
+
+        return {
+          ok: true,
+          locale,
+          path: currentPath,
+          markdownUrl,
+          content
+        }
+      }
+    })
+  }
+
+  return definitions
+}
+
+function registerWithProvideContext (modelContext, toolDefinitions) {
+  if (typeof modelContext.provideContext !== 'function') return null
+
+  const payload = {
+    tools: toolDefinitions.map((tool) => ({
+      name: tool.name,
+      description: tool.description,
+      inputSchema: tool.inputSchema,
+      execute: tool.execute
+    }))
+  }
+
+  const result = modelContext.provideContext(payload)
+
+  if (typeof result === 'function') {
+    return result
+  }
+
+  if (result && typeof result.dispose === 'function') {
+    return () => result.dispose()
+  }
+
+  if (result && typeof result.unregister === 'function') {
+    return () => result.unregister()
+  }
+
+  return null
+}
+
+export function setupWebMcp ({ router, route, store, translate, locale }) {
+  const webMcp = docsectorConfig.webMcp || {}
+  if (!webMcp.enabled) return () => {}
+
+  if (!isSecurePageContext()) return () => {}
+
+  const modelContext = navigator?.modelContext
+  if (!modelContext) return () => {}
+
+  if (activeCleanup) {
+    activeCleanup()
+    activeCleanup = null
+  }
+
+  const prefix = toSafeToolPrefix(webMcp.toolPrefix || 'docs')
+  const mcpToolSuffix = String(docsectorConfig.mcp?.toolSuffix || 'docs')
+    .replace(/[^A-Za-z0-9_]/g, '_')
+
+  const tools = {
+    searchDocs: webMcp.tools?.searchDocs !== false,
+    getPage: webMcp.tools?.getPage !== false,
+    navigateTo: webMcp.tools?.navigateTo !== false,
+    copyCurrentPage: webMcp.tools?.copyCurrentPage !== false
+  }
+
+  const definitions = createToolDefinitions({
+    prefix,
+    mcpToolSuffix,
+    bridgeEndpoint: webMcp.bridgeEndpoint || '/mcp',
+    bridgeToMcp: webMcp.bridgeToMcp !== false,
+    tools,
+    router,
+    getCurrentPath: () => route.path,
+    getCurrentHash: () => route.hash,
+    getLocale: () => locale.value,
+    getAbsoluteI18nPath: () => store?.state?.i18n?.absolute,
+    translate
+  })
+
+  if (definitions.length === 0) return () => {}
+
+  const supportsRegisterTool = typeof modelContext.registerTool === 'function'
+  const supportsProvideContext = typeof modelContext.provideContext === 'function'
+  const mode = webMcp.apiMode === 'registerTool' ? 'registerTool' : 'dual'
+
+  const abortController = new AbortController()
+  const cleanups = [() => abortController.abort()]
+
+  try {
+    if (supportsRegisterTool) {
+      for (const tool of definitions) {
+        modelContext.registerTool({
+          name: tool.name,
+          description: tool.description,
+          inputSchema: tool.inputSchema,
+          annotations: tool.annotations,
+          execute: tool.execute
+        }, { signal: abortController.signal })
+      }
+    } else if (mode === 'registerTool') {
+      return () => {}
+    }
+
+    if ((!supportsRegisterTool || mode === 'dual') && supportsProvideContext) {
+      const provideCleanup = registerWithProvideContext(modelContext, definitions)
+      if (provideCleanup) {
+        cleanups.push(provideCleanup)
+      }
+    }
+  } catch (error) {
+    if (import.meta.env?.DEV) {
+      console.warn('[docsector:webmcp] Failed to register tools', error)
+    }
+    return () => {}
+  }
+
+  const cleanup = () => {
+    while (cleanups.length > 0) {
+      const fn = cleanups.pop()
+      try {
+        fn()
+      } catch {
+        // Ignore cleanup errors
+      }
+    }
+  }
+
+  activeCleanup = cleanup
+  return cleanup
+}
+
+export default {
+  setupWebMcp
+}

package/src/index.js

@@ -78,6 +78,26 @@
  * @param {string} [config.agentSkills.path='/.well-known/agent-skills/index.json'] - Output URI path for Agent Skills index
  * @param {string} [config.agentSkills.schema='https://schemas.agentskills.io/discovery/0.2.0/schema.json'] - JSON Schema identifier for index payload
  * @param {Array<{name:string,type:'skill-md'|'archive',description:string,url:string,digest?:string}>} [config.agentSkills.skills=[]] - Skills to publish in discovery index
+ * @param {Object} [config.mcpServerCard] - MCP Server Card discovery settings
+ * @param {boolean} [config.mcpServerCard.enabled=false] - Enables generation of MCP Server Card discovery document
+ * @param {string} [config.mcpServerCard.path='/.well-known/mcp/server-card.json'] - Output URI path for MCP Server Card
+ * @param {string} [config.mcpServerCard.transportEndpoint='/mcp'] - MCP transport endpoint exposed by the server
+ * @param {string} [config.mcpServerCard.transportType='streamable-http'] - Transport type label for discovery metadata
+ * @param {string} [config.mcpServerCard.protocolVersion='2025-03-26'] - Protocol version advertised by the server card
+ * @param {Object} [config.mcpServerCard.capabilities] - Optional capability overrides for tools/resources/prompts
+ * @param {Array<Object>} [config.mcpServerCard.remotes=[]] - Optional additional remotes to include in the server card
+ * @param {Object} [config.mcpServerCard.metadata] - Optional additional metadata merged into the server card payload
+ * @param {Object} [config.webMcp] - WebMCP browser tools settings
+ * @param {boolean} [config.webMcp.enabled=false] - Enables browser-side WebMCP tool registration on page load
+ * @param {'registerTool'|'dual'} [config.webMcp.apiMode='dual'] - Registration mode: registerTool only or registerTool + provideContext fallback
+ * @param {string} [config.webMcp.toolPrefix='docs'] - Prefix used to build WebMCP tool names (e.g. docs.search_docs)
+ * @param {string} [config.webMcp.bridgeEndpoint='/mcp'] - Relative endpoint used to bridge search/get_page to the MCP HTTP server
+ * @param {boolean} [config.webMcp.bridgeToMcp=true] - Uses MCP endpoint bridge for search/get_page tools when true
+ * @param {Object} [config.webMcp.tools] - Per-tool enable flags
+ * @param {boolean} [config.webMcp.tools.searchDocs=true] - Enables tool search_docs
+ * @param {boolean} [config.webMcp.tools.getPage=true] - Enables tool get_page
+ * @param {boolean} [config.webMcp.tools.navigateTo=true] - Enables tool navigate_to
+ * @param {boolean} [config.webMcp.tools.copyCurrentPage=true] - Enables tool copy_current_page
  * @returns {Object} Resolved Docsector configuration
  */
 export function createDocsector (config = {}) {
@@ -169,6 +189,34 @@ export function createDocsector (config = {}) {
       schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
       skills: [],
       ...config.agentSkills
+    },
+
+    mcpServerCard: {
+      enabled: false,
+      path: '/.well-known/mcp/server-card.json',
+      transportEndpoint: '/mcp',
+      transportType: 'streamable-http',
+      protocolVersion: '2025-03-26',
+      capabilities: null,
+      remotes: [],
+      metadata: null,
+      ...config.mcpServerCard
+    },
+
+    webMcp: {
+      enabled: false,
+      apiMode: 'dual',
+      toolPrefix: 'docs',
+      bridgeEndpoint: '/mcp',
+      bridgeToMcp: true,
+      ...config.webMcp,
+      tools: {
+        searchDocs: true,
+        getPage: true,
+        navigateTo: true,
+        copyCurrentPage: true,
+        ...(config.webMcp?.tools || {})
+      }
     }
   }
 }

package/src/quasar.factory.js

@@ -757,6 +757,8 @@ function createMarkdownBuildPlugin (projectRoot) {
       const contentSignalsEnabled = contentSignalsConfig.enabled === true
       const agentSkillsConfig = config.agentSkills || {}
       const agentSkillsEnabled = agentSkillsConfig.enabled === true
+      const mcpServerCardConfig = config.mcpServerCard || {}
+      const mcpServerCardEnabled = mcpServerCardConfig.enabled === true
 
       const toUrl = (href) => {
         if (!href) return null
@@ -1112,6 +1114,54 @@ export async function onRequest (context) {
         }
       }
 
+      if (mcpServerCardEnabled) {
+        if (!config.mcp) {
+          console.warn('\x1b[33m[docsector]\x1b[0m Skipped MCP Server Card generation: mcp config is not enabled')
+        } else {
+          const mcpServerCardPath = mcpServerCardConfig.path || '/.well-known/mcp/server-card.json'
+          const cardDistPath = normalizeLocalPath(mcpServerCardPath)
+
+          if (!cardDistPath) {
+            console.warn(`\x1b[33m[docsector]\x1b[0m Skipped MCP Server Card generation: path must be a local URI path, got "${mcpServerCardPath}"`)
+          } else {
+            const cardHref = mcpServerCardPath.startsWith('/') ? mcpServerCardPath : `/${mcpServerCardPath}`
+            const mcpServerName = config.mcp.serverName || config.branding?.name || 'docs'
+            const mcpServerVersion = config.branding?.version || '1.0.0'
+            const mcpToolSuffix = config.mcp.toolSuffix || 'docs'
+            const transportEndpoint = mcpServerCardConfig.transportEndpoint || '/mcp'
+            const endpoint = toUrl(transportEndpoint)
+
+            if (!endpoint) {
+              console.warn('\x1b[33m[docsector]\x1b[0m Skipped MCP Server Card generation: unable to resolve transport endpoint URL')
+            } else {
+              const cardPayload = buildMcpServerCardPayload({
+                config,
+                mcpServerCardConfig,
+                serverName: mcpServerName,
+                serverVersion: mcpServerVersion,
+                endpoint,
+                toolSuffix: mcpToolSuffix
+              })
+
+              const cardDir = resolve(distDir, cardDistPath, '..')
+              mkdirSync(cardDir, { recursive: true })
+              writeFileSync(
+                resolve(distDir, cardDistPath),
+                JSON.stringify(cardPayload, null, 2) + '\n'
+              )
+              console.log(`\x1b[36m[docsector]\x1b[0m Generated ${cardHref}`)
+
+              const headersWithServerCard = readFileSync(headersPath, 'utf-8')
+              if (!headersWithServerCard.includes(cardHref)) {
+                const serverCardHeaders = `${cardHref}\n  Content-Type: application/json; charset=utf-8\n`
+                writeFileSync(headersPath, headersWithServerCard.trimEnd() + '\n\n' + serverCardHeaders)
+                console.log(`\x1b[36m[docsector]\x1b[0m Added _headers rule for ${cardHref}`)
+              }
+            }
+          }
+        }
+      }
+
       console.log(`\x1b[36m[docsector]\x1b[0m Added _headers rule for .md files`)
 
       // Add homepage Link headers for agent discovery (RFC 8288 / RFC 9727)
@@ -1504,6 +1554,87 @@ function resolveAgentSkillArtifactPath (artifactUrl, { siteUrl, distDir }) {
   return resolve(distDir, relativePath)
 }
 
+function mergeObjects (base, override) {
+  if (!override || typeof override !== 'object' || Array.isArray(override)) {
+    return base
+  }
+
+  return { ...base, ...override }
+}
+
+function buildMcpServerCardPayload ({
+  config,
+  mcpServerCardConfig,
+  serverName,
+  serverVersion,
+  endpoint,
+  toolSuffix
+}) {
+  const transportType = mcpServerCardConfig.transportType || 'streamable-http'
+  const protocolVersion = mcpServerCardConfig.protocolVersion || '2025-03-26'
+  const baseTools = [
+    `search_${toolSuffix}`,
+    `get_page_${toolSuffix}`
+  ]
+
+  const defaultCapabilities = {
+    tools: {
+      supported: true,
+      names: baseTools
+    },
+    resources: {
+      supported: false
+    },
+    prompts: {
+      supported: false
+    }
+  }
+
+  const capabilitiesOverride = (mcpServerCardConfig.capabilities && typeof mcpServerCardConfig.capabilities === 'object' && !Array.isArray(mcpServerCardConfig.capabilities))
+    ? mcpServerCardConfig.capabilities
+    : {}
+  const capabilities = {
+    ...capabilitiesOverride,
+    tools: mergeObjects(defaultCapabilities.tools, capabilitiesOverride.tools),
+    resources: mergeObjects(defaultCapabilities.resources, capabilitiesOverride.resources),
+    prompts: mergeObjects(defaultCapabilities.prompts, capabilitiesOverride.prompts)
+  }
+
+  const primaryRemote = {
+    transportType,
+    endpoint,
+    supportedProtocolVersions: [protocolVersion]
+  }
+
+  const customRemotes = Array.isArray(mcpServerCardConfig.remotes)
+    ? mcpServerCardConfig.remotes
+    : []
+  const remotes = [primaryRemote, ...customRemotes]
+
+  const payload = {
+    serverInfo: {
+      name: serverName,
+      version: serverVersion
+    },
+    title: config.branding?.name || serverName,
+    description: config.branding?.description || null,
+    transport: {
+      type: transportType,
+      endpoint
+    },
+    remotes,
+    capabilities,
+    tools: baseTools.map(name => ({ name }))
+  }
+
+  const metadata = mcpServerCardConfig.metadata
+  if (metadata && typeof metadata === 'object' && !Array.isArray(metadata)) {
+    return { ...payload, ...metadata }
+  }
+
+  return payload
+}
+
 /**
  * Create a complete Quasar configuration for a docsector-reader consumer project.
  *