kodza-mcp 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,39 @@
+Kodza License
+
+Copyright (c) 2025-2026 fcwebdesign (Kodza)
+
+Kodza components are original works. Their code (the HTML, CSS and JavaScript of
+each component, the React version Kodza provides, and what your AI receives through
+the Kodza MCP server) is free to use.
+
+You may:
+- use them in any number of projects, personal or commercial, including client work;
+- copy, modify and adapt them, and combine them with your own code;
+- ship them as part of a website, an application, a theme, a template or a plugin
+  you build, as long as that product offers more than the components themselves;
+- install and run the Kodza MCP server, and let an AI assistant fetch the
+  components and add them to your project;
+- keep them in your own or your team's snippets;
+- show a component or two in a free article, tutorial or code playground,
+  with a link to Kodza.
+No attribution is required in your projects. A link back is always appreciated.
+
+You may not:
+- sell, sublicense or redistribute the components themselves, alone, in a bundle
+  or as a ported version (React, Vue, Svelte...), Kodza's own React version
+  included, free or paid, modified or not;
+- offer them through another catalogue, registry, marketplace or MCP server;
+- make them the core of a paid course, membership or tutorial series;
+- repackage them with superficial changes, or present them as your own work;
+- use the Kodza name and logo to promote something that is not Kodza.
+
+Not covered by this license: the Kodza website and its design, the demo pages and
+their copy, the preview images and videos, the house images in /media (placeholders:
+swap them for your own before you ship), and the Kodza name and logo.
+All rights reserved.
+
+Copies that break these terms will be reported and taken down.
+
+THE COMPONENTS ARE PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED. IN NO EVENT SHALL THE AUTHORS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY ARISING FROM THE COMPONENTS OR THEIR USE.

package/README.md

@@ -1,3 +1,143 @@
-# Temporary Holding Version
+# kodza-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+An MCP server for [Kodza](https://kodza.dev): free, premium UI components and effects in
+plain HTML, CSS and vanilla JavaScript. Your AI assistant finds the component, gets its exact code
+and knows how to wire it into a plain page, WordPress, Shopify or React. No framework, no build
+step, no API key.
+
+## Install
+
+Kodza runs at `https://kodza.dev/api/mcp`. Nothing to install: give your assistant the address.
+
+**Claude Code**
+
+```bash
+claude mcp add -t http kodza https://kodza.dev/api/mcp
+```
+
+**Codex** (the CLI, the IDE extension and the app share `~/.codex/config.toml`)
+
+```bash
+codex mcp add kodza --url https://kodza.dev/api/mcp
+```
+
+**Cursor** (`.cursor/mcp.json` for one project, `~/.cursor/mcp.json` for all)
+
+```json
+{
+  "mcpServers": {
+    "kodza": { "url": "https://kodza.dev/api/mcp" }
+  }
+}
+```
+
+From a project file, the server starts switched off: turn it on in *Customize → MCPs*.
+
+**VS Code**
+
+```bash
+code --add-mcp '{"name":"kodza","type":"http","url":"https://kodza.dev/api/mcp"}'
+```
+
+That one is for every project. For one project only, in `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "kodza": { "type": "http", "url": "https://kodza.dev/api/mcp" }
+  }
+}
+```
+
+### Run it locally
+
+Rather keep the search on your machine, or using a client that only starts local servers (like
+Claude Desktop's `claude_desktop_config.json`)? The same server runs through npx (Node 18 or newer):
+
+```json
+{
+  "mcpServers": {
+    "kodza": { "command": "npx", "args": ["-y", "kodza-mcp"] }
+  }
+}
+```
+
+In a terminal: `claude mcp add kodza -- npx -y kodza-mcp`, `codex mcp add kodza -- npx -y kodza-mcp`.
+
+**Server won't start?** `spawn npx ENOENT`, or `No such file or directory` in VS Code: the editor
+can't find your Node. Give `command` the full path from `which npx`, and the server
+`"env": { "PATH": "<that folder>:/usr/bin:/bin" }`: `npx` needs `node` right next to it.
+
+### Then ask
+
+Ask for what you need: *"add a button that fills from the cursor"*, *"a sticky header that
+hides while I read, in my WordPress theme"*, *"a date picker for this form"*.
+
+## Tools
+
+| Tool | What it does |
+|---|---|
+| `search_components` | Finds components by what they do or look like (`query`), or lists a `category`. Returns slugs. |
+| `get_component` | One component: description, API (CSS variables and their defaults, modifier classes, `data-` attributes, events), what each key does (for the components that take the keyboard), its dark-mode values, how to install it (`target`: `html`, `artifact` for a Claude artifact, `wordpress`, `shopify`, `react`), its files and the full code. `inline: false` leaves the CSS and JS out of the code, for an assistant that downloads the files. |
+
+## Exact files, not retyped code
+
+An assistant that can run commands should not retype a component: a CSS with its theme guard
+runs to several hundred lines, retyping it costs thousands of tokens and can drop or change a
+line. Each component's CSS, JS and HTML are served as files, byte for byte what the Kodza site
+copies, and `get_component` gives the commands:
+
+```bash
+curl -fsSL --create-dirs -o kodza/kodza-drawer.css https://kodza.dev/registry/drawer/kodza-drawer.css
+curl -fsSL --create-dirs -o kodza/kodza-drawer.js https://kodza.dev/registry/drawer/kodza-drawer.js
+```
+
+The install notes then load those files (a `<link>` and a `<script defer>`, `wp_enqueue_style`
+and `wp_enqueue_script`, Shopify `assets/`, Next.js `public/`). Only the HTML is pasted and
+adapted. The code stays inline by default, for assistants that can't run anything (a chat, a
+Claude artifact); `inline: false` drops the CSS and JS blocks to save the reading too.
+
+## How Kodza components behave
+
+- Three pieces, pasted as they are: HTML, CSS, and often a small vanilla JS file.
+- The CSS only targets `kodza-` classes: it never touches the rest of the page or the theme.
+- Restyle with the `--kz-…` variables, the modifier classes and the `data-` attributes.
+- Dark mode: every component comes with its values for a dark background, ready for
+  `@media (prefers-color-scheme: dark)` or your own dark selector.
+- They take the page's font. The Kodza look is Geist (Google Fonts).
+- Any number of instances per page; one copy of the JS serves them all.
+- Content added after the page load (AJAX, SPA, a builder preview):
+  `document.dispatchEvent(new CustomEvent('kodza:init', { detail: { root } }))` starts it,
+  `'kodza:destroy'` stops it and puts the original markup back.
+- `prefers-reduced-motion`, keyboard and WCAG AA are checked on every component.
+
+## What Kodza counts
+
+Kodza counts which components AI assistants fetch, to know what is actually used: the component,
+the assistant's name (as it gives it when connecting, like `claude-code` or `cursor-vscode`) and
+the target, when one was asked for (`html`, `artifact`, `wordpress`, `shopify`, `react`). That's
+all.
+
+Through kodza.dev/api/mcp, your search words reach the server to run the search, and are thrown
+away with the answer: never stored, never logged. Your files and your code stay on your machine:
+the tools only take a few words and a slug. With the local server (npx), the search itself runs on
+your machine.
+
+## Options
+
+`KODZA_REGISTRY` points the local server at another copy of the catalogue: a URL, or a local folder
+that contains `registry/` and `components/` (the library's build output). Default:
+`https://kodza.dev`. The download commands then point at that copy too (`file://` for a folder).
+
+```bash
+KODZA_REGISTRY=http://localhost:5180 npx -y kodza-mcp
+```
+
+Hosting your own copy: `http.js` exports `handle(request, { source })`, which takes a web
+`Request` and returns its `Response` (the server is stateless, with no dependency).
+
+## License
+
+The Kodza License, like the rest of Kodza: use the components in any project, personal,
+client or commercial, no attribution required; don't resell or redistribute them as such.
+Full text in [LICENSE](LICENSE).

package/http.js

@@ -0,0 +1,97 @@
+// Kodza MCP server, the hosted one (kodza.dev/api/mcp): the same tools as the local server
+// (kodza.js), over Streamable HTTP, without state and without the MCP SDK. Each POST carries one
+// JSON-RPC message (or a batch) and gets its answer as plain JSON; there is no event stream to
+// open (GET answers 405), no session to keep, nothing for the user to install.
+//
+// The assistant's name, given once when it connects, comes back to it inside its session id: the
+// server keeps nothing, and later calls still say who asks (README, "What Kodza counts"). Nothing
+// the assistant sends is stored or logged here.
+import { randomUUID } from 'node:crypto';
+import { INSTRUCTIONS, TOOLS, VERSION, registry } from './kodza.js';
+
+// The protocol versions it speaks, newest first: these two tools travel the same way in each
+const PROTOCOLS = ['2025-11-25', '2025-06-18', '2025-03-26', '2024-11-05'];
+
+// Assistants that run in a browser (an inspector, a web app) call it from another origin
+const CORS = {
+  'access-control-allow-origin': '*',
+  'access-control-allow-methods': 'GET, POST, DELETE, OPTIONS',
+  'access-control-allow-headers': 'content-type, accept, authorization, mcp-session-id, mcp-protocol-version, last-event-id',
+  'access-control-expose-headers': 'mcp-session-id',
+};
+
+const reply = (status, body, extra = {}) =>
+  new Response(body === undefined ? null : JSON.stringify(body), {
+    status,
+    headers: { ...CORS, ...(body !== undefined && { 'content-type': 'application/json' }), ...extra },
+  });
+const ok = (id, result) => ({ jsonrpc: '2.0', id, result });
+const failure = (id, code, message) => ({ jsonrpc: '2.0', id: id ?? null, error: { code, message } });
+
+// The session id: random, then the assistant's name (ASCII, in base64url)
+const ascii = (s) => String(s || '').replace(/[^\x20-\x7e]/g, '').slice(0, 64);
+const sessionFor = (client) => `${randomUUID()}${client ? `.${Buffer.from(client).toString('base64url')}` : ''}`;
+const clientOf = (session) => {
+  const encoded = String(session || '').split('.')[1];
+  return encoded ? ascii(Buffer.from(encoded, 'base64url').toString()) : '';
+};
+
+// One HTTP request (a web Request, as Vercel and Node give it) to its Response
+export async function handle(request, { source = 'https://kodza.dev' } = {}) {
+  if (request.method === 'OPTIONS') return reply(204);
+  if (request.method !== 'POST') {
+    return reply(405, failure(null, -32000, 'Method not allowed: this server answers POST only.'), { allow: 'POST, OPTIONS' });
+  }
+  let input;
+  try {
+    input = JSON.parse(await request.text());
+  } catch {
+    return reply(400, failure(null, -32700, 'Parse error'));
+  }
+  const batch = Array.isArray(input);
+  const messages = batch ? input : [input];
+  if (!messages.length) return reply(400, failure(null, -32600, 'Invalid request'));
+
+  const kodza = registry(source);
+  let client = clientOf(request.headers.get('mcp-session-id'));
+  let session = null;
+
+  async function answer({ id, method, params }) {
+    const p = params && typeof params === 'object' ? params : {};
+    switch (method) {
+      case 'initialize': {
+        client = ascii(p.clientInfo?.name);
+        session = sessionFor(client);
+        return ok(id, {
+          protocolVersion: PROTOCOLS.includes(p.protocolVersion) ? p.protocolVersion : PROTOCOLS[0],
+          capabilities: { tools: { listChanged: false } },
+          serverInfo: { name: 'kodza', title: 'Kodza', version: VERSION },
+          instructions: INSTRUCTIONS,
+        });
+      }
+      case 'ping':
+        return ok(id, {});
+      case 'tools/list':
+        return ok(id, { tools: TOOLS });
+      case 'tools/call': {
+        const result = await kodza.call(p.name, p.arguments, client);
+        return result ? ok(id, result) : failure(id, -32602, `Unknown tool: ${p.name}`);
+      }
+      default:
+        return failure(id, -32601, `Method not found: ${method}`);
+    }
+  }
+
+  const answers = [];
+  for (const message of messages) {
+    if (!message || typeof message !== 'object' || message.jsonrpc !== '2.0') {
+      answers.push(failure(message?.id, -32600, 'Invalid request'));
+      continue;
+    }
+    // Notifications, and the client's own responses, get no answer
+    if (typeof message.method !== 'string' || message.id === undefined) continue;
+    answers.push(await answer(message));
+  }
+  if (!answers.length) return reply(202);
+  return reply(200, batch ? answers : answers[0], session ? { 'mcp-session-id': session } : {});
+}

package/index.js

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+// Kodza MCP server, the local one: lets an AI coding assistant find a Kodza component and get its
+// exact code, its API (CSS variables, modifiers, data attributes) and how to wire it into a plain
+// HTML page, WordPress, Shopify or React. Run by npx, it talks to the assistant over stdio; the
+// search runs on the user's machine. The tools themselves are in kodza.js, shared with the hosted
+// server (http.js).
+//
+// KODZA_REGISTRY points it at another copy of the catalogue: a URL, or a local folder (handy while
+// working on the library).
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { INSTRUCTIONS, TOOLS, VERSION, registry } from './kodza.js';
+
+const kodza = registry(process.env.KODZA_REGISTRY || 'https://kodza.dev');
+
+const server = new Server(
+  { name: 'kodza', title: 'Kodza', version: VERSION },
+  { capabilities: { tools: {} }, instructions: INSTRUCTIONS }
+);
+
+server.setRequestHandler(ListToolsRequestSchema, () => ({ tools: TOOLS }));
+
+server.setRequestHandler(CallToolRequestSchema, async ({ params }) => {
+  const result = await kodza.call(params.name, params.arguments, server.getClientVersion()?.name);
+  return result || { content: [{ type: 'text', text: `Unknown tool "${params.name}".` }], isError: true };
+});
+
+await server.connect(new StdioServerTransport());

package/kodza.js

@@ -0,0 +1,234 @@
+// The Kodza tools, shared by the two servers: index.js (stdio, run by npx on the user's machine)
+// and http.js (Streamable HTTP, hosted on kodza.dev). No dependency: the hosted one runs without
+// the MCP SDK.
+//
+// The data is the static registry published with the site (registry/index.json, one
+// registry/<slug>.json and one components/<slug>.md per component, and the code to copy as
+// files in registry/<slug>/). The source is its URL, or a local folder (handy while working on
+// the library).
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { pathToFileURL } from 'node:url';
+
+export const VERSION = '0.1.0';
+export const TARGETS = ['html', 'artifact', 'wordpress', 'shopify', 'react'];
+const INDEX_TTL = 30 * 60 * 1000;
+// Where a missing component is requested and voted for (a public repo, no code)
+const REQUEST_URL = 'https://github.com/kodza-dev/requests/discussions/new?category=requests';
+
+export const INSTRUCTIONS = `Kodza is a free library of premium UI components and effects in plain HTML, CSS and vanilla JavaScript (no framework, no build step), made to be pasted into any site: a plain HTML page, WordPress, Shopify, or a React app.
+Use it when the user wants a polished UI element or effect (buttons, links, text effects, sliders and galleries, cards, navigation, scroll effects, preloaders and page transitions, forms, overlays, feedback, data display) without adding a framework: search_components to find one, then get_component for its exact code.
+Rules for the code you get: if you can run shell commands, download the CSS and JS files with the commands of the component's Files section (byte for byte what the Kodza site copies) instead of retyping them, and call get_component with inline: false to leave them out of the answer; only the HTML is yours to adapt and paste. Without a shell, paste the code as it is (HTML, CSS, JS), including the generated theme guard at the end of the CSS (the :not(#_) lines keep the site's own CSS from restyling buttons and fields); restyle through its --kz-* CSS variables, modifier classes and data- attributes rather than by editing its CSS; one copy of the JS per page serves every instance; for content inserted after page load, dispatch kodza:init on document with { detail: { root } } (and kodza:destroy before removing it).
+Components take the page's font; the Kodza look is Geist (Google Fonts). Each component comes with its dark-mode values (the "Dark mode" section): use them when the page has a dark theme. Building a Claude artifact (claude.ai)? Ask get_component with target "artifact": the artifact blocks images from other sites, among other limits.`;
+
+export const TOOLS = [
+  {
+    name: 'search_components',
+    title: 'Search Kodza components',
+    description: 'Find Kodza UI components (plain HTML/CSS/vanilla JS) by what they do or look like, e.g. "button fill hover", "image slider", "sticky header", "date picker". Leave query empty to list a whole category. Returns slugs to pass to get_component.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        query: { type: 'string', description: 'Words describing the component or effect, in English' },
+        category: { type: 'string', description: 'buttons, links, text, images, cards, navigation, scroll, transitions, forms, overlays, feedback or data' },
+        limit: { type: 'integer', minimum: 1, maximum: 50, description: 'How many results, 12 by default' },
+      },
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+  {
+    name: 'get_component',
+    title: 'Get a Kodza component',
+    description: 'The full code of one Kodza component (HTML, CSS and, when it has one, vanilla JS), its API (CSS variables with defaults, modifier classes, data attributes, events), what each key does when it takes the keyboard, its dark-mode values and how to install it. Its CSS and JS are also served as exact files, with the curl commands to download them: if you can run shell commands, download them instead of retyping the code, and pass inline: false to leave them out of the answer. Give target to get only the instructions for that stack.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        slug: { type: 'string', description: 'The component slug, from search_components (e.g. "button-fill")' },
+        target: { type: 'string', enum: TARGETS, description: 'Where it goes: html (a plain page), artifact (a Claude artifact on claude.ai), wordpress, shopify or react. All of them when omitted' },
+        inline: { type: 'boolean', description: 'false: leave the CSS and JS out of the Code section (you download those files with the given commands). true by default, for assistants that cannot run commands' },
+      },
+      required: ['slug'],
+    },
+    annotations: { readOnlyHint: true, openWorldHint: false },
+  },
+];
+
+// The arguments against the tool's schema: the message of the first mistake, or null
+function invalid(tool, args) {
+  const { properties, required = [] } = tool.inputSchema;
+  for (const key of required) if (args[key] === undefined) return `${key} is required`;
+  for (const [key, value] of Object.entries(args)) {
+    const spec = properties[key];
+    if (!spec || value === undefined) continue;
+    const type = spec.type === 'integer' ? Number.isInteger(value) && 'integer' : typeof value;
+    if (type !== spec.type) return `${key} must be ${spec.type === 'integer' ? 'an' : 'a'} ${spec.type}`;
+    if (spec.enum && !spec.enum.includes(value)) return `${key} must be one of ${spec.enum.join(', ')}`;
+    if (value < spec.minimum || value > spec.maximum) return `${key} must be between ${spec.minimum} and ${spec.maximum}`;
+  }
+  return null;
+}
+
+// What the Kodza site counts (README, "What Kodza counts"): the assistant's name, as its client
+// gives it when connecting, and the target asked for. Never the query, never the user's code
+const ascii = (s) => String(s || '').replace(/[^\x20-\x7e]/g, '').slice(0, 64);
+const headers = (client, target) => ({
+  'user-agent': `kodza-mcp/${VERSION}`,
+  ...(ascii(client) && { 'x-kodza-client': ascii(client) }),
+  ...(target && { 'x-kodza-target': target }),
+});
+
+// ---------------------------------------------------------------- one registry
+
+const registries = new Map();
+
+// The tools on one source, kept (with its index) for the life of the process
+export function registry(source) {
+  const key = String(source).replace(/\/$/, '');
+  if (!registries.has(key)) registries.set(key, open(key));
+  return registries.get(key);
+}
+
+function open(source) {
+  const remote = /^https?:\/\//.test(source);
+  // Where the component files are downloaded from: the source itself (a local folder as file://)
+  const filesBase = remote ? source : pathToFileURL(path.resolve(source)).href;
+  let index = null;
+  let loadedAt = 0;
+
+  async function read(file, client, target) {
+    if (remote) {
+      const res = await fetch(`${source}/${file}`, { headers: headers(client, target) });
+      if (res.status === 404) return null;
+      if (!res.ok) throw new Error(`Kodza registry: ${res.status} on ${file}`);
+      return res.text();
+    }
+    try {
+      return await fs.readFile(path.join(source, file), 'utf8');
+    } catch (err) {
+      if (err.code === 'ENOENT') return null;
+      throw err;
+    }
+  }
+
+  async function getIndex(client) {
+    if (!index || Date.now() - loadedAt > INDEX_TTL) {
+      const text = await read('registry/index.json', client);
+      try {
+        index = JSON.parse(text);
+      } catch {
+        throw new Error(`No Kodza registry at ${source}`);
+      }
+      loadedAt = Date.now();
+    }
+    return index;
+  }
+
+  async function search({ query = '', category, limit = 12 }, client) {
+    const { components, categories } = await getIndex(client);
+    if (category && !categories.some((c) => c.id === category)) {
+      return `Unknown category "${category}". Categories: ${categories.map((c) => `${c.id} (${c.count})`).join(', ')}.`;
+    }
+    const pool = components.filter((c) => !category || c.category === category);
+    const terms = queryTerms(query);
+    const found = terms.length
+      ? pool.map((c) => ({ c, s: score(c, terms) })).filter((r) => r.s > 0).sort((a, b) => b.s - a.s).map((r) => r.c)
+      : pool;
+    if (!found.length) {
+      return `Nothing in Kodza matches "${query}"${category ? ` in ${category}` : ''}. Try fewer or broader words, or browse a category: ${categories.map((c) => c.id).join(', ')}.\n\nStill missing? The user can request it, and vote for it, here: ${REQUEST_URL}`;
+    }
+    const shown = found.slice(0, Math.max(1, Math.min(limit, 50)));
+    return [
+      `${found.length} Kodza component${found.length > 1 ? 's' : ''}${terms.length ? ` for "${query}"` : ''}${category ? ` in ${category}` : ''}${found.length > shown.length ? ` (first ${shown.length})` : ''}:`,
+      '',
+      ...shown.map(line),
+      '',
+      'Next: get_component with a slug for the code, the API and how to install it.',
+    ].join('\n');
+  }
+
+  async function getComponent({ slug, target, inline = true }, client) {
+    const clean = String(slug).trim().toLowerCase().replace(/^\/+|\/+$/g, '').replace(/^components\//, '');
+    // The index decides what exists (a host may answer any path with its home page)
+    const { components, site } = await getIndex(client);
+    let markdown = components.some((c) => c.slug === clean) ? await read(`components/${clean}.md`, client, target) : null;
+    if (markdown?.startsWith('# ')) {
+      // Files from the registry actually read, not from the public site
+      const from = `${String(site || '').replace(/\/$/, '')}/registry/${clean}/`;
+      if (site && !from.startsWith(`${filesBase}/`)) markdown = markdown.replaceAll(from, `${filesBase}/registry/${clean}/`);
+      return forTarget(inline ? markdown : withoutFileCode(markdown), target);
+    }
+    const hint = await search({ query: clean.replace(/[-_]/g, ' '), limit: 5 }, client);
+    return `No Kodza component "${slug}".\n\n${hint}`;
+  }
+
+  const run = { search_components: search, get_component: getComponent };
+
+  // One tools/call: its result, or null for a tool Kodza doesn't have. A wrong argument or a
+  // registry out of reach is a tool error the assistant can read, with nothing it sent in it
+  async function call(name, args, client) {
+    const tool = TOOLS.find((t) => t.name === name);
+    if (!tool) return null;
+    const given = args && typeof args === 'object' && !Array.isArray(args) ? args : {};
+    const wrong = invalid(tool, given);
+    if (wrong) return { content: [{ type: 'text', text: `Invalid arguments for ${name}: ${wrong}.` }], isError: true };
+    try {
+      return { content: [{ type: 'text', text: await run[name](given, client) }] };
+    } catch (err) {
+      const known = /^(Kodza registry|No Kodza registry)/.test(err.message);
+      return { content: [{ type: 'text', text: `${known ? err.message : 'Kodza registry out of reach'}. Try again in a moment.` }], isError: true };
+    }
+  }
+
+  return { call };
+}
+
+// ---------------------------------------------------------------- search
+
+const STOP = new Set('a an the and or of for to in on with my our your some any that this it is be like nice cool simple component components effect effects ui kodza'.split(' '));
+// Lowercase words, without accents, cut to a rough stem (loader, loading, loads → load)
+const stem = (w) => (w.length > 4 ? w.replace(/(ings?|ers?|ed|es|s)$/, '') : w);
+const words = (s) => s.toLowerCase().normalize('NFD').replace(/[̀-ͯ]/g, '').split(/[^a-z0-9]+/).filter(Boolean).map(stem);
+const queryTerms = (s) => s.toLowerCase().split(/[^a-z0-9]+/).filter((w) => w.length > 1 && !STOP.has(w)).map(stem);
+
+// How well a component answers the query: words matched first, then where they matched
+function score(component, terms) {
+  const title = words(component.title);
+  const slug = words(component.slug);
+  const tags = component.tags.flatMap(words);
+  const description = words(component.description);
+  const hit = (list, term) => list.some((w) => w === term || (term.length > 3 && (w.startsWith(term) || term.startsWith(w) && w.length > 3)));
+  let matched = 0;
+  let points = 0;
+  for (const term of terms) {
+    const p = (hit(title, term) ? 6 : 0) + (hit(slug, term) ? 3 : 0) + (hit(tags, term) ? 4 : 0) + (hit(description, term) ? 1 : 0) + (component.category === term ? 2 : 0);
+    if (p) matched++;
+    points += p;
+  }
+  // At least half of the words have to match somewhere
+  return matched * 2 >= terms.length ? matched * 100 + points : 0;
+}
+
+const line = (c) => `- \`${c.slug}\` — **${c.title}** (${c.category}${c.js ? '' : ', CSS only'}): ${c.description}`;
+
+// ---------------------------------------------------------------- one component
+
+// Keep only the integration notes for the target the assistant is working with
+function forTarget(markdown, target) {
+  if (!target) return markdown;
+  // An artifact is a plain page with its own limits: it gets both sections
+  const labels = { html: ['Plain HTML page'], artifact: ['Plain HTML page', 'Claude artifact'], wordpress: ['WordPress'], shopify: ['Shopify'], react: ['React / Next.js'] };
+  return markdown.replace(/## Use it\n([\s\S]*?)(?=\n## Code)/, (block) => {
+    const keep = block.split(/\n(?=### )/).filter((part) => !part.startsWith('### ') || labels[target].some((label) => part.startsWith(`### ${label}`)));
+    return keep.join('\n');
+  });
+}
+
+// Without the CSS and JS blocks of the Code section: the assistant downloads those files
+function withoutFileCode(markdown) {
+  const at = markdown.indexOf('\n## Code\n');
+  if (at < 0 || !markdown.includes('\n## Files\n')) return markdown;
+  const left = [];
+  const code = markdown.slice(at).replace(/\n```(css|js)\n[\s\S]*?\n```\n/g, (block, lang) => (left.push(lang.toUpperCase()), ''));
+  const note = `\nThe ${left.join(' and the ')} ${left.length > 1 ? 'are' : 'is'} left out here (inline: false): download ${left.length > 1 ? 'them' : 'it'} with the commands of the Files section. The HTML below is the part to adapt and paste.\n`;
+  return markdown.slice(0, at) + code.replace('\n## Code\n', `\n## Code\n${note}`);
+}

package/package.json

@@ -1,6 +1,34 @@
 {
   "name": "kodza-mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for Kodza: free premium UI components in plain HTML, CSS and vanilla JS, ready for AI coding assistants.",
+  "mcpName": "dev.kodza/kodza",
+  "homepage": "https://kodza.dev/docs/",
+  "type": "module",
+  "bin": {
+    "kodza-mcp": "index.js"
+  },
+  "files": [
+    "index.js",
+    "kodza.js",
+    "http.js",
+    "README.md",
+    "LICENSE"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "SEE LICENSE IN LICENSE",
+  "keywords": [
+    "mcp",
+    "ui",
+    "components",
+    "vanilla",
+    "css",
+    "wordpress"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.1",
+    "zod": "^4.6.7"
+  }
+}