@docsector/docsector-reader 1.3.1 → 1.5.0

package/README.md

@@ -29,6 +29,8 @@ Transform Markdown content into beautiful, navigable documentation sites — wit
 - 🗺️ **Sitemap Generation** — Automatic `sitemap.xml` generation at build time with all page URLs (requires `siteUrl` in config)
 - 🤖 **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
 - 🔗 **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)
@@ -140,6 +142,69 @@ 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"`.
+
+---
+
 ## � 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).
@@ -333,6 +398,68 @@ Check `checks.botAccessControl.contentSignals.status` equals `"pass"`.
 
 ---
 
+## 🧩 Agent Skills Discovery Index
+
+Docsector Reader can publish a discovery index at:
+
+- `/.well-known/agent-skills/index.json`
+
+The generated payload follows Agent Skills Discovery RFC v0.2.0 and includes:
+
+- `$schema`
+- `skills[]` entries with `name`, `type`, `description`, `url`, `digest`
+
+When `digest` is omitted in config, Docsector computes it automatically from the referenced local artifact and writes it as:
+
+- `sha256:{hex}`
+
+### Configure
+
+```javascript
+export default {
+  // ...other config
+
+  agentSkills: {
+    enabled: true,
+    path: '/.well-known/agent-skills/index.json',
+    schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
+    skills: [
+      {
+        name: 'my-docs-mcp',
+        type: 'skill-md',
+        description: 'Search and fetch docs pages via MCP.',
+        url: '/.well-known/agent-skills/my-docs-mcp/SKILL.md'
+      }
+    ]
+  }
+}
+```
+
+Notes:
+
+- `name` must be lowercase alphanumeric plus hyphens.
+- `type` must be `skill-md` or `archive`.
+- `url` should point to a locally published artifact when auto-digest is used.
+
+### Validate
+
+```bash
+npx docsector build
+cat dist/spa/.well-known/agent-skills/index.json
+```
+
+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.agentSkills.status` equals `"pass"`.
+
+---
+
 ## �🚀 Quick Start
 
 ### 📦 Install
@@ -487,6 +614,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',
@@ -496,6 +631,20 @@ export default {
     applyToAllBlocks: false
   },
 
+  agentSkills: {
+    enabled: true,
+    path: '/.well-known/agent-skills/index.json',
+    schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
+    skills: [
+      {
+        name: 'my-docs-mcp',
+        type: 'skill-md',
+        description: 'Search and fetch docs pages via MCP.',
+        url: '/.well-known/agent-skills/my-docs-mcp/SKILL.md'
+      }
+    ]
+  },
+
   languages: [
     { image: '/images/flags/united-states-of-america.png', label: 'English (US)', value: 'en-US' },
     { image: '/images/flags/brazil.png', label: 'Português (BR)', value: 'pt-BR' }

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.3.1'
+const VERSION = '1.5.0'
 
 const HELP = `
   Docsector Reader v${VERSION}
@@ -133,6 +133,21 @@ 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 }
+  //   }
+  // },
+
   // @ Homepage Link headers for agent discovery (optional)
   // linkHeaders: {
   //   enabled: true,
@@ -181,6 +196,23 @@ export default {
   //   applyToAllBlocks: false
   // },
 
+  // @ Agent Skills discovery index (optional)
+  // Publishes /.well-known/agent-skills/index.json (RFC v0.2.0)
+  // and computes sha256 digests from local artifacts.
+  // agentSkills: {
+  //   enabled: true,
+  //   path: '/.well-known/agent-skills/index.json',
+  //   schema: 'https://schemas.agentskills.io/discovery/0.2.0/schema.json',
+  //   skills: [
+  //     {
+  //       name: 'my-docs-mcp',
+  //       type: 'skill-md',
+  //       description: 'Search and read docs pages through MCP.',
+  //       url: '/.well-known/agent-skills/my-docs-mcp/SKILL.md'
+  //     }
+  //   ]
+  // },
+
   // @ Languages
   languages: [
     {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@docsector/docsector-reader",
-  "version": "1.3.1",
+  "version": "1.5.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/index.js

@@ -73,6 +73,20 @@
  * @param {'yes'|'no'|boolean} [config.contentSignals.aiInput='yes'] - Permission for AI input/inference-time consumption
  * @param {string} [config.contentSignals.userAgent='*'] - Target User-agent block for directive injection
  * @param {boolean} [config.contentSignals.applyToAllBlocks=false] - When true, applies directive to every User-agent block
+ * @param {Object} [config.agentSkills] - Agent Skills discovery index settings
+ * @param {boolean} [config.agentSkills.enabled=false] - Enables generation of Agent Skills discovery index
+ * @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
  * @returns {Object} Resolved Docsector configuration
  */
 export function createDocsector (config = {}) {
@@ -156,6 +170,26 @@ export function createDocsector (config = {}) {
       userAgent: '*',
       applyToAllBlocks: false,
       ...config.contentSignals
+    },
+
+    agentSkills: {
+      enabled: false,
+      path: '/.well-known/agent-skills/index.json',
+      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
     }
   }
 }

package/src/quasar.factory.js

@@ -755,6 +755,23 @@ function createMarkdownBuildPlugin (projectRoot) {
       const webBotAuthSignatureLabel = webBotAuthConfig.signatureLabel || 'sig1'
       const contentSignalsConfig = config.contentSignals || {}
       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
+        if (/^https?:\/\//i.test(href)) return href
+        const normalizedHref = href.startsWith('/') ? href : `/${href}`
+        return siteUrl ? `${siteUrl}${normalizedHref}` : normalizedHref
+      }
+
+      const normalizeLocalPath = (href) => {
+        if (!href || /^https?:\/\//i.test(href)) return null
+        const path = href.startsWith('/') ? href.slice(1) : href
+        return path || null
+      }
 
       if (markdownNegotiationEnabled || webBotAuthEnabled) {
         const functionsDir = resolve(projectRoot, 'functions')
@@ -1022,6 +1039,129 @@ export async function onRequest (context) {
         }
       }
 
+      if (agentSkillsEnabled) {
+        const agentSkillsPath = agentSkillsConfig.path || '/.well-known/agent-skills/index.json'
+        const agentSkillsSchema = agentSkillsConfig.schema || 'https://schemas.agentskills.io/discovery/0.2.0/schema.json'
+        const indexDistPath = normalizeLocalPath(agentSkillsPath)
+
+        if (!indexDistPath) {
+          console.warn(`\x1b[33m[docsector]\x1b[0m Skipped Agent Skills index generation: path must be a local URI path, got "${agentSkillsPath}"`)
+        } else {
+          const indexHref = agentSkillsPath.startsWith('/') ? agentSkillsPath : `/${agentSkillsPath}`
+          const configuredSkills = Array.isArray(agentSkillsConfig.skills)
+            ? agentSkillsConfig.skills
+            : []
+
+          const normalizedSkills = configuredSkills.map((skill, index) => {
+            if (!skill || typeof skill !== 'object') {
+              throw new Error(`[docsector] agentSkills.skills[${index}] must be an object`)
+            }
+
+            const name = String(skill.name || '').trim().toLowerCase()
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(name)) {
+              throw new Error(`[docsector] agentSkills.skills[${index}].name must be lowercase alphanumeric and hyphen-separated`)
+            }
+
+            const type = normalizeAgentSkillType(skill.type, index)
+            const description = String(skill.description || '').trim()
+            if (!description) {
+              throw new Error(`[docsector] agentSkills.skills[${index}].description is required`)
+            }
+
+            const url = toUrl(skill.url)
+            if (!url) {
+              throw new Error(`[docsector] agentSkills.skills[${index}].url is required`)
+            }
+
+            let digest = normalizeAgentSkillDigest(skill.digest)
+            if (!digest) {
+              const artifactPath = resolveAgentSkillArtifactPath(url, { siteUrl, distDir })
+              if (!artifactPath || !existsSync(artifactPath)) {
+                throw new Error(`[docsector] Unable to compute digest for agentSkills.skills[${index}] (${name}). Artifact not found at ${url}`)
+              }
+              const artifactContents = readFileSync(artifactPath)
+              digest = `sha256:${createHash('sha256').update(artifactContents).digest('hex')}`
+            }
+
+            return {
+              name,
+              type,
+              description,
+              url,
+              digest
+            }
+          })
+
+          const agentSkillsIndex = {
+            $schema: agentSkillsSchema,
+            skills: normalizedSkills
+          }
+
+          const indexDir = resolve(distDir, indexDistPath, '..')
+          mkdirSync(indexDir, { recursive: true })
+          writeFileSync(
+            resolve(distDir, indexDistPath),
+            JSON.stringify(agentSkillsIndex, null, 2) + '\n'
+          )
+          console.log(`\x1b[36m[docsector]\x1b[0m Generated ${indexHref}`)
+
+          const headersWithSkills = readFileSync(headersPath, 'utf-8')
+          if (!headersWithSkills.includes(indexHref)) {
+            const skillsHeaders = `${indexHref}\n  Content-Type: application/json; charset=utf-8\n`
+            writeFileSync(headersPath, headersWithSkills.trimEnd() + '\n\n' + skillsHeaders)
+            console.log(`\x1b[36m[docsector]\x1b[0m Added _headers rule for ${indexHref}`)
+          }
+        }
+      }
+
+      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)
@@ -1081,19 +1221,6 @@ export async function onRequest (context) {
         const apiCatalogEnabled = apiCatalogConfig.enabled !== false
         const apiCatalogPath = (apiCatalogConfig.path || apiCatalogHref || '/.well-known/api-catalog')
 
-        const toUrl = (href) => {
-          if (!href) return null
-          if (/^https?:\/\//i.test(href)) return href
-          const normalizedHref = href.startsWith('/') ? href : `/${href}`
-          return siteUrl ? `${siteUrl}${normalizedHref}` : normalizedHref
-        }
-
-        const normalizeLocalPath = (href) => {
-          if (!href || /^https?:\/\//i.test(href)) return null
-          const path = href.startsWith('/') ? href.slice(1) : href
-          return path || null
-        }
-
         if (apiCatalogEnabled && apiCatalogPath) {
           const catalogDistPath = normalizeLocalPath(apiCatalogPath)
 
@@ -1376,6 +1503,138 @@ function applyContentSignalsToRobots (robotsContent, { contentSignalLine, userAg
   return updated.join('\n').replace(/\n+$/g, '') + '\n'
 }
 
+function normalizeAgentSkillType (type, index) {
+  const normalizedType = String(type || '').trim()
+  if (normalizedType !== 'skill-md' && normalizedType !== 'archive') {
+    throw new Error(`[docsector] agentSkills.skills[${index}].type must be "skill-md" or "archive"`)
+  }
+  return normalizedType
+}
+
+function normalizeAgentSkillDigest (digest) {
+  if (digest === null || digest === undefined || digest === '') return null
+  const normalizedDigest = String(digest).trim().toLowerCase()
+  if (!/^sha256:[a-f0-9]{64}$/.test(normalizedDigest)) {
+    throw new Error('[docsector] agentSkills.skills[*].digest must follow "sha256:{hex}"')
+  }
+  return normalizedDigest
+}
+
+function resolveAgentSkillArtifactPath (artifactUrl, { siteUrl, distDir }) {
+  if (!artifactUrl || typeof artifactUrl !== 'string') {
+    return null
+  }
+
+  let pathname = null
+
+  if (/^https?:\/\//i.test(artifactUrl)) {
+    if (!siteUrl) return null
+
+    let artifact
+    let base
+    try {
+      artifact = new URL(artifactUrl)
+      base = new URL(siteUrl)
+    } catch {
+      return null
+    }
+
+    if (artifact.origin !== base.origin) {
+      return null
+    }
+
+    pathname = artifact.pathname
+  } else {
+    pathname = artifactUrl.startsWith('/') ? artifactUrl : `/${artifactUrl}`
+  }
+
+  const relativePath = pathname.replace(/^\/+/, '')
+  if (!relativePath) return null
+
+  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.
  *