@mk-kit/mcp 0.44.0

package/data/llms.txt

@@ -0,0 +1,88 @@
+# mk-kit
+
+> Themable, accessible Angular 22 component library for admin dashboards and UIs. Signals-based, WCAG 2.1 AA, controlled entirely through CSS variables with light/dark out of the box. — `@mk-kit/ui` 0.44.0. 170 components, 41 directives, 16 services and 130 helper functions across 23 tree-shakeable entry points. MIT licensed, zero runtime dependencies beyond Angular. Standalone components, signals, OnPush, zoneless-ready, SSR-safe, RTL and i18n via `provideMkI18n`.
+
+Install with `ng add @mk-kit/ui` (or `npm i @mk-kit/ui` + import `@mk-kit/ui/styles/mk-kit.css`). Import from the group entry points (`@mk-kit/ui/forms`, `@mk-kit/ui/table`, …) so each lazy chunk only carries what it uses; the root `@mk-kit/ui` entry re-exports everything. Every component is standalone: add the class to a component's `imports`. Theme with `--mk-*` CSS custom properties; `MkThemeService` switches light/dark/system and density.
+
+## Docs
+
+- [mk-kit — Introduction](https://mk-kit.dev/introduction)
+- [Getting started](https://mk-kit.dev/getting-started)
+- [Accessibility](https://mk-kit.dev/accessibility)
+- [Bundle cost](https://mk-kit.dev/cost)
+- [Theming](https://mk-kit.dev/theming)
+- [Core & services](https://mk-kit.dev/core-services)
+- [Touch & mobile](https://mk-kit.dev/touch)
+- [Material migration](https://mk-kit.dev/migration)
+- [Blog](https://mk-kit.dev/blog)
+- [All components](https://mk-kit.dev/components-index)
+- [Changelog](https://mk-kit.dev/changelog)
+
+## Component pages
+
+- [Badges & labels](https://mk-kit.dev/components/badges-avatars)
+- [Cards & lists](https://mk-kit.dev/components/cards-lists)
+- [Table & data grid](https://mk-kit.dev/components/table)
+- [Loading & progress](https://mk-kit.dev/components/loading)
+- [Text inputs](https://mk-kit.dev/components/text-inputs)
+- [Phone & postal code](https://mk-kit.dev/components/phone-postal)
+- [Money & payment](https://mk-kit.dev/components/payment)
+- [Signature pad](https://mk-kit.dev/components/signature)
+- [Keypad & on-screen keyboard](https://mk-kit.dev/components/touch-keys)
+- [Images & lightbox](https://mk-kit.dev/components/images)
+- [Media manager](https://mk-kit.dev/components/media-manager)
+- [Toggles & switches](https://mk-kit.dev/components/toggles)
+- [Sliders & rating](https://mk-kit.dev/components/sliders)
+- [Tooltips & popovers](https://mk-kit.dev/components/popovers)
+- [Dialogs](https://mk-kit.dev/components/dialogs)
+- [Status & notifications](https://mk-kit.dev/components/status)
+- [Proportion & KPI charts](https://mk-kit.dev/components/proportion-charts)
+- [Dashboard example](https://mk-kit.dev/examples/dashboard)
+- [Data table example](https://mk-kit.dev/examples/data-table)
+- [Content editor](https://mk-kit.dev/components/content-editor)
+- [Date & time](https://mk-kit.dev/components/date-time)
+- [Drag & drop](https://mk-kit.dev/components/drag-drop)
+- [Context menu](https://mk-kit.dev/components/context-menu)
+- [Buttons](https://mk-kit.dev/components/buttons)
+- [Dynamic form](https://mk-kit.dev/components/dynamic-form)
+- [Forms](https://mk-kit.dev/components/forms)
+- [Signal Forms](https://mk-kit.dev/components/signal-forms)
+- [Selection](https://mk-kit.dev/components/selection)
+- [Rich text](https://mk-kit.dev/components/rich-text)
+- [Code & content](https://mk-kit.dev/components/markdown)
+- [Stepper](https://mk-kit.dev/components/stepper)
+- [Organisation chart](https://mk-kit.dev/components/org-chart)
+- [Tree](https://mk-kit.dev/components/tree)
+- [Icon](https://mk-kit.dev/components/icon)
+- [Snackbar](https://mk-kit.dev/components/snackbar)
+- [Bottom sheet](https://mk-kit.dev/components/bottom-sheet)
+- [Sort](https://mk-kit.dev/components/sort)
+- [Trend charts](https://mk-kit.dev/components/charts)
+- [Empty state & timeline](https://mk-kit.dev/components/empty-timeline)
+- [Structure](https://mk-kit.dev/components/structure)
+- [Layout](https://mk-kit.dev/components/layout)
+- [Chat](https://mk-kit.dev/components/chat)
+- [Query builder](https://mk-kit.dev/components/query-builder)
+- [Drawer](https://mk-kit.dev/components/drawer)
+- [Command palette & nav](https://mk-kit.dev/components/command-nav)
+- [Misc display](https://mk-kit.dev/components/data)
+- [Feedback](https://mk-kit.dev/components/feedback)
+- [Navigation](https://mk-kit.dev/components/navigation)
+- [Utilities](https://mk-kit.dev/components/utilities)
+- [Kanban](https://mk-kit.dev/components/kanban)
+
+## API reference
+
+- [API reference (browsable)](https://mk-kit.dev/api)
+- [api.json](https://mk-kit.dev/api.json): every export with inputs, outputs, methods and types, machine-readable
+- [llms-full.txt](https://mk-kit.dev/llms-full.txt): the complete API reference as Markdown in one file
+
+## For AI assistants
+
+- MCP server: `npx -y @mk-kit/mcp` (tools: search_mk_kit, get_mk_kit_export, list_mk_kit_exports, get_mk_kit_overview) — https://www.npmjs.com/package/@mk-kit/mcp
+
+## Source
+
+- [GitHub](https://github.com/mk-kit/mk-kit)
+- [npm](https://www.npmjs.com/package/@mk-kit/ui)
+- [Changelog](https://github.com/mk-kit/mk-kit/blob/main/CHANGELOG.md)

package/data.js

@@ -0,0 +1,58 @@
+import { readFile } from 'node:fs/promises';
+/**
+ * Load the API snapshot. The package bundles the artefacts of the release it
+ * shipped with (`data/`); unless `MK_KIT_MCP_OFFLINE` is set, a newer set is
+ * fetched from the docs site (`MK_KIT_SITE`, default https://mk-kit.dev) so
+ * an old install still answers for the current library version. Any network
+ * problem silently keeps the bundled copy.
+ */
+export async function loadData(env = process.env) {
+    const bundled = await loadBundled();
+    if (env['MK_KIT_MCP_OFFLINE'])
+        return bundled;
+    const site = (env['MK_KIT_SITE'] ?? bundled.api.site ?? 'https://mk-kit.dev').replace(/\/$/, '');
+    try {
+        const remote = await fetchRemote(site);
+        return newer(remote.api.version, bundled.api.version) ? remote : bundled;
+    }
+    catch {
+        return bundled;
+    }
+}
+async function loadBundled() {
+    const dir = new URL('./data/', import.meta.url);
+    const [apiText, llms, llmsFull] = await Promise.all([
+        readFile(new URL('api.json', dir), 'utf8'),
+        readFile(new URL('llms.txt', dir), 'utf8'),
+        readFile(new URL('llms-full.txt', dir), 'utf8'),
+    ]);
+    return { api: JSON.parse(apiText), llms, llmsFull, source: 'bundled' };
+}
+async function fetchRemote(site) {
+    const get = async (path) => {
+        const res = await fetch(`${site}${path}`, { signal: AbortSignal.timeout(4000) });
+        if (!res.ok)
+            throw new Error(`${path}: ${res.status}`);
+        return res.text();
+    };
+    const apiText = await get('/api.json');
+    const api = JSON.parse(apiText);
+    if (!api?.entries?.length || typeof api.version !== 'string')
+        throw new Error('bad api.json');
+    const [llms, llmsFull] = await Promise.all([get('/llms.txt'), get('/llms-full.txt')]);
+    return { api, llms, llmsFull, source: site };
+}
+/** semver-ish: is `a` newer than `b`? */
+export function newer(a, b) {
+    const pa = a.split(/[.-]/).map(Number);
+    const pb = b.split(/[.-]/).map(Number);
+    for (let i = 0; i < 3; i++) {
+        const x = pa[i] ?? 0;
+        const y = pb[i] ?? 0;
+        if (Number.isNaN(x) || Number.isNaN(y))
+            return false;
+        if (x !== y)
+            return x > y;
+    }
+    return false;
+}

package/index.js

@@ -0,0 +1,225 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { z } from 'zod';
+export const API_KINDS = [
+    'component',
+    'directive',
+    'pipe',
+    'service',
+    'class',
+    'function',
+    'token',
+    'const',
+    'interface',
+    'type',
+    'enum',
+];
+export class MkKitIndex {
+    data;
+    items = [];
+    byName = new Map();
+    bySelector = new Map();
+    constructor(data) {
+        this.data = data;
+        const sections = splitSections(data.llmsFull);
+        for (const entry of data.api.entries) {
+            for (const item of entry.exports) {
+                const markdown = sections.get(`${entry.name}/${item.name}`) ?? renderFallback(item, entry);
+                const ix = { entry, item, markdown };
+                this.items.push(ix);
+                // First entry wins on a duplicate name (root re-export order).
+                if (!this.byName.has(item.name.toLowerCase()))
+                    this.byName.set(item.name.toLowerCase(), ix);
+                for (const s of item.selectors ?? []) {
+                    if (!this.bySelector.has(s.toLowerCase()))
+                        this.bySelector.set(s.toLowerCase(), ix);
+                }
+            }
+        }
+    }
+    /** Exact lookup by class name (`MkSelect`), selector (`mk-select`, `mkButton`) or pipe name. */
+    get(name) {
+        const q = name.trim().toLowerCase().replace(/^<|>$/g, '').replace(/^\[|\]$/g, '');
+        return this.byName.get(q) ?? this.bySelector.get(q);
+    }
+    search(query, opts = {}) {
+        const q = query.trim().toLowerCase();
+        const words = q.split(/\s+/).filter(Boolean);
+        const limit = opts.limit ?? 10;
+        const scored = [];
+        for (const ix of this.items) {
+            if (opts.kind && ix.item.kind !== opts.kind)
+                continue;
+            if (opts.entry && ix.entry.name !== opts.entry)
+                continue;
+            const name = ix.item.name.toLowerCase();
+            const sels = (ix.item.selectors ?? []).map((s) => s.toLowerCase());
+            const desc = ix.item.description.toLowerCase();
+            let score = 0;
+            if (name === q || sels.includes(q))
+                score = 100;
+            else if (name.startsWith(q) || sels.some((s) => s.startsWith(q)))
+                score = 60;
+            else if (name.includes(q) || sels.some((s) => s.includes(q)))
+                score = 40;
+            else if (words.length && words.every((w) => name.includes(w) || sels.some((s) => s.includes(w)) || desc.includes(w))) {
+                score = 10 + words.filter((w) => name.includes(w)).length * 5;
+            }
+            if (!score)
+                continue;
+            // Components and directives are what people usually mean.
+            if (ix.item.kind === 'component' || ix.item.kind === 'directive')
+                score += 3;
+            else if (ix.item.kind === 'service' || ix.item.kind === 'function')
+                score += 1;
+            scored.push({ ix, score });
+        }
+        scored.sort((a, b) => b.score - a.score || a.ix.item.name.localeCompare(b.ix.item.name));
+        return scored.slice(0, limit).map((s) => s.ix);
+    }
+}
+/** Map `entry/Name` → Markdown section from llms-full.txt. */
+function splitSections(full) {
+    const out = new Map();
+    let entry = '';
+    let current = null;
+    const flush = () => {
+        if (current)
+            out.set(current.key, current.lines.join('\n').trim());
+        current = null;
+    };
+    for (const line of full.split('\n')) {
+        const h2 = /^## @mk-kit\/ui\/([\w-]+)\s*$/.exec(line);
+        if (h2) {
+            flush();
+            entry = h2[1];
+            continue;
+        }
+        const h3 = /^### (\w+) \((\w+)\)\s*$/.exec(line);
+        if (h3) {
+            flush();
+            current = { key: `${entry}/${h3[1]}`, lines: [line] };
+            continue;
+        }
+        if (current)
+            current.lines.push(line);
+    }
+    flush();
+    return out;
+}
+function renderFallback(item, entry) {
+    const lines = [`### ${item.name} (${item.kind})`, ''];
+    if (item.selector)
+        lines.push(`Selector: \`${item.selector}\``, '');
+    lines.push(`Import: \`import { ${item.name} } from '${entry.import}';\``, '');
+    if (item.description)
+        lines.push(item.description, '');
+    return lines.join('\n').trim();
+}
+export function brief(item, max = 140) {
+    const first = item.description.split(/\n\s*\n/)[0]?.replace(/\s+/g, ' ').replace(/`/g, '') ?? '';
+    return first.length > max ? first.slice(0, max - 1) + '…' : first;
+}
+function line(ix) {
+    const sel = ix.item.selector ? ` \`${ix.item.selector}\`` : ix.item.kind === 'pipe' ? '' : '';
+    const dep = ix.item.deprecated ? ' [deprecated]' : '';
+    const b = brief(ix.item);
+    return `- **${ix.item.name}** (${ix.item.kind})${sel} — ${ix.entry.import}${dep}${b ? `\n  ${b}` : ''}`;
+}
+/* ------------------------------------------------------------------------ */
+/* Server                                                                    */
+/* ------------------------------------------------------------------------ */
+const KIND = z.enum(API_KINDS);
+/**
+ * Build the mk-kit MCP server over a data snapshot. Pure — no I/O, so it is
+ * unit-testable over an in-memory transport; `bin.ts` wires stdio.
+ */
+export function createMkKitServer(data) {
+    const index = new MkKitIndex(data);
+    const { api } = data;
+    const version = `${api.package} ${api.version}`;
+    const server = new McpServer({ name: 'mk-kit', version: api.version }, {
+        instructions: `Reference for ${version}, the Angular component library (mk-kit.dev). ` +
+            `Use search_mk_kit to find a component/directive/service/helper by name, selector or what it does, ` +
+            `then get_mk_kit_export for its full API (inputs, outputs, methods, import path). ` +
+            `Call get_mk_kit_overview once for install/setup conventions. ` +
+            `Every component is standalone: import the class from the entry point shown and add it to \`imports\`.`,
+    });
+    server.registerTool('search_mk_kit', {
+        title: 'Search the mk-kit API',
+        description: `Find exports of ${version} by name, selector (mk-select, mkButton) or free text describing what you need ` +
+            `("date range", "toast", "csv export"). Returns the best matches with kind, import path and a one-line summary. ` +
+            `Follow up with get_mk_kit_export for the full API.`,
+        inputSchema: {
+            query: z.string().min(1).describe('Name, selector or free-text description'),
+            kind: KIND.optional().describe('Restrict to one kind of export'),
+            entry: z.string().optional().describe('Restrict to one entry point, e.g. "forms" or "table"'),
+            limit: z.number().int().min(1).max(50).optional().describe('Max results (default 10)'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, ({ query, kind, entry, limit }) => {
+        const hits = index.search(query, { kind, entry, limit });
+        const text = hits.length
+            ? `${hits.length} result${hits.length === 1 ? '' : 's'} for "${query}":\n\n${hits.map(line).join('\n')}`
+            : `No export of ${api.package} matches "${query}". Try a shorter term, a selector (mk-…) or list_mk_kit_exports.`;
+        return { content: [{ type: 'text', text }] };
+    });
+    server.registerTool('get_mk_kit_export', {
+        title: 'Get one mk-kit export',
+        description: `Full API of one export of ${version} as Markdown: import path, selector, description with usage example, ` +
+            `inputs (type, default, two-way), outputs, methods, properties or type definition, and the docs page. ` +
+            `Accepts a class name (MkSelect), a selector (mk-select, mkButton) or a helper/type name (mkToCsv, MkTone).`,
+        inputSchema: {
+            name: z.string().min(1).describe('Class name, selector or exported symbol'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, ({ name }) => {
+        const ix = index.get(name);
+        if (ix)
+            return { content: [{ type: 'text', text: ix.markdown }] };
+        const near = index.search(name, { limit: 5 });
+        const text = near.length
+            ? `No export named "${name}". Did you mean:\n\n${near.map(line).join('\n')}`
+            : `No export named "${name}" in ${version}.`;
+        return { content: [{ type: 'text', text }], isError: true };
+    });
+    server.registerTool('list_mk_kit_exports', {
+        title: 'List mk-kit exports',
+        description: `Browse ${version}: every entry point with its exports, or one entry point / one kind. ` +
+            `Use it to see what exists before searching; each line carries a one-line summary.`,
+        inputSchema: {
+            entry: z.string().optional().describe('Entry point name, e.g. "forms", "table", "core"'),
+            kind: KIND.optional().describe('Only this kind of export'),
+        },
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, ({ entry, kind }) => {
+        const entries = entry ? api.entries.filter((e) => e.name === entry) : api.entries;
+        if (!entries.length) {
+            return {
+                content: [{ type: 'text', text: `Unknown entry point "${entry}". Entry points: ${api.entries.map((e) => e.name).join(', ')}.` }],
+                isError: true,
+            };
+        }
+        const detailed = !!entry || !!kind;
+        const blocks = entries.map((e) => {
+            const items = kind ? e.exports.filter((x) => x.kind === kind) : e.exports;
+            if (!detailed) {
+                const comps = e.exports.filter((x) => x.kind === 'component' || x.kind === 'directive');
+                const names = comps.map((x) => x.selector ? `${x.name} (${x.selector})` : x.name);
+                return `## ${e.import} — ${e.exports.length} exports\n${names.length ? names.join(', ') : '(types and helpers)'}`;
+            }
+            return `## ${e.import} — ${items.length} export${items.length === 1 ? '' : 's'}${kind ? ` of kind ${kind}` : ''}\n${items.map((x) => line({ entry: e, item: x, markdown: '' })).join('\n') || '(none)'}`;
+        });
+        return { content: [{ type: 'text', text: blocks.join('\n\n') }] };
+    });
+    server.registerTool('get_mk_kit_overview', {
+        title: 'mk-kit overview',
+        description: `What ${version} is, how to install and set it up (ng add, theme stylesheet, entry points, theming, i18n), ` +
+            `and links to every docs page. Read once before using the library.`,
+        inputSchema: {},
+        annotations: { readOnlyHint: true, idempotentHint: true, openWorldHint: false },
+    }, () => ({ content: [{ type: 'text', text: data.llms }] }));
+    server.registerResource('llms.txt', 'mk-kit://llms.txt', { title: 'mk-kit llms.txt', description: 'Docs index for LLMs', mimeType: 'text/markdown' }, (uri) => ({ contents: [{ uri: uri.href, mimeType: 'text/markdown', text: data.llms }] }));
+    server.registerResource('llms-full.txt', 'mk-kit://llms-full.txt', { title: 'mk-kit full API reference', description: 'Every export as Markdown', mimeType: 'text/markdown' }, (uri) => ({ contents: [{ uri: uri.href, mimeType: 'text/markdown', text: data.llmsFull }] }));
+    server.registerResource('api.json', 'mk-kit://api.json', { title: 'mk-kit api.json', description: 'Machine-readable API surface', mimeType: 'application/json' }, (uri) => ({ contents: [{ uri: uri.href, mimeType: 'application/json', text: JSON.stringify(api) }] }));
+    return server;
+}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@mk-kit/mcp",
+  "version": "0.44.0",
+  "description": "MCP server for @mk-kit/ui — lets AI coding assistants look up every component, directive, service and helper of the mk-kit Angular library (inputs, outputs, methods, import paths, docs links).",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "mk-kit-mcp": "bin.js"
+  },
+  "main": "index.js",
+  "files": [
+    "*.js",
+    "data/",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "angular",
+    "components",
+    "mk-kit",
+    "ai",
+    "claude",
+    "cursor",
+    "copilot"
+  ],
+  "homepage": "https://mk-kit.dev/api",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/mk-kit/mk-kit.git",
+    "directory": "projects/mcp"
+  },
+  "bugs": "https://github.com/mk-kit/mk-kit/issues",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "zod": "^4.0.0"
+  }
+}