npm - @smwb/ui-mcp-solid - Versions diffs - 0.1.0 - Mend

@smwb/ui-mcp-solid 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (122) hide show

package/customizationMeta.mjs ADDED Viewed

@@ -0,0 +1,451 @@
+import fs from "node:fs";
+import path from "node:path";
+import {
+  compactText,
+  normalizeText,
+  resolveComponent,
+  searchComponents,
+  similarityScore,
+  splitCamelCase,
+  tokenize,
+} from "./componentMeta.mjs";
+const APPEARANCE_PROP_NAMES = new Set([
+  "variant",
+  "size",
+  "color",
+  "colorTheme",
+  "themeMode",
+  "animation",
+  "dense",
+  "fullWidth",
+  "backdrop",
+  "orientation",
+  "elevation",
+  "severity",
+  "type",
+  "inline",
+  "placement",
+  "scrollable",
+  "stackable",
+  "stacked",
+  "icon",
+  "deleteIcon",
+  "startAdornment",
+  "endAdornment",
+  "rippleCenter",
+  "disableRipple",
+  "showFirstButton",
+  "showLastButton",
+  "textAlign",
+  "withTicks",
+  "width",
+  "height",
+  "fill",
+  "weight",
+  "grade",
+]);
+const GLOBAL_CUSTOMIZATION_TOPICS = [
+  {
+    id: "global/runtime-css",
+    name: "Runtime CSS Custom Properties",
+    description: "Change colors, spacing, radius, elevation, and component tokens at runtime without rebuilding CSS.",
+    summary:
+      "Override semantic `--smui-*` custom properties on `:root`, on `[data-theme=\"dark\"]`, or on any subtree.",
+    howTo: [
+      "Set CSS variables on `:root` or a scoped container.",
+      "Prefer `--smui-*` tokens over targeting internal `.smwb-*` classes.",
+      "Use component-specific tokens such as `--smui-tooltipBg` or `--smui-tableBorderColor` when needed.",
+    ],
+    examples: [
+      {
+        title: "Brand color",
+        language: "css",
+        code: ":root { --smui-primaryColor: #00695c; --smui-radius-md: 2px; }",
+      },
+      {
+        title: "Dense region",
+        language: "css",
+        code: ".settings-panel { --smui-space-md: 8px; --smui-space-lg: 12px; }",
+      },
+    ],
+    relatedDocs: ["AI_THEMING.md", "README.md"],
+    keywords: ["css", "variables", "tokens", "theme", "runtime", "custom properties", "smui", "colors", "spacing"],
+  },
+  {
+    id: "global/dark-mode",
+    name: "Light and Dark Theme",
+    description: "Switch the library between light and dark appearance using `data-theme` or `useTheme()`.",
+    summary: "Dark tokens are emitted under `:root[data-theme=\"dark\"]`.",
+    howTo: [
+      "Set `<html data-theme=\"dark\">` for SSR or static HTML.",
+      "Use `useTheme()` from `@smwb/ui-react` for client-side toggling with persistence.",
+      "Combine with runtime `--smui-*` overrides for brand-specific dark palettes.",
+    ],
+    examples: [
+      {
+        title: "Theme toggle",
+        language: "tsx",
+        code: "const { theme, setTheme } = useTheme();",
+      },
+    ],
+    relatedDocs: ["AI_THEMING.md", "README.md"],
+    keywords: ["dark", "light", "theme", "useTheme", "data-theme", "mode"],
+  },
+  {
+    id: "global/less-overrides",
+    name: "Compile-Time Less Overrides",
+    description: "Rebuild the stylesheet after changing design tokens in `theme.config` or a custom theme folder.",
+    summary: "Use Less token overrides for library-wide rebranding, density, radius, and per-component defaults.",
+    howTo: [
+      "Create `theme.config` at the Less compiler root.",
+      "Assign tokens such as `@primaryColor`, `@smui-spacing-unit`, `@cardPadding`.",
+      "Recompile `styles/less/components.less` and import the generated CSS in the app.",
+    ],
+    examples: [
+      {
+        title: "theme.config",
+        language: "less",
+        code: "@theme: \"summer\";\n@primaryColor: @md-teal-600;\n@smui-radius-md: 2px;",
+      },
+    ],
+    relatedDocs: ["AI_LESS_OVERRIDES.md", "README.md"],
+    keywords: ["less", "theme.config", "compile", "tokens", "rebrand", "override", "build"],
+  },
+  {
+    id: "global/component-props",
+    name: "Component Appearance Props",
+    description: "Customize a single instance through props such as `variant`, `color`, `size`, and component-specific options.",
+    summary: "This is the cheapest per-instance customization layer and requires no CSS rebuild.",
+    howTo: [
+      "Inspect the component `*Props` metadata or call `get_component_props`.",
+      "Use standardized props where available: `size`, `color`, `variant`.",
+      "Prefer props before writing custom CSS for one-off UI changes.",
+    ],
+    examples: [
+      {
+        title: "Button appearance",
+        language: "tsx",
+        code: "<Button variant=\"outlined\" color=\"primary\" size=\"large\" label=\"Save\" />",
+      },
+    ],
+    relatedDocs: ["AI_THEMING.md"],
+    keywords: ["props", "variant", "color", "size", "appearance", "instance"],
+  },
+  {
+    id: "global/classname-style",
+    name: "className and style",
+    description: "Most components accept `className` and `style` on the root element for local layout or minor visual tweaks.",
+    summary: "Use this for spacing, positioning, or small visual adjustments outside the design tokens.",
+    howTo: [
+      "Pass `className` for app-level layout or utility classes.",
+      "Pass `style` only for local exceptions; prefer tokens and props first.",
+      "Avoid relying on internal `.smwb-*` selectors when possible.",
+    ],
+    examples: [
+      {
+        title: "Local spacing",
+        language: "tsx",
+        code: "<Card className=\"my-panel\" style={{ marginTop: 16 }} />",
+      },
+    ],
+    relatedDocs: ["AI_THEMING.md", "README.md"],
+    keywords: ["className", "style", "css", "layout", "local"],
+  },
+];
+function extractEnumValues(typeText) {
+  if (!typeText) {
+    return [];
+  }
+  const matches = typeText.match(/"([^"]+)"/g);
+  if (!matches) {
+    return [];
+  }
+  return matches.map((value) => value.slice(1, -1));
+}
+function resolveLessPath(id, packageRoot) {
+  const segments = id.split("/").filter(Boolean);
+  const candidates = [
+    path.join("styles/less/components", ...segments.slice(1), `${segments.at(-1)}.less`),
+    path.join("styles/less/components", segments.at(-1), `${segments.at(-1)}.less`),
+    path.join("styles/less/components", segments.slice(-2).join("/"), `${segments.at(-1)}.less`),
+  ];
+  for (const relativePath of candidates) {
+    if (fs.existsSync(path.join(packageRoot, relativePath))) {
+      return relativePath.replace(/\\/g, "/");
+    }
+  }
+  return candidates[0].replace(/\\/g, "/");
+}
+function buildAppearanceProps(entry) {
+  const appearance = {};
+  for (const [propName, propMeta] of Object.entries(entry.props ?? {})) {
+    if (!APPEARANCE_PROP_NAMES.has(propName)) {
+      continue;
+    }
+    appearance[propName] = {
+      type: propMeta.type,
+      required: propMeta.required,
+      description: propMeta.description,
+      values: extractEnumValues(propMeta.type),
+    };
+  }
+  return appearance;
+}
+function buildRecommendations(entry, appearanceProps, lessPath) {
+  const recommendations = [];
+  if (Object.keys(appearanceProps).length) {
+    recommendations.push("Start with component props such as variant, color, and size for instance-level customization.");
+  }
+  recommendations.push("Use runtime `--smui-*` CSS variables for live theme tweaks without rebuilding CSS.");
+  recommendations.push(`Inspect \`${lessPath}\` for component-specific Less tokens and runtime CSS variables.`);
+  recommendations.push("Use `theme.config` when the change should apply library-wide after recompiling Less.");
+  if (entry.inheritedAttributes) {
+    recommendations.push("The root element also accepts standard HTML attributes, plus `className` and `style`.");
+  }
+  return recommendations;
+}
+export function buildComponentCustomization(entry, packageRoot) {
+  const appearanceProps = buildAppearanceProps(entry);
+  const lessPath = resolveLessPath(entry.id, packageRoot);
+  const lessFileExists = fs.existsSync(path.join(packageRoot, lessPath));
+  return {
+    id: entry.id,
+    type: "component",
+    name: entry.name,
+    description: entry.description,
+    customization: {
+      props: appearanceProps,
+      runtimeCss: {
+        description: "Override `--smui-*` CSS custom properties globally or on a subtree.",
+        lessPath: lessFileExists ? lessPath : undefined,
+        inspect: lessFileExists
+          ? `Search for var(--smui- in ${lessPath}`
+          : "Search styles/less/variables.less for global --smui-* tokens.",
+      },
+      lessVariables: {
+        description: "Override component Less tokens in theme.config and recompile the stylesheet.",
+        lessPath: lessFileExists ? lessPath : undefined,
+        inspect: lessFileExists ? `Search for @ tokens in ${lessPath}` : "Search styles/less/default/globals/default.variables.less",
+      },
+      className: {
+        available: Boolean(entry.inheritedAttributes),
+        description: "Additional CSS class name(s) on the root element.",
+      },
+      style: {
+        available: Boolean(entry.inheritedAttributes),
+        description: "Inline CSS styles on the root element.",
+      },
+    },
+    recommendations: buildRecommendations(entry, appearanceProps, lessPath),
+    relatedDocs: ["AI_THEMING.md", "AI_LESS_OVERRIDES.md"],
+  };
+}
+function enrichGlobalTopic(topic) {
+  return {
+    ...topic,
+    type: "global",
+    searchText: normalizeText(
+      [topic.id, topic.name, topic.description, topic.summary, ...(topic.keywords ?? []), ...(topic.howTo ?? [])].join(" ")
+    ),
+  };
+}
+export function loadCustomizationCatalog(catalog, packageRoot) {
+  const globalTopics = GLOBAL_CUSTOMIZATION_TOPICS.map(enrichGlobalTopic);
+  const components = catalog.all.map((entry) => {
+    const customization = buildComponentCustomization(entry, packageRoot);
+    return {
+      ...customization,
+      searchText: normalizeText(
+        [
+          customization.id,
+          customization.name,
+          customization.description,
+          ...Object.keys(customization.customization.props),
+          ...customization.recommendations,
+          "customization",
+          "theme",
+          "variant",
+          "color",
+          "size",
+          "less",
+          "css",
+        ].join(" ")
+      ),
+    };
+  });
+  const byId = new Map();
+  const byName = new Map();
+  for (const topic of [...globalTopics, ...components]) {
+    byId.set(normalizeText(topic.id), topic);
+    byName.set(normalizeText(topic.name), topic);
+  }
+  return {
+    globalTopics,
+    components,
+    all: [...globalTopics, ...components],
+    byId,
+    byName,
+  };
+}
+function scoreTopic(topic, query, queryTokens, queryCompact) {
+  let score = 0;
+  const reasons = [];
+  const name = normalizeText(topic.name);
+  const id = normalizeText(topic.id);
+  if (name === query || id === query || id.endsWith(`/${query}`)) {
+    score += 1000;
+    reasons.push("exact-match");
+  }
+  if (compactText(name) === queryCompact || compactText(id) === queryCompact) {
+    score += 900;
+    reasons.push("compact-match");
+  }
+  if (name.includes(query) || id.includes(query) || topic.searchText.includes(query)) {
+    score += 420;
+    reasons.push("text-match");
+  }
+  for (const token of queryTokens) {
+    if (name.includes(token) || id.includes(token) || topic.searchText.includes(token)) {
+      score += 60;
+      reasons.push("token-match");
+    }
+    if (topic.type === "component" && Object.keys(topic.customization?.props ?? {}).includes(token)) {
+      score += 120;
+      reasons.push("prop-match");
+    }
+  }
+  const fuzzy = similarityScore(name, queryCompact);
+  if (queryCompact.length >= 3 && fuzzy >= 0.72) {
+    score += Math.round(fuzzy * 220);
+    reasons.push("fuzzy-match");
+  }
+  if (topic.type === "global" && ["theme", "less", "css", "dark", "props"].includes(queryCompact)) {
+    score += 80;
+    reasons.push("global-keyword");
+  }
+  return { score, reasons: [...new Set(reasons)] };
+}
+export function searchCustomization(catalog, customizationCatalog, query, limit = 10) {
+  const normalizedQuery = normalizeText(query ?? "");
+  if (!normalizedQuery) {
+    return customizationCatalog.all.slice(0, limit).map((topic) => summarizeCustomizationTopic(topic));
+  }
+  const queryTokens = tokenize(normalizedQuery);
+  const queryCompact = compactText(normalizedQuery);
+  return customizationCatalog.all
+    .map((topic) => ({ topic, ...scoreTopic(topic, normalizedQuery, queryTokens, queryCompact) }))
+    .filter((item) => item.score >= 50)
+    .sort(
+      (a, b) =>
+        b.score - a.score ||
+        (a.topic.type === "component" && b.topic.type === "global" ? -1 : 0) ||
+        a.topic.name.localeCompare(b.topic.name)
+    )
+    .slice(0, limit)
+    .map(({ topic, score, reasons }) => ({
+      ...summarizeCustomizationTopic(topic),
+      score,
+      matchReasons: reasons,
+    }));
+}
+function summarizeCustomizationTopic(topic) {
+  if (topic.type === "global") {
+    return {
+      id: topic.id,
+      type: topic.type,
+      name: topic.name,
+      description: topic.description,
+      summary: topic.summary,
+    };
+  }
+  return {
+    id: topic.id,
+    type: topic.type,
+    name: topic.name,
+    description: topic.description,
+    appearanceProps: Object.keys(topic.customization.props),
+    layers: ["props", "runtimeCss", "lessVariables", "className", "style"].filter((layer) => {
+      if (layer === "props") {
+        return Object.keys(topic.customization.props).length > 0;
+      }
+      if (layer === "className" || layer === "style") {
+        return topic.customization[layer]?.available;
+      }
+      return true;
+    }),
+  };
+}
+export function resolveCustomizationTopic(customizationCatalog, nameOrId) {
+  const key = normalizeText(nameOrId ?? "");
+  if (!key) {
+    return null;
+  }
+  return (
+    customizationCatalog.byId.get(key) ??
+    customizationCatalog.byName.get(key) ??
+    customizationCatalog.all.find((topic) => normalizeText(topic.name) === key) ??
+    null
+  );
+}
+export function getCustomization(catalog, customizationCatalog, nameOrId) {
+  const direct = resolveCustomizationTopic(customizationCatalog, nameOrId);
+  if (direct) {
+    return stripSearchText(direct);
+  }
+  const component = resolveComponent(catalog, nameOrId);
+  if (component) {
+    const built = customizationCatalog.components.find((item) => item.id === component.id);
+    if (built) {
+      return stripSearchText(built);
+    }
+  }
+  const [bestMatch] = searchCustomization(catalog, customizationCatalog, nameOrId, 1);
+  if (!bestMatch || bestMatch.score < 120) {
+    return null;
+  }
+  const resolved = resolveCustomizationTopic(customizationCatalog, bestMatch.id);
+  return resolved ? stripSearchText(resolved) : null;
+}
+function stripSearchText(topic) {
+  const { searchText: _searchText, ...rest } = topic;
+  return rest;
+}
+export { GLOBAL_CUSTOMIZATION_TOPICS };

package/package.json ADDED Viewed

@@ -0,0 +1,37 @@
+{
+  "name": "@smwb/ui-mcp-solid",
+  "version": "0.1.0",
+  "description": "Model Context Protocol server exposing the @smwb/ui-solid (SolidJS) component catalog and customization guide.",
+  "license": "MIT",
+  "type": "module",
+  "engines": {
+    "node": ">=20"
+  },
+  "bin": {
+    "ui-mcp-solid": "./server.mjs"
+  },
+  "files": [
+    "server.mjs",
+    "componentMeta.mjs",
+    "customizationMeta.mjs",
+    "component-meta"
+  ],
+  "scripts": {
+    "build": "npm run build:meta",
+    "build:meta": "node scripts/generate-meta.mjs",
+    "start": "node server.mjs",
+    "test": "vitest run",
+    "jest": "vitest run"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "zod": "^4.4.3"
+  },
+  "devDependencies": {
+    "@smwb/ui-solid": "^0.1.0",
+    "@smwb/ui-styles": "^1.0.0",
+    "glob": "^13.0.6",
+    "typescript": "^6.0.3",
+    "vitest": "^2.1.9"
+  }
+}

package/server.mjs ADDED Viewed

@@ -0,0 +1,169 @@
+#!/usr/bin/env node
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { getComponentProps, loadCatalogFromPackageRoot, searchComponents } from "./componentMeta.mjs";
+import { getCustomization, loadCustomizationCatalog, searchCustomization } from "./customizationMeta.mjs";
+const scriptDir = path.dirname(fileURLToPath(import.meta.url));
+// server.mjs sits at the package root; metadata lives in ./component-meta.
+const packageRoot = scriptDir;
+const catalog = loadCatalogFromPackageRoot(packageRoot);
+const customizationCatalog = loadCustomizationCatalog(catalog, packageRoot);
+const server = new McpServer(
+  {
+    name: "ui-solid-components",
+    version: process.env.npm_package_version ?? "0.0.0",
+  },
+  {
+    instructions:
+      "@smwb/ui-solid component catalog and customization guide. Use search_components / get_component_props for API metadata, and search_customization / get_customization for theming and appearance options.",
+  }
+);
+server.registerTool(
+  "search_components",
+  {
+    title: "Search @smwb/ui-solid components",
+    description:
+      "Search the @smwb/ui-solid component catalog by exact, partial, fuzzy, or multi-word queries across names, ids, descriptions, and prop names.",
+    inputSchema: z.object({
+      query: z.string().describe("Search query, for example: button, chat, text field"),
+      limit: z.number().int().min(1).max(50).optional().describe("Maximum number of matches to return"),
+    }),
+  },
+  async ({ query, limit }) => {
+    const results = searchComponents(catalog, query, limit ?? 10);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ count: results.length, results }, null, 2),
+        },
+      ],
+      structuredContent: { count: results.length, results },
+    };
+  }
+);
+server.registerTool(
+  "get_component_props",
+  {
+    title: "Get @smwb/ui-solid component props",
+    description:
+      "Return the full metadata document for a @smwb/ui-solid component, including prop names, types, required flags, descriptions, and required Less imports (`styles.base`, `styles.entries`, `styles.dependencies`, `styles.importExample`).",
+    inputSchema: z.object({
+      nameOrId: z
+        .string()
+        .describe("Exact component name (Button) or metadata id (inputs/button/button, dataDisplay/chat/chat)"),
+    }),
+  },
+  async ({ nameOrId }) => {
+    const result = getComponentProps(catalog, nameOrId);
+    if (!result) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                error: "Component not found",
+                nameOrId,
+                hint: "Call search_components first to discover valid ids and names.",
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      structuredContent: result,
+    };
+  }
+);
+server.registerTool(
+  "search_customization",
+  {
+    title: "Search @smwb/ui-solid customization options",
+    description:
+      "Search global theming approaches and component-specific customization options by exact, partial, fuzzy, or multi-word queries.",
+    inputSchema: z.object({
+      query: z
+        .string()
+        .describe("Search query, for example: button color, dark theme, less override, runtime css"),
+      limit: z.number().int().min(1).max(50).optional().describe("Maximum number of matches to return"),
+    }),
+  },
+  async ({ query, limit }) => {
+    const results = searchCustomization(catalog, customizationCatalog, query, limit ?? 10);
+    return {
+      content: [{ type: "text", text: JSON.stringify({ count: results.length, results }, null, 2) }],
+      structuredContent: { count: results.length, results },
+    };
+  }
+);
+server.registerTool(
+  "get_customization",
+  {
+    title: "Get @smwb/ui-solid customization guide",
+    description:
+      "Return what and how can be customized for a component or a global theming topic, including props, runtime CSS variables, Less overrides, and recommendations.",
+    inputSchema: z.object({
+      nameOrId: z
+        .string()
+        .describe(
+          "Component name/id (Button, inputs/button/button) or global topic id (global/runtime-css, global/dark-mode, global/less-overrides)"
+        ),
+    }),
+  },
+  async ({ nameOrId }) => {
+    const result = getCustomization(catalog, customizationCatalog, nameOrId);
+    if (!result) {
+      return {
+        isError: true,
+        content: [
+          {
+            type: "text",
+            text: JSON.stringify(
+              {
+                error: "Customization topic not found",
+                nameOrId,
+                hint: "Call search_customization first to discover valid component and global topic ids.",
+              },
+              null,
+              2
+            ),
+          },
+        ],
+      };
+    }
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      structuredContent: result,
+    };
+  }
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error(
+    `@smwb/ui-solid MCP server ready (${catalog.count} components, ${customizationCatalog.globalTopics.length} global customization topics loaded)`
+  );
+}
+main().catch((error) => {
+  console.error(error);
+  process.exit(1);
+});