@hyperblur/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,80 @@
-# Temporary Holding Version
+# @hyperblur/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](https://modelcontextprotocol.io) server for [Hyperblur](https://hyperblur.dev), the catalog of copy-paste React visual effects. It lets MCP clients such as Claude Code, Cursor and Claude Desktop search the catalog, read an effect's props and usage, fetch its source, and install it into a project through the shadcn registry.
+
+## Requirements
+
+- Node.js 20 or later
+- For `install_effect`: a React project with a `package.json`, set up for shadcn (`components.json`)
+
+## Setup
+
+### Claude Code
+
+```sh
+claude mcp add hyperblur -- npx -y @hyperblur/mcp
+```
+
+### Cursor
+
+Add to `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all projects:
+
+```json
+{
+  "mcpServers": {
+    "hyperblur": {
+      "command": "npx",
+      "args": ["-y", "@hyperblur/mcp"]
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json` (Settings > Developer > Edit Config), then restart the app:
+
+```json
+{
+  "mcpServers": {
+    "hyperblur": {
+      "command": "npx",
+      "args": ["-y", "@hyperblur/mcp"]
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Default | Description |
+| --- | --- | --- |
+| `HYPERBLUR_SITE_URL` | `https://hyperblur.vercel.app` | Site that serves the catalog (`/r/index.json`) and registry items (`/r/<slug>.json`). Point it at `http://localhost:3000` when working on the site locally. |
+
+Pass it through the `env` field of your client config, or with `claude mcp add hyperblur -e HYPERBLUR_SITE_URL=http://localhost:3000 -- npx -y @hyperblur/mcp`.
+
+The catalog index is cached in memory for five minutes.
+
+## Tools
+
+| Tool | Purpose |
+| --- | --- |
+| `search_effects` | Search by keyword and optional category (`text`, `motion`, `overlay`, `hover`). Returns slug, title, category, description and install command for each match. |
+| `get_effect` | Full reference for one effect: props table, usage example, import line, dependencies, install command and docs link. |
+| `get_effect_source` | The component source and its target path, for writing the file by hand when shadcn is not available. |
+| `install_effect` | Runs `npx shadcn@latest add <registry-url> --yes` in the given project directory (`--overwrite` optional) and reports the output and installed file. |
+
+It also exposes the resource `hyperblur://catalog` (the full catalog index as JSON) and the prompt `add_effect`, which walks through looking up and installing an effect by slug.
+
+## Development
+
+```sh
+npm install
+npm run build
+npm test
+HYPERBLUR_SITE_URL=http://localhost:3000 npm start
+```
+
+## License
+
+MIT

package/dist/catalog.js

@@ -0,0 +1,327 @@
+import { z } from "zod";
+export const DEFAULT_SITE_URL = "https://hyperblur.vercel.app";
+export const SITE_URL_ENV = "HYPERBLUR_SITE_URL";
+export const INDEX_TTL_MS = 5 * 60 * 1000;
+export const FETCH_TIMEOUT_MS = 15_000;
+export const CATEGORIES = ["text", "motion", "overlay", "hover"];
+const propSchema = z.object({
+    name: z.string(),
+    type: z.string(),
+    default: z.string().optional(),
+    required: z.boolean().optional(),
+    description: z.string().default(""),
+});
+const effectSchema = z.object({
+    slug: z.string().min(1),
+    component: z.string().min(1),
+    title: z.string(),
+    description: z.string().default(""),
+    category: z.string(),
+    tags: z.array(z.string()).default([]),
+    props: z.array(propSchema).default([]),
+    usage: z.string().default(""),
+    dependencies: z.array(z.string()).default([]),
+    install: z.string().optional(),
+    docs: z.string().optional(),
+    file: z.string().optional(),
+});
+const indexSchema = z.object({
+    name: z.string().default("hyperblur"),
+    homepage: z.string().optional(),
+    generatedAt: z.string().optional(),
+    items: z.array(effectSchema),
+});
+const registryFileSchema = z.object({
+    path: z.string(),
+    type: z.string().optional(),
+    target: z.string().optional(),
+    content: z.string(),
+});
+const registryItemSchema = z.object({
+    name: z.string(),
+    dependencies: z.array(z.string()).default([]),
+    devDependencies: z.array(z.string()).default([]),
+    registryDependencies: z.array(z.string()).default([]),
+    files: z.array(registryFileSchema).min(1),
+});
+export class CatalogError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = "CatalogError";
+    }
+}
+export class UnknownEffectError extends CatalogError {
+    slug;
+    validSlugs;
+    constructor(slug, validSlugs) {
+        const suggestions = suggestSlugs(slug, validSlugs);
+        const hint = suggestions.length > 0 ? ` Did you mean ${suggestions.map((s) => `"${s}"`).join(" or ")}?` : "";
+        super(`Unknown effect "${slug}".${hint} Valid slugs: ${validSlugs.join(", ")}.`);
+        this.name = "UnknownEffectError";
+        this.slug = slug;
+        this.validSlugs = validSlugs;
+    }
+}
+export function resolveSiteUrl(env = process.env) {
+    const raw = env[SITE_URL_ENV]?.trim() || DEFAULT_SITE_URL;
+    let parsed;
+    try {
+        parsed = new URL(raw);
+    }
+    catch {
+        throw new CatalogError(`${SITE_URL_ENV} must be an absolute http(s) URL such as http://localhost:3000, got "${raw}".`);
+    }
+    if (parsed.protocol !== "http:" && parsed.protocol !== "https:") {
+        throw new CatalogError(`${SITE_URL_ENV} must use http or https, got "${raw}".`);
+    }
+    return raw.replace(/\/+$/, "");
+}
+export function importLine(effect) {
+    return `import { ${effect.component} } from "@/components/hyperblur/${effect.slug}";`;
+}
+export class Catalog {
+    siteUrl;
+    indexUrl;
+    fetchImpl;
+    ttlMs;
+    timeoutMs;
+    now;
+    cached;
+    pending;
+    sources = new Map();
+    constructor(options = {}) {
+        this.siteUrl = (options.siteUrl ?? DEFAULT_SITE_URL).replace(/\/+$/, "");
+        this.indexUrl = `${this.siteUrl}/r/index.json`;
+        this.fetchImpl = options.fetch ?? globalThis.fetch;
+        this.ttlMs = options.ttlMs ?? INDEX_TTL_MS;
+        this.timeoutMs = options.timeoutMs ?? FETCH_TIMEOUT_MS;
+        this.now = options.now ?? Date.now;
+    }
+    itemUrl(slug) {
+        return `${this.siteUrl}/r/${slug}.json`;
+    }
+    installCommand(slug) {
+        return `npx shadcn@latest add ${this.itemUrl(slug)}`;
+    }
+    async getIndex() {
+        if (this.cached && this.now() - this.cached.fetchedAt < this.ttlMs) {
+            return this.cached.index;
+        }
+        if (!this.pending) {
+            this.pending = this.loadIndex()
+                .then((index) => {
+                this.cached = { index, fetchedAt: this.now() };
+                return index;
+            })
+                .finally(() => {
+                this.pending = undefined;
+            });
+        }
+        try {
+            return await this.pending;
+        }
+        catch (error) {
+            if (this.cached) {
+                return this.cached.index;
+            }
+            throw error;
+        }
+    }
+    async listSlugs() {
+        const index = await this.getIndex();
+        return index.items.map((item) => item.slug);
+    }
+    async search(options = {}) {
+        const index = await this.getIndex();
+        const limit = Math.max(1, Math.floor(options.limit ?? 10));
+        const pool = options.category ? index.items.filter((item) => item.category === options.category) : index.items;
+        const tokens = tokenize(options.query ?? "");
+        if (tokens.length === 0) {
+            return { total: pool.length, results: pool.slice(0, limit) };
+        }
+        const phrase = tokens.join(" ");
+        const ranked = pool
+            .map((effect, position) => ({ effect, position, rank: rankEffect(effect, tokens, phrase) }))
+            .filter((entry) => entry.rank !== undefined)
+            .sort((a, b) => b.rank.tier - a.rank.tier || b.rank.score - a.rank.score || a.position - b.position);
+        return { total: ranked.length, results: ranked.slice(0, limit).map((entry) => entry.effect) };
+    }
+    async getEffect(slug) {
+        const index = await this.getIndex();
+        const wanted = normalizeSlug(slug);
+        const effect = index.items.find((item) => item.slug === wanted);
+        if (!effect) {
+            throw new UnknownEffectError(slug, index.items.map((item) => item.slug));
+        }
+        return effect;
+    }
+    async getSource(slug) {
+        const effect = await this.getEffect(slug);
+        const cached = this.sources.get(effect.slug);
+        if (cached && this.now() - cached.fetchedAt < this.ttlMs) {
+            return cached.source;
+        }
+        const raw = await this.fetchJson(effect.file, `the registry item for "${effect.slug}"`);
+        const parsed = registryItemSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new CatalogError(`The registry item at ${effect.file} is not a valid shadcn registry item: ${z.prettifyError(parsed.error)}`);
+        }
+        const source = {
+            effect,
+            files: parsed.data.files.map((file) => ({
+                path: file.path,
+                target: file.target ?? `components/hyperblur/${baseName(file.path)}`,
+                content: file.content,
+            })),
+            dependencies: parsed.data.dependencies,
+            devDependencies: parsed.data.devDependencies,
+            registryDependencies: parsed.data.registryDependencies,
+        };
+        this.sources.set(effect.slug, { source, fetchedAt: this.now() });
+        return source;
+    }
+    async loadIndex() {
+        const raw = await this.fetchJson(this.indexUrl, "the catalog index");
+        const parsed = indexSchema.safeParse(raw);
+        if (!parsed.success) {
+            throw new CatalogError(`The catalog index at ${this.indexUrl} has an unexpected shape: ${z.prettifyError(parsed.error)}`);
+        }
+        const homepage = (parsed.data.homepage ?? DEFAULT_SITE_URL).replace(/\/+$/, "");
+        return {
+            name: parsed.data.name,
+            homepage: this.siteUrl,
+            ...(parsed.data.generatedAt ? { generatedAt: parsed.data.generatedAt } : {}),
+            items: parsed.data.items.map((item) => ({
+                slug: item.slug,
+                component: item.component,
+                title: item.title,
+                description: item.description,
+                category: item.category,
+                tags: item.tags,
+                props: item.props,
+                usage: item.usage,
+                dependencies: item.dependencies,
+                install: this.installCommand(item.slug),
+                docs: item.docs ? this.rebase(item.docs, homepage) : `${this.siteUrl}/effects/${item.slug}`,
+                file: this.itemUrl(item.slug),
+            })),
+        };
+    }
+    rebase(url, homepage) {
+        return url.startsWith(`${homepage}/`) ? `${this.siteUrl}${url.slice(homepage.length)}` : url;
+    }
+    async fetchJson(url, what) {
+        let response;
+        try {
+            response = await this.fetchImpl(url, {
+                headers: { accept: "application/json" },
+                signal: AbortSignal.timeout(this.timeoutMs),
+            });
+        }
+        catch (error) {
+            throw new CatalogError(`Could not reach the Hyperblur site at ${this.siteUrl} while loading ${what} (${describeFetchError(error, this.timeoutMs)}). ` +
+                `Check that the site is online and reachable from this machine, or set ${SITE_URL_ENV} to a reachable Hyperblur instance.`);
+        }
+        if (!response.ok) {
+            const status = `${response.status} ${response.statusText}`.trim();
+            throw new CatalogError(`Failed to load ${what}: ${url} responded with HTTP ${status}.`);
+        }
+        try {
+            return await response.json();
+        }
+        catch {
+            throw new CatalogError(`Failed to load ${what}: ${url} did not return valid JSON.`);
+        }
+    }
+}
+function rankEffect(effect, tokens, phrase) {
+    const slug = effect.slug.toLowerCase();
+    const title = effect.title.toLowerCase();
+    const description = effect.description.toLowerCase();
+    const tags = effect.tags.map((tag) => tag.toLowerCase());
+    let tier = 0;
+    let score = 0;
+    for (const token of tokens) {
+        const inName = slug.includes(token) || title.includes(token);
+        const exactTag = tags.includes(token);
+        const partialTag = !exactTag && tags.some((tag) => tag.includes(token));
+        const inDescription = description.includes(token);
+        if (!inName && !exactTag && !partialTag && !inDescription) {
+            return undefined;
+        }
+        if (inName) {
+            tier = 1;
+            score += 10;
+        }
+        if (exactTag)
+            score += 5;
+        if (partialTag)
+            score += 3;
+        if (inDescription)
+            score += 1;
+    }
+    if (slug === phrase.replace(/ /g, "-") || title === phrase) {
+        score += 100;
+    }
+    else if (slug.includes(phrase.replace(/ /g, "-")) || title.includes(phrase)) {
+        score += 20;
+    }
+    return { tier, score };
+}
+function tokenize(query) {
+    return query
+        .toLowerCase()
+        .split(/[\s,]+/)
+        .map((token) => token.trim())
+        .filter((token) => token.length > 0);
+}
+function normalizeSlug(slug) {
+    return slug.trim().toLowerCase().replace(/\.json$/, "").replace(/\s+/g, "-");
+}
+function baseName(filePath) {
+    return filePath.split("/").pop() ?? filePath;
+}
+function suggestSlugs(input, validSlugs) {
+    const wanted = normalizeSlug(input);
+    if (wanted.length === 0)
+        return [];
+    const parts = wanted.split("-").filter((part) => part.length > 2);
+    const close = (a, b) => editDistance(a, b) <= Math.max(1, Math.floor(Math.min(a.length, b.length) / 4));
+    return validSlugs
+        .filter((slug) => slug.includes(wanted) ||
+        wanted.includes(slug) ||
+        parts.some((part) => slug.includes(part)) ||
+        close(wanted, slug) ||
+        slug.split("-").some((piece) => piece.length > 2 && close(wanted, piece)))
+        .slice(0, 3);
+}
+function editDistance(a, b) {
+    let previous = Array.from({ length: b.length + 1 }, (_, index) => index);
+    for (let i = 1; i <= a.length; i += 1) {
+        const current = [i];
+        for (let j = 1; j <= b.length; j += 1) {
+            const cost = a[i - 1] === b[j - 1] ? 0 : 1;
+            current[j] = Math.min((previous[j] ?? 0) + 1, (current[j - 1] ?? 0) + 1, (previous[j - 1] ?? 0) + cost);
+        }
+        previous = current;
+    }
+    return previous[b.length] ?? 0;
+}
+function describeFetchError(error, timeoutMs) {
+    if (error instanceof Error) {
+        if (error.name === "TimeoutError" || error.name === "AbortError") {
+            return `timed out after ${Math.round(timeoutMs / 1000)}s`;
+        }
+        const cause = error.cause;
+        if (cause && typeof cause === "object") {
+            const code = cause.code;
+            const message = cause.message;
+            if (typeof code === "string")
+                return code;
+            if (typeof message === "string" && message.length > 0)
+                return message;
+        }
+        return error.message;
+    }
+    return String(error);
+}

package/dist/cli.js

@@ -0,0 +1,19 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { Catalog, resolveSiteUrl } from "./catalog.js";
+import { createServer } from "./server.js";
+async function main() {
+    const catalog = new Catalog({ siteUrl: resolveSiteUrl() });
+    const server = createServer({ catalog });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    const shutdown = () => {
+        server.close().finally(() => process.exit(0));
+    };
+    process.on("SIGINT", shutdown);
+    process.on("SIGTERM", shutdown);
+}
+main().catch((error) => {
+    console.error(`hyperblur-mcp failed to start: ${error instanceof Error ? error.message : String(error)}`);
+    process.exit(1);
+});

package/dist/install.js

@@ -0,0 +1,80 @@
+import { spawn } from "node:child_process";
+import { stat } from "node:fs/promises";
+import path from "node:path";
+export const INSTALL_TIMEOUT_MS = 3 * 60 * 1000;
+const OUTPUT_LIMIT = 30_000;
+const KILL_GRACE_MS = 5_000;
+export function shadcnArgs(itemUrl, overwrite) {
+    return ["shadcn@latest", "add", itemUrl, "--yes", ...(overwrite ? ["--overwrite"] : [])];
+}
+export function npxInvocation(args) {
+    if (process.platform === "win32") {
+        const npxCli = path.join(path.dirname(process.execPath), "node_modules", "npm", "bin", "npx-cli.js");
+        return { command: process.execPath, args: [npxCli, ...args] };
+    }
+    return { command: "npx", args };
+}
+export async function validateProjectDir(projectDir) {
+    if (!path.isAbsolute(projectDir)) {
+        return `projectDir must be an absolute path, got "${projectDir}". Pass the full path to the root of the React project (the folder that contains package.json).`;
+    }
+    const dirStat = await stat(projectDir).catch(() => undefined);
+    if (!dirStat) {
+        return `projectDir "${projectDir}" does not exist. Pass the full path to the root of an existing React project.`;
+    }
+    if (!dirStat.isDirectory()) {
+        return `projectDir "${projectDir}" is a file, not a directory. Pass the project root folder that contains package.json.`;
+    }
+    const manifest = await stat(path.join(projectDir, "package.json")).catch(() => undefined);
+    if (!manifest?.isFile()) {
+        return `No package.json found in "${projectDir}". Point projectDir at the root of the React project, or create the project first.`;
+    }
+    return undefined;
+}
+export async function findInstalledFile(projectDir, target) {
+    const candidates = [path.join(projectDir, target), path.join(projectDir, "src", target)];
+    for (const candidate of candidates) {
+        const found = await stat(candidate).catch(() => undefined);
+        if (found?.isFile())
+            return candidate;
+    }
+    return undefined;
+}
+export const runCommand = (command, args, options) => new Promise((resolve) => {
+    let output = "";
+    let timedOut = false;
+    let settled = false;
+    let killTimer;
+    const append = (chunk) => {
+        output += chunk.toString("utf8");
+        if (output.length > OUTPUT_LIMIT * 2) {
+            output = output.slice(-OUTPUT_LIMIT);
+        }
+    };
+    const child = spawn(command, args, {
+        cwd: options.cwd,
+        shell: false,
+        stdio: ["ignore", "pipe", "pipe"],
+        env: { ...process.env, npm_config_yes: "true" },
+        windowsHide: true,
+    });
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        clearTimeout(timer);
+        if (killTimer)
+            clearTimeout(killTimer);
+        const trimmed = output.length > OUTPUT_LIMIT ? `[output truncated]\n${output.slice(-OUTPUT_LIMIT)}` : output;
+        resolve({ ...result, timedOut, output: trimmed });
+    };
+    const timer = setTimeout(() => {
+        timedOut = true;
+        child.kill("SIGTERM");
+        killTimer = setTimeout(() => child.kill("SIGKILL"), KILL_GRACE_MS);
+    }, options.timeoutMs);
+    child.stdout.on("data", append);
+    child.stderr.on("data", append);
+    child.on("error", (error) => finish({ exitCode: null, signal: null, spawnError: error.message }));
+    child.on("close", (exitCode, signal) => finish({ exitCode, signal }));
+});

package/dist/server.js

@@ -0,0 +1,258 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { completable } from "@modelcontextprotocol/sdk/server/completable.js";
+import { z } from "zod";
+import { CATEGORIES, Catalog, importLine } from "./catalog.js";
+import { INSTALL_TIMEOUT_MS, findInstalledFile, npxInvocation, runCommand, shadcnArgs, validateProjectDir, } from "./install.js";
+export const SERVER_NAME = "hyperblur";
+export const SERVER_VERSION = "0.1.0";
+const CATEGORY_GUIDE = "text = animated typography (glitch, neon, decode, wave, motion blur); motion = reveals and movement (pixel and shutter reveals, speed lines); overlay = full-surface layers drawn over content (scanlines, film grain, VHS, grid floor); hover = pointer interactions that wrap an element (tilt, magnetic, chromatic split).";
+const SEARCH_DESCRIPTION = `Search the Hyperblur catalog of copy-paste React visual effects (glitch and neon text, motion blur, scanlines, film grain, VHS, 3D tilt, magnetic hover, pixel and shutter reveals, and more).
+
+Use this first whenever the user asks for a visual effect, animation, text treatment, retro/cyberpunk look, or hover interaction in a React or Next.js project and you do not already know the exact effect slug. Leave "query" empty to browse the whole catalog, optionally narrowed by "category".
+
+Matching is case-insensitive against slug, title, description and tags; every word of the query must match somewhere, and effects whose title or slug match rank first.
+
+Returns a compact markdown list: slug, title, category, one-line description and the shadcn install command for each match, plus how many matched in total. Next step: call get_effect with a slug to get props, usage and the import line.`;
+const GET_DESCRIPTION = `Get the full reference for one Hyperblur effect by slug: title, description, category, tags, a props table (name, type, default or required, description), a JSX usage example, the exact import line, npm dependencies, the shadcn install command and the docs URL.
+
+Use this after search_effects (or when the user names an effect) and before writing code that renders the component, so the props you pass are real. It does not return the component source; use get_effect_source for that, or install_effect to add the file to a project.
+
+An unknown slug returns an error that lists every valid slug.`;
+const SOURCE_DESCRIPTION = `Get the complete TypeScript/React source of a Hyperblur effect, exactly as the shadcn registry ships it, along with the target path where the file belongs (for example components/hyperblur/glitch-text.tsx) and any npm dependencies it needs.
+
+Use this when you need to write the component file yourself: the project does not use shadcn, has no components.json, running npx is not possible, or install_effect failed. Write the content to the target path (under src/ if the project keeps components there) and install any listed dependencies. Prefer install_effect when shadcn is available.`;
+const INSTALL_DESCRIPTION = `Install a Hyperblur effect into a local React project by running "npx shadcn@latest add <registry-url> --yes" in projectDir. This writes the component file into the project (normally components/hyperblur/<slug>.tsx, or under src/ depending on components.json) and installs its npm dependencies.
+
+Use this when the user wants the effect added to a project on this machine and the project uses shadcn (has a components.json, or can be initialized by shadcn). projectDir must be the absolute path of the project root containing package.json; nothing runs if it does not. Existing files are kept unless overwrite is true. The command can take up to 3 minutes.
+
+Returns the exit status, the combined shadcn output, and the path of the installed file. If it fails, read the output, or fall back to get_effect_source and write the file by hand.`;
+export function createServer(options) {
+    const { catalog } = options;
+    const runner = options.runner ?? runCommand;
+    const installTimeoutMs = options.installTimeoutMs ?? INSTALL_TIMEOUT_MS;
+    const server = new McpServer({ name: SERVER_NAME, version: SERVER_VERSION, title: "Hyperblur" }, {
+        instructions: "Hyperblur is a catalog of copy-paste React visual effects distributed through the shadcn registry. Find effects with search_effects, read props and usage with get_effect, then add them with install_effect (runs shadcn) or get_effect_source (write the file yourself). Components are imported from @/components/hyperblur/<slug>.",
+    });
+    server.registerTool("search_effects", {
+        title: "Search Hyperblur effects",
+        description: SEARCH_DESCRIPTION,
+        inputSchema: {
+            query: z
+                .string()
+                .max(200)
+                .optional()
+                .describe('Words to look for, e.g. "glitch", "retro crt", "hover tilt", "text reveal". Omit to list everything.'),
+            category: z.enum(CATEGORIES).optional().describe(`Restrict results to one category. ${CATEGORY_GUIDE}`),
+            limit: z.number().int().min(1).max(50).default(10).describe("Maximum number of effects to return (1-50, default 10)."),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ query, category, limit }) => guard(async () => {
+        const { total, results } = await catalog.search({
+            ...(query !== undefined ? { query } : {}),
+            ...(category !== undefined ? { category } : {}),
+            limit,
+        });
+        return text(formatSearch(results, total, query, category));
+    }));
+    server.registerTool("get_effect", {
+        title: "Get Hyperblur effect details",
+        description: GET_DESCRIPTION,
+        inputSchema: {
+            slug: z.string().min(1).describe('Effect slug from search_effects, e.g. "glitch-text" or "tilt-card".'),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ slug }) => guard(async () => text(formatEffect(await catalog.getEffect(slug)))));
+    server.registerTool("get_effect_source", {
+        title: "Get Hyperblur effect source",
+        description: SOURCE_DESCRIPTION,
+        inputSchema: {
+            slug: z.string().min(1).describe('Effect slug from search_effects, e.g. "glitch-text".'),
+        },
+        annotations: { readOnlyHint: true, destructiveHint: false, idempotentHint: true, openWorldHint: true },
+    }, async ({ slug }) => guard(async () => text(formatSource(await catalog.getSource(slug)))));
+    server.registerTool("install_effect", {
+        title: "Install Hyperblur effect",
+        description: INSTALL_DESCRIPTION,
+        inputSchema: {
+            slug: z.string().min(1).describe('Effect slug from search_effects, e.g. "glitch-text".'),
+            projectDir: z
+                .string()
+                .min(1)
+                .describe('Absolute path to the React project root that contains package.json, e.g. "/Users/me/code/my-app".'),
+            overwrite: z
+                .boolean()
+                .default(false)
+                .describe("Replace the component file if it already exists. Default false keeps existing files."),
+        },
+        annotations: { readOnlyHint: false, destructiveHint: true, idempotentHint: true, openWorldHint: true },
+    }, async ({ slug, projectDir, overwrite }) => guard(async () => {
+        const problem = await validateProjectDir(projectDir);
+        if (problem)
+            return error(problem);
+        const effect = await catalog.getEffect(slug);
+        const args = shadcnArgs(effect.file, overwrite);
+        const invocation = npxInvocation(args);
+        const result = await runner(invocation.command, invocation.args, { cwd: projectDir, timeoutMs: installTimeoutMs });
+        const target = (await catalog
+            .getSource(effect.slug)
+            .then((source) => source.files[0]?.target)
+            .catch(() => undefined)) ?? `components/hyperblur/${effect.slug}.tsx`;
+        const installed = await findInstalledFile(projectDir, target);
+        const commandLine = `npx ${args.join(" ")}`;
+        const lines = [];
+        const succeeded = result.exitCode === 0 && !result.timedOut && !result.spawnError;
+        if (succeeded) {
+            lines.push(`Installed **${effect.title}** (\`${effect.slug}\`) into ${projectDir}.`);
+        }
+        else if (result.spawnError) {
+            lines.push(`Could not start npx: ${result.spawnError}. Make sure Node.js and npm are installed and on PATH, or use get_effect_source to write the file by hand.`);
+        }
+        else if (result.timedOut) {
+            lines.push(`The shadcn command did not finish within ${Math.round(installTimeoutMs / 1000)} seconds and was stopped.`);
+        }
+        else {
+            lines.push(`The shadcn command failed (exit code ${result.exitCode ?? `signal ${result.signal ?? "unknown"}`}). Check the output below; use get_effect_source to write the file by hand if shadcn is not set up in this project.`);
+        }
+        lines.push("", `- Command: \`${commandLine}\``, `- Working directory: \`${projectDir}\``);
+        if (installed) {
+            lines.push(`- Installed file: \`${installed}\``);
+        }
+        else if (succeeded) {
+            lines.push(`- Installed file: expected at \`${target}\` relative to your components alias (see components.json)`);
+        }
+        if (succeeded) {
+            lines.push(`- Import: \`${importLine(effect)}\``);
+            if (effect.usage)
+                lines.push(`- Usage: \`${effect.usage}\``);
+        }
+        lines.push("", "Output:", "```", result.output.trim() || "(no output)", "```");
+        return succeeded ? text(lines.join("\n")) : error(lines.join("\n"));
+    }));
+    server.registerResource("catalog", "hyperblur://catalog", {
+        title: "Hyperblur catalog",
+        description: "The full Hyperblur catalog index as JSON: every effect with its props, usage, install command and docs URL.",
+        mimeType: "application/json",
+    }, async (uri) => ({
+        contents: [{ uri: uri.href, mimeType: "application/json", text: JSON.stringify(await catalog.getIndex(), null, 2) }],
+    }));
+    server.registerPrompt("add_effect", {
+        title: "Add a Hyperblur effect",
+        description: "Add a Hyperblur effect to the current project: look it up, then install it or write its source.",
+        argsSchema: {
+            slug: completable(z.string().describe('Effect slug, e.g. "glitch-text".'), async (value) => {
+                const slugs = await catalog.listSlugs().catch(() => []);
+                const prefix = (value ?? "").toLowerCase();
+                return slugs.filter((slug) => slug.startsWith(prefix));
+            }),
+        },
+    }, ({ slug }) => ({
+        messages: [
+            {
+                role: "user",
+                content: {
+                    type: "text",
+                    text: [
+                        `Add the Hyperblur effect "${slug}" to this project.`,
+                        "",
+                        `1. Call get_effect with slug "${slug}" to read its props, usage and import line.`,
+                        "2. If the project uses shadcn (it has a components.json), call install_effect with the absolute path of the project root as projectDir.",
+                        "3. Otherwise, or if the install fails, call get_effect_source and write the file to its target path yourself, then install any listed dependencies.",
+                        "4. Render the component where it fits, using only the props listed by get_effect.",
+                    ].join("\n"),
+                },
+            },
+        ],
+    }));
+    return server;
+}
+export function formatSearch(results, total, query, category) {
+    const scope = [query ? `"${query}"` : undefined, category ? `category ${category}` : undefined].filter(Boolean).join(", ");
+    if (results.length === 0) {
+        return `No Hyperblur effects match ${scope || "your search"}. Try a broader word (for example "text", "blur", "retro", "hover"), drop the category filter, or call search_effects with no query to list everything.`;
+    }
+    const heading = results.length === total
+        ? `Found ${total} Hyperblur effect${total === 1 ? "" : "s"}${scope ? ` for ${scope}` : ""}:`
+        : `Showing ${results.length} of ${total} Hyperblur effects${scope ? ` for ${scope}` : ""} (raise limit to see more):`;
+    const items = results.map((effect) => `- **${effect.title}** \`${effect.slug}\` (${effect.category}): ${effect.description}\n  Install: \`${effect.install}\``);
+    return [heading, "", ...items, "", "Call get_effect with a slug for props, usage and the import line."].join("\n");
+}
+export function formatEffect(effect) {
+    const lines = [
+        `# ${effect.title} (\`${effect.slug}\`)`,
+        "",
+        effect.description,
+        "",
+        `- Category: ${effect.category}`,
+        `- Tags: ${effect.tags.length > 0 ? effect.tags.join(", ") : "none"}`,
+        `- Component: \`${effect.component}\``,
+        `- Import: \`${importLine(effect)}\``,
+        `- Install: \`${effect.install}\``,
+        `- npm dependencies: ${effect.dependencies.length > 0 ? effect.dependencies.join(", ") : "none"}`,
+        `- Docs: ${effect.docs}`,
+        "",
+        "## Props",
+        "",
+    ];
+    if (effect.props.length === 0) {
+        lines.push("This component takes no props of its own.");
+    }
+    else {
+        lines.push("| Prop | Type | Default | Description |", "| --- | --- | --- | --- |");
+        for (const prop of effect.props) {
+            lines.push(`| \`${prop.name}\` | \`${cell(prop.type)}\` | ${defaultCell(prop)} | ${cell(prop.description)} |`);
+        }
+    }
+    if (effect.usage) {
+        lines.push("", "## Usage", "", "```tsx", importLine(effect), "", effect.usage, "```");
+    }
+    lines.push("", "Next: install_effect adds the file with shadcn; get_effect_source returns the source to write by hand.");
+    return lines.join("\n");
+}
+export function formatSource(source) {
+    const { effect } = source;
+    const lines = [
+        `# Source for ${effect.title} (\`${effect.slug}\`)`,
+        "",
+        `- Import after writing the file: \`${importLine(effect)}\``,
+        `- npm dependencies: ${source.dependencies.length > 0 ? `${source.dependencies.join(", ")} (install them with the project's package manager)` : "none"}`,
+    ];
+    if (source.devDependencies.length > 0) {
+        lines.push(`- npm dev dependencies: ${source.devDependencies.join(", ")}`);
+    }
+    if (source.registryDependencies.length > 0) {
+        lines.push(`- shadcn registry dependencies: ${source.registryDependencies.join(", ")}`);
+    }
+    lines.push("- Place the file at the target path below, relative to the project root (use src/ as a prefix if the project keeps components under src/).");
+    for (const file of source.files) {
+        lines.push("", `## ${file.target}`, "", `\`\`\`${fence(file.target)}`, file.content.trimEnd(), "```");
+    }
+    return lines.join("\n");
+}
+function defaultCell(prop) {
+    if (prop.required)
+        return "required";
+    if (prop.default !== undefined)
+        return `\`${cell(prop.default)}\``;
+    return "optional";
+}
+function cell(value) {
+    return value.replace(/\|/g, "\\|").replace(/\n/g, " ");
+}
+function fence(target) {
+    const extension = target.split(".").pop() ?? "";
+    return ["tsx", "ts", "jsx", "js", "css", "json"].includes(extension) ? extension : "";
+}
+function text(value) {
+    return { content: [{ type: "text", text: value }] };
+}
+function error(value) {
+    return { content: [{ type: "text", text: value }], isError: true };
+}
+async function guard(run) {
+    try {
+        return await run();
+    }
+    catch (caught) {
+        return error(caught instanceof Error ? caught.message : String(caught));
+    }
+}

package/package.json

@@ -1,6 +1,53 @@
 {
   "name": "@hyperblur/mcp",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "MCP server for Hyperblur: search, inspect and install copy-paste React visual effects from any MCP client.",
+  "license": "MIT",
+  "type": "module",
+  "homepage": "https://hyperblur.dev",
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "hyperblur",
+    "react",
+    "shadcn",
+    "effects"
+  ],
+  "bin": {
+    "hyperblur-mcp": "dist/cli.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "clean": "node -e \"process.getBuiltinModule('fs').rmSync('dist', { recursive: true, force: true })\"",
+    "build": "npm run clean && tsc -p tsconfig.json && node -e \"process.getBuiltinModule('fs').chmodSync('dist/cli.js', 0o755)\"",
+    "dev": "node --watch src/cli.ts",
+    "typecheck": "tsc -p tsconfig.test.json",
+    "test": "npm run typecheck && node --test \"test/**/*.test.ts\"",
+    "start": "node dist/cli.js",
+    "prepublishOnly": "npm run build && npm test"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.32.2",
+    "zod": "^4.6.7"
+  },
+  "devDependencies": {
+    "@types/node": "^26.6.6",
+    "typescript": "^7.0.2"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Hyperblur/Hyperblur.git",
+    "directory": "packages/mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/Hyperblur/Hyperblur/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}