@sewadah/selaras 0.3.2 → 0.4.0

package/README.md

@@ -37,6 +37,12 @@ matter of overriding variables, not rebuilding the library.
   wrappers for `@nuxt/content`.
 - Components auto-import with an `S` prefix (`SButton`, `SSelect`, ...).
 
+## Agent support
+
+Use the [Selaras skill](skills/selaras/SKILL.md) to guide component selection and customization. The package also includes `selaras-mcp`, a local stdio MCP server with versioned documentation search, component discovery, and Vue examples. It needs no hosted service or API key.
+
+See the [agent support guides](https://sewadahapp.github.io/selaras/overview/agent-support/overview) for skill installation, MCP client configuration, and the public `llms.txt` exports.
+
 ## Quick Setup
 
 Install the module to your Nuxt application with one command:

package/agent/catalog.mjs

@@ -0,0 +1,73 @@
+import { readFile } from 'node:fs/promises'
+
+export async function loadCatalog(url = new URL('../dist/agent/catalog.json', import.meta.url)) {
+  const catalog = JSON.parse(await readFile(url, 'utf8'))
+  if (typeof catalog.version !== 'string' || !Array.isArray(catalog.documents) || !Array.isArray(catalog.examples))
+    throw new Error('Invalid Selaras documentation catalog. Reinstall the package or run agent:build in the repository.')
+  return catalog
+}
+
+export function documentSummary(document) {
+  return {
+    path: document.path,
+    title: document.title,
+    description: document.description,
+    category: document.category,
+    component: document.component,
+    examples: document.examples,
+    uri: `selaras://docs${document.path}`,
+  }
+}
+
+export function findDocument(catalog, path) {
+  const normalized = `/${path.replace(/^\/+/, '').replace(/\.md$/, '')}`
+  return catalog.documents.find(document => document.path === normalized
+    || document.component?.toLowerCase() === path.toLowerCase())
+}
+
+export function searchDocuments(catalog, query, limit = 10) {
+  const words = query.toLowerCase().match(/[\p{L}\p{N}_-]+/gu) ?? []
+  if (!words.length)
+    return []
+  return catalog.documents.map((document) => {
+    const title = `${document.title} ${document.component ?? ''}`.toLowerCase()
+    const description = document.description.toLowerCase()
+    const content = document.content.toLowerCase()
+    const score = words.reduce((total, word) => total
+      + (title.includes(word) ? 10 : 0)
+      + (description.includes(word) ? 4 : 0)
+      + (document.path.includes(word) ? 2 : 0)
+      + (content.includes(word) ? 1 : 0), 0)
+    return { document, score }
+  }).filter(result => result.score > 0).sort((a, b) => b.score - a.score || a.document.path.localeCompare(b.document.path)).slice(0, limit).map(({ document }) => documentSummary(document))
+}
+
+export function readSection(content, section) {
+  if (!section)
+    return content
+  const headings = []
+  let fence
+  let offset = 0
+  for (const line of content.split('\n')) {
+    const marker = line.match(/^ {0,3}(`{3,}|~{3,})/)
+    if (fence) {
+      if (marker && marker[1][0] === fence[0] && marker[1].length >= fence.length && !line.slice(marker[0].length).trim())
+        fence = undefined
+    }
+    else if (marker) {
+      fence = marker[1]
+    }
+    else {
+      const heading = line.match(/^(#{1,6})[ \t]+(\S.*)$/)
+      if (heading)
+        headings.push({ level: heading[1].length, title: heading[2], offset })
+    }
+    offset += line.length + 1
+  }
+  const index = headings.findIndex(heading => heading.title.replace(/`/g, '').toLowerCase() === section.toLowerCase())
+  if (index < 0)
+    return undefined
+  const start = headings[index]
+  const end = headings.slice(index + 1).find(heading => heading.level <= start.level)
+  return content.slice(start.offset, end?.offset ?? content.length).trim()
+}

package/agent/mcp.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+import process from 'node:process'
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+import { loadCatalog } from './catalog.mjs'
+import { createServer } from './server.mjs'
+
+async function main() {
+  const server = createServer(await loadCatalog())
+  await server.connect(new StdioServerTransport())
+}
+
+main().catch((error) => {
+  console.error(`[selaras-mcp] ${error instanceof Error ? error.message : error}`)
+  process.exitCode = 1
+})

package/agent/server.mjs

@@ -0,0 +1,58 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
+import { z } from 'zod'
+import { documentSummary, findDocument, readSection, searchDocuments } from './catalog.mjs'
+
+const annotations = { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: false }
+const text = value => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value, null, 2) }] })
+const failure = message => ({ ...text(message), isError: true })
+
+export function createServer(catalog) {
+  const server = new McpServer({ name: 'selaras', version: catalog.version }, {
+    instructions: 'Use the component catalog before implementing UI. Read matching API guides and Vue examples; customize existing Selaras components with props, slots, ui, and shared configuration. This offline catalog matches the installed package version.',
+  })
+  server.registerTool('list_components', {
+    description: 'Discover Selaras components and composites, their documentation paths, and available examples. Filter by category such as forms, overlays, data, or dashboard.',
+    inputSchema: { category: z.string().max(100).optional() },
+    annotations,
+  }, async ({ category }) => text(catalog.documents.filter(document => document.component
+    && (!category || document.category.toLowerCase().includes(category.toLowerCase()))).map(documentSummary)))
+  server.registerTool('search_documentation', {
+    description: 'Search component APIs, setup, theming, icons, messages, adaptive controls, and composables. Returns matching guide paths to read next.',
+    inputSchema: { query: z.string().trim().min(1).max(200), limit: z.number().int().min(1).max(20).default(10) },
+    annotations,
+  }, async ({ query, limit }) => text(searchDocuments(catalog, query, limit)))
+  server.registerTool('get_documentation', {
+    description: 'Read a guide by its catalog path or component name (for example SSelect). Contains API tables and complete Vue source for embedded examples. Optionally read one heading section.',
+    inputSchema: { path: z.string().min(1).max(200), section: z.string().max(200).optional() },
+    annotations,
+  }, async ({ path, section }) => {
+    const document = findDocument(catalog, path)
+    if (!document)
+      return failure('Unknown documentation path. Use search_documentation or list_components to find a guide.')
+    const content = readSection(document.content, section)
+    return content === undefined
+      ? failure(`Unknown section in ${document.path}. Read the full guide to see available headings.`)
+      : text(`# ${document.title}\n\nPackage version: ${catalog.version}\nDocumentation: ${document.path}\n\n${content}`)
+  })
+  server.registerTool('get_example', {
+    description: 'Read the exact Vue source of a named example from a component guide or list_components result.',
+    inputSchema: { name: z.string().min(1).max(200) },
+    annotations,
+  }, async ({ name }) => {
+    const example = catalog.examples.find(example => example.name === name)
+    return example ? text(example.source) : failure('Unknown example name. Read the examples field in list_components or a component guide.')
+  })
+  server.registerResource('catalog', 'selaras://catalog', {
+    description: 'Guide and component index for this Selaras package version.',
+    mimeType: 'application/json',
+  }, async uri => ({ contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify({ version: catalog.version, documents: catalog.documents.map(documentSummary) }) }] }))
+  server.registerResource('documentation', new ResourceTemplate('selaras://docs/{+path}', {
+    list: async () => ({ resources: catalog.documents.map(document => ({ uri: documentSummary(document).uri, name: document.title, description: document.description, mimeType: 'text/markdown' })) }),
+  }), { mimeType: 'text/markdown', description: 'Versioned Selaras documentation with Vue examples.' }, async (uri, { path }) => {
+    const document = typeof path === 'string' ? findDocument(catalog, path) : undefined
+    if (!document)
+      throw new Error('Unknown Selaras documentation resource')
+    return { contents: [{ uri: uri.href, mimeType: 'text/markdown', text: document.content }] }
+  })
+  return server
+}