@hashicorp/design-system-mcp 0.1.0

package/dist/index.js

@@ -0,0 +1,107 @@
+#!/usr/bin/env node
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { dirname, resolve } from "node:path";
+import { readFileSync } from "node:fs";
+import { fileURLToPath } from "node:url";
+import { registerPrompts } from "./prompts/index.js";
+import { registerResources } from "./resources/index.js";
+import { registerTools } from "./tools/index.js";
+const currentFilePath = fileURLToPath(import.meta.url);
+const currentDirectoryPath = dirname(currentFilePath);
+const packageJsonPath = resolve(currentDirectoryPath, "../package.json");
+const defaultServerVersion = "0.0.0";
+const getServerVersion = () => {
+    try {
+        const rawPackageJson = readFileSync(packageJsonPath, "utf8");
+        const parsedPackageJson = JSON.parse(rawPackageJson);
+        if (typeof parsedPackageJson.version === "string") {
+            return parsedPackageJson.version;
+        }
+    }
+    catch (error) {
+        console.error("Unable to read MCP package version:", error);
+    }
+    return defaultServerVersion;
+};
+const buildServer = () => {
+    const server = new McpServer({
+        name: "helios-design-system-mcp",
+        version: getServerVersion(),
+    });
+    return server;
+};
+const installLifecycleHandlers = (server) => {
+    let isShuttingDown = false;
+    const shutdown = async (reason, error) => {
+        if (isShuttingDown) {
+            return;
+        }
+        isShuttingDown = true;
+        if (error) {
+            process.exitCode = 1;
+            console.error(`Shutting down MCP server due to ${reason}:`, error);
+        }
+        else {
+            console.error(`Shutting down MCP server (${reason})`);
+        }
+        try {
+            await server.close();
+            console.error("MCP server shutdown complete");
+        }
+        catch (closeError) {
+            process.exitCode = 1;
+            console.error("Failed to close MCP server cleanly:", closeError);
+        }
+    };
+    const onSigint = () => {
+        void shutdown("SIGINT").finally(() => process.exit(process.exitCode ?? 0));
+    };
+    const onSigterm = () => {
+        void shutdown("SIGTERM").finally(() => process.exit(process.exitCode ?? 0));
+    };
+    const onUnhandledRejection = (reason) => {
+        void shutdown("unhandledRejection", reason).finally(() => process.exit(process.exitCode ?? 1));
+    };
+    const onUncaughtException = (error) => {
+        void shutdown("uncaughtException", error).finally(() => process.exit(process.exitCode ?? 1));
+    };
+    process.once("SIGINT", onSigint);
+    process.once("SIGTERM", onSigterm);
+    process.once("unhandledRejection", onUnhandledRejection);
+    process.once("uncaughtException", onUncaughtException);
+    return {
+        shutdown,
+    };
+};
+const main = async () => {
+    let shutdown;
+    try {
+        const server = buildServer();
+        shutdown = installLifecycleHandlers(server).shutdown;
+        registerPrompts(server);
+        registerResources(server);
+        registerTools(server);
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        // STDIO servers must never write to stdout; use stderr for diagnostics.
+        console.error("Helios Design System MCP server running on stdio");
+    }
+    catch (error) {
+        if (shutdown) {
+            await shutdown("startup-failure", error);
+        }
+        else {
+            console.error("Failed to initialize MCP server:", error);
+        }
+        throw error;
+    }
+};
+void main().catch((error) => {
+    console.error("Fatal error in MCP server:", error);
+    process.exit(1);
+});

package/dist/prompts/index.js

@@ -0,0 +1,10 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+const PROMPTS = [];
+export function registerPrompts(server) {
+    for (const prompt of PROMPTS) {
+        server.registerPrompt(prompt.name, prompt.config, prompt.callback);
+    }
+}

package/dist/prompts/types.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export {};

package/dist/resources/completions.js

@@ -0,0 +1,30 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+// matching loop for resource template completion callback
+import { normalizeLookupValue } from "../catalog/normalize.js";
+export const completeFromAliases = ({ items, getAliases, getValue, value, }) => {
+    const query = normalizeLookupValue(value);
+    const matches = [];
+    for (const item of items) {
+        const aliases = getAliases(item);
+        const isMatch = query.length === 0 ||
+            aliases.some((alias) => alias.toLowerCase().includes(query));
+        if (isMatch) {
+            matches.push(getValue(item));
+        }
+    }
+    return matches;
+};
+export const withSafeCompletion = (resourceName, complete) => {
+    return (value) => {
+        try {
+            return complete(value);
+        }
+        catch (error) {
+            console.error(`Resource completion failed (${resourceName}):`, error);
+            return [];
+        }
+    };
+};

package/dist/resources/components/constants.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const COMPONENTS_URI = "hds://components";
+export const COMPONENT_BY_NAME_URI_TEMPLATE = `${COMPONENTS_URI}/{componentName}`;

package/dist/resources/components/get-component-by-name.js

@@ -0,0 +1,54 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { completeFromAliases, withSafeCompletion, } from "../completions.js";
+import { defineDetailResource } from "../define-resource.js";
+import { toJsonResourceResponse } from "../responses.js";
+import { buildDetailUri } from "../uri.js";
+import { COMPONENTS_URI, COMPONENT_BY_NAME_URI_TEMPLATE } from "./constants.js";
+import { getOrLoadComponentStore } from "../../stores/components/index.js";
+import { toSerializableComponent } from "./utils.js";
+export const completeComponentNames = (components, value) => {
+    return completeFromAliases({
+        items: components,
+        // the gts class name a consumer imports, `HdsAdvancedTableTh`, alongside the hbs invocation
+        // name and the module path, so a partial of any of the three completes
+        getAliases: (component) => [
+            component.name,
+            component.name.replaceAll("::", ""),
+            component.modulePath,
+        ],
+        getValue: (component) => component.name,
+        value,
+    });
+};
+export const readComponentByNameResource = (store, componentName) => {
+    const component = store.getComponentByName(componentName);
+    const uri = buildDetailUri(COMPONENTS_URI, componentName);
+    if (component === null) {
+        return toJsonResourceResponse(uri, {
+            found: false,
+            requestedComponentName: componentName,
+            message: "Component not found for provided componentName.",
+        });
+    }
+    return toJsonResourceResponse(uri, {
+        found: true,
+        requestedComponentName: componentName,
+        component: toSerializableComponent(component),
+    });
+};
+export const createGetComponentByNameResource = (getStore) => {
+    return defineDetailResource({
+        name: "get_hds_component",
+        uriTemplate: COMPONENT_BY_NAME_URI_TEMPLATE,
+        title: "HDS component detail",
+        description: "Detailed component record for a specific component name",
+        variableName: "componentName",
+        complete: withSafeCompletion("get_hds_component", (value) => completeComponentNames(getStore().listComponents(), value)),
+        read: (componentName) => readComponentByNameResource(getStore(), componentName),
+    });
+};
+const getComponentByNameResource = createGetComponentByNameResource(getOrLoadComponentStore);
+export default getComponentByNameResource;

package/dist/resources/components/get-components.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { toJsonResourceResponse } from "../responses.js";
+import { COMPONENTS_URI } from "./constants.js";
+import { getOrLoadComponentStore } from "../../stores/components/index.js";
+import { toSerializableComponentSummary } from "./utils.js";
+export const readComponentsResource = (store) => {
+    const meta = store.getMeta();
+    const payload = {
+        totalComponentCount: meta.totalComponentCount,
+        source: meta.source,
+        components: store
+            .listComponents()
+            .map((component) => toSerializableComponentSummary(component)),
+    };
+    return toJsonResourceResponse(COMPONENTS_URI, payload);
+};
+export const createGetComponentsResource = (getStore) => {
+    return {
+        name: "get_hds_components",
+        uri: COMPONENTS_URI,
+        config: {
+            title: "HDS component catalog index",
+            description: "Canonical list of components with summary metadata",
+            mimeType: "application/json",
+        },
+        readCallback: async () => readComponentsResource(getStore()),
+    };
+};
+export const getComponentsResource = createGetComponentsResource(getOrLoadComponentStore);
+export default getComponentsResource;

package/dist/resources/components/index.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import getComponentByNameResource from "./get-component-by-name.js";
+import getComponentsResource from "./get-components.js";
+const COMPONENTS_RESOURCES = [
+    getComponentsResource,
+    getComponentByNameResource,
+];
+export default COMPONENTS_RESOURCES;

package/dist/resources/components/utils.js

@@ -0,0 +1,39 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const toSerializableComponentSummary = (component) => {
+    return {
+        name: component.name,
+        modulePath: component.modulePath,
+        ...(component.docsPath === undefined
+            ? {}
+            : { docsPath: component.docsPath }),
+    };
+};
+export const toSerializableComponent = (component) => {
+    return {
+        name: component.name,
+        modulePath: component.modulePath,
+        ...(component.docsPath === undefined
+            ? {}
+            : { docsPath: component.docsPath }),
+        ...(component.element === undefined ? {} : { element: component.element }),
+        args: component.args.map((arg) => ({
+            name: arg.name,
+            type: arg.type,
+            required: arg.required,
+            ...(arg.values === undefined ? {} : { values: arg.values }),
+            ...(arg.inheritedFrom === undefined
+                ? {}
+                : { inheritedFrom: arg.inheritedFrom }),
+        })),
+        blocks: component.blocks.map((block) => ({
+            name: block.name,
+            yields: block.yields.map((blockYield) => ({
+                name: blockYield.name,
+                type: blockYield.type,
+            })),
+        })),
+    };
+};

package/dist/resources/define-resource.js

@@ -0,0 +1,35 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+// descriptor factory for the detail resource every domain registers
+import { ResourceTemplate } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { toJsonResourceResponse } from "./responses.js";
+import { decodeUriSegment } from "./uri.js";
+const JSON_MIME_TYPE = "application/json";
+export const defineDetailResource = ({ name, uriTemplate, title, description, variableName, complete, read, }) => {
+    return {
+        name,
+        template: new ResourceTemplate(uriTemplate, {
+            list: undefined,
+            complete: {
+                [variableName]: (value) => complete(value),
+            },
+        }),
+        config: {
+            title,
+            description,
+            mimeType: JSON_MIME_TYPE,
+        },
+        readCallback: async (uri, variables) => {
+            const variable = variables[variableName];
+            if (typeof variable !== "string" || variable.trim().length === 0) {
+                return toJsonResourceResponse(uri.toString(), {
+                    found: false,
+                    message: `Missing ${variableName} variable.`,
+                });
+            }
+            return read(decodeUriSegment(variable));
+        },
+    };
+};

package/dist/resources/hds-icons/constants.js

@@ -0,0 +1,6 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const ICONS_URI = "hds://icons";
+export const ICON_BY_NAME_URI_TEMPLATE = `${ICONS_URI}/{iconName}`;

package/dist/resources/hds-icons/get-icon-by-name.js

@@ -0,0 +1,48 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { completeFromAliases, withSafeCompletion, } from "../completions.js";
+import { defineDetailResource } from "../define-resource.js";
+import { toJsonResourceResponse } from "../responses.js";
+import { buildDetailUri } from "../uri.js";
+import { ICONS_URI, ICON_BY_NAME_URI_TEMPLATE } from "./constants.js";
+import { getOrLoadIconStore } from "../../stores/hds-icons/index.js";
+import { toSerializableIcon } from "./utils.js";
+export const completeIconNames = (icons, value) => {
+    return completeFromAliases({
+        items: icons,
+        getAliases: (icon) => [icon.iconName, ...icon.fileNames],
+        getValue: (icon) => icon.iconName,
+        value,
+    });
+};
+export const readIconByNameResource = (store, iconName) => {
+    const icon = store.getIconByName(iconName);
+    const uri = buildDetailUri(ICONS_URI, iconName);
+    if (icon === null) {
+        return toJsonResourceResponse(uri, {
+            found: false,
+            requestedIconName: iconName,
+            message: "Icon not found for provided iconName or fileName.",
+        });
+    }
+    return toJsonResourceResponse(uri, {
+        found: true,
+        requestedIconName: iconName,
+        icon: toSerializableIcon(icon),
+    });
+};
+export const createGetIconByNameResource = (getStore) => {
+    return defineDetailResource({
+        name: "get_hds_icon",
+        uriTemplate: ICON_BY_NAME_URI_TEMPLATE,
+        title: "HDS icon detail",
+        description: "Detailed Flight icon record for a specific icon name",
+        variableName: "iconName",
+        complete: withSafeCompletion("get_hds_icon", (value) => completeIconNames(getStore().listIconAliases(), value)),
+        read: (iconName) => readIconByNameResource(getStore(), iconName),
+    });
+};
+const getIconByNameResource = createGetIconByNameResource(getOrLoadIconStore);
+export default getIconByNameResource;

package/dist/resources/hds-icons/get-icons.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { toJsonResourceResponse } from "../responses.js";
+import { ICONS_URI } from "./constants.js";
+import { getOrLoadIconStore } from "../../stores/hds-icons/index.js";
+import { toSerializableIconSummary } from "./utils.js";
+export const readIconsResource = (store) => {
+    const meta = store.getMeta();
+    const payload = {
+        totalIconCount: meta.totalIconCount,
+        totalAssetCount: meta.totalAssetCount,
+        categories: meta.categories,
+        source: meta.source,
+        icons: store.listIcons().map((icon) => toSerializableIconSummary(icon)),
+    };
+    return toJsonResourceResponse(ICONS_URI, payload);
+};
+export const createGetIconsResource = (getStore) => {
+    return {
+        name: "get_hds_icons",
+        uri: ICONS_URI,
+        config: {
+            title: "HDS icon catalog index",
+            description: "Canonical list of Flight icons with summary metadata",
+            mimeType: "application/json",
+        },
+        readCallback: async () => readIconsResource(getStore()),
+    };
+};
+export const getIconsResource = createGetIconsResource(getOrLoadIconStore);
+export default getIconsResource;

package/dist/resources/hds-icons/index.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import getIconByNameResource from "./get-icon-by-name.js";
+import getIconsResource from "./get-icons.js";
+const HDS_ICONS_RESOURCES = [
+    getIconsResource,
+    getIconByNameResource,
+];
+export default HDS_ICONS_RESOURCES;

package/dist/resources/hds-icons/utils.js

@@ -0,0 +1,26 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const toSerializableIconSummary = (icon) => {
+    return {
+        iconName: icon.iconName,
+        description: icon.description,
+        category: icon.category,
+        sizes: icon.sizes,
+        hasMapping: icon.hasMapping,
+    };
+};
+export const toSerializableIcon = (icon) => {
+    return {
+        ...toSerializableIconSummary(icon),
+        variants: icon.variants.map((variant) => ({
+            id: variant.id,
+            fileName: variant.fileName,
+            size: variant.size,
+            width: variant.width,
+            height: variant.height,
+            ...(variant.mapping === undefined ? {} : { mapping: variant.mapping }),
+        })),
+    };
+};

package/dist/resources/index.js

@@ -0,0 +1,23 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { withSafeResourceHandler } from "./responses.js";
+import hdsIconsResources from "./hds-icons/index.js";
+import tokensResources from "./tokens/index.js";
+import componentsResources from "./components/index.js";
+const RESOURCES = [
+    ...componentsResources,
+    ...hdsIconsResources,
+    ...tokensResources,
+];
+export function registerResources(server) {
+    for (const resource of RESOURCES) {
+        if ("uri" in resource) {
+            server.registerResource(resource.name, resource.uri, resource.config, withSafeResourceHandler(resource.name, resource.readCallback));
+        }
+        else if ("template" in resource) {
+            server.registerResource(resource.name, resource.template, resource.config, withSafeResourceHandler(resource.name, resource.readCallback));
+        }
+    }
+}

package/dist/resources/responses.js

@@ -0,0 +1,34 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const toJsonResourceResponse = (uri, payload) => {
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: "application/json",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+};
+export const withSafeResourceHandler = (resourceName, handler) => {
+    return async (...args) => {
+        const [uri] = args;
+        try {
+            return await handler(...args);
+        }
+        catch (error) {
+            console.error(`Resource handler failed (${resourceName}):`, error);
+            const errorPayload = error instanceof Error
+                ? { name: error.name, message: error.message }
+                : { message: String(error) };
+            return toJsonResourceResponse(uri.toString(), {
+                ok: false,
+                resource: resourceName,
+                error: errorPayload,
+            });
+        }
+    };
+};

package/dist/resources/tokens/constants.js

@@ -0,0 +1,2 @@
+export const TOKENS_URI = "hds://tokens";
+export const TOKEN_BY_KEY_URI_TEMPLATE = `${TOKENS_URI}/{tokenKey}`;

package/dist/resources/tokens/get-token-by-key.js

@@ -0,0 +1,51 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { completeFromAliases, withSafeCompletion } from "../completions.js";
+import { defineDetailResource } from "../define-resource.js";
+import { getOrLoadTokenStore } from "../../stores/tokens/index.js";
+import { toJsonResourceResponse } from "../responses.js";
+import { buildDetailUri } from "../uri.js";
+import { TOKENS_URI, TOKEN_BY_KEY_URI_TEMPLATE } from "./constants.js";
+import { toSerializableTokenSummary } from "./utils.js";
+export const completeTokenKeys = (tokens, value) => {
+    return completeFromAliases({
+        items: tokens,
+        getAliases: (token) => [token.key, token.name, token.path.join(".")],
+        getValue: (token) => token.key,
+        value,
+    });
+};
+export const readTokenByKeyResource = (store, tokenKey) => {
+    const token = store.getTokenByKey(tokenKey);
+    const uri = buildDetailUri(TOKENS_URI, tokenKey);
+    if (token === null) {
+        return toJsonResourceResponse(uri, {
+            found: false,
+            requestedTokenKey: tokenKey,
+            message: "Token not found for provided tokenKey.",
+        });
+    }
+    return toJsonResourceResponse(uri, {
+        found: true,
+        requestedTokenKey: tokenKey,
+        token: {
+            ...toSerializableTokenSummary(token),
+            ...(token.original === undefined ? {} : { original: token.original }),
+        },
+    });
+};
+export const createGetTokenByKeyResource = (getStore) => {
+    return defineDetailResource({
+        name: "get_hds_token",
+        uriTemplate: TOKEN_BY_KEY_URI_TEMPLATE,
+        title: "HDS token detail",
+        description: "Detailed token record for a specific token key",
+        variableName: "tokenKey",
+        complete: withSafeCompletion("get_hds_token", (value) => completeTokenKeys(getStore().listTokens(), value)),
+        read: (tokenKey) => readTokenByKeyResource(getStore(), tokenKey),
+    });
+};
+const getTokenByKeyResource = createGetTokenByKeyResource(getOrLoadTokenStore);
+export default getTokenByKeyResource;

package/dist/resources/tokens/get-tokens.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { toJsonResourceResponse } from "../responses.js";
+import { getOrLoadTokenStore } from "../../stores/tokens/index.js";
+import { toSerializableTokenSummary } from "./utils.js";
+import { TOKENS_URI } from "./constants.js";
+export const readTokensResource = (store) => {
+    const meta = store.getMeta();
+    const payload = {
+        totalTokenCount: meta.totalTokenCount,
+        source: meta.source,
+        tokens: store
+            .listTokens()
+            .map((token) => toSerializableTokenSummary(token)),
+    };
+    return toJsonResourceResponse(TOKENS_URI, payload);
+};
+export const createGetTokensResource = (getStore) => {
+    return {
+        name: "get_hds_tokens",
+        uri: TOKENS_URI,
+        config: {
+            title: "HDS token catalog index",
+            description: "Canonical list of tokens with summary metadata",
+            mimeType: "application/json",
+        },
+        readCallback: async () => readTokensResource(getStore()),
+    };
+};
+export const getTokensResource = createGetTokensResource(getOrLoadTokenStore);
+export default getTokensResource;

package/dist/resources/tokens/index.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import getTokensResource from "./get-tokens.js";
+import getTokenByKeyResource from "./get-token-by-key.js";
+const TOKENS_RESOURCES = [
+    getTokensResource,
+    getTokenByKeyResource,
+];
+export default TOKENS_RESOURCES;

package/dist/resources/tokens/utils.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const toSerializableTokenSummary = (token) => {
+    return {
+        key: token.key,
+        name: token.name,
+        type: token.type,
+        value: token.value,
+        cssVar: token.cssVar,
+        category: token.category,
+        path: token.path,
+    };
+};

package/dist/resources/types.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export {};

package/dist/resources/uri.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const buildDetailUri = (baseUri, key) => {
+    return `${baseUri}/${encodeURIComponent(key)}`;
+};
+export const decodeUriSegment = (value) => {
+    try {
+        return decodeURIComponent(value);
+    }
+    catch {
+        return value;
+    }
+};