@public-ui/mcp 3.0.7-rc.3 → 4.0.0-alpha.8

package/dist/mcp.mjs

@@ -0,0 +1,291 @@
+import { McpServer, ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import express from 'express';
+import { createRequire } from 'node:module';
+import { z } from 'zod';
+import { getSampleIndexMetadata, getAllEntries, getEntryById } from './data.mjs';
+import { searchEntries } from './search.mjs';
+import 'node:fs';
+import 'node:url';
+import 'fuse.js';
+
+const KIND_OPTIONS = ["doc", "sample", "scenario", "spec"];
+function isValidKind(value) {
+  return typeof value === "string" && KIND_OPTIONS.includes(value);
+}
+function normalizeTags(tags) {
+  return Array.isArray(tags) ? tags : [];
+}
+function formatTagsForText(tags) {
+  const normalized = normalizeTags(tags);
+  return normalized.length > 0 ? normalized.join(", ") : "none";
+}
+const require = createRequire(import.meta.url);
+const {
+  version: PACKAGE_VERSION = "0.0.0",
+  name: PACKAGE_NAME = "@public-ui/mcp",
+  description: PACKAGE_DESCRIPTION
+} = require("../package.json");
+const ENABLE_LOGGING = process.env.MCP_LOGGING === "true" || process.env.MCP_LOGGING === "1";
+function log(type, message, data) {
+  if (!ENABLE_LOGGING) return;
+  const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+  const prefix = `[${timestamp}] [${type.toUpperCase()}]`;
+  if (data) {
+    console.error(`${prefix} ${message}`, JSON.stringify(data, null, 2));
+  } else {
+    console.error(`${prefix} ${message}`);
+  }
+}
+function createKolibriMcpServer() {
+  const server = new McpServer({
+    name: PACKAGE_NAME,
+    version: PACKAGE_VERSION
+  });
+  return configureServer(server);
+}
+function configureServer(server) {
+  server.registerTool(
+    "search",
+    {
+      title: "Search KoliBri Samples and Docs",
+      description: 'Search for KoliBri component samples, scenarios, specifications, and documentation using fuzzy search. Parameters: query (optional string), kind (optional select: "doc", "sample", "scenario", or "spec"), limit (optional number, default 10).',
+      inputSchema: {
+        query: z.string().optional().default(""),
+        kind: z.enum(KIND_OPTIONS).optional(),
+        limit: z.number().optional()
+      },
+      outputSchema: {
+        query: z.string(),
+        totalResults: z.number()
+      }
+    },
+    ({ query, kind, limit }) => {
+      log("tool", "search called", { query, kind, limit });
+      const queryStr = typeof query === "string" ? query : "";
+      const allEntries = getAllEntries();
+      const searchOptions = {
+        limit: typeof limit === "number" ? limit : 10
+      };
+      if (isValidKind(kind)) {
+        searchOptions.kind = kind;
+      }
+      const results = searchEntries(allEntries, queryStr, searchOptions);
+      log("tool", "search completed", {
+        query: queryStr,
+        resultCount: results.length,
+        options: searchOptions
+      });
+      const structuredContent = {
+        query: queryStr,
+        totalResults: results.length,
+        results: results.map(({ item, score }) => ({
+          id: item.id,
+          kind: item.kind,
+          name: item.name,
+          group: item.group ?? "N/A",
+          description: item.description ?? "N/A",
+          tags: normalizeTags(item.tags),
+          score: score ?? 1,
+          path: item.path ?? "N/A"
+        }))
+      };
+      const resultText = results.length ? results.map(({ item, score }, index) => {
+        const matchScore = ((score ?? 1) * 100).toFixed(1);
+        const pathLine = item.path ? `
+   Path: ${item.path}` : "";
+        return `${index + 1}. [${item.kind}] ${item.id}: ${item.name}
+   Description: ${item.description ?? "N/A"}
+   Match score: ${matchScore}%
+   Tags: ${formatTagsForText(item.tags)}${pathLine}`;
+      }).join("\n\n") : "No matches found.";
+      const tipText = results.length ? "\n\n\u{1F4A1} Tip: Use 'fetch' with any ID above to see full entry details." : "";
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Found ${results.length} result(s) for "${queryStr}":
+
+${resultText}${tipText}`
+          }
+        ],
+        structuredContent
+      };
+    }
+  );
+  server.registerTool(
+    "fetch",
+    {
+      title: "Get Sample or Doc Entry",
+      description: 'Get a specific sample, specification, or documentation entry by its ID. Parameter: id (required string, e.g. "button/basic", "spec/button", or "docs/getting-started")',
+      inputSchema: {
+        id: z.string()
+      },
+      outputSchema: {
+        id: z.string(),
+        kind: z.string(),
+        name: z.string()
+      }
+    },
+    ({ id }) => {
+      log("tool", "fetch called", { id });
+      const idStr = String(id ?? "");
+      if (!idStr) {
+        log("error", "fetch failed: empty id");
+        throw new Error("ID parameter is required");
+      }
+      const entry = getEntryById(idStr);
+      if (!entry) {
+        log("error", "fetch failed: entry not found", { id: idStr });
+        throw new Error(`Entry with ID "${idStr}" not found`);
+      }
+      log("tool", "fetch completed", { id: idStr, kind: entry.kind });
+      const output = {
+        id: entry.id,
+        kind: entry.kind,
+        name: entry.name,
+        group: entry.group ?? "N/A",
+        description: entry.description ?? "N/A",
+        tags: entry.tags ?? [],
+        code: entry.code ?? "No code available",
+        path: entry.path ?? "N/A"
+      };
+      return {
+        content: [
+          {
+            type: "text",
+            text: `# ${entry.name}
+
+ID: ${entry.id}
+Kind: ${entry.kind}
+Group: ${entry.group ?? "N/A"}
+Description: ${entry.description ?? "N/A"}
+Tags: ${entry.tags?.join(", ") ?? "none"}
+
+## Code
+
+\`\`\`
+${entry.code ?? "No code available"}
+\`\`\``
+          }
+        ],
+        structuredContent: output
+      };
+    }
+  );
+  server.registerResource(
+    "info",
+    new ResourceTemplate("kolibri://info", { list: void 0 }),
+    {
+      title: "KoliBri MCP Server Info",
+      description: "Get information about the KoliBri MCP Server and available samples"
+    },
+    (uri) => {
+      log("resource", "info accessed", { uri: uri.href });
+      const metadata = getSampleIndexMetadata();
+      const infoText = `# KoliBri MCP Server v${PACKAGE_VERSION}
+
+${PACKAGE_DESCRIPTION ?? ""}
+
+## Sample Index
+- Generated: ${metadata.generatedAt ?? "unknown"}
+- Build mode: ${metadata.buildMode}
+- Total entries: ${metadata.counts.total}
+- Documentation: ${metadata.counts.totalDocs}
+- Specifications: ${metadata.counts.totalSpecs ?? 0}
+- Samples: ${metadata.counts.totalSamples}
+- Scenarios: ${metadata.counts.totalScenarios ?? 0}
+
+## Repository
+- Branch: ${metadata.repo.branch ?? "N/A"}
+- Commit: ${metadata.repo.commit ?? "N/A"}
+- URL: ${metadata.repo.repoUrl ?? "N/A"}
+`;
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: infoText
+          }
+        ]
+      };
+    }
+  );
+  server.registerResource(
+    "best-practices",
+    new ResourceTemplate("kolibri://best-practices", { list: void 0 }),
+    {
+      title: "KoliBri Best Practices",
+      description: "Essential guidelines for working with KoliBri Web Components"
+    },
+    (uri) => {
+      log("resource", "best-practices accessed", { uri: uri.href });
+      const practicesText = `# KoliBri Web Components - Best Practices
+
+## Essential Guidelines
+
+1. **Component Registration**
+   Always register KoliBri Web Components in the browser runtime before rendering them.
+
+2. **Integration Setup**
+   Choose the integration guide that matches your project setup to load and bundle the components correctly.
+
+3. **Icon Font Assets**
+   Bundle the KoliBri icon font assets (for example codicon.css and codicon.ttf) so kol-icon glyphs can render.
+
+4. **Form Validation**
+   Wrap input elements with <kol-form> and feed its _errorList to surface validation issues via the generated error summary.
+
+## Additional Resources
+
+Use the 'search' tool to find specific component examples and implementation details.
+Use the 'fetch' tool to retrieve full code samples for specific components.
+`;
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "text/markdown",
+            text: practicesText
+          }
+        ]
+      };
+    }
+  );
+  return server;
+}
+if (import.meta.url === `file://${process.argv[1]}` || process.argv[1]?.endsWith("/mcp.ts") || process.argv[1]?.endsWith("/mcp.cjs") || process.argv[1]?.endsWith("/mcp.mjs")) {
+  const server = createKolibriMcpServer();
+  const app = express();
+  app.use(express.json());
+  app.post("/mcp", async (req, res) => {
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0,
+      enableJsonResponse: true
+    });
+    res.on("close", () => {
+      void transport.close();
+    });
+    await server.connect(transport);
+    await transport.handleRequest(req, res, req.body);
+  });
+  const port = parseInt(process.env.PORT || "3000");
+  void app.listen(port, () => {
+    console.log(`KoliBri MCP Server v${PACKAGE_VERSION} running on http://localhost:${port}/mcp`);
+    const metadata = getSampleIndexMetadata();
+    console.log(
+      `Loaded ${metadata.counts.total} entries (${metadata.counts.totalDocs} docs, ${metadata.counts.totalSamples} samples, ${metadata.counts.totalScenarios ?? 0} scenarios)`
+    );
+    if (ENABLE_LOGGING) {
+      console.log("\u{1F50D} Logging is ENABLED (MCP_LOGGING=true)");
+    } else {
+      console.log("\u{1F4A1} Logging is disabled. Set MCP_LOGGING=true to enable request logging");
+    }
+  }).on("error", (error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+  });
+}
+
+export { createKolibriMcpServer };

package/dist/search.cjs

@@ -0,0 +1,52 @@
+'use strict';
+
+const Fuse = require('fuse.js');
+
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+const Fuse__default = /*#__PURE__*/_interopDefaultCompat(Fuse);
+
+const FUSE_OPTIONS = {
+  includeScore: true,
+  shouldSort: true,
+  threshold: 0.4,
+  // Default threshold for single-word queries
+  minMatchCharLength: 2,
+  // useExtendedSearch is set dynamically based on query type
+  keys: [
+    { name: "id", weight: 0.2 },
+    { name: "name", weight: 0.2 },
+    { name: "group", weight: 0.15 },
+    { name: "description", weight: 0.1 },
+    { name: "tags", weight: 0.05 }
+  ]
+};
+function searchEntries(entries, query, options = {}) {
+  const normalizedQuery = query.trim();
+  const filteredEntries = options.kind ? entries.filter((e) => e.kind === options.kind) : entries;
+  if (!normalizedQuery) {
+    return filteredEntries.map((item) => ({ item, score: 1 }));
+  }
+  const words = normalizedQuery.split(/\s+/).filter((w) => w.length > 0);
+  const isMultiWord = words.length > 1;
+  const fuseOptions = {
+    ...FUSE_OPTIONS,
+    // Use higher threshold for multi-word queries to find more results
+    threshold: options.threshold ?? (isMultiWord ? 0.6 : FUSE_OPTIONS.threshold),
+    // Only use extended search for multi-word queries
+    useExtendedSearch: isMultiWord
+  };
+  const fuse = new Fuse__default(filteredEntries, fuseOptions);
+  const searchQuery = isMultiWord ? words.map((w) => `'${w}`).join(" | ") : normalizedQuery;
+  const results = fuse.search(searchQuery);
+  const searchResults = results.map((result) => ({
+    item: result.item,
+    score: result.score ?? 1
+  }));
+  if (options.limit && options.limit > 0) {
+    return searchResults.slice(0, options.limit);
+  }
+  return searchResults;
+}
+
+exports.searchEntries = searchEntries;

package/dist/search.d.cts

@@ -0,0 +1,16 @@
+import { SampleEntry } from './data.cjs';
+
+type EntryKind = SampleEntry['kind'];
+interface SearchOptions {
+    threshold?: number;
+    limit?: number;
+    kind?: EntryKind;
+}
+interface SearchResult {
+    item: SampleEntry;
+    score: number;
+}
+declare function searchEntries(entries: SampleEntry[], query: string, options?: SearchOptions): SearchResult[];
+
+export { searchEntries };
+export type { SearchOptions };

package/dist/search.d.mts

@@ -0,0 +1,16 @@
+import { SampleEntry } from './data.mjs';
+
+type EntryKind = SampleEntry['kind'];
+interface SearchOptions {
+    threshold?: number;
+    limit?: number;
+    kind?: EntryKind;
+}
+interface SearchResult {
+    item: SampleEntry;
+    score: number;
+}
+declare function searchEntries(entries: SampleEntry[], query: string, options?: SearchOptions): SearchResult[];
+
+export { searchEntries };
+export type { SearchOptions };

package/dist/search.d.ts

@@ -0,0 +1,16 @@
+import { SampleEntry } from './data.js';
+
+type EntryKind = SampleEntry['kind'];
+interface SearchOptions {
+    threshold?: number;
+    limit?: number;
+    kind?: EntryKind;
+}
+interface SearchResult {
+    item: SampleEntry;
+    score: number;
+}
+declare function searchEntries(entries: SampleEntry[], query: string, options?: SearchOptions): SearchResult[];
+
+export { searchEntries };
+export type { SearchOptions };

package/dist/search.mjs

@@ -0,0 +1,46 @@
+import Fuse from 'fuse.js';
+
+const FUSE_OPTIONS = {
+  includeScore: true,
+  shouldSort: true,
+  threshold: 0.4,
+  // Default threshold for single-word queries
+  minMatchCharLength: 2,
+  // useExtendedSearch is set dynamically based on query type
+  keys: [
+    { name: "id", weight: 0.2 },
+    { name: "name", weight: 0.2 },
+    { name: "group", weight: 0.15 },
+    { name: "description", weight: 0.1 },
+    { name: "tags", weight: 0.05 }
+  ]
+};
+function searchEntries(entries, query, options = {}) {
+  const normalizedQuery = query.trim();
+  const filteredEntries = options.kind ? entries.filter((e) => e.kind === options.kind) : entries;
+  if (!normalizedQuery) {
+    return filteredEntries.map((item) => ({ item, score: 1 }));
+  }
+  const words = normalizedQuery.split(/\s+/).filter((w) => w.length > 0);
+  const isMultiWord = words.length > 1;
+  const fuseOptions = {
+    ...FUSE_OPTIONS,
+    // Use higher threshold for multi-word queries to find more results
+    threshold: options.threshold ?? (isMultiWord ? 0.6 : FUSE_OPTIONS.threshold),
+    // Only use extended search for multi-word queries
+    useExtendedSearch: isMultiWord
+  };
+  const fuse = new Fuse(filteredEntries, fuseOptions);
+  const searchQuery = isMultiWord ? words.map((w) => `'${w}`).join(" | ") : normalizedQuery;
+  const results = fuse.search(searchQuery);
+  const searchResults = results.map((result) => ({
+    item: result.item,
+    score: result.score ?? 1
+  }));
+  if (options.limit && options.limit > 0) {
+    return searchResults.slice(0, options.limit);
+  }
+  return searchResults;
+}
+
+export { searchEntries };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@public-ui/mcp",
-  "version": "3.0.7-rc.3",
+  "version": "4.0.0-alpha.8",
   "license": "EUPL-1.2",
   "homepage": "https://public-ui.github.io",
   "repository": {
@@ -32,7 +32,8 @@
   "main": "dist/index.cjs",
   "module": "dist/index.mjs",
   "bin": {
-    "kolibri-mcp": "dist/cli.mjs"
+    "@public-ui/mcp": "dist/cli.cjs",
+    "kolibri-mcp": "dist/cli.cjs"
   },
   "exports": {
     ".": {
@@ -40,18 +41,59 @@
       "require": "./dist/index.cjs"
     }
   },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "1.24.3",
+    "express": "5.2.1",
+    "fuse.js": "7.1.0",
+    "zod": "3.25.76",
+    "@public-ui/components": "4.0.0-alpha.8"
+  },
   "devDependencies": {
-    "prettier": "3.6.2",
+    "@modelcontextprotocol/inspector": "0.17.5",
+    "@types/express": "5.0.6",
+    "@types/node": "24.10.1",
+    "@typescript-eslint/eslint-plugin": "7.18.0",
+    "@typescript-eslint/parser": "7.18.0",
+    "eslint": "8.57.1",
+    "eslint-config-prettier": "9.1.2",
+    "eslint-plugin-html": "8.1.3",
+    "eslint-plugin-jsdoc": "50.8.0",
+    "eslint-plugin-json": "3.1.0",
+    "knip": "5.71.0",
+    "nodemon": "3.1.11",
+    "prettier": "3.7.4",
+    "prettier-plugin-organize-imports": "4.3.0",
+    "tsx": "4.21.0",
+    "typescript": "5.9.3",
     "unbuild": "3.6.1"
   },
   "files": [
     "dist/",
+    "shared/",
     "README.md"
   ],
   "scripts": {
-    "build": "node prebuild.js && unbuild",
-    "format": "prettier --check src",
+    "build:deps": "pnpm --filter @public-ui/mcp^... build",
+    "generate-index": "node ./scripts/generate-sample-index.mjs",
+    "prebuild": "pnpm generate-index",
+    "build": "unbuild",
+    "predev": "pnpm generate-index",
+    "dev": "nodemon",
+    "format": "prettier -c src test public",
+    "lint": "pnpm lint:eslint && pnpm lint:tsc",
+    "lint:eslint": "eslint src test 'public/**/*.html'",
+    "lint:tsc": "tsc --noemit",
+    "preinspect": "pnpm generate-index",
+    "inspect": "mcp-inspector tsx src/cli.ts",
     "prestart": "pnpm build",
-    "start": "node dist/index.mjs"
+    "start": "node dist/mcp.cjs",
+    "start:stdio": "node dist/cli.cjs",
+    "pretest": "pnpm build",
+    "test": "node --test test/*.test.js",
+    "test:api": "node test-vercel-api.mjs",
+    "unused": "knip",
+    "vercel:dev": "vercel dev",
+    "vercel:deploy": "vercel",
+    "vercel:deploy:prod": "vercel --prod"
   }
 }

package/shared/.gitkeep

@@ -0,0 +1 @@
+# Keep this directory in git, but exclude generated JSON files