@commercetools/nimbus-mcp 0.1.0 → 2.10.0

package/package.json

@@ -1,8 +1,20 @@
 {
   "name": "@commercetools/nimbus-mcp",
-  "version": "0.1.0",
+  "version": "2.10.0",
   "description": "MCP server for the Nimbus design system",
   "type": "module",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "files": [
+    "dist",
+    "data"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/commercetools/nimbus.git"
+  },
   "bin": {
     "nimbus-mcp": "./dist/index.js"
   },
@@ -13,16 +25,23 @@
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.27.1",
-    "fuse.js": "^7.1.0",
     "zod": "^3.25.67"
   },
   "devDependencies": {
-    "@types/node": "^24.10.13",
+    "@modelcontextprotocol/inspector": "^0.21.2",
+    "@types/node": "^24.11.0",
+    "tsup": "^8.5.1",
+    "tsx": "^4.21.0",
     "typescript": "~5.9.3",
-    "tsx": "^4.21.0"
+    "@commercetools/nimbus": "^2.10.0",
+    "@commercetools/nimbus-icons": "^2.10.0",
+    "@commercetools/nimbus-tokens": "^2.10.0"
   },
   "scripts": {
-    "build": "tsc",
-    "dev": "tsx src/index.ts"
+    "prebuild": "tsx scripts/prebuild.ts",
+    "build": "pnpm prebuild && tsup",
+    "dev": "tsx src/index.ts",
+    "mcp-inspector": "mcp-inspector tsx src/index.ts",
+    "mcp-inspector:cli": "mcp-inspector --cli tsx src/index.ts"
   }
 }

package/dist/data-loader.d.ts

@@ -1,102 +0,0 @@
-/** Returns `true` when running inside the Nimbus monorepo. */
-export declare function isMonorepoMode(): boolean;
-/** Returns the resolved data directory for the current mode. */
-export declare function getDataDir(): string;
-export interface RouteManifestEntry {
-    path: string;
-    id: string;
-    title: string;
-    description: string;
-    category: string;
-    tags: string[];
-    menu: string[];
-    order: number;
-    chunkName: string;
-    tabs?: Array<{
-        key: string;
-        title: string;
-        order: number;
-    }>;
-}
-export interface RouteManifest {
-    routes: RouteManifestEntry[];
-}
-export declare const getRouteManifest: () => Promise<RouteManifest>;
-export interface RouteData {
-    meta: {
-        id: string;
-        title: string;
-        description: string;
-        route: string;
-        menu: string[];
-        tags: string[];
-        toc?: Array<{
-            id: string;
-            title: string;
-            depth: number;
-        }>;
-        [key: string]: unknown;
-    };
-    [key: string]: unknown;
-}
-/**
- * Loads a per-component route JSON by slug.
- * Example: `getRouteData("components-inputs-button")`
- */
-export declare function getRouteData(slug: string): Promise<RouteData>;
-export interface TypeData {
-    displayName: string;
-    description: string;
-    filePath: string;
-    props: Record<string, {
-        name: string;
-        description: string;
-        required: boolean;
-        type: {
-            name: string;
-        };
-        defaultValue?: {
-            value: string;
-        };
-    }>;
-    methods: unknown[];
-    tags: Record<string, string>;
-}
-/**
- * Loads a per-component type JSON by component name.
- * Example: `getTypeData("Button")`
- */
-export declare function getTypeData(componentName: string): Promise<TypeData>;
-export declare const getTypesIndex: () => Promise<TypeData[]>;
-export interface SearchIndexEntry {
-    id: string;
-    title: string;
-    description: string;
-    tags: string[];
-    route: string;
-    menu: string[];
-    content: string;
-}
-export declare const getSearchIndex: () => Promise<SearchIndexEntry[]>;
-export interface DocEntry {
-    meta: {
-        id: string;
-        title: string;
-        description: string;
-        route: string;
-        menu: string[];
-        tags: string[];
-        [key: string]: unknown;
-    };
-    mdx: string;
-}
-export type DocsManifest = Record<string, DocEntry>;
-export declare const getDocsManifest: () => Promise<DocsManifest>;
-/**
- * Returns docs entries whose route starts with `home/design-tokens`.
- */
-export declare function getTokenData(): Promise<DocEntry[]>;
-/**
- * Returns the Icons docs entry from the docs manifest.
- */
-export declare function getIconData(): Promise<DocEntry | undefined>;

package/dist/data-loader.js

@@ -1,104 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-const __dirname = dirname(fileURLToPath(import.meta.url));
-/**
- * Resolves the package root by walking up from the current file's directory
- * until we find the package.json for nimbus-mcp.
- */
-function findPackageRoot() {
-    let dir = __dirname;
-    while (dir !== dirname(dir)) {
-        if (existsSync(resolve(dir, "package.json"))) {
-            return dir;
-        }
-        dir = dirname(dir);
-    }
-    return __dirname;
-}
-const PACKAGE_ROOT = findPackageRoot();
-/** Path to route-manifest.json when running inside the monorepo. */
-const MONOREPO_DATA_DIR = resolve(PACKAGE_ROOT, "../../apps/docs/src/data");
-/** Path to bundled data shipped with the npm package. */
-const BUNDLED_DATA_DIR = resolve(PACKAGE_ROOT, "data");
-/** Marker file used to detect monorepo mode. */
-const MONOREPO_MARKER = resolve(MONOREPO_DATA_DIR, "route-manifest.json");
-// ---------------------------------------------------------------------------
-// Mode detection
-// ---------------------------------------------------------------------------
-let _isMonorepo = null;
-/** Returns `true` when running inside the Nimbus monorepo. */
-export function isMonorepoMode() {
-    if (_isMonorepo === null) {
-        _isMonorepo = existsSync(MONOREPO_MARKER);
-    }
-    return _isMonorepo;
-}
-/** Returns the resolved data directory for the current mode. */
-export function getDataDir() {
-    return isMonorepoMode() ? MONOREPO_DATA_DIR : BUNDLED_DATA_DIR;
-}
-// ---------------------------------------------------------------------------
-// Generic helpers
-// ---------------------------------------------------------------------------
-async function readJson(filePath) {
-    const raw = await readFile(filePath, "utf-8");
-    return JSON.parse(raw);
-}
-/**
- * Creates a lazy accessor that reads and caches a JSON file on first call.
- */
-function lazyJson(relativePath) {
-    let cached;
-    return async () => {
-        if (cached === undefined) {
-            const fullPath = resolve(getDataDir(), relativePath);
-            cached = await readJson(fullPath);
-        }
-        return cached;
-    };
-}
-export const getRouteManifest = lazyJson("route-manifest.json");
-/**
- * Loads a per-component route JSON by slug.
- * Example: `getRouteData("components-inputs-button")`
- */
-export async function getRouteData(slug) {
-    const fullPath = resolve(getDataDir(), "routes", `${slug}.json`);
-    return readJson(fullPath);
-}
-/**
- * Loads a per-component type JSON by component name.
- * Example: `getTypeData("Button")`
- */
-export async function getTypeData(componentName) {
-    const fullPath = resolve(getDataDir(), "types", `${componentName}.json`);
-    return readJson(fullPath);
-}
-// ---------------------------------------------------------------------------
-// Types index
-// ---------------------------------------------------------------------------
-export const getTypesIndex = lazyJson("types.json");
-export const getSearchIndex = lazyJson("search-index.json");
-export const getDocsManifest = lazyJson("docs.json");
-// ---------------------------------------------------------------------------
-// Convenience: token data
-// ---------------------------------------------------------------------------
-/**
- * Returns docs entries whose route starts with `home/design-tokens`.
- */
-export async function getTokenData() {
-    const docs = await getDocsManifest();
-    return Object.values(docs).filter((entry) => entry.meta.route.startsWith("design-tokens"));
-}
-// ---------------------------------------------------------------------------
-// Convenience: icon data
-// ---------------------------------------------------------------------------
-/**
- * Returns the Icons docs entry from the docs manifest.
- */
-export async function getIconData() {
-    const docs = await getDocsManifest();
-    return Object.values(docs).find((entry) => entry.meta.id === "Icons" || entry.meta.route.includes("icons"));
-}

package/dist/index.d.ts

@@ -1,13 +0,0 @@
-#!/usr/bin/env node
-/**
- * Nimbus MCP Server — stdio entry point.
- *
- * Connects the MCP server to stdin/stdout so it can be used with any MCP
- * client (e.g. Claude Desktop, Claude Code) via the stdio transport.
- *
- * Usage:
- *   node dist/index.js
- *   # or via package bin:
- *   nimbus-mcp
- */
-export type { ComponentMeta, DesignToken, ToolResult } from "./types.js";

package/dist/server.d.ts

@@ -1,9 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/**
- * Creates and configures the Nimbus MCP server.
- *
- * Each tool lives in `src/tools/` and exports a `register*` function that
- * receives the server instance and calls `server.registerTool(...)`. This
- * file collects all registrations in one place.
- */
-export declare function createServer(): McpServer;

package/dist/server.js

@@ -1,22 +0,0 @@
-import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-import { registerListComponents } from "./tools/list-components.js";
-/**
- * Creates and configures the Nimbus MCP server.
- *
- * Each tool lives in `src/tools/` and exports a `register*` function that
- * receives the server instance and calls `server.registerTool(...)`. This
- * file collects all registrations in one place.
- */
-export function createServer() {
-    const server = new McpServer({
-        name: "nimbus-mcp",
-        version: "0.1.0",
-    }, {
-        capabilities: {
-            tools: {},
-        },
-    });
-    // Register all tools
-    registerListComponents(server);
-    return server;
-}

package/dist/server.spec.d.ts

@@ -1 +0,0 @@
-export {};

package/dist/server.spec.js

@@ -1,69 +0,0 @@
-import { describe, it, expect } from "vitest";
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
-import { InMemoryTransport } from "@modelcontextprotocol/sdk/inMemory.js";
-import { createServer } from "./server.js";
-/**
- * Integration tests for the Nimbus MCP server.
- *
- * These tests run the server in-process using InMemoryTransport so no
- * child-process spawning or stdio wiring is needed. Add new tools freely —
- * the tool-list tests only assert structure and cardinality, never specific
- * tool names, so they won't break when new tools are registered.
- */
-function createTestClient() {
-    const server = createServer();
-    const [clientTransport, serverTransport] = InMemoryTransport.createLinkedPair();
-    const client = new Client({ name: "test-client", version: "1.0.0" }, { capabilities: {} });
-    return {
-        server,
-        client,
-        clientTransport,
-        serverTransport,
-        async connect() {
-            await server.connect(serverTransport);
-            await client.connect(clientTransport);
-        },
-        async close() {
-            await client.close();
-        },
-    };
-}
-describe("MCP server — initialize handshake", () => {
-    it("responds to initialize with server info and capabilities", async () => {
-        // client.connect() performs the initialize handshake automatically
-        const ctx = createTestClient();
-        await ctx.connect();
-        const serverVersion = ctx.client.getServerVersion();
-        expect(serverVersion).toBeDefined();
-        expect(serverVersion?.name).toBe("nimbus-mcp");
-        expect(serverVersion?.version).toMatch(/^\d+\.\d+\.\d+$/);
-        const capabilities = ctx.client.getServerCapabilities();
-        expect(capabilities).toBeDefined();
-        expect(capabilities?.tools).toBeDefined();
-        await ctx.close();
-    });
-});
-describe("MCP server — tools/list", () => {
-    it("returns a non-empty array of tools", async () => {
-        const ctx = createTestClient();
-        await ctx.connect();
-        const { tools } = await ctx.client.listTools();
-        expect(Array.isArray(tools)).toBe(true);
-        expect(tools.length).toBeGreaterThan(0);
-        await ctx.close();
-    });
-    it("every tool has a name, description, and inputSchema", async () => {
-        const ctx = createTestClient();
-        await ctx.connect();
-        const { tools } = await ctx.client.listTools();
-        for (const tool of tools) {
-            expect(typeof tool.name).toBe("string");
-            expect(tool.name.length).toBeGreaterThan(0);
-            expect(tool.description).toBeDefined();
-            expect(tool.description.length).toBeGreaterThan(0);
-            expect(tool.inputSchema).toBeDefined();
-            expect(tool.inputSchema.type).toBe("object");
-        }
-        await ctx.close();
-    });
-});

package/dist/tools/list-components.d.ts

@@ -1,9 +0,0 @@
-import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
-/**
- * Registers the `list_components` tool on the given MCP server.
- *
- * Returns a list of all Nimbus component names and descriptions from the
- * route manifest. This is a lightweight discovery tool — use
- * `get_component_docs` to fetch full documentation for a specific component.
- */
-export declare function registerListComponents(server: McpServer): void;

package/dist/tools/list-components.js

@@ -1,42 +0,0 @@
-import { getRouteManifest } from "../data-loader.js";
-/**
- * Registers the `list_components` tool on the given MCP server.
- *
- * Returns a list of all Nimbus component names and descriptions from the
- * route manifest. This is a lightweight discovery tool — use
- * `get_component_docs` to fetch full documentation for a specific component.
- */
-export function registerListComponents(server) {
-    server.registerTool("list_components", {
-        title: "List Components",
-        description: "Returns the names and descriptions of all available Nimbus components.",
-        inputSchema: {},
-    }, async () => {
-        try {
-            const manifest = await getRouteManifest();
-            const components = manifest.routes
-                .filter((route) => route.category === "components")
-                .map((route) => `${route.title}: ${route.description}`)
-                .join("\n");
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: components || "No components found.",
-                    },
-                ],
-            };
-        }
-        catch {
-            return {
-                content: [
-                    {
-                        type: "text",
-                        text: "Component data is not available in this environment.",
-                    },
-                ],
-                isError: true,
-            };
-        }
-    });
-}

package/dist/types.d.ts

@@ -1,28 +0,0 @@
-/**
- * Shared type definitions for the Nimbus MCP server.
- */
-/** Metadata about a Nimbus component. */
-export interface ComponentMeta {
-    /** Component name in PascalCase (e.g. "Button", "DatePicker"). */
-    name: string;
-    /** Brief description of the component's purpose. */
-    description: string;
-    /** Filesystem path to the component directory. */
-    path: string;
-}
-/** A single design token entry. */
-export interface DesignToken {
-    /** Token name (e.g. "color.primary.500"). */
-    name: string;
-    /** Resolved token value. */
-    value: string;
-    /** Category the token belongs to (e.g. "color", "spacing"). */
-    category: string;
-}
-/** Result returned by MCP tool handlers. */
-export interface ToolResult {
-    content: Array<{
-        type: "text";
-        text: string;
-    }>;
-}

package/dist/types.js

@@ -1,4 +0,0 @@
-/**
- * Shared type definitions for the Nimbus MCP server.
- */
-export {};

package/src/data-loader.ts

@@ -1,226 +0,0 @@
-import { readFile } from "node:fs/promises";
-import { existsSync } from "node:fs";
-import { resolve, dirname } from "node:path";
-import { fileURLToPath } from "node:url";
-
-const __dirname = dirname(fileURLToPath(import.meta.url));
-
-/**
- * Resolves the package root by walking up from the current file's directory
- * until we find the package.json for nimbus-mcp.
- */
-function findPackageRoot(): string {
-  let dir = __dirname;
-  while (dir !== dirname(dir)) {
-    if (existsSync(resolve(dir, "package.json"))) {
-      return dir;
-    }
-    dir = dirname(dir);
-  }
-  return __dirname;
-}
-
-const PACKAGE_ROOT = findPackageRoot();
-
-/** Path to route-manifest.json when running inside the monorepo. */
-const MONOREPO_DATA_DIR = resolve(PACKAGE_ROOT, "../../apps/docs/src/data");
-
-/** Path to bundled data shipped with the npm package. */
-const BUNDLED_DATA_DIR = resolve(PACKAGE_ROOT, "data");
-
-/** Marker file used to detect monorepo mode. */
-const MONOREPO_MARKER = resolve(MONOREPO_DATA_DIR, "route-manifest.json");
-
-// ---------------------------------------------------------------------------
-// Mode detection
-// ---------------------------------------------------------------------------
-
-let _isMonorepo: boolean | null = null;
-
-/** Returns `true` when running inside the Nimbus monorepo. */
-export function isMonorepoMode(): boolean {
-  if (_isMonorepo === null) {
-    _isMonorepo = existsSync(MONOREPO_MARKER);
-  }
-  return _isMonorepo;
-}
-
-/** Returns the resolved data directory for the current mode. */
-export function getDataDir(): string {
-  return isMonorepoMode() ? MONOREPO_DATA_DIR : BUNDLED_DATA_DIR;
-}
-
-// ---------------------------------------------------------------------------
-// Generic helpers
-// ---------------------------------------------------------------------------
-
-async function readJson<T>(filePath: string): Promise<T> {
-  const raw = await readFile(filePath, "utf-8");
-  return JSON.parse(raw) as T;
-}
-
-/**
- * Creates a lazy accessor that reads and caches a JSON file on first call.
- */
-function lazyJson<T>(relativePath: string): () => Promise<T> {
-  let cached: T | undefined;
-  return async () => {
-    if (cached === undefined) {
-      const fullPath = resolve(getDataDir(), relativePath);
-      cached = await readJson<T>(fullPath);
-    }
-    return cached;
-  };
-}
-
-// ---------------------------------------------------------------------------
-// Route manifest
-// ---------------------------------------------------------------------------
-
-export interface RouteManifestEntry {
-  path: string;
-  id: string;
-  title: string;
-  description: string;
-  category: string;
-  tags: string[];
-  menu: string[];
-  order: number;
-  chunkName: string;
-  tabs?: Array<{ key: string; title: string; order: number }>;
-}
-
-export interface RouteManifest {
-  routes: RouteManifestEntry[];
-}
-
-export const getRouteManifest = lazyJson<RouteManifest>("route-manifest.json");
-
-// ---------------------------------------------------------------------------
-// Per-component route data
-// ---------------------------------------------------------------------------
-
-export interface RouteData {
-  meta: {
-    id: string;
-    title: string;
-    description: string;
-    route: string;
-    menu: string[];
-    tags: string[];
-    toc?: Array<{ id: string; title: string; depth: number }>;
-    [key: string]: unknown;
-  };
-  [key: string]: unknown;
-}
-
-/**
- * Loads a per-component route JSON by slug.
- * Example: `getRouteData("components-inputs-button")`
- */
-export async function getRouteData(slug: string): Promise<RouteData> {
-  const fullPath = resolve(getDataDir(), "routes", `${slug}.json`);
-  return readJson<RouteData>(fullPath);
-}
-
-// ---------------------------------------------------------------------------
-// Per-component type data
-// ---------------------------------------------------------------------------
-
-export interface TypeData {
-  displayName: string;
-  description: string;
-  filePath: string;
-  props: Record<
-    string,
-    {
-      name: string;
-      description: string;
-      required: boolean;
-      type: { name: string };
-      defaultValue?: { value: string };
-    }
-  >;
-  methods: unknown[];
-  tags: Record<string, string>;
-}
-
-/**
- * Loads a per-component type JSON by component name.
- * Example: `getTypeData("Button")`
- */
-export async function getTypeData(componentName: string): Promise<TypeData> {
-  const fullPath = resolve(getDataDir(), "types", `${componentName}.json`);
-  return readJson<TypeData>(fullPath);
-}
-
-// ---------------------------------------------------------------------------
-// Types index
-// ---------------------------------------------------------------------------
-
-export const getTypesIndex = lazyJson<TypeData[]>("types.json");
-
-// ---------------------------------------------------------------------------
-// Search index
-// ---------------------------------------------------------------------------
-
-export interface SearchIndexEntry {
-  id: string;
-  title: string;
-  description: string;
-  tags: string[];
-  route: string;
-  menu: string[];
-  content: string;
-}
-
-export const getSearchIndex = lazyJson<SearchIndexEntry[]>("search-index.json");
-
-// ---------------------------------------------------------------------------
-// Docs (token / icon data is embedded in the docs.json manifest)
-// ---------------------------------------------------------------------------
-
-export interface DocEntry {
-  meta: {
-    id: string;
-    title: string;
-    description: string;
-    route: string;
-    menu: string[];
-    tags: string[];
-    [key: string]: unknown;
-  };
-  mdx: string;
-}
-
-export type DocsManifest = Record<string, DocEntry>;
-
-export const getDocsManifest = lazyJson<DocsManifest>("docs.json");
-
-// ---------------------------------------------------------------------------
-// Convenience: token data
-// ---------------------------------------------------------------------------
-
-/**
- * Returns docs entries whose route starts with `home/design-tokens`.
- */
-export async function getTokenData(): Promise<DocEntry[]> {
-  const docs = await getDocsManifest();
-  return Object.values(docs).filter((entry) =>
-    entry.meta.route.startsWith("design-tokens")
-  );
-}
-
-// ---------------------------------------------------------------------------
-// Convenience: icon data
-// ---------------------------------------------------------------------------
-
-/**
- * Returns the Icons docs entry from the docs manifest.
- */
-export async function getIconData(): Promise<DocEntry | undefined> {
-  const docs = await getDocsManifest();
-  return Object.values(docs).find(
-    (entry) => entry.meta.id === "Icons" || entry.meta.route.includes("icons")
-  );
-}