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

package/README.md

@@ -1,238 +1,438 @@
-# KoliBri MCP Server
+# @public-ui/mcp
 
-[![npm version](https://badge.fury.io/js/@public-ui%2Fmcp.svg)](https://www.npmjs.com/package/@public-ui/mcp)
-[![License: EUPL-1.2](https://img.shields.io/badge/License-EUPL--1.2-blue.svg)](https://opensource.org/licenses/EUPL-1.2)
+[![npm](https://img.shields.io/npm/v/@public-ui/mcp)](https://www.npmjs.com/package/@public-ui/components)
+[![license](https://img.shields.io/npm/l/@public-ui/mcp)](https://github.com/public-ui/kolibri/blob/main/LICENSE)
+[![downloads](https://img.shields.io/npm/dt/@public-ui/mcp)](https://www.npmjs.com/package/@public-ui/mcp)
+[![issues](https://img.shields.io/github/issues/public-ui/kolibri)](https://github.com/public-ui/kolibri/issues)
+[![pull requests](https://img.shields.io/github/issues-pr/public-ui/kolibri)](https://github.com/public-ui/kolibri/pulls)
+[![size](https://img.shields.io/bundlephobia/min/@public-ui/mcp)](https://bundlephobia.com/result?p=@public-ui/kolibri-cli)
+![contributors](https://img.shields.io/github/contributors/public-ui/kolibri)
 
-A **Model Context Protocol (MCP) server** that provides AI agents with access to **136+ KoliBri component examples** and their source code. This enables LLMs to understand and generate code using the KoliBri design system components.
+> **Model Context Protocol Server for KoliBri – Access 200+ Component Examples**
 
-## 🚀 Quick Start
+Provides AI agents and MCP clients direct access to KoliBri component samples, specifications, scenarios, and documentation through the Model Context Protocol (MCP).
 
-### Installation
+**Primary Usage**: Remote HTTP endpoint (StreamableHTTP transport) – zero installation required  
+**Alternative**: Local stdio transport for Claude Desktop, VS Code, and other MCP clients
 
-```bash
-npm install @public-ui/mcp
-# or
-pnpm add @public-ui/mcp
-# or
-yarn add @public-ui/mcp
+## Quick Start
+
+### Recommended: Use Remote HTTP Server
+
+No installation needed! Use the hosted MCP server directly:
+
+```json
+{
+	"servers": {
+		"kolibri": {
+			"url": "https://public-ui-kolibri-mcp.vercel.app/mcp",
+			"type": "http"
+		}
+	}
+}
 ```
 
-### Usage as MCP Server
+Add this to:
+
+- **VS Code**: `mcp.json` in workspace root or `~/.config/mcp/mcp.json`
+- **Claude Desktop**: `claude_desktop_config.json` (see below)
 
-Start the MCP server for AI agents:
+### Alternative: Local Installation
+
+For offline use or local development:
 
 ```bash
-npx @public-ui/mcp
+npm install -g @public-ui/mcp
 ```
 
-The server will start on `http://localhost:3030` and provide the following endpoints:
+After installation, run with:
 
-- `GET /mcp/health` - Server status and content counts
-- `GET /mcp/samples` - List all available component examples
-- `GET /mcp/sample?id=sample/button/basic` - Get specific sample source code
-- `GET /mcp/docs` - List Markdown documentation
-- `GET /mcp/doc?id=doc/README` - Get a specific documentation entry
+```bash
+kolibri-mcp
+```
 
-The sample and doc indexes are prebuilt for deployments, therefore no manual refresh endpoint is exposed in production.
+## Usage
 
-### Integration with AI Tools
+### Recommended: Remote HTTP Server
 
-#### Claude Desktop (Anthropic)
+**Zero installation required!** Use the hosted endpoint directly:
 
-Add to your Claude Desktop configuration:
+#### VS Code Copilot
+
+Create `mcp.json` in workspace root or `~/.config/mcp/mcp.json`:
+
+```json
+{
+	"servers": {
+		"kolibri": {
+			"url": "https://public-ui-kolibri-mcp.vercel.app/mcp",
+			"type": "http"
+		}
+	},
+	"inputs": []
+}
+```
+
+#### Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
+
+```json
+{
+	"mcpServers": {
+		"kolibri": {
+			"url": "https://public-ui-kolibri-mcp.vercel.app/mcp",
+			"type": "http"
+		}
+	}
+}
+```
+
+**Benefits:**
+
+- ✅ No installation needed
+- ✅ Always up-to-date with latest samples
+- ✅ Works from any device
+- ✅ Zero maintenance
+
+### Alternative: Local stdio Transport
+
+For offline use, local development, or when you prefer local execution:
+
+#### Running via CLI
+
+```bash
+# With npx (no installation needed)
+npx @public-ui/mcp
+
+# Or after global installation
+kolibri-mcp
+```
+
+#### VS Code Copilot (Local)
+
+````json
+{
+  "servers": {
+    "kolibri": {
+      "command": "kolibri-mcp"
+    }
+  },
+  "inputs": []
+}
+```#### Claude Desktop (Local)
 
 ```json
 {
 	"mcpServers": {
 		"kolibri": {
 			"command": "npx",
-			"args": ["@public-ui/mcp"],
-			"env": {}
+			"args": ["@public-ui/mcp"]
 		}
 	}
 }
+````
+
+### Self-Hosted HTTP Server
+
+To run your own HTTP server instance:
+
+```bash
+# Start on default port 3000
+node dist/mcp.mjs
+
+# Or specify a custom port
+PORT=8080 node dist/mcp.mjs
 ```
 
-#### Custom MCP Client
+The server provides a StreamableHTTP endpoint at `POST /mcp`.
 
-```javascript
-import { spawn } from 'child_process';
+### Programmatically (stdio)
 
-// Start MCP server
-const mcpServer = spawn('npx', ['@public-ui/mcp']);
+```typescript
+import { createKolibriMcpServer } from '@public-ui/mcp';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 
-// Make requests to the server
-const response = await fetch('http://localhost:3030/mcp/samples');
-const samples = await response.json();
+const server = createKolibriMcpServer();
+const transport = new StdioServerTransport();
+
+await server.connect(transport);
 ```
 
-## 📚 What's Included
+## Logging
+
+The MCP server supports optional request logging for debugging and monitoring. Logging is **disabled by default** and outputs to stderr to avoid interfering with the stdio protocol.
 
-This MCP server provides access to **136+ KoliBri component examples** and the core **Markdown documentation** of the project, including:
+### Enable Logging
 
-- **Basic Components**: Button, Input, Link, Icon, Badge, etc.
-- **Form Components**: Form, Select, Textarea, Checkbox, Radio, etc.
-- **Layout Components**: Card, Accordion, Tabs, Modal, etc.
-- **Navigation**: Breadcrumb, Pagination, Navigation, etc.
-- **Data Display**: Table, Alert, Toast, Progress, etc.
-- **Advanced Components**: Tree, Tooltip, Popover, etc.
-- **Docs**: `README.md`, `docs/*.md`, migration guides, security guidelines, and more.
+Set the environment variable `MCP_LOGGING=true` or `MCP_LOGGING=1`:
 
-Each sample includes:
+```bash
+# stdio mode with logging (for debugging)
+MCP_LOGGING=true npx @public-ui/mcp
+
+# Or after global installation
+MCP_LOGGING=true kolibri-mcp
+
+# HTTP Server with logging
+MCP_LOGGING=true node dist/mcp.mjs
+
+# Custom port with logging
+MCP_LOGGING=true PORT=8080 node dist/mcp.mjs
+```
+
+### Note for stdio Mode
 
-- ✅ **Complete source code** (React/TypeScript)
-- ✅ **Component usage examples**
-- ✅ **Accessibility implementations**
-- ✅ **Responsive design patterns**
+All logs are written to **stderr** to ensure they don't interfere with the JSON-RPC communication on stdout. This allows you to debug stdio sessions without breaking the protocol.
 
-## 🔌 API Reference
+### Log Types
 
-### GET /mcp/health
+When enabled, logs include:
 
-Returns server status and metadata:
+- **[TOOL]** - Tool invocations (search, fetch) with parameters and results
+- **[RESOURCE]** - Resource accesses (info, best-practices)
+- **[ERROR]** - Error conditions and failures
+
+### Log Format
+
+```
+[timestamp] [TYPE] message {json_data}
+```
+
+**Example:**
+
+```
+[2025-11-06T09:45:23.456Z] [TOOL] search called {
+  "query": "button",
+  "kind": "sample",
+  "limit": 10
+}
+[2025-11-06T09:45:23.478Z] [TOOL] search completed {
+  "query": "button",
+  "resultCount": 5,
+  "options": { "limit": 10, "kind": "sample" }
+}
+```
+
+## Available Tools
+
+### 1. `hello_kolibri`
+
+A simple greeting tool for testing the connection and getting server metadata.
+
+**Parameters:**
+
+- `name` (string, optional): Name to greet
+
+**Example:**
 
 ```json
 {
-	"status": "ok",
-	"healthy": true,
-	"totalEntries": 154,
-	"totalSamples": 136,
-	"totalDocs": 18,
-	"message": "System healthy with 154 entries available",
-	"generatedAt": "2024-05-28T08:15:30.000Z",
-	"ai-hints": [
-		"Always register KoliBri Web Components in the browser runtime before rendering them.",
-		"Choose the integration guide that matches your project setup to load and bundle the components correctly."
-	]
+	"name": "hello_kolibri",
+	"arguments": { "name": "World" }
 }
 ```
 
-### GET /mcp/docs
+### 2. `search`
 
-List Markdown-based documentation entries:
+Search for KoliBri component samples, scenarios, and documentation using fuzzy search powered by Fuse.js.
 
-```bash
-# Get all docs
-curl http://localhost:3030/mcp/docs
+**Parameters:**
+
+- `query` (string, optional): Search query (leave empty to return all entries)
+- `kind` (string, optional): Filter by "doc", "sample", or "scenario"
+- `limit` (number, optional): Maximum results (default: 10)
 
-# Filter by term
-curl "http://localhost:3030/mcp/docs?q=theme"
+**Example:**
+
+```json
+{
+	"name": "search",
+	"arguments": {
+		"query": "button",
+		"kind": "sample",
+		"limit": 5
+	}
+}
 ```
 
-### GET /mcp/doc?id={docId}
+### 3. `fetch`
 
-Fetch Markdown documentation by referencing its `docs/...` identifier:
+Get a specific sample or documentation entry by its ID.
 
-```bash
-curl "http://localhost:3030/mcp/doc?id=doc/README"
+**Parameters:**
+
+- `id` (string, required): Entry ID (e.g., "button/basic")
+
+**Example:**
+
+```json
+{
+	"name": "fetch",
+	"arguments": { "id": "button/basic" }
+}
+```
+
+## Available Resources
+
+### 1. `info`
+
+Get information about the KoliBri MCP Server and available samples.
+
+**Resource URI:** `kolibri://info`
+
+**Example:**
+
+```json
+{
+	"method": "resources/read",
+	"params": { "uri": "kolibri://info" }
+}
 ```
 
-Returns the Markdown content together with metadata. Every sample or doc response exposes a `kind` field so that clients can distinguish between component examples and documentation entries.
+### 2. `best-practices`
+
+Essential guidelines for working with KoliBri Web Components. This resource provides base knowledge that AI agents should always consider when working with KoliBri components.
+
+**Resource URI:** `kolibri://best-practices`
+
+**Includes:**
+
+1. Always register KoliBri Web Components in the browser runtime before rendering them
+2. Choose the integration guide that matches your project setup to load and bundle the components correctly
+3. Bundle the KoliBri icon font assets (for example codicon.css and codicon.ttf) so kol-icon glyphs can render
+4. Wrap input elements with `<kol-form>` and feed its `_errorList` to surface validation issues via the generated error summary
+
+**Example:**
 
 ```json
 {
-	"id": "sample/button/basic",
-	"group": "button",
-	"name": "basic",
-	"path": "packages/samples/react/src/components/button/basic.tsx",
-	"code": "import React from 'react';\nimport { KolButton } from '@public-ui/react';\n...",
-	"kind": "sample",
-	"ai-hints": [
-		"Always register KoliBri Web Components in the browser runtime before rendering them.",
-		"Choose the integration guide that matches your project setup to load and bundle the components correctly."
-	]
+	"method": "resources/read",
+	"params": { "uri": "kolibri://best-practices" }
 }
 ```
 
-### GET /mcp/docs
+## Example Usage
+
+### With MCP Clients (Recommended)
+
+The easiest way to use the MCP server is through an MCP-compatible client:
+
+- **Claude Desktop**: Ask "@kolibri show me a button example"
+- **VS Code Copilot**: Ask "@kolibri how do I use KolButton?"
+- **MCP Inspector**: Visual debugging tool for testing tools and resources
+
+### Direct stdio Testing (Advanced)
+
+For testing the stdio transport directly with JSON-RPC messages:
 
-List Markdown-based documentation entries:
+**Search for button components:**
 
 ```bash
-curl http://localhost:3030/mcp/docs
+echo '{"jsonrpc":"2.0","id":1,"method":"tools/call","params":{"name":"search","arguments":{"query":"button"}}}' | kolibri-mcp
+```
+
+**Search for accessibility documentation:**
+
+```bash
+echo '{"jsonrpc":"2.0","id":2,"method":"tools/call","params":{"name":"search","arguments":{"query":"accessibility","kind":"doc"}}}' | kolibri-mcp
+```
+
+**Get a specific sample:**
 
-# Filter by term
-curl "http://localhost:3030/mcp/docs?q=theme"
+```bash
+echo '{"jsonrpc":"2.0","id":3,"method":"tools/call","params":{"name":"fetch","arguments":{"id":"sample/button/basic"}}}' | kolibri-mcp
 ```
 
-### GET /mcp/doc?id={docId}
+### Testing with MCP Inspector
 
-Fetch Markdown documentation by referencing its `docs/...` identifier:
+For visual testing and debugging:
 
 ```bash
-curl "http://localhost:3030/mcp/doc?id=doc/README"
+# Install MCP Inspector globally
+npm install -g @modelcontextprotocol/inspector
+
+# Run the server with inspector
+mcp-inspector kolibri-mcp
 ```
 
-Returns the Markdown content together with metadata. Every sample or doc response exposes a `kind` field so that clients can distinguish between component examples and documentation entries.
+This opens a web interface where you can test all tools and resources interactively.
 
-All JSON responses contain an `ai-hints` string array that reiterates in English that KoliBri Web Components must be registered in the browser and that integration steps vary with the chosen project setup.
+## Development
 
-## 🛠️ Use Cases
+```bash
+# Install dependencies
+pnpm install
+
+# Generate sample index (required before build)
+pnpm generate-index
 
-### For AI Agents
+# Build
+pnpm build
 
-- **Code Generation**: Generate KoliBri components with proper usage patterns
-- **Documentation**: Understand component APIs and props
-- **Best Practices**: Learn accessibility and responsive design implementations
-- **Debugging**: Find working examples for troubleshooting
+# Start stdio mode (for local MCP clients)
+pnpm run start:stdio
 
-### For Developers
+# Start HTTP server (for remote access)
+pnpm start
 
-- **Component Discovery**: Browse all available KoliBri components
-- **Copy-Paste Examples**: Get ready-to-use component code
-- **Learning Resource**: Understand KoliBri design system patterns
-- **Integration Guide**: See how components work together
+# Development with inspector
+pnpm run inspect
 
-## 🌐 Online Demo
+# Format
+pnpm format
 
-Try the live API at: [https://public-ui-kolibri-mcp.vercel.app/mcp/](https://public-ui-kolibri-mcp.vercel.app/mcp/)
+# Test
+pnpm test
+```
 
-- Landing page with API documentation
-- Interactive sample browser
-- Real-time health status
-- Direct API access
+## Deployment
 
-## 🔧 Configuration
+### Vercel
 
-### Environment Variables
+This package can be deployed to Vercel as a serverless API:
 
 ```bash
-PORT=3030          # Server port (default: 3030)
-NODE_ENV=production # Environment mode
+# Quick start
+pnpm run generate-index
+pnpm run build
+vercel --prod
 ```
 
-### Programmatic Usage
+After deployment, the following endpoints are available:
 
-```javascript
-import { handleApiRequest } from '@public-ui/mcp';
+- `GET /` - Landing page with API documentation
+- `POST /mcp` - MCP server endpoint (StreamableHTTP transport)
 
-// Create custom server
-const server = require('http').createServer((req, res) => {
-	handleApiRequest(req, res);
-});
+For detailed deployment instructions:
 
-server.listen(3030, () => {
-	console.log('KoliBri MCP Server running on port 3030');
-});
-```
+- **Quick Start**: See [QUICK_START_VERCEL.md](./QUICK_START_VERCEL.md)
+- **Full Guide**: See [VERCEL_DEPLOYMENT.md](./VERCEL_DEPLOYMENT.md)
 
-## 📖 About KoliBri
+### Local stdio mode
+
+```bash
+# Start server locally (stdio)
+pnpm run start:stdio
+# or
+kolibri-mcp
+```
 
-[KoliBri](https://public-ui.github.io) is a comprehensive design system and component library focused on:
+## Sample Data
 
-- ♿ **Accessibility-first** design (WCAG 2.1 AA compliant)
-- 🎨 **Themeable** components with design tokens
-- 🔧 **Framework-agnostic** (React, Angular, Vue, etc.)
-- 🏛️ **Government-ready** (developed by ITZBund)
+Currently includes example entries for:
 
-## 📄 License
+- **Samples**: button/basic, input/text, table/basic
+- **Docs**: getting-started, accessibility
 
-This project is licensed under the [EUPL-1.2](https://opensource.org/licenses/EUPL-1.2) license.
+In production, this would be replaced with actual KoliBri component data.
 
-## 🤝 Contributing
+## Dependencies
 
-See [AGENTS.md](./AGENTS.md) for development instructions and contribution guidelines.
+- `@modelcontextprotocol/sdk`: ^1.21.0 - Official MCP SDK
+- `fuse.js`: ^7.1.0 - Fuzzy search library
+- `zod`: ^3.23.8 - Schema validation
 
----
+## License
 
-**Made with ❤️ by [ITZBund](https://www.itzbund.de) for the German government and open source community.**
+EUPL-1.2

package/dist/cli.cjs

@@ -1,48 +1,43 @@
 #!/usr/bin/env node
 'use strict';
 
-require('./index.cjs');
-const http = require('http');
-const apiHandler = require('./api-handler.cjs');
-require('node:http');
-require('./sample-index.cjs');
-require('node:fs/promises');
-require('node:path');
+const stdio_js = require('@modelcontextprotocol/sdk/server/stdio.js');
+const node_module = require('node:module');
+const data = require('./data.cjs');
+const mcp = require('./mcp.cjs');
+require('node:fs');
 require('node:url');
+require('@modelcontextprotocol/sdk/server/mcp.js');
+require('@modelcontextprotocol/sdk/server/streamableHttp.js');
+require('express');
+require('zod');
+require('./search.cjs');
+require('fuse.js');
 
-const PORT = process.env.PORT || 3030;
-const server = http.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;
+var _documentCurrentScript = typeof document !== 'undefined' ? document.currentScript : null;
+const require$1 = node_module.createRequire((typeof document === 'undefined' ? require('u' + 'rl').pathToFileURL(__filename).href : (_documentCurrentScript && _documentCurrentScript.tagName.toUpperCase() === 'SCRIPT' && _documentCurrentScript.src || new URL('cli.cjs', document.baseURI).href)));
+const { version: PACKAGE_VERSION = "0.0.0" } = require$1("../package.json");
+const ENABLE_LOGGING = process.env.MCP_LOGGING === "true" || process.env.MCP_LOGGING === "1";
+async function main() {
+  const server = mcp.createKolibriMcpServer();
+  const transport = new stdio_js.StdioServerTransport();
+  await server.connect(transport);
+  const metadata = data.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)");
   }
-  apiHandler.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/cli.d.cts

@@ -0,0 +1 @@
+

package/dist/cli.d.mts

@@ -0,0 +1 @@
+

package/dist/cli.d.ts

@@ -0,0 +1 @@
+