@quasar/mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+The MIT License (MIT)
+
+Copyright (c) 2015-present Razvan Stoenescu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.

package/README.md

@@ -0,0 +1,67 @@
+![Quasar Framework logo](https://cdn.quasar.dev/logo-v2/header.png)
+
+# @quasar/mcp
+
+> An [MCP](https://modelcontextprotocol.io) server that gives AI agents the Quasar documentation and component API of the exact versions installed in your project.
+
+<img alt="@quasar/mcp npm version" src="https://img.shields.io/npm/v/%40quasar/mcp.svg?label=@quasar/mcp">
+
+[![mcp tests](https://github.com/quasarframework/quasar/actions/workflows/mcp-tests.yml/badge.svg?branch=dev)](https://github.com/quasarframework/quasar/actions/workflows/mcp-tests.yml)
+
+The documentation pages ship inside the `quasar` and `@quasar/app-vite` packages (in their `dist/mcp` folder), and the component API inside `quasar` (`dist/api`), so the server works offline and always describes what you run. There is no fallback to quasar.dev: a project on releases predating the bundled docs gets the API only, and the server says so.
+
+## Setup
+
+Add the server to your MCP client, from the project folder. Nothing gets installed in the project: `npx` starts the latest release when online and the cached copy when offline (the retries flag keeps that fallback quick):
+
+```json
+{
+  "mcpServers": {
+    "quasar": {
+      "command": "npx",
+      "args": ["-y", "--fetch-retries=0", "@quasar/mcp@latest"]
+    }
+  }
+}
+```
+
+The server serves the project it is started in. Clients that start servers elsewhere can point it at the project with `--project <dir>`.
+
+See the [AI Agents](https://quasar.dev/start/ai-agents) page for the per-client instructions.
+
+## Tools
+
+| Tool            | What it returns                                                                                                                               |
+| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------- |
+| `list_pages`    | every page available offline with its approximate size, grouped by the package shipping it                                                    |
+| `search_docs`   | the pages matching some keywords, with their description, approximate size and the sections the keywords occur in                             |
+| `get_page`      | one page, one section of it (by heading, or the `#anchor` of a pasted link), or its outline, as markdown                                      |
+| `list_api`      | the names of the API descriptors: components, plugins, directives, utilities                                                                  |
+| `get_api`       | the props, slots, events and methods of one of them, one part, or one member, as the site shows them; `format: "json"` for the raw descriptor |
+| `check_updates` | whether newer releases of quasar, @quasar/app-vite or this server exist                                                                       |
+
+At session start the server also tells the agent which package versions it serves, what is missing, and which updates are available (checked in the background, cached for a day, never while offline, the same mechanism the Quasar CLI uses; `NO_UPDATE_NOTIFIER` disables it).
+
+## Chat Support
+
+Ask questions at the official community Discord server: [https://chat.quasar.dev](https://chat.quasar.dev)
+
+## Community Forum
+
+Ask questions at the official community forum: [https://forum.quasar.dev](https://forum.quasar.dev)
+
+## Contributing
+
+I'm excited if you want to contribute to Quasar under any form (report bugs, write a plugin, fix an issue, write a new feature). Please read the [Contributing Guide](../CONTRIBUTING.md).
+
+## Semver
+
+Quasar is following [Semantic Versioning 2.0](https://semver.org/).
+
+The documentation slices the packages ship (`dist/mcp`) carry a `format` number in their `meta.json`. It moves only when the shape the server parses changes, and this server's major version tracks it: `@quasar/mcp@1` reads format 1. A project whose installed packages carry another format is told so at session start, with the server to run instead.
+
+## License
+
+Copyright (c) 2026-present Razvan Stoenescu
+
+[MIT License](http://en.wikipedia.org/wiki/MIT_License)

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@quasar/mcp",
+  "version": "1.0.0",
+  "description": "MCP server for AI agents: the Quasar documentation and component API, served from the packages installed in your project",
+  "keywords": [
+    "agent",
+    "ai",
+    "docs",
+    "mcp",
+    "model-context-protocol",
+    "quasar",
+    "vue"
+  ],
+  "homepage": "https://quasar.dev",
+  "bugs": "https://github.com/quasarframework/quasar/issues",
+  "license": "MIT",
+  "author": {
+    "name": "Razvan Stoenescu",
+    "email": "razvan.stoenescu@gmail.com",
+    "url": "https://github.com/quasarframework"
+  },
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/quasarframework/quasar",
+    "directory": "mcp"
+  },
+  "funding": {
+    "type": "github",
+    "url": "https://donate.quasar.dev"
+  },
+  "bin": {
+    "quasar-mcp": "./src/bin.js"
+  },
+  "files": [
+    "src",
+    "!src/**/*.test.js",
+    "!src/test"
+  ],
+  "type": "module",
+  "exports": "./src/index.js",
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@quasar/update-notifier": "^1.1.0",
+    "zod": "^4.6.0"
+  },
+  "devDependencies": {
+    "vitest": "^5.0.1"
+  },
+  "engines": {
+    "node": ">= 22.0.0"
+  },
+  "scripts": {
+    "test": "pnpm test:unit && pnpm test:e2e",
+    "test:unit": "vitest run",
+    "pretest:e2e": "pnpm --filter quasar generate:mcp && pnpm --filter @quasar/app-vite generate:mcp",
+    "test:e2e": "vitest run -c vitest-e2e.config.js"
+  }
+}

package/src/api.js

@@ -0,0 +1,272 @@
+import { existsSync, readFileSync, readdirSync } from 'node:fs'
+import { join } from 'node:path'
+
+import { extractSection } from './docs.js'
+
+/** The sections of an API descriptor `get_api` can serve on their own. */
+export const API_PARTS = [
+  'props',
+  'slots',
+  'events',
+  'methods',
+  'computedProps',
+  'value',
+  'arg',
+  'modifiers',
+  'injection',
+  'quasarConfOptions'
+]
+
+/**
+ * The heading(s) the docs renderer (docs/build/mcp/api/render.js)
+ * gives each part in `api/<Name>.md`.
+ */
+const PART_HEADINGS = {
+  props: ['Props'],
+  slots: ['Slots', 'Scoped Slots'],
+  events: ['Events'],
+  methods: ['Methods'],
+  computedProps: ['Computed Props'],
+  value: ['Directive Value'],
+  arg: ['Directive Argument'],
+  modifiers: ['Directive Modifiers'],
+  injection: ['Vue Injection'],
+  quasarConfOptions: ['quasar.config.js Options']
+}
+
+/** The parts whose entries are named members `get_api` can serve one of. */
+export const MEMBER_PARTS = [
+  'props',
+  'computedProps',
+  'methods',
+  'events',
+  'slots',
+  'modifiers'
+]
+
+/**
+ * Member names compare without case or punctuation: `modelValue`,
+ * `model-value` and the rendered `@update:model-value` all meet.
+ *
+ * @param {string} value
+ * @returns {string}
+ */
+function normalizeMember(value) {
+  return value.toLowerCase().replaceAll(/[^a-z0-9]/g, '')
+}
+
+const cache = new Map()
+
+/**
+ * @param {string} apiDir
+ * @returns {string[]} Descriptor names (`QBtn`, `Notify`, `Ripple`, ...), sorted.
+ */
+export function listApi(apiDir) {
+  return readdirSync(apiDir)
+    .filter(file => file.endsWith('.json'))
+    .map(file => file.slice(0, -'.json'.length))
+    .sort()
+}
+
+/**
+ * @param {string} apiDir
+ * @param {string} name
+ * @returns {Record<string, unknown> | null}
+ */
+export function readApi(apiDir, name) {
+  const file = join(apiDir, `${name}.json`)
+  let api = cache.get(file)
+  if (api === void 0) {
+    try {
+      api = JSON.parse(readFileSync(file, 'utf8'))
+    } catch {
+      return null
+    }
+    cache.set(file, api)
+  }
+  return api
+}
+
+/**
+ * Case-insensitive lookup that also forgives a missing `Q` prefix, so
+ * `btn`, `qbtn` and `QBtn` all find QBtn.
+ *
+ * @param {string} apiDir
+ * @param {string} name
+ * @returns {string | null} The canonical descriptor name.
+ */
+export function resolveApiName(apiDir, name) {
+  const names = listApi(apiDir)
+  const wanted = name.trim().toLowerCase()
+  return (
+    names.find(known => known.toLowerCase() === wanted) ??
+    names.find(known => known.toLowerCase() === `q${wanted}`) ??
+    null
+  )
+}
+
+/**
+ * @param {string} apiDir
+ * @param {string} name
+ * @returns {string[]} Names containing the input, for a miss.
+ */
+export function similarApiNames(apiDir, name) {
+  const needle = name.trim().toLowerCase().replace(/^q/, '')
+  return listApi(apiDir)
+    .filter(known => known.toLowerCase().includes(needle))
+    .slice(0, 8)
+}
+
+/**
+ * The descriptor as the site inlines it (`api/<Name>.md` in the ui
+ * slice, rendered by the docs generator), whole or one part. Null when
+ * the installed release bundles no rendered form, or the part has no
+ * section there.
+ *
+ * @param {string} docsDir The ui slice (`dist/mcp`).
+ * @param {string} name
+ * @param {string} [part]
+ * @returns {string | null}
+ */
+export function readApiMarkdown(docsDir, name, part) {
+  const markdown = readApiFile(docsDir, name)
+  if (markdown === null) {
+    return null
+  }
+  if (part === void 0) {
+    return markdown
+  }
+  const sections = PART_HEADINGS[part]
+    .map(heading => extractSection(markdown, heading))
+    .filter(section => section !== null)
+  return sections.length === 0 ? null : sections.join('\n\n') + '\n'
+}
+
+/**
+ * @param {string} docsDir
+ * @param {string} name
+ * @returns {string | null}
+ */
+function readApiFile(docsDir, name) {
+  const file = join(docsDir, 'api', `${name}.md`)
+  let markdown = cache.get(file)
+  if (markdown === void 0) {
+    if (!existsSync(file)) {
+      return null
+    }
+    markdown = readFileSync(file, 'utf8')
+    cache.set(file, markdown)
+  }
+  return markdown
+}
+
+/**
+ * The members of a descriptor named like `member`, across the parts
+ * that have named members or in the one given.
+ *
+ * @param {Record<string, unknown>} api
+ * @param {string} member
+ * @param {string} [part]
+ * @returns {Array<{ part: string, name: string }>}
+ */
+export function findApiMembers(api, member, part) {
+  const wanted = normalizeMember(member)
+  const matches = []
+  for (const candidate of part === void 0 ? MEMBER_PARTS : [part]) {
+    const entries = api[candidate]
+    if (!entries || typeof entries !== 'object') {
+      continue
+    }
+    for (const name of Object.keys(entries)) {
+      if (normalizeMember(name) === wanted) {
+        matches.push({ part: candidate, name })
+      }
+    }
+  }
+  return matches
+}
+
+/**
+ * @param {Record<string, unknown>} api
+ * @param {string} member
+ * @param {string} [part]
+ * @returns {string[]} `part.name` of the members containing the input, for a miss.
+ */
+export function similarApiMembers(api, member, part) {
+  const needle = normalizeMember(member)
+  const similar = []
+  for (const candidate of part === void 0 ? MEMBER_PARTS : [part]) {
+    const entries = api[candidate]
+    if (!entries || typeof entries !== 'object') {
+      continue
+    }
+    for (const name of Object.keys(entries)) {
+      if (needle !== '' && normalizeMember(name).includes(needle)) {
+        similar.push(`${candidate}.${name}`)
+      }
+    }
+  }
+  return similar.slice(0, 8)
+}
+
+/**
+ * The name a rendered entry line (`- \`pagination\``, `- \`@click\``,
+ * `- \`#default\``, `- \`toggle(): void\``) is about, null for any
+ * other line.
+ *
+ * @param {string} line
+ * @returns {string | null}
+ */
+function entryName(line) {
+  const match = /^- `([^`]+)`/.exec(line)
+  return match === null
+    ? null
+    : match[1].replace(/^[@#]/, '').replace(/\(.*$/, '')
+}
+
+/**
+ * The rendered entries of the given members, each under its section
+ * heading. Null when the release bundles no rendered form or none of
+ * the members has an entry there.
+ *
+ * @param {string} docsDir
+ * @param {string} name
+ * @param {Array<{ part: string, name: string }>} members From findApiMembers().
+ * @returns {string | null}
+ */
+export function readApiMembersMarkdown(docsDir, name, members) {
+  const markdown = readApiFile(docsDir, name)
+  if (markdown === null) {
+    return null
+  }
+  const found = []
+  for (const member of members) {
+    const wanted = normalizeMember(member.name)
+    for (const heading of PART_HEADINGS[member.part]) {
+      const section = extractSection(markdown, heading)
+      if (section === null) {
+        continue
+      }
+      const [headingLine, ...lines] = section.split('\n')
+      let entry = null
+      for (const line of lines) {
+        const current = entryName(line)
+        if (current !== null) {
+          if (entry !== null) {
+            break
+          }
+          if (normalizeMember(current) === wanted) {
+            entry = [line]
+          }
+        } else if (entry !== null) {
+          entry.push(line)
+        }
+      }
+      if (entry !== null) {
+        found.push(`${headingLine}\n\n${entry.join('\n').trim()}`)
+        break
+      }
+    }
+  }
+  return found.length === 0 ? null : found.join('\n\n') + '\n'
+}

package/src/bin.js

@@ -0,0 +1,63 @@
+#!/usr/bin/env node
+
+import { parseArgs } from 'node:util'
+
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
+
+import { loadProject } from './project.js'
+import { createServer } from './server.js'
+import { version } from './version.js'
+
+const usage = `Usage: quasar-mcp [--project <dir>]
+
+MCP server (stdio) for the Quasar documentation and component API of the
+packages installed in a project. Point your MCP client at it, e.g.:
+
+  { "mcpServers": { "quasar": { "command": "npx", "args": ["-y", "--fetch-retries=0", "@quasar/mcp@latest"] } } }
+
+Options:
+  --project <dir>  Project to serve, the one whose installed quasar and
+                   @quasar/app-vite carry the docs (default: cwd; when
+                   cwd has none, the first app found below it is served)
+  -v, --version    Print the version and exit
+  -h, --help       Print this help and exit
+`
+
+let values
+try {
+  ;({ values } = parseArgs({
+    options: {
+      project: { type: 'string' },
+      version: { type: 'boolean', short: 'v' },
+      help: { type: 'boolean', short: 'h' }
+    },
+    strict: true
+  }))
+} catch (err) {
+  console.error(err.message)
+  console.error(usage)
+  process.exit(1)
+}
+
+if (values.help === true) {
+  console.log(usage)
+  process.exit()
+}
+
+if (values.version === true) {
+  console.log(version)
+  process.exit()
+}
+
+// stdout carries the protocol: anything else a dependency might print
+// there would corrupt the session, so route every console channel to
+// stderr, which MCP clients keep as the server's log.
+for (const channel of ['log', 'info', 'debug', 'table', 'dir']) {
+  console[channel] = console.error
+}
+
+const project = loadProject(values.project, {
+  explicit: values.project !== void 0
+})
+const server = await createServer({ project })
+await server.connect(new StdioServerTransport())