@public-ui/mcp 4.0.0-alpha.2 → 4.0.0-alpha.8

package/dist/cli.mjs

@@ -1,46 +1,40 @@
 #!/usr/bin/env node
-import './index.mjs';
-import { createServer } from 'http';
-import { handleApiRequest } from './api-handler.mjs';
-import 'node:http';
-import './sample-index.mjs';
-import 'node:fs/promises';
-import 'node:path';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { createRequire } from 'node:module';
+import { getSampleIndexMetadata } from './data.mjs';
+import { createKolibriMcpServer } from './mcp.mjs';
+import 'node:fs';
 import 'node:url';
+import '@modelcontextprotocol/sdk/server/mcp.js';
+import '@modelcontextprotocol/sdk/server/streamableHttp.js';
+import 'express';
+import 'zod';
+import './search.mjs';
+import 'fuse.js';
 
-const PORT = process.env.PORT || 3030;
-const server = createServer((req, res) => {
-  res.setHeader("Access-Control-Allow-Origin", "*");
-  res.setHeader("Access-Control-Allow-Methods", "GET, POST, OPTIONS");
-  res.setHeader("Access-Control-Allow-Headers", "Content-Type");
-  if (req.method === "OPTIONS") {
-    res.writeHead(200);
-    res.end();
-    return;
+const require = createRequire(import.meta.url);
+const { version: PACKAGE_VERSION = "0.0.0" } = require("../package.json");
+const ENABLE_LOGGING = process.env.MCP_LOGGING === "true" || process.env.MCP_LOGGING === "1";
+async function main() {
+  const server = createKolibriMcpServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  const metadata = getSampleIndexMetadata();
+  console.error(`
+\u{1F680} KoliBri MCP Server v${PACKAGE_VERSION}`);
+  console.error("\u2501".repeat(50));
+  console.error(`\u{1F4CA} Loaded ${metadata.counts.total} entries:`);
+  console.error(`   \u2022 ${metadata.counts.totalSamples} samples`);
+  console.error(`   \u2022 ${metadata.counts.totalSpecs ?? 0} specs`);
+  console.error(`   \u2022 ${metadata.counts.totalScenarios ?? 0} scenarios`);
+  console.error(`   \u2022 ${metadata.counts.totalDocs} docs`);
+  console.error("\u2501".repeat(50));
+  if (ENABLE_LOGGING) {
+    console.error("\u{1F50D} Logging: ENABLED (MCP_LOGGING=true)");
+  } else {
+    console.error("\u{1F4A1} Logging: disabled (set MCP_LOGGING=true to enable)");
   }
-  handleApiRequest(req);
-});
-server.listen(PORT, () => {
-  console.log(`\u{1F680} KoliBri MCP Server running on http://localhost:${PORT}`);
-  console.log(`\u{1F4CA} API endpoints:`);
-  console.log(`   GET  /mcp/health   - Server status`);
-  console.log(`   GET  /mcp/samples  - List all samples`);
-  console.log(`   GET  /mcp/sample   - Get specific sample`);
-  console.log(`   GET  /mcp/docs - List docs`);
-  console.log(`   GET  /mcp/doc  - Get specific doc`);
-  console.log(`\u{1F4DA} Documentation: https://www.npmjs.com/package/@public-ui/mcp`);
-});
-process.on("SIGTERM", () => {
-  console.log("\u{1F6D1} Received SIGTERM, shutting down gracefully...");
-  server.close(() => {
-    console.log("\u2705 Server closed");
-    process.exit(0);
-  });
-});
-process.on("SIGINT", () => {
-  console.log("\u{1F6D1} Received SIGINT, shutting down gracefully...");
-  server.close(() => {
-    console.log("\u2705 Server closed");
-    process.exit(0);
-  });
-});
+  console.error("\u{1F50C} Transport: stdio");
+  console.error("\u2705 Ready for MCP requests\n");
+}
+void main();

package/dist/data.cjs

@@ -0,0 +1,88 @@
+'use strict';
+
+const node_fs = require('node:fs');
+const node_url = require('node:url');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+let cachedData;
+function calculateCounts(entries) {
+  const byKind = {};
+  for (const entry of entries) {
+    const key = entry.kind;
+    byKind[key] = (byKind[key] ?? 0) + 1;
+  }
+  return {
+    total: entries.length,
+    totalDocs: byKind.doc ?? 0,
+    totalSamples: byKind.sample ?? 0,
+    totalScenarios: byKind.scenario ?? 0,
+    totalSpecs: byKind.spec ?? 0,
+    byKind
+  };
+}
+function normalizeEntry(entry) {
+  const normalizedKind = entry.kind === "doc" ? "doc" : entry.kind === "scenario" ? "scenario" : entry.kind === "spec" ? "spec" : "sample";
+  const tags = Array.isArray(entry.tags) ? entry.tags.map((tag) => String(tag)).filter((tag) => tag.trim().length > 0) : void 0;
+  return {
+    ...entry,
+    kind: normalizedKind,
+    tags
+  };
+}
+function normalizeMetadata(metadata, entries) {
+  const counts = calculateCounts(entries);
+  const repo = metadata?.repo ?? { commit: null, branch: null, repoUrl: null };
+  return {
+    generatedAt: metadata?.generatedAt ?? null,
+    buildMode: metadata?.buildMode ?? "unknown",
+    counts: {
+      total: metadata?.counts?.total ?? counts.total,
+      totalDocs: metadata?.counts?.totalDocs ?? counts.totalDocs,
+      totalSamples: metadata?.counts?.totalSamples ?? counts.totalSamples,
+      totalScenarios: metadata?.counts?.totalScenarios ?? counts.totalScenarios,
+      totalSpecs: metadata?.counts?.totalSpecs ?? counts.totalSpecs,
+      byKind: metadata?.counts?.byKind instanceof Map ? Object.fromEntries(metadata.counts.byKind.entries()) : metadata?.counts?.byKind ? Object.fromEntries(Object.entries(metadata.counts.byKind).map(([key, value]) => [key, Number(value)])) : counts.byKind
+    },
+    repo: {
+      commit: repo.commit ?? null,
+      branch: repo.branch ?? null,
+      repoUrl: repo.repoUrl ?? null
+    }
+  };
+}
+function loadSampleData() {
+  if (cachedData) {
+    return cachedData;
+  }
+  try {
+    const sharedIndexUrl = new URL("../shared/sample-index.json", (typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('data.cjs', document.baseURI).href)));
+    const filePath = node_url.fileURLToPath(sharedIndexUrl);
+    const raw = node_fs.readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    const entries = Array.isArray(parsed.entries) ? parsed.entries.map(normalizeEntry) : [];
+    if (entries.length === 0) {
+      throw new Error("Sample index does not contain any entries.");
+    }
+    const metadata = normalizeMetadata(parsed.metadata, entries);
+    cachedData = { entries, metadata };
+    return cachedData;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to load sample index from shared/sample-index.json. Please run 'pnpm generate-index' to create the index file. Error: ${message}`
+    );
+  }
+}
+function getAllEntries() {
+  return loadSampleData().entries;
+}
+function getEntryById(id) {
+  return getAllEntries().find((entry) => entry.id === id);
+}
+function getSampleIndexMetadata() {
+  return loadSampleData().metadata;
+}
+
+exports.getAllEntries = getAllEntries;
+exports.getEntryById = getEntryById;
+exports.getSampleIndexMetadata = getSampleIndexMetadata;

package/dist/data.d.cts

@@ -0,0 +1,34 @@
+interface SampleEntry {
+    id: string;
+    kind: 'doc' | 'sample' | 'scenario' | 'spec';
+    name: string;
+    group?: string;
+    description?: string;
+    tags?: string[];
+    code?: string;
+    path?: string;
+}
+interface SampleIndexCounts {
+    total: number;
+    totalDocs: number;
+    totalSamples: number;
+    totalScenarios: number;
+    totalSpecs: number;
+    byKind: Record<string, number>;
+}
+interface SampleIndexMetadata {
+    generatedAt: string | null;
+    buildMode: string;
+    counts: SampleIndexCounts;
+    repo: {
+        commit: string | null;
+        branch: string | null;
+        repoUrl: string | null;
+    };
+}
+declare function getAllEntries(): SampleEntry[];
+declare function getEntryById(id: string): SampleEntry | undefined;
+declare function getSampleIndexMetadata(): SampleIndexMetadata;
+
+export { getAllEntries, getEntryById, getSampleIndexMetadata };
+export type { SampleEntry };

package/dist/data.d.mts

@@ -0,0 +1,34 @@
+interface SampleEntry {
+    id: string;
+    kind: 'doc' | 'sample' | 'scenario' | 'spec';
+    name: string;
+    group?: string;
+    description?: string;
+    tags?: string[];
+    code?: string;
+    path?: string;
+}
+interface SampleIndexCounts {
+    total: number;
+    totalDocs: number;
+    totalSamples: number;
+    totalScenarios: number;
+    totalSpecs: number;
+    byKind: Record<string, number>;
+}
+interface SampleIndexMetadata {
+    generatedAt: string | null;
+    buildMode: string;
+    counts: SampleIndexCounts;
+    repo: {
+        commit: string | null;
+        branch: string | null;
+        repoUrl: string | null;
+    };
+}
+declare function getAllEntries(): SampleEntry[];
+declare function getEntryById(id: string): SampleEntry | undefined;
+declare function getSampleIndexMetadata(): SampleIndexMetadata;
+
+export { getAllEntries, getEntryById, getSampleIndexMetadata };
+export type { SampleEntry };

package/dist/data.d.ts

@@ -0,0 +1,34 @@
+interface SampleEntry {
+    id: string;
+    kind: 'doc' | 'sample' | 'scenario' | 'spec';
+    name: string;
+    group?: string;
+    description?: string;
+    tags?: string[];
+    code?: string;
+    path?: string;
+}
+interface SampleIndexCounts {
+    total: number;
+    totalDocs: number;
+    totalSamples: number;
+    totalScenarios: number;
+    totalSpecs: number;
+    byKind: Record<string, number>;
+}
+interface SampleIndexMetadata {
+    generatedAt: string | null;
+    buildMode: string;
+    counts: SampleIndexCounts;
+    repo: {
+        commit: string | null;
+        branch: string | null;
+        repoUrl: string | null;
+    };
+}
+declare function getAllEntries(): SampleEntry[];
+declare function getEntryById(id: string): SampleEntry | undefined;
+declare function getSampleIndexMetadata(): SampleIndexMetadata;
+
+export { getAllEntries, getEntryById, getSampleIndexMetadata };
+export type { SampleEntry };

package/dist/data.mjs

@@ -0,0 +1,83 @@
+import { readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+let cachedData;
+function calculateCounts(entries) {
+  const byKind = {};
+  for (const entry of entries) {
+    const key = entry.kind;
+    byKind[key] = (byKind[key] ?? 0) + 1;
+  }
+  return {
+    total: entries.length,
+    totalDocs: byKind.doc ?? 0,
+    totalSamples: byKind.sample ?? 0,
+    totalScenarios: byKind.scenario ?? 0,
+    totalSpecs: byKind.spec ?? 0,
+    byKind
+  };
+}
+function normalizeEntry(entry) {
+  const normalizedKind = entry.kind === "doc" ? "doc" : entry.kind === "scenario" ? "scenario" : entry.kind === "spec" ? "spec" : "sample";
+  const tags = Array.isArray(entry.tags) ? entry.tags.map((tag) => String(tag)).filter((tag) => tag.trim().length > 0) : void 0;
+  return {
+    ...entry,
+    kind: normalizedKind,
+    tags
+  };
+}
+function normalizeMetadata(metadata, entries) {
+  const counts = calculateCounts(entries);
+  const repo = metadata?.repo ?? { commit: null, branch: null, repoUrl: null };
+  return {
+    generatedAt: metadata?.generatedAt ?? null,
+    buildMode: metadata?.buildMode ?? "unknown",
+    counts: {
+      total: metadata?.counts?.total ?? counts.total,
+      totalDocs: metadata?.counts?.totalDocs ?? counts.totalDocs,
+      totalSamples: metadata?.counts?.totalSamples ?? counts.totalSamples,
+      totalScenarios: metadata?.counts?.totalScenarios ?? counts.totalScenarios,
+      totalSpecs: metadata?.counts?.totalSpecs ?? counts.totalSpecs,
+      byKind: metadata?.counts?.byKind instanceof Map ? Object.fromEntries(metadata.counts.byKind.entries()) : metadata?.counts?.byKind ? Object.fromEntries(Object.entries(metadata.counts.byKind).map(([key, value]) => [key, Number(value)])) : counts.byKind
+    },
+    repo: {
+      commit: repo.commit ?? null,
+      branch: repo.branch ?? null,
+      repoUrl: repo.repoUrl ?? null
+    }
+  };
+}
+function loadSampleData() {
+  if (cachedData) {
+    return cachedData;
+  }
+  try {
+    const sharedIndexUrl = new URL("../shared/sample-index.json", import.meta.url);
+    const filePath = fileURLToPath(sharedIndexUrl);
+    const raw = readFileSync(filePath, "utf8");
+    const parsed = JSON.parse(raw);
+    const entries = Array.isArray(parsed.entries) ? parsed.entries.map(normalizeEntry) : [];
+    if (entries.length === 0) {
+      throw new Error("Sample index does not contain any entries.");
+    }
+    const metadata = normalizeMetadata(parsed.metadata, entries);
+    cachedData = { entries, metadata };
+    return cachedData;
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    throw new Error(
+      `Failed to load sample index from shared/sample-index.json. Please run 'pnpm generate-index' to create the index file. Error: ${message}`
+    );
+  }
+}
+function getAllEntries() {
+  return loadSampleData().entries;
+}
+function getEntryById(id) {
+  return getAllEntries().find((entry) => entry.id === id);
+}
+function getSampleIndexMetadata() {
+  return loadSampleData().metadata;
+}
+
+export { getAllEntries, getEntryById, getSampleIndexMetadata };

package/dist/mcp.cjs

@@ -0,0 +1,298 @@
+'use strict';
+
+const mcp_js = require('@modelcontextprotocol/sdk/server/mcp.js');
+const streamableHttp_js = require('@modelcontextprotocol/sdk/server/streamableHttp.js');
+const express = require('express');
+const node_module = require('node:module');
+const zod = require('zod');
+const data = require('./data.cjs');
+const search = require('./search.cjs');
+require('node:fs');
+require('node:url');
+require('fuse.js');
+
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+function _interopDefaultCompat (e) { return e && typeof e === 'object' && 'default' in e ? e.default : e; }
+
+const express__default = /*#__PURE__*/_interopDefaultCompat(express);
+
+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$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('mcp.cjs', document.baseURI).href)));
+const {
+  version: PACKAGE_VERSION = "0.0.0",
+  name: PACKAGE_NAME = "@public-ui/mcp",
+  description: PACKAGE_DESCRIPTION
+} = require$1("../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 mcp_js.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: zod.z.string().optional().default(""),
+        kind: zod.z.enum(KIND_OPTIONS).optional(),
+        limit: zod.z.number().optional()
+      },
+      outputSchema: {
+        query: zod.z.string(),
+        totalResults: zod.z.number()
+      }
+    },
+    ({ query, kind, limit }) => {
+      log("tool", "search called", { query, kind, limit });
+      const queryStr = typeof query === "string" ? query : "";
+      const allEntries = data.getAllEntries();
+      const searchOptions = {
+        limit: typeof limit === "number" ? limit : 10
+      };
+      if (isValidKind(kind)) {
+        searchOptions.kind = kind;
+      }
+      const results = search.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: zod.z.string()
+      },
+      outputSchema: {
+        id: zod.z.string(),
+        kind: zod.z.string(),
+        name: zod.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 = data.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 mcp_js.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 = data.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 mcp_js.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 ((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('mcp.cjs', document.baseURI).href)) === `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__default();
+  app.use(express__default.json());
+  app.post("/mcp", async (req, res) => {
+    const transport = new streamableHttp_js.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 = data.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);
+  });
+}
+
+exports.createKolibriMcpServer = createKolibriMcpServer;

package/dist/mcp.d.cts

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Create a configured KoliBri MCP server instance.
+ * Can be used with both stdio and HTTP transports.
+ */
+declare function createKolibriMcpServer(): McpServer;
+
+export { createKolibriMcpServer };

package/dist/mcp.d.mts

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Create a configured KoliBri MCP server instance.
+ * Can be used with both stdio and HTTP transports.
+ */
+declare function createKolibriMcpServer(): McpServer;
+
+export { createKolibriMcpServer };

package/dist/mcp.d.ts

@@ -0,0 +1,9 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Create a configured KoliBri MCP server instance.
+ * Can be used with both stdio and HTTP transports.
+ */
+declare function createKolibriMcpServer(): McpServer;
+
+export { createKolibriMcpServer };