nyxui-mcp 1.0.0

package/mcp-server.mjs

@@ -0,0 +1,686 @@
+#!/usr/bin/env node
+
+import { fileURLToPath, pathToFileURL } from "node:url";
+import {
+  McpServer,
+  ResourceTemplate,
+} from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+const __filename = fileURLToPath(import.meta.url);
+const siteUrl = "https://nyxui.com";
+
+const docSections = ["components", "templates", "blocks", "root"];
+const registryTypes = [
+  "registry:style",
+  "registry:ui",
+  "registry:example",
+  "registry:lib",
+];
+const registryKinds = ["component", "example", "style", "utility"];
+
+let docsCache;
+let registryCache;
+const publicRegistryCache = new Map();
+
+// ── fetchers ───────────────────────────────────────────────────
+
+async function getRegistry() {
+  if (registryCache) return registryCache;
+  const res = await fetch(`${siteUrl}/registry.json`);
+  if (!res.ok) throw new Error(`Failed to fetch registry: ${res.status}`);
+  registryCache = await res.json();
+  return registryCache;
+}
+
+async function getPublicRegistryItem(name) {
+  if (publicRegistryCache.has(name)) return publicRegistryCache.get(name);
+  try {
+    const res = await fetch(`${siteUrl}/r/${name}.json`);
+    if (!res.ok) {
+      publicRegistryCache.set(name, null);
+      return null;
+    }
+    const parsed = await res.json();
+    publicRegistryCache.set(name, parsed);
+    return parsed;
+  } catch {
+    publicRegistryCache.set(name, null);
+    return null;
+  }
+}
+
+async function getDocs() {
+  if (docsCache) return docsCache;
+  const res = await fetch(`${siteUrl}/api/docs`);
+  if (!res.ok) throw new Error(`Failed to fetch docs: ${res.status}`);
+  const raw = await res.json();
+
+  // parse frontmatter from each doc
+  docsCache = raw.map(({ slug, content }) => {
+    const parsed = parseFrontmatter(content);
+    const section = getDocSection(slug);
+    return {
+      slug,
+      section,
+      title: typeof parsed.data.title === "string" ? parsed.data.title : slug,
+      description:
+        typeof parsed.data.description === "string"
+          ? parsed.data.description
+          : "",
+      tags: Array.isArray(parsed.data.tags) ? parsed.data.tags : [],
+      published: parsed.data.published !== false,
+      frontmatter: parsed.data,
+      body: parsed.body,
+      content,
+    };
+  });
+
+  docsCache.sort((a, b) => a.slug.localeCompare(b.slug));
+  return docsCache;
+}
+
+// ── frontmatter parser ─────────────────────────────────────────
+
+function cleanValue(value) {
+  const trimmed = value.trim();
+  if (
+    (trimmed.startsWith('"') && trimmed.endsWith('"')) ||
+    (trimmed.startsWith("'") && trimmed.endsWith("'"))
+  ) {
+    return trimmed.slice(1, -1);
+  }
+  if (trimmed === "true") return true;
+  if (trimmed === "false") return false;
+  if (/^\d+(\.\d+)?$/.test(trimmed)) return Number(trimmed);
+  return trimmed;
+}
+
+function parseArray(value) {
+  const inner = value.trim().replace(/^\[/, "").replace(/\]$/, "");
+  if (!inner) return [];
+  return inner
+    .split(",")
+    .map((item) => cleanValue(item))
+    .filter(Boolean);
+}
+
+function parseFrontmatter(raw) {
+  const match = raw.match(/^---\r?\n([\s\S]*?)\r?\n---\r?\n?/);
+  if (!match) return { data: {}, body: raw };
+
+  const block = match[1];
+  const data = {};
+
+  for (const line of block.split(/\r?\n/)) {
+    const keyValue = line.match(/^([A-Za-z0-9_-]+):\s*(.*)$/);
+    if (!keyValue) continue;
+    const [, key, value] = keyValue;
+    if (value.trim().startsWith("[") && value.trim().endsWith("]")) {
+      data[key] = parseArray(value);
+    } else {
+      data[key] = cleanValue(value);
+    }
+  }
+
+  return { data, body: raw.slice(match[0].length) };
+}
+
+// ── helpers ────────────────────────────────────────────────────
+
+function normalizeText(value) {
+  return value
+    .toLowerCase()
+    .replace(/[^a-z0-9]+/g, " ")
+    .trim();
+}
+
+function tokenize(value) {
+  return new Set(
+    normalizeText(value)
+      .split(/\s+/)
+      .filter((t) => t.length > 2),
+  );
+}
+
+function escapeRegExp(value) {
+  return value.replace(/[.*+?^${}()|[\]\\]/g, "\\$&");
+}
+
+function getDocSection(slug) {
+  const section = slug.split("/")[0];
+  return docSections.includes(section) ? section : "root";
+}
+
+function getDocUrl(doc) {
+  if (doc.section === "components")
+    return `${siteUrl}/components/${doc.slug.replace(/^components\//, "")}`;
+  if (doc.section === "templates")
+    return `${siteUrl}/templates/${doc.slug.replace(/^templates\//, "")}`;
+  if (doc.section === "blocks")
+    return `${siteUrl}/blocks/${doc.slug.replace(/^blocks\//, "")}`;
+  if (doc.slug === "index") return `${siteUrl}/docs`;
+  return `${siteUrl}/docs/${doc.slug}`;
+}
+
+function buildSnippet(body, query) {
+  const normalizedBody = body.replace(/\s+/g, " ").trim();
+  const normalizedQuery = query.toLowerCase();
+  const index = normalizedBody.toLowerCase().indexOf(normalizedQuery);
+  if (index === -1) return normalizedBody.slice(0, 220);
+  const start = Math.max(0, index - 80);
+  const end = Math.min(normalizedBody.length, index + query.length + 140);
+  return normalizedBody.slice(start, end);
+}
+
+function scoreDoc(doc, query) {
+  const haystack =
+    `${doc.title}\n${doc.description}\n${doc.body}`.toLowerCase();
+  const normalizedQuery = query.toLowerCase();
+  if (!haystack.includes(normalizedQuery)) return 0;
+  let score = 1;
+  if (doc.title.toLowerCase().includes(normalizedQuery)) score += 5;
+  if (doc.description.toLowerCase().includes(normalizedQuery)) score += 3;
+  const matches = haystack.match(
+    new RegExp(escapeRegExp(normalizedQuery), "g"),
+  );
+  score += Math.min(matches?.length ?? 0, 10);
+  return score;
+}
+
+function getRegistryKind(item) {
+  switch (item.type) {
+    case "registry:ui":
+      return "component";
+    case "registry:example":
+      return "example";
+    case "registry:style":
+      return "style";
+    case "registry:lib":
+      return "utility";
+    default:
+      return item.type;
+  }
+}
+
+function matchesRegistryFilter(item, filter) {
+  if (!filter) return true;
+  if (registryTypes.includes(filter)) return item.type === filter;
+  switch (filter) {
+    case "component":
+      return item.type === "registry:ui";
+    case "example":
+      return item.type === "registry:example";
+    case "style":
+      return item.type === "registry:style";
+    case "utility":
+      return item.type === "registry:lib";
+    default:
+      return false;
+  }
+}
+
+function scoreRegistryItem(item, query) {
+  const kind = getRegistryKind(item);
+  const haystack = [
+    item.name,
+    item.title ?? "",
+    item.description ?? "",
+    item.type,
+    kind,
+  ]
+    .join("\n")
+    .toLowerCase();
+  const normalizedQuery = query.toLowerCase();
+  if (!haystack.includes(normalizedQuery)) return 0;
+  let score = 1;
+  if (item.name.toLowerCase() === normalizedQuery) score += 10;
+  if (item.name.toLowerCase().includes(normalizedQuery)) score += 6;
+  if ((item.title ?? "").toLowerCase().includes(normalizedQuery)) score += 5;
+  if ((item.description ?? "").toLowerCase().includes(normalizedQuery))
+    score += 3;
+  if (kind.includes(normalizedQuery)) score += 2;
+  const matches = haystack.match(
+    new RegExp(escapeRegExp(normalizedQuery), "g"),
+  );
+  score += Math.min(matches?.length ?? 0, 10);
+  return score;
+}
+
+function normalizeRegistryDependency(value) {
+  if (typeof value !== "string") return "";
+  const normalized = value.includes("/r/") ? value.split("/r/").pop() : value;
+  return normalized.replace(/\.json$/, "");
+}
+
+function getInstallUrl(name) {
+  return `${siteUrl}/r/${name}.json`;
+}
+function getInstallCommand(name) {
+  return `npx shadcn@latest add "${getInstallUrl(name)}"`;
+}
+
+function findDocForName(docs, name) {
+  const exactCandidates = [
+    `components/${name}`,
+    `templates/${name}`,
+    `blocks/${name}`,
+    name,
+  ];
+  return (
+    docs.find((doc) => exactCandidates.includes(doc.slug)) ??
+    docs.find((doc) => doc.slug.endsWith(`/${name}`)) ??
+    null
+  );
+}
+
+function getExamplesForItem(registry, name) {
+  return registry.items.filter(
+    (item) =>
+      item.type === "registry:example" &&
+      (item.registryDependencies ?? []).some(
+        (dep) => normalizeRegistryDependency(dep) === name,
+      ),
+  );
+}
+
+function buildRegistryPreview(item, docs, registry) {
+  const doc = findDocForName(docs, item.name);
+  const examples = getExamplesForItem(registry, item.name);
+  return {
+    name: item.name,
+    kind: getRegistryKind(item),
+    type: item.type,
+    title: item.title ?? item.name,
+    description: item.description ?? null,
+    installUrl: getInstallUrl(item.name),
+    installCommand: getInstallCommand(item.name),
+    docsUrl: doc ? getDocUrl(doc) : null,
+    exampleNames: examples.slice(0, 5).map((e) => e.name),
+  };
+}
+
+function getRelatedItems(baseItem, docs, registry, limit = 5) {
+  const baseDoc = findDocForName(docs, baseItem.name);
+  const baseTags = new Set(
+    (baseDoc?.tags ?? []).map((tag) => normalizeText(tag)),
+  );
+  const baseTokens = tokenize(
+    `${baseItem.name} ${baseItem.title ?? ""} ${baseItem.description ?? ""}`,
+  );
+
+  return registry.items
+    .filter((c) => c.name !== baseItem.name && c.type === baseItem.type)
+    .map((candidate) => {
+      const candidateDoc = findDocForName(docs, candidate.name);
+      const candidateTokens = tokenize(
+        `${candidate.name} ${candidate.title ?? ""} ${candidate.description ?? ""}`,
+      );
+      let score = 0;
+      if (baseDoc && candidateDoc && candidateDoc.section === baseDoc.section)
+        score += 2;
+      if (baseDoc && candidateDoc) {
+        const sharedTags = (candidateDoc.tags ?? []).filter((tag) =>
+          baseTags.has(normalizeText(tag)),
+        ).length;
+        score += sharedTags * 3;
+      }
+      for (const token of candidateTokens) {
+        if (baseTokens.has(token)) score += 1;
+      }
+      return { candidate, score };
+    })
+    .filter((e) => e.score > 0)
+    .sort(
+      (a, b) =>
+        b.score - a.score || a.candidate.name.localeCompare(b.candidate.name),
+    )
+    .slice(0, limit)
+    .map(({ candidate }) => buildRegistryPreview(candidate, docs, registry));
+}
+
+async function buildRegistryItemPayload(
+  item,
+  { includeSource = false, includeExamples = true, includeRelated = true } = {},
+) {
+  const docs = await getDocs();
+  const registry = await getRegistry();
+  const doc = findDocForName(docs, item.name);
+  const publicItem = await getPublicRegistryItem(item.name);
+  const mergedItem = publicItem ? { ...item, ...publicItem } : item;
+
+  const files = includeSource
+    ? (mergedItem.files ?? [])
+    : (mergedItem.files ?? []).map(({ content, ...file }) => file);
+
+  return {
+    name: mergedItem.name,
+    kind: getRegistryKind(mergedItem),
+    type: mergedItem.type,
+    title: mergedItem.title ?? mergedItem.name,
+    description: mergedItem.description ?? null,
+    install: {
+      url: getInstallUrl(mergedItem.name),
+      command: getInstallCommand(mergedItem.name),
+    },
+    docs: doc
+      ? {
+          slug: doc.slug,
+          section: doc.section,
+          title: doc.title,
+          description: doc.description,
+          tags: doc.tags,
+          url: getDocUrl(doc),
+        }
+      : null,
+    dependencies: mergedItem.dependencies ?? [],
+    devDependencies: mergedItem.devDependencies ?? [],
+    registryDependencies: mergedItem.registryDependencies ?? [],
+    files,
+    cssVars: mergedItem.cssVars ?? null,
+    css: mergedItem.css ?? null,
+    examples: includeExamples
+      ? getExamplesForItem(registry, mergedItem.name).map((e) =>
+          buildRegistryPreview(e, docs, registry),
+        )
+      : [],
+    relatedItems: includeRelated
+      ? getRelatedItems(mergedItem, docs, registry)
+      : [],
+  };
+}
+
+async function listRegistryItemsResult({ filter, query, limit, offset }) {
+  const docs = await getDocs();
+  const registry = await getRegistry();
+
+  const filteredItems = registry.items
+    .filter((item) => matchesRegistryFilter(item, filter))
+    .map((item) => ({
+      item,
+      score: query ? scoreRegistryItem(item, query) : 1,
+    }))
+    .filter((e) => e.score > 0)
+    .sort((a, b) =>
+      query
+        ? b.score - a.score || a.item.name.localeCompare(b.item.name)
+        : a.item.name.localeCompare(b.item.name),
+    );
+
+  const total = filteredItems.length;
+  const items = filteredItems
+    .slice(offset, offset + limit)
+    .map(({ item }) => buildRegistryPreview(item, docs, registry));
+
+  return { total, limit, offset, items };
+}
+
+// ── result helpers ─────────────────────────────────────────────
+
+function textResult(value) {
+  const text =
+    typeof value === "string" ? value : JSON.stringify(value, null, 2);
+  return { content: [{ type: "text", text }] };
+}
+
+function errorResult(message) {
+  return { isError: true, content: [{ type: "text", text: message }] };
+}
+
+function validateRegistryFilter(filter) {
+  if (!filter) return null;
+  if (registryKinds.includes(filter) || registryTypes.includes(filter))
+    return null;
+  return `Invalid registry filter "${filter}". Use one of ${[...registryKinds, ...registryTypes].join(", ")}.`;
+}
+
+// ── server ─────────────────────────────────────────────────────
+
+export function createServer() {
+  const server = new McpServer({ name: "nyxui-mcp", version: "1.0.0" });
+
+  server.tool(
+    "listRegistryItems",
+    {
+      kind: z.string().optional(),
+      query: z.string().min(1).optional(),
+      limit: z.number().int().min(1).max(50).default(20),
+      offset: z.number().int().min(0).default(0),
+    },
+    async ({ kind, query, limit, offset }) => {
+      const validationError = validateRegistryFilter(kind);
+      if (validationError) return errorResult(validationError);
+      return textResult(
+        await listRegistryItemsResult({ filter: kind, query, limit, offset }),
+      );
+    },
+  );
+
+  server.tool(
+    "searchRegistryItems",
+    {
+      query: z.string().min(1),
+      kind: z.string().optional(),
+      limit: z.number().int().min(1).max(50).default(10),
+      offset: z.number().int().min(0).default(0),
+    },
+    async ({ query, kind, limit, offset }) => {
+      const validationError = validateRegistryFilter(kind);
+      if (validationError) return errorResult(validationError);
+      return textResult(
+        await listRegistryItemsResult({ filter: kind, query, limit, offset }),
+      );
+    },
+  );
+
+  server.tool(
+    "getRegistryItem",
+    {
+      name: z.string().min(1),
+      includeSource: z.boolean().default(false),
+      includeExamples: z.boolean().default(true),
+      includeRelated: z.boolean().default(true),
+    },
+    async ({ name, includeSource, includeExamples, includeRelated }) => {
+      const registry = await getRegistry();
+      const item = registry.items.find((e) => e.name === name);
+      if (!item) return errorResult(`Registry item "${name}" not found.`);
+      return textResult(
+        await buildRegistryItemPayload(item, {
+          includeSource,
+          includeExamples,
+          includeRelated,
+        }),
+      );
+    },
+  );
+
+  server.tool("project_overview", {}, async () => {
+    const docs = await getDocs();
+    const registry = await getRegistry();
+
+    const docsBySection = docs.reduce((acc, doc) => {
+      acc[doc.section] = (acc[doc.section] ?? 0) + 1;
+      return acc;
+    }, {});
+
+    const registryByKind = registry.items.reduce((acc, item) => {
+      const kind = getRegistryKind(item);
+      acc[kind] = (acc[kind] ?? 0) + 1;
+      return acc;
+    }, {});
+
+    return textResult({
+      name: "Nyx UI",
+      siteUrl,
+      docsCount: docs.length,
+      registryItemCount: registry.items.length,
+      docsBySection,
+      registryByKind,
+      primaryTools: [
+        "listRegistryItems",
+        "searchRegistryItems",
+        "getRegistryItem",
+      ],
+    });
+  });
+
+  server.tool(
+    "list_docs",
+    {
+      section: z.enum(["components", "templates", "blocks", "root"]).optional(),
+      includeUnpublished: z.boolean().default(false),
+    },
+    async ({ section, includeUnpublished }) => {
+      const docs = await getDocs();
+      const filteredDocs = docs
+        .filter((doc) => !section || doc.section === section)
+        .filter((doc) => includeUnpublished || doc.published);
+      return textResult(
+        filteredDocs.map((doc) => ({
+          slug: doc.slug,
+          section: doc.section,
+          title: doc.title,
+          description: doc.description,
+          tags: doc.tags,
+          published: doc.published,
+          url: getDocUrl(doc),
+        })),
+      );
+    },
+  );
+
+  server.tool("get_doc", { slug: z.string().min(1) }, async ({ slug }) => {
+    const docs = await getDocs();
+    const doc = docs.find((e) => e.slug === slug.replace(/\.mdx$/, ""));
+    if (!doc) return errorResult(`Document not found for slug "${slug}".`);
+    return textResult({
+      slug: doc.slug,
+      section: doc.section,
+      title: doc.title,
+      description: doc.description,
+      frontmatter: doc.frontmatter,
+      url: getDocUrl(doc),
+      body: doc.body,
+    });
+  });
+
+  server.tool(
+    "search_docs",
+    {
+      query: z.string().min(1),
+      section: z.enum(["components", "templates", "blocks", "root"]).optional(),
+      limit: z.number().int().min(1).max(20).default(5),
+      includeUnpublished: z.boolean().default(false),
+    },
+    async ({ query, section, limit, includeUnpublished }) => {
+      const docs = await getDocs();
+      const matches = docs
+        .filter((doc) => !section || doc.section === section)
+        .filter((doc) => includeUnpublished || doc.published)
+        .map((doc) => ({ doc, score: scoreDoc(doc, query) }))
+        .filter((r) => r.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit)
+        .map(({ doc, score }) => ({
+          slug: doc.slug,
+          section: doc.section,
+          title: doc.title,
+          description: doc.description,
+          score,
+          url: getDocUrl(doc),
+          snippet: buildSnippet(doc.body, query),
+        }));
+      return textResult(matches);
+    },
+  );
+
+  server.resource("catalog", "nyxui://catalog", async (uri) => {
+    const docs = await getDocs();
+    const registry = await getRegistry();
+    return {
+      contents: [
+        {
+          uri: uri.href,
+          mimeType: "application/json",
+          text: JSON.stringify(
+            {
+              name: "Nyx UI MCP Catalog",
+              primaryTools: [
+                "listRegistryItems",
+                "searchRegistryItems",
+                "getRegistryItem",
+              ],
+              docs: docs.map((doc) => ({
+                slug: doc.slug,
+                section: doc.section,
+                title: doc.title,
+                url: getDocUrl(doc),
+              })),
+              registryItems: registry.items.map((item) =>
+                buildRegistryPreview(item, docs, registry),
+              ),
+            },
+            null,
+            2,
+          ),
+        },
+      ],
+    };
+  });
+
+  server.resource(
+    "registry-item",
+    new ResourceTemplate("nyxui://registry/{name}", { list: undefined }),
+    async (uri, { name }) => {
+      const registry = await getRegistry();
+      const item = registry.items.find((e) => e.name === name);
+      if (!item) {
+        return {
+          contents: [
+            {
+              uri: uri.href,
+              mimeType: "application/json",
+              text: JSON.stringify(
+                { error: `Registry item "${name}" not found.` },
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      }
+      const publicItem = await getPublicRegistryItem(name);
+      return {
+        contents: [
+          {
+            uri: uri.href,
+            mimeType: "application/json",
+            text: JSON.stringify(publicItem ?? item, null, 2),
+          },
+        ],
+      };
+    },
+  );
+
+  return server;
+}
+
+export async function startServer() {
+  const server = createServer();
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  return server;
+}
+
+const isEntrypoint =
+  process.argv[1] && pathToFileURL(process.argv[1]).href === import.meta.url;
+
+if (isEntrypoint) {
+  startServer().catch((error) => {
+    console.error("[nyxui-mcp] Failed to start server");
+    console.error(error);
+    process.exit(1);
+  });
+}

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "nyxui-mcp",
+  "version": "1.0.0",
+  "description": "Official MCP server for Nyx UI - Modern React components built with Tailwind CSS and Framer Motion",
+  "type": "module",
+  "bin": {
+    "nyxui-mcp": "./mcp-server.mjs"
+  },
+  "scripts": {
+    "start": "node mcp-server.mjs"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "latest",
+    "zod": "latest"
+  },
+  "keywords": [
+    "mcp",
+    "nyxui",
+    "nyx-ui",
+    "ui-components",
+    "model-context-protocol",
+    "react",
+    "tailwindcss",
+    "framer-motion",
+    "nextjs"
+  ],
+  "author": "Mihir Jaiswal",
+  "license": "MIT",
+  "homepage": "https://nyxui.com",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/MihirJaiswal/nyxui-mcp"
+  },
+  "bugs": {
+    "url": "https://github.com/MihirJaiswal/nyxui-mcp/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/readme.md

@@ -0,0 +1,64 @@
+# nyxui-mcp
+
+Official [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for [Nyx UI](https://nyxui.com/).
+
+## Installation
+
+Add to your MCP client config:
+
+```json
+{
+  "mcpServers": {
+    "nyxui": {
+      "command": "npx",
+      "args": ["-y", "nyxui-mcp@latest"]
+    }
+  }
+}
+```
+
+### Supported Clients
+
+- Claude Desktop
+- Cursor
+- Windsurf
+- Cline
+
+## Example Usage
+
+Once configured, you can ask things like:
+
+> "Install the animated code block from Nyx UI"
+
+> "Show me all Nyx UI components"
+
+> "How do I use the Apple Glass Effect component?"
+
+> "Find me a card component from Nyx UI"
+
+## Available Tools
+
+| Tool                  | Description                                                      |
+| --------------------- | ---------------------------------------------------------------- |
+| `listRegistryItems`   | Browse all Nyx UI components with optional filters               |
+| `searchRegistryItems` | Search components by keyword                                     |
+| `getRegistryItem`     | Get details, install command and source for a specific component |
+| `search_docs`         | Search Nyx UI documentation                                      |
+| `get_doc`             | Get a specific documentation page                                |
+| `list_docs`           | List all documentation pages                                     |
+| `project_overview`    | Get a high level overview of Nyx UI                              |
+
+## Links
+
+- [Nyx UI Website](https://nyxui.com)
+- [Components](https://nyxui.com/components)
+- [Documentation](https://nyxui.com/docs)
+- [GitHub](https://github.com/MihirJaiswal/nyxui)
+
+## Author
+
+Made by [Mihir Jaiswal](https://x.com/mihir_jaiswal_)
+
+## License
+
+MIT