@baklavue/mcp 1.0.0

package/README.md

@@ -0,0 +1,72 @@
+# @baklavue/mcp
+
+MCP (Model Context Protocol) server for Baklavue. Exposes Baklavue component APIs, composables, and documentation to AI assistants like Cursor, Claude, and Windsurf.
+
+## Usage
+
+### From the Baklavue Repo
+
+```bash
+# From repo root
+bun run mcp
+
+# Or from this package
+cd packages/mcp && bun run start
+```
+
+### From Another Project (when published)
+
+```bash
+npx @baklavue/mcp
+```
+
+### Cursor Configuration
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "Baklavue": {
+      "command": "bun",
+      "args": ["run", "--cwd", "/path/to/baklavue", "mcp"]
+    }
+  }
+}
+```
+
+Or with npx (when published):
+
+```json
+{
+  "mcpServers": {
+    "Baklavue": {
+      "command": "npx",
+      "args": ["@baklavue/mcp"]
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `list_components` | List all Bv* components with categories |
+| `get_component` | Full component documentation |
+| `get_component_metadata` | Props, events, slots only |
+| `list_composables` | List composables |
+| `get_composable` | Composable documentation |
+| `search_components_by_category` | Filter by category |
+| `get_documentation_page` | Get guide pages |
+| `list_documentation_pages` | List guide pages |
+
+## Build
+
+```bash
+bun run build
+```
+
+## Documentation
+
+See the [MCP Guide](https://erbilnas.github.io/baklavue/guide/mcp) for full setup instructions and usage examples.

package/dist/data/component-categories.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Component to category mapping for Baklavue components.
+ * Based on docs/components/index.md structure.
+ */
+export declare const COMPONENT_CATEGORIES: Record<string, string>;
+export declare const CATEGORY_LABELS: Record<string, string>;
+export declare const COMPONENT_LIST: string[];

package/dist/data/component-categories.js

@@ -0,0 +1,48 @@
+/**
+ * Component to category mapping for Baklavue components.
+ * Based on docs/components/index.md structure.
+ */
+export const COMPONENT_CATEGORIES = {
+    // Form Components
+    Button: "form",
+    Input: "form",
+    Checkbox: "form",
+    Radio: "form",
+    Switch: "form",
+    Select: "form",
+    Textarea: "form",
+    FileUpload: "form",
+    Datepicker: "form",
+    // Feedback Components
+    Alert: "feedback",
+    Badge: "feedback",
+    Banner: "feedback",
+    Chip: "feedback",
+    Tag: "feedback",
+    Notification: "feedback",
+    Spinner: "feedback",
+    // Layout Components
+    Dialog: "layout",
+    Drawer: "layout",
+    Dropdown: "layout",
+    Tooltip: "layout",
+    Accordion: "layout",
+    Tab: "layout",
+    Stepper: "layout",
+    // Navigation Components
+    Link: "navigation",
+    Pagination: "navigation",
+    SplitButton: "navigation",
+    // Data Display
+    Table: "data",
+    Icon: "data",
+    Image: "data",
+};
+export const CATEGORY_LABELS = {
+    form: "Form",
+    feedback: "Feedback",
+    layout: "Layout",
+    navigation: "Navigation",
+    data: "Data",
+};
+export const COMPONENT_LIST = Object.keys(COMPONENT_CATEGORIES);

package/dist/data/loaders.d.ts

@@ -0,0 +1,22 @@
+export interface ComponentInfo {
+    name: string;
+    bvName: string;
+    category: string;
+    categoryLabel: string;
+    description?: string;
+}
+export interface ComposableInfo {
+    name: string;
+    description?: string;
+}
+export declare function listComponents(): ComponentInfo[];
+export declare function getComponentDoc(componentName: string): string | null;
+export declare function getComponentMetadata(componentName: string): {
+    props?: string;
+    events?: string;
+    slots?: string;
+} | null;
+export declare function listComposables(): ComposableInfo[];
+export declare function getComposableDoc(composableName: string): string | null;
+export declare function getDocumentationPage(path: string): string | null;
+export declare function listDocumentationPages(): string[];

package/dist/data/loaders.js

@@ -0,0 +1,346 @@
+import { existsSync, readdirSync, readFileSync } from "node:fs";
+import { dirname, join } from "node:path";
+import { fileURLToPath } from "node:url";
+import { CATEGORY_LABELS, COMPONENT_CATEGORIES, COMPONENT_LIST, } from "./component-categories.js";
+const __dirname = dirname(fileURLToPath(import.meta.url));
+/**
+ * Resolve docs path for MCP server.
+ * - When published (npx @baklavue/mcp): docs are bundled at dist/docs/
+ * - When running from monorepo: docs are at repo root docs/
+ */
+function getDocsPath() {
+    // Published package: loaders are in dist/data/, docs are in dist/docs/
+    const packageDocs = join(__dirname, "..", "docs");
+    if (existsSync(join(packageDocs, "components"))) {
+        return packageDocs;
+    }
+    // Monorepo: repo root has docs/
+    const cwd = process.cwd();
+    if (existsSync(join(cwd, "docs")) && existsSync(join(cwd, "packages"))) {
+        return join(cwd, "docs");
+    }
+    const mcpParent = join(cwd, "..", "..");
+    if (existsSync(join(mcpParent, "docs"))) {
+        return join(mcpParent, "docs");
+    }
+    return packageDocs;
+}
+const docsPath = getDocsPath();
+export function listComponents() {
+    return COMPONENT_LIST.map((name) => {
+        const category = COMPONENT_CATEGORIES[name] ?? "other";
+        return {
+            name,
+            bvName: `Bv${name}`,
+            category,
+            categoryLabel: CATEGORY_LABELS[category] ?? category,
+        };
+    });
+}
+export function getComponentDoc(componentName) {
+    const normalized = componentName.replace(/^Bv/, "");
+    const path = join(docsPath, "components", `${normalized.toLowerCase()}.md`);
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, "utf-8");
+}
+export function getComponentMetadata(componentName) {
+    const doc = getComponentDoc(componentName);
+    if (!doc)
+        return null;
+    const result = {};
+    // Extract Props table (between ## Props and next ## or end)
+    const propsMatch = doc.match(/## Props\s*\n\n([\s\S]*?)(?=\n## |$)/);
+    if (propsMatch)
+        result.props = propsMatch[1].trim();
+    // Extract Events table
+    const eventsMatch = doc.match(/## Events\s*\n\n([\s\S]*?)(?=\n## |$)/);
+    if (eventsMatch)
+        result.events = eventsMatch[1].trim();
+    // Extract Slots table
+    const slotsMatch = doc.match(/## Slots\s*\n\n([\s\S]*?)(?=\n## |$)/);
+    if (slotsMatch)
+        result.slots = slotsMatch[1].trim();
+    return result;
+}
+export function listComposables() {
+    const indexPath = join(docsPath, "composables", "index.md");
+    if (!existsSync(indexPath))
+        return [];
+    const composables = [
+        { name: "useFile", description: "Parse, create, and download CSV, TSV, and JSON files" },
+        {
+            name: "useNotification",
+            description: "Programmatically manage notifications",
+        },
+        {
+            name: "useScrollToError",
+            description: "Scroll to element with validation error",
+        },
+        {
+            name: "useZodForm",
+            description: "Form validation with Zod schemas",
+        },
+        {
+            name: "useBaklavaTheme",
+            description: "Overwrite Baklava colors (Vue preset or custom)",
+        },
+        {
+            name: "useDisclosure",
+            description: "Open/close state for Dialog, Drawer, Dropdown",
+        },
+        {
+            name: "usePagination",
+            description: "Pagination state for tables and lists",
+        },
+        {
+            name: "useConfirmDialog",
+            description: "Confirm/cancel dialog flow",
+        },
+        {
+            name: "useClipboard",
+            description: "Copy text to clipboard. Supports source, copiedDuring, legacy fallback, isSupported",
+        },
+        {
+            name: "useShare",
+            description: "Share text, URLs, or files via Web Share API",
+        },
+        {
+            name: "useBase64",
+            description: "Convert Blob/File/ArrayBuffer/canvas to Base64 data URLs",
+        },
+        {
+            name: "usePrevious",
+            description: "Track previous value of a ref for diffing or undo logic",
+        },
+        {
+            name: "useToggle",
+            description: "Simple boolean toggle",
+        },
+        {
+            name: "useDateFormat",
+            description: "Reactive locale-aware date formatting (Intl)",
+        },
+        {
+            name: "useNumberFormat",
+            description: "Reactive locale-aware number/currency formatting (Intl)",
+        },
+        {
+            name: "useSlug",
+            description: "Convert string to URL-friendly slug",
+        },
+        {
+            name: "useAsyncState",
+            description: "Generic async state (loading, error, data) without fetch",
+        },
+        {
+            name: "useBreakpoints",
+            description: "Responsive breakpoints (isMobile, isTablet, isDesktop)",
+        },
+        {
+            name: "useMediaQuery",
+            description: "Single media query matcher",
+        },
+        {
+            name: "useCookie",
+            description: "Reactive sync with document.cookie",
+        },
+        {
+            name: "useLocalStorage",
+            description: "Reactive sync with localStorage",
+        },
+        {
+            name: "useSessionStorage",
+            description: "Reactive sync with sessionStorage",
+        },
+        {
+            name: "useDebounceFn",
+            description: "Debounce function execution",
+        },
+        {
+            name: "useDebouncedRef",
+            description: "Debounced ref value",
+        },
+        {
+            name: "useThrottleFn",
+            description: "Throttle function execution",
+        },
+        {
+            name: "useThrottledRef",
+            description: "Throttled ref value",
+        },
+        {
+            name: "useIntervalFn",
+            description: "Pausable interval",
+        },
+        {
+            name: "useTimeoutFn",
+            description: "Cancellable timeout",
+        },
+        {
+            name: "createFetch",
+            description: "Create preconfigured useFetch instance (axios.create-like)",
+        },
+        {
+            name: "useFetch",
+            description: "Reactive fetch with loading/error/data (axios-like API)",
+        },
+        {
+            name: "useQuery",
+            description: "Data fetching with caching, retries, and invalidation",
+        },
+        {
+            name: "useQueryClient",
+            description: "Cache invalidation and manual cache access for useQuery",
+        },
+        {
+            name: "useMutation",
+            description: "Mutations (POST/PUT/DELETE) with cache invalidation",
+        },
+        {
+            name: "useInfiniteQuery",
+            description: "Infinite scroll / cursor-based pagination",
+        },
+        {
+            name: "useLazyQuery",
+            description: "On-demand queries that fetch when execute() is called",
+        },
+        {
+            name: "usePolling",
+            description: "Polling with fetch state for non-query scenarios",
+        },
+        {
+            name: "useIntersectionObserver",
+            description: "Detect element visibility in viewport",
+        },
+        {
+            name: "useRafFn",
+            description: "Animation frame loop",
+        },
+        {
+            name: "useStepper",
+            description: "Multi-step wizard state for BvStepper",
+        },
+        {
+            name: "useScrollVisibility",
+            description: "Scroll-based visibility for scroll-to-top and sticky UI",
+        },
+        {
+            name: "useScrollLock",
+            description: "Lock body scroll when modals/drawers are open",
+        },
+        {
+            name: "useAlert",
+            description: "Programmatic show/hide for inline BvAlert",
+        },
+        {
+            name: "useLoading",
+            description: "Generic loading state with optional delay",
+        },
+        {
+            name: "useFocusTrap",
+            description: "Trap focus within modals/dialogs",
+        },
+        {
+            name: "useId",
+            description: "Stable unique IDs for accessibility attributes",
+        },
+        {
+            name: "useFormState",
+            description: "Form dirty and touched state without validation",
+        },
+        {
+            name: "useFieldArray",
+            description: "Dynamic array fields for forms",
+        },
+        {
+            name: "useFormPersistence",
+            description: "Auto-save form data to localStorage/sessionStorage",
+        },
+        {
+            name: "useStepperForm",
+            description: "Multi-step form validation with useStepper",
+        },
+    ];
+    return composables;
+}
+const COMPOSABLE_TO_FILE = {
+    useFile: "file",
+    useNotification: "notification",
+    useScrollToError: "scrollToError",
+    useZodForm: "formValidation",
+    useBaklavaTheme: "theme",
+    useDisclosure: "disclosure",
+    usePagination: "pagination",
+    useConfirmDialog: "confirmDialog",
+    useClipboard: "clipboard",
+    useShare: "share",
+    useBase64: "base64",
+    usePrevious: "previous",
+    useToggle: "toggle",
+    useDateFormat: "format",
+    useNumberFormat: "format",
+    useSlug: "slug",
+    useAsyncState: "asyncState",
+    useBreakpoints: "breakpoints",
+    useMediaQuery: "breakpoints",
+    useCookie: "cookie",
+    useLocalStorage: "storage",
+    useSessionStorage: "storage",
+    useDebounceFn: "debounce",
+    useDebouncedRef: "debounce",
+    useThrottleFn: "throttle",
+    useThrottledRef: "throttle",
+    useIntervalFn: "timer",
+    useTimeoutFn: "timer",
+    createFetch: "fetch",
+    useFetch: "fetch",
+    useQuery: "query",
+    useQueryClient: "query",
+    useMutation: "mutation",
+    useInfiniteQuery: "infiniteQuery",
+    useLazyQuery: "lazyQuery",
+    usePolling: "polling",
+    useIntersectionObserver: "intersectionObserver",
+    useRafFn: "raf",
+    useStepper: "stepper",
+    useScrollVisibility: "scrollVisibility",
+    useScrollLock: "scrollLock",
+    useAlert: "alert",
+    useLoading: "loading",
+    useFocusTrap: "focusTrap",
+    useId: "id",
+    useFormState: "formState",
+    useFieldArray: "fieldArray",
+    useFormPersistence: "formPersistence",
+    useStepperForm: "stepperForm",
+};
+export function getComposableDoc(composableName) {
+    const file = COMPOSABLE_TO_FILE[composableName] ??
+        composableName.replace(/^use/, "").toLowerCase();
+    const path = join(docsPath, "composables", `${file}.md`);
+    if (!existsSync(path))
+        return null;
+    return readFileSync(path, "utf-8");
+}
+export function getDocumentationPage(path) {
+    // path could be "installation", "getting-started", "design-tokens", etc.
+    const normalized = path.replace(/^\//, "").replace(/\.md$/, "");
+    const fullPath = join(docsPath, "guide", `${normalized}.md`);
+    if (!existsSync(fullPath))
+        return null;
+    return readFileSync(fullPath, "utf-8");
+}
+export function listDocumentationPages() {
+    const guidePath = join(docsPath, "guide");
+    if (!existsSync(guidePath))
+        return [];
+    try {
+        return readdirSync(guidePath)
+            .filter((f) => f.endsWith(".md"))
+            .map((f) => f.replace(".md", ""));
+    }
+    catch {
+        return ["installation", "getting-started", "design-tokens", "contributing"];
+    }
+}