@hashicorp/design-system-mcp 0.1.0

package/dist/tools/docs/search-docs.js

@@ -0,0 +1,143 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { toJsonToolResponse, withSafeToolHandler } from "../responses.js";
+import { clampFilterValue, clampSearchLimit, MAX_FILTER_LENGTH, } from "../search.js";
+import { DEFAULT_SEARCH_LIMIT, DOCS_TABS, MAX_QUERY_LENGTH, MAX_SEARCH_LIMIT, SEARCH_DOCS_TOOL_NAME, VERSION_HISTORY_TAB, } from "./constants.js";
+import { getOrLoadDocsStore } from "../../stores/docs/index.js";
+import { toSerializableSearchResult } from "./utils.js";
+export const searchDocsInputShape = {
+    query: z
+        .string()
+        .min(1)
+        .describe("Natural language or keyword query, e.g. 'how do I make a button full width' or 'sticky table header'."),
+    limit: z
+        .number()
+        .int()
+        .min(1)
+        .max(MAX_SEARCH_LIMIT)
+        .default(DEFAULT_SEARCH_LIMIT)
+        .describe(`Maximum results to return (1-${MAX_SEARCH_LIMIT}). Defaults to ${DEFAULT_SEARCH_LIMIT}.`),
+    section: z
+        .string()
+        .min(1)
+        .max(MAX_FILTER_LENGTH)
+        .optional()
+        .describe("Restrict to one top-level docs section: about, components, content, foundations, getting-started, icons, layouts, overrides, patterns, utilities, whats-new."),
+    tab: z
+        .string()
+        .min(1)
+        .max(MAX_FILTER_LENGTH)
+        .optional()
+        .describe(`Restrict to one page tab. The corpus uses exactly these: ${DOCS_TABS.join(", ")}. Version and changelog questions must pass tab: '${VERSION_HISTORY_TAB}', which is otherwise down-ranked.`),
+    docsPath: z
+        .string()
+        .min(1)
+        .max(MAX_FILTER_LENGTH)
+        .optional()
+        .describe("Restrict to one docs route or route prefix, e.g. 'components/button' or 'components/form'. This is the same value the hds://components resource reports as a component's docsPath."),
+};
+const searchDocsResultShape = z.object({
+    id: z.string(),
+    score: z.number(),
+    relScore: z.number(),
+    title: z.string(),
+    pageDescription: z.string().optional(),
+    route: z.string(),
+    docsPath: z.string(),
+    section: z.string(),
+    tab: z.string().optional(),
+    headingPath: z.array(z.string()),
+    url: z.string(),
+    pageAnchored: z.boolean(),
+    pageMatchedTerms: z.array(z.string()),
+    snippet: z.string(),
+});
+export const searchDocsOutputShape = {
+    query: z.string(),
+    bundledAt: z.string(),
+    siteBaseUrl: z.string(),
+    totalMatches: z.number().int(),
+    returnedMatches: z.number().int(),
+    truncated: z.boolean(),
+    matchedTerms: z.array(z.string()),
+    unmatchedTerms: z.array(z.string()),
+    filters: z.object({
+        section: z.string().optional(),
+        tab: z.string().optional(),
+        docsPath: z.string().optional(),
+    }),
+    unknownFilters: z.array(z.string()),
+    availableSections: z.array(z.string()).optional(),
+    availableTabs: z.array(z.string()).optional(),
+    results: z.array(searchDocsResultShape),
+    provenance: z.string(),
+};
+export const searchDocsOutputSchema = z.object(searchDocsOutputShape);
+const DESCRIPTION = [
+    "Search the bundled Helios Design System documentation (helios.hashicorp.design) and return ranked passages with snippets.",
+    "The corpus is a snapshot committed into this server: search runs entirely locally and never makes a network request.",
+    "Every result carries the canonical URL of the passage, and the response carries the bundledAt timestamp, so a client that needs the live page can fetch it itself.",
+    "Follow up with read_hds_docs, passing a result's `id`, to read the full passage including its code examples.",
+    "Results are ranked, not filtered for truth: a non-empty result set is not evidence that Helios has the thing you asked about. Check `pageAnchored` and `unmatchedTerms`, and read the snippets.",
+].join(" ");
+export const searchDocs = (store, input) => {
+    const meta = store.getMeta();
+    const limit = clampSearchLimit(input.limit, MAX_SEARCH_LIMIT);
+    const query = input.query.slice(0, MAX_QUERY_LENGTH);
+    const outcome = store.search({
+        query,
+        limit,
+        ...(input.section === undefined
+            ? {}
+            : { section: clampFilterValue(input.section) }),
+        ...(input.tab === undefined ? {} : { tab: clampFilterValue(input.tab) }),
+        ...(input.docsPath === undefined
+            ? {}
+            : { docsPath: clampFilterValue(input.docsPath) }),
+    });
+    const filterHelp = outcome.unknownFilters.length === 0
+        ? {}
+        : {
+            availableSections: store.listSections(),
+            availableTabs: store.listTabs(),
+        };
+    return {
+        query,
+        bundledAt: meta.bundledAt,
+        siteBaseUrl: meta.siteBaseUrl,
+        totalMatches: outcome.totalMatches,
+        returnedMatches: outcome.hits.length,
+        truncated: outcome.totalMatches > outcome.hits.length,
+        matchedTerms: outcome.matchedTerms,
+        unmatchedTerms: outcome.unmatchedTerms,
+        filters: outcome.filters,
+        unknownFilters: outcome.unknownFilters,
+        ...filterHelp,
+        results: outcome.hits.map((hit) => toSerializableSearchResult(hit)),
+        provenance: `Bundled snapshot of ${meta.siteBaseUrl} taken at ${meta.bundledAt}; ${meta.totalPageCount} pages, ${meta.totalChunkCount} passages. Fetch a result's url for the live page.`,
+    };
+};
+export const createSearchDocsTool = (getStore) => {
+    const executeCallback = withSafeToolHandler(SEARCH_DOCS_TOOL_NAME, (input) => toJsonToolResponse(searchDocs(getStore(), input)));
+    return defineTool({
+        name: SEARCH_DOCS_TOOL_NAME,
+        config: {
+            title: "Search HDS documentation",
+            description: DESCRIPTION,
+            inputSchema: searchDocsInputShape,
+            outputSchema: searchDocsOutputShape,
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        },
+        executeCallback,
+    });
+};
+const searchDocsTool = createSearchDocsTool(getOrLoadDocsStore);
+export default searchDocsTool;

package/dist/tools/docs/utils.js

@@ -0,0 +1,82 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { getHeadingPath } from "../../stores/docs/lookup.js";
+const TRUNCATION_NOTE = "\n\n[truncated: raise maxBytes to read the rest]";
+const REPLACEMENT_CHARACTER = "�";
+const CHUNK_SEPARATOR = "\n\n";
+export const toSerializableSearchResult = (hit) => {
+    return {
+        id: hit.chunk.id,
+        score: hit.score,
+        relScore: hit.relScore,
+        title: hit.page.title,
+        ...(hit.page.description === undefined
+            ? {}
+            : { pageDescription: hit.page.description }),
+        route: hit.chunk.route,
+        docsPath: hit.chunk.route,
+        section: hit.chunk.section,
+        ...(hit.chunk.tab === undefined ? {} : { tab: hit.chunk.tab }),
+        headingPath: getHeadingPath(hit.chunk),
+        url: hit.chunk.url,
+        pageAnchored: hit.pageMatchedTerms.length > 0,
+        pageMatchedTerms: hit.pageMatchedTerms,
+        snippet: hit.snippet,
+    };
+};
+// absent rather than empty when a page carries neither link
+export const toSerializablePageLinks = (page) => {
+    const links = {
+        ...(page.links?.github === undefined ? {} : { github: page.links.github }),
+        ...(page.links?.figma === undefined ? {} : { figma: page.links.figma }),
+    };
+    return Object.keys(links).length === 0 ? undefined : links;
+};
+export const truncateToBytes = (value, maxBytes) => {
+    if (Buffer.byteLength(value, "utf8") <= maxBytes) {
+        return { value, truncated: false };
+    }
+    const noteBytes = Buffer.byteLength(TRUNCATION_NOTE, "utf8");
+    const budget = Math.max(maxBytes - noteBytes, 0);
+    const decoded = new TextDecoder("utf-8").decode(Buffer.from(value, "utf8").subarray(0, budget));
+    let truncatedValue = decoded;
+    while (truncatedValue.endsWith(REPLACEMENT_CHARACTER)) {
+        truncatedValue = truncatedValue.slice(0, -1);
+    }
+    return {
+        value: `${truncatedValue.trimEnd()}${TRUNCATION_NOTE}`,
+        truncated: true,
+    };
+};
+export const joinChunkContent = (chunks) => {
+    return chunks.map((chunk) => chunk.content.trim()).join(CHUNK_SEPARATOR);
+};
+export const selectChunkContent = (chunks, maxBytes) => {
+    const { value: content, truncated } = truncateToBytes(joinChunkContent(chunks), maxBytes);
+    if (!truncated) {
+        return {
+            content,
+            truncated,
+            includedIds: chunks.map((chunk) => chunk.id),
+            omittedIds: [],
+        };
+    }
+    // the note is appended verbatim, so what precedes it is exactly the content that survived
+    const keptLength = content.length - TRUNCATION_NOTE.length;
+    let offset = 0;
+    let keptCount = 0;
+    for (const chunk of chunks) {
+        if (offset >= keptLength)
+            break;
+        offset += chunk.content.trim().length + CHUNK_SEPARATOR.length;
+        keptCount += 1;
+    }
+    return {
+        content,
+        truncated,
+        includedIds: chunks.slice(0, keptCount).map((chunk) => chunk.id),
+        omittedIds: chunks.slice(keptCount).map((chunk) => chunk.id),
+    };
+};

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

@@ -0,0 +1,5 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const SEARCH_ICONS_TOOL_NAME = "search_hds_icons";

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

@@ -0,0 +1,7 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import searchIconsTool from "./search-icons.js";
+const HDS_ICONS_TOOLS = [searchIconsTool];
+export default HDS_ICONS_TOOLS;

package/dist/tools/hds-icons/search-icons.js

@@ -0,0 +1,123 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+import { CATALOG_TOOL_ANNOTATIONS, defineTool } from "../define-tool.js";
+import catalogSourceOutputSchema from "../output-schema.js";
+import { toJsonToolResponse, withSafeToolHandler, } from "../responses.js";
+import { MAX_FILTER_LENGTH, clampFilterValue, clampSearchLimit, collectUnknownFilters, searchCountsOutputShape, searchLimitSchema, } from "../search.js";
+import { DEFAULT_SEARCH_LIMIT, MAX_QUERY_LENGTH, MAX_SEARCH_LIMIT, } from "../constants.js";
+import { SEARCH_ICONS_TOOL_NAME } from './constants.js';
+import { getOrLoadIconStore } from "../../stores/hds-icons/index.js";
+export const searchIconsInputShape = {
+    query: z
+        .string()
+        .min(1)
+        .describe("Icon name or keyword, e.g. 'alert', 'triangle', 'arrow-right' or 'warning'. Matched as a case-insensitive substring against the icon name, its description keywords, its category, its Figma mapping and its variant file names."),
+    limit: searchLimitSchema(MAX_SEARCH_LIMIT, DEFAULT_SEARCH_LIMIT),
+    category: z
+        .string()
+        .min(1)
+        .max(MAX_FILTER_LENGTH)
+        .optional()
+        .describe("Restrict to one icon category, e.g. 'Status', 'Arrows', 'Interface' or 'Products'. A value the catalog does not use comes back in unknownFilters alongside the categories that exist."),
+    size: z
+        .string()
+        .min(1)
+        .max(MAX_FILTER_LENGTH)
+        .optional()
+        .describe("Restrict to icons available at one size, such as '16' or '24'. A value the catalog does not use comes back in unknownFilters alongside the sizes that exist."),
+    hasMapping: z
+        .boolean()
+        .optional()
+        .describe("Restrict to icons that do (true) or do not (false) carry a Figma component mapping. Leave unset unless you are reconciling code against the Figma library."),
+};
+const searchIconsResultShape = z.object({
+    // the name passed to <Hds::Icon @name= />, without a size suffix
+    iconName: z.string(),
+    description: z.string(),
+    category: z.string(),
+    sizes: z.array(z.string()),
+    hasMapping: z.boolean(),
+});
+export const searchIconsOutputShape = {
+    query: z.string(),
+    ...searchCountsOutputShape,
+    totalIconCount: z.number().int(),
+    filters: z.object({
+        category: z.string().optional(),
+        size: z.string().optional(),
+        hasMapping: z.boolean().optional(),
+    }),
+    unknownFilters: z.array(z.string()),
+    availableCategories: z.array(z.string()).optional(),
+    availableSizes: z.array(z.string()).optional(),
+    results: z.array(searchIconsResultShape),
+    source: catalogSourceOutputSchema,
+};
+export const searchIconsOutputSchema = z.object(searchIconsOutputShape);
+const DESCRIPTION = [
+    "Find HDS icons — the icon set Helios ships — by name or keyword, from the catalog inside the installed @hashicorp/flight-icons package.",
+    "Each icon's searchable text includes its description keywords, so 'warning' reaches alert-triangle even though the two share no characters.",
+    "Use it to pick the @name value for <Hds::Icon> or <Hds::Button @icon=>, and to confirm an icon exists before writing a name that would render nothing.",
+    "Use the optional size filter when you need an icon available at a particular size; otherwise pick the size at the call site.",
+    "The catalog is read from disk and never fetched. Exact and prefix matches on the icon name rank first, so an icon you named by hand comes back at the top; keyword-only matches rank last. If `truncated` is true, narrow the query or filter by category.",
+].join(" ");
+export const searchIcons = (store, input) => {
+    const meta = store.getMeta();
+    const limit = clampSearchLimit(input.limit, MAX_SEARCH_LIMIT);
+    const query = input.query.slice(0, MAX_QUERY_LENGTH);
+    const category = input.category === undefined ? undefined : clampFilterValue(input.category);
+    const size = input.size === undefined ? undefined : clampFilterValue(input.size);
+    const { totalMatches, hits } = store.searchIcons({
+        query,
+        limit,
+        ...(category === undefined ? {} : { category }),
+        ...(size === undefined ? {} : { size }),
+        ...(input.hasMapping === undefined ? {} : { hasMapping: input.hasMapping }),
+    });
+    const unknownFilters = collectUnknownFilters([
+        { name: "category", value: category, known: meta.categories },
+        { name: "size", value: size, known: meta.sizes },
+    ]);
+    const hasUnknownCategory = unknownFilters.some((filter) => filter.startsWith("category:"));
+    const hasUnknownSize = unknownFilters.some((filter) => filter.startsWith("size:"));
+    return {
+        query,
+        totalMatches,
+        returnedMatches: hits.length,
+        truncated: totalMatches > hits.length,
+        // so `totalMatches` can be read against the size of the catalog it came from
+        totalIconCount: meta.totalIconCount,
+        filters: {
+            ...(category === undefined ? {} : { category }),
+            ...(size === undefined ? {} : { size }),
+            ...(input.hasMapping === undefined
+                ? {}
+                : { hasMapping: input.hasMapping }),
+        },
+        unknownFilters,
+        // only worth spending tokens on the valid values when the filter did not land
+        ...(hasUnknownCategory ? { availableCategories: meta.categories } : {}),
+        ...(hasUnknownSize ? { availableSizes: meta.sizes } : {}),
+        results: hits,
+        source: meta.source,
+    };
+};
+export const createSearchIconsTool = (getStore) => {
+    const executeCallback = withSafeToolHandler(SEARCH_ICONS_TOOL_NAME, (input) => toJsonToolResponse(searchIcons(getStore(), input)));
+    return defineTool({
+        name: SEARCH_ICONS_TOOL_NAME,
+        config: {
+            title: "Search HDS icons",
+            description: DESCRIPTION,
+            inputSchema: searchIconsInputShape,
+            outputSchema: searchIconsOutputShape,
+            annotations: CATALOG_TOOL_ANNOTATIONS,
+        },
+        executeCallback,
+    });
+};
+const searchIconsTool = createSearchIconsTool(getOrLoadIconStore);
+export default searchIconsTool;

package/dist/tools/index.js

@@ -0,0 +1,19 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import componentsTools from "./components/index.js";
+import docsTools from "./docs/index.js";
+import hdsIconsTools from "./hds-icons/index.js";
+import tokensTools from "./tokens/index.js";
+export const TOOLS = [
+    ...componentsTools,
+    ...docsTools,
+    ...hdsIconsTools,
+    ...tokensTools,
+];
+export function registerTools(server) {
+    for (const tool of TOOLS) {
+        tool.register(server);
+    }
+}

package/dist/tools/output-schema.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+import { CATALOG_ANCHORS } from "../catalog/loader.js";
+const catalogSourceOutputSchema = z.object({
+    version: z.string().nullable(),
+    resolvedVia: z.enum(CATALOG_ANCHORS),
+});
+export default catalogSourceOutputSchema;

package/dist/tools/responses.js

@@ -0,0 +1,52 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const toJsonToolResponse = (payload) => {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(payload, null, 2),
+            },
+        ],
+        structuredContent: payload,
+    };
+};
+export const toDocumentToolResponse = (metadata, document) => {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(metadata, null, 2),
+            },
+            {
+                type: "text",
+                text: document,
+            },
+        ],
+        structuredContent: metadata,
+    };
+};
+// this adds the stderr diagnostic and a message naming the tool, so an unreadable
+// catalog degrades to one failed call rather than taking the server down
+export const withSafeToolHandler = (toolName, handler) => {
+    return async (...args) => {
+        try {
+            return await handler(...args);
+        }
+        catch (error) {
+            console.error(`Tool handler failed (${toolName}):`, error);
+            const message = error instanceof Error ? error.message : String(error);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: `${toolName} failed: ${message}`,
+                    },
+                ],
+                isError: true,
+            };
+        }
+    };
+};

package/dist/tools/search.js

@@ -0,0 +1,36 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+import { normalizeLookupValue } from "../catalog/normalize.js";
+export const MAX_FILTER_LENGTH = 256;
+export const clampFilterValue = (value) => {
+    return value.slice(0, MAX_FILTER_LENGTH);
+};
+export const clampSearchLimit = (value, maxLimit) => {
+    return Math.min(Math.max(Math.trunc(value), 1), maxLimit);
+};
+export const searchLimitSchema = (maxLimit, defaultLimit) => {
+    return z
+        .number()
+        .int()
+        .min(1)
+        .max(maxLimit)
+        .default(defaultLimit)
+        .describe(`Maximum results to return (1-${maxLimit}). Defaults to ${defaultLimit}.`);
+};
+export const searchCountsOutputShape = {
+    totalMatches: z.number().int(),
+    returnedMatches: z.number().int(),
+    truncated: z.boolean(),
+};
+export const collectUnknownFilters = (filters) => {
+    return filters.flatMap(({ name, value, known }) => {
+        if (value === undefined)
+            return [];
+        const normalized = normalizeLookupValue(value);
+        const isKnown = known.some((candidate) => normalizeLookupValue(candidate) === normalized);
+        return isKnown ? [] : [`${name}: ${value}`];
+    });
+};

package/dist/tools/tokens/constants.js

@@ -0,0 +1,5 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const SEARCH_TOKENS_TOOL_NAME = "search_hds_tokens";

package/dist/tools/tokens/index.js

@@ -0,0 +1,7 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import searchTokensTool from "./search-tokens.js";
+const TOKENS_TOOLS = [searchTokensTool];
+export default TOKENS_TOOLS;

package/dist/tools/tokens/search-tokens.js

@@ -0,0 +1,144 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+import { SEARCH_TOKENS_TOOL_NAME } from './constants.js';
+import { CATALOG_TOOL_ANNOTATIONS, defineTool } from "../define-tool.js";
+import catalogSourceOutputSchema from "../output-schema.js";
+import { toJsonToolResponse, withSafeToolHandler, } from "../responses.js";
+import { MAX_FILTER_LENGTH, clampFilterValue, clampSearchLimit, collectUnknownFilters, searchCountsOutputShape, searchLimitSchema, } from "../search.js";
+import { DEFAULT_SEARCH_LIMIT, MAX_QUERY_LENGTH, MAX_SEARCH_LIMIT, } from "../constants.js";
+import { getOrLoadTokenStore } from "../../stores/tokens/index.js";
+import { TOKEN_TYPES } from "../../stores/tokens/schema.js";
+export const searchTokensInputShape = {
+    query: z
+        .string()
+        .min(1)
+        .describe("Token name fragment or value, e.g. 'foreground-action', 'border radius', 'blue-200' or '#1060ff'. Matched as a case-insensitive substring against the token key, its CSS variable name, its dotted path and its value."),
+    limit: searchLimitSchema(MAX_SEARCH_LIMIT, DEFAULT_SEARCH_LIMIT),
+    type: z
+        .enum(TOKEN_TYPES)
+        .optional()
+        .describe("Restrict to one token type. 'color' and 'dimension' are the two that carry most of the catalog."),
+    category: z
+        .string()
+        .min(1)
+        .max(MAX_FILTER_LENGTH)
+        .optional()
+        .describe("Restrict to one token category, e.g. 'color', 'border' or 'typography'. A value the catalog does not use comes back in unknownFilters alongside the categories that exist."),
+};
+const searchTokensResultShape = z.object({
+    // the catalog key, in braces: {color.foreground.action}
+    key: z.string(),
+    name: z.string(),
+    // the name to use in CSS: var(--token-color-foreground-action)
+    cssVar: z.string(),
+    type: z.enum(TOKEN_TYPES),
+    // a string for most tokens, an array for the font-family ones
+    value: z.json(),
+    category: z.string(),
+    comment: z.string().optional(),
+    // the unresolved semantic reference, e.g. {color.palette.blue-200}
+    alias: z.string().optional(),
+});
+export const searchTokensOutputShape = {
+    query: z.string(),
+    ...searchCountsOutputShape,
+    totalTokenCount: z.number().int(),
+    filters: z.object({
+        type: z.enum(TOKEN_TYPES).optional(),
+        category: z.string().optional(),
+    }),
+    unknownFilters: z.array(z.string()),
+    availableCategories: z.array(z.string()).optional(),
+    results: z.array(searchTokensResultShape),
+    source: catalogSourceOutputSchema,
+};
+// the payload type is derived from the declared schema, so a drift between the two is a
+// compile error rather than a runtime output-validation failure
+export const searchTokensOutputSchema = z.object(searchTokensOutputShape);
+const DESCRIPTION = [
+    "Find Helios design tokens by name or value, from the token catalog inside the installed @hashicorp/design-system-tokens package.",
+    "Every result carries the cssVar to write in a stylesheet — var(--token-color-foreground-action) — so use this to replace a hard-coded color, spacing or radius with the token that holds it.",
+    "The query matches the token value too, so searching a hex code finds which token already defines it.",
+    "The catalog is read from disk and never fetched. Exact and prefix matches on the token key, name or CSS variable rank first, so a token you named by hand comes back at the top; value-only matches rank last. If `truncated` is true, narrow the query or filter by type.",
+].join(" ");
+export const searchTokens = (store, input) => {
+    const meta = store.getMeta();
+    const limit = clampSearchLimit(input.limit, MAX_SEARCH_LIMIT);
+    // both the query and the category are echoed back, so they are bounded before they are
+    // repeated rather than only at the declared schema; `type` is closed over TOKEN_TYPES
+    const query = input.query.slice(0, MAX_QUERY_LENGTH);
+    const category = input.category === undefined ? undefined : clampFilterValue(input.category);
+    const { totalMatches, hits } = store.searchTokens({
+        query,
+        limit,
+        ...(input.type === undefined ? {} : { type: input.type }),
+        ...(category === undefined ? {} : { category }),
+    });
+    const unknownFilters = collectUnknownFilters([
+        { name: "category", value: category, known: meta.categories },
+    ]);
+    return {
+        query,
+        totalMatches,
+        returnedMatches: hits.length,
+        truncated: totalMatches > hits.length,
+        // so `totalMatches` can be read against the size of the catalog it came from
+        totalTokenCount: meta.totalTokenCount,
+        filters: {
+            ...(input.type === undefined ? {} : { type: input.type }),
+            ...(category === undefined ? {} : { category }),
+        },
+        unknownFilters,
+        // only worth spending tokens on the valid values when the filter did not land
+        ...(unknownFilters.length === 0
+            ? {}
+            : { availableCategories: meta.categories }),
+        /**
+         * Two fields of the store summary are dropped rather than forwarded. `attributes` is the
+         * raw catalog record's own metadata and repeats `category` verbatim. `path` is `key` with
+         * its braces stripped and split on dots, which cost 24% of the payload to say nothing the
+         * key does not already say — and a bounded payload is the whole reason these tools exist.
+         */
+        results: hits.map((token) => ({
+            key: token.key,
+            name: token.name,
+            cssVar: token.cssVar,
+            type: token.type,
+            value: toResultValue(token.value),
+            category: token.category,
+            ...(token.comment === undefined ? {} : { comment: token.comment }),
+            ...(token.alias === undefined ? {} : { alias: token.alias }),
+        })),
+        source: meta.source,
+    };
+};
+/**
+ * Thirteen tokens carry an inlined SVG data url, up to 528 characters each, which is enough to
+ * make a full result four times the size of the same search over any other category. The head of
+ * one still identifies it; nobody reconstructs an icon from a search result.
+ */
+const MAX_VALUE_LENGTH = 120;
+const toResultValue = (value) => {
+    if (typeof value !== "string" || value.length <= MAX_VALUE_LENGTH)
+        return value;
+    return `${value.slice(0, MAX_VALUE_LENGTH)}…`;
+};
+export const createSearchTokensTool = (getStore) => {
+    const executeCallback = withSafeToolHandler(SEARCH_TOKENS_TOOL_NAME, (input) => toJsonToolResponse(searchTokens(getStore(), input)));
+    return defineTool({
+        name: SEARCH_TOKENS_TOOL_NAME,
+        config: {
+            title: "Search HDS design tokens",
+            description: DESCRIPTION,
+            inputSchema: searchTokensInputShape,
+            outputSchema: searchTokensOutputShape,
+            annotations: CATALOG_TOOL_ANNOTATIONS,
+        },
+        executeCallback,
+    });
+};
+const searchTokensTool = createSearchTokensTool(getOrLoadTokenStore);
+export default searchTokensTool;

package/dist/tools/types.js

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

package/dist/types.js

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