@hashicorp/design-system-mcp 0.1.0

package/dist/stores/tokens/index.js

@@ -0,0 +1,105 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { normalizeLookupValue } from "../../catalog/normalize.js";
+import { DEFAULT_CATALOG_SOURCE, createCatalogLoader, } from "../../catalog/loader.js";
+import { getTokenLookupKeys, normalizeTokenLookupKey, toTokenRecord, } from "./lookup.js";
+import { tokenCatalogSchema } from "./schema.js";
+import { searchRanked } from "../rank.js";
+const toSearchBlob = (token) => {
+    const path = token.path.join(" ");
+    const category = token.category ?? "";
+    const value = typeof token.value === "string"
+        ? token.value
+        : (JSON.stringify(token.value) ?? "");
+    return [
+        token.key,
+        token.name,
+        token.cssVar ?? "",
+        path,
+        category,
+        value,
+        token.comment ?? "",
+        token.alias ?? "",
+    ]
+        .join(" ")
+        .toLowerCase();
+};
+// the catalog key, the generated name and the CSS variable, all of which a caller may paste;
+// the value stays in the blob so searching a hex code still finds the token that defines it
+const toRankable = (token) => {
+    return {
+        identities: [
+            normalizeTokenLookupKey(token.key),
+            normalizeLookupValue(token.name),
+            normalizeLookupValue(token.cssVar ?? ""),
+            normalizeLookupValue(token.path.join(".")),
+        ],
+        blob: toSearchBlob(token),
+    };
+};
+export const parseTokenCatalog = (value) => {
+    return tokenCatalogSchema.parse(value);
+};
+export const createTokenCatalogStore = (rows, source = DEFAULT_CATALOG_SOURCE) => {
+    const tokenRecords = rows.map((row) => toTokenRecord(row));
+    const tokenLookup = new Map();
+    for (const [index, row] of rows.entries()) {
+        const token = tokenRecords[index];
+        if (token === undefined) {
+            continue;
+        }
+        for (const key of getTokenLookupKeys(row)) {
+            tokenLookup.set(key, token);
+        }
+    }
+    const categories = [
+        ...new Set(tokenRecords.map((token) => token.category)),
+    ].sort((left, right) => left.localeCompare(right));
+    return {
+        getMeta: () => ({
+            totalTokenCount: tokenRecords.length,
+            categories,
+            source,
+        }),
+        listTokens: () => 
+        // eslint-disable-next-line @typescript-eslint/no-unused-vars
+        tokenRecords.map(({ original: _original, ...summary }) => summary),
+        getTokenByKey: (key) => {
+            return tokenLookup.get(normalizeTokenLookupKey(key)) ?? null;
+        },
+        searchTokens: ({ query, limit, type, category }) => {
+            const normalizedCategory = category === undefined ? null : normalizeLookupValue(category);
+            const { totalMatches, hits } = searchRanked({
+                records: tokenRecords,
+                query,
+                limit,
+                toRankable,
+                matches: (token) => {
+                    if (type !== undefined && token.type !== type) {
+                        return false;
+                    }
+                    return (normalizedCategory === null ||
+                        normalizeLookupValue(token.category ?? "") === normalizedCategory);
+                },
+            });
+            return {
+                totalMatches,
+                // eslint-disable-next-line @typescript-eslint/no-unused-vars
+                hits: hits.map(({ original: _original, ...summary }) => summary),
+            };
+        },
+    };
+};
+const tokenCatalogLoader = createCatalogLoader({
+    specifier: "@hashicorp/design-system-tokens/dist/docs/products/tokens.json",
+    anchors: ["project-root", "components", "default"],
+    create: (value, source) => createTokenCatalogStore(parseTokenCatalog(value), source),
+});
+export const loadTokenCatalog = () => {
+    return tokenCatalogLoader.load();
+};
+export const getOrLoadTokenStore = () => {
+    return tokenCatalogLoader.getOrLoad();
+};

package/dist/stores/tokens/lookup.js

@@ -0,0 +1,65 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { TOKEN_TYPES } from "./schema.js";
+import { normalizeLookupValue } from "../../catalog/normalize.js";
+const KNOWN_TOKEN_TYPE_LOOKUP = new Set(TOKEN_TYPES);
+const trimTokenBraces = (value) => {
+    return value.replace(/^\{/u, "").replace(/\}$/u, "");
+};
+const trimCssVarPrefix = (value) => {
+    return value.replace(/^--/u, "");
+};
+export const normalizeTokenLookupKey = (value) => {
+    return trimCssVarPrefix(trimTokenBraces(normalizeLookupValue(value)));
+};
+export const toTokenType = (value) => {
+    if (value === undefined) {
+        return "other";
+    }
+    const normalized = value.trim();
+    if (KNOWN_TOKEN_TYPE_LOOKUP.has(normalized)) {
+        return normalized;
+    }
+    return "other";
+};
+export const toCssVarName = (tokenName) => {
+    return `--${tokenName}`;
+};
+const TOKEN_ALIAS_PATTERN = /^\{[^{}]+\}$/u;
+export const toTokenAlias = (original) => {
+    const value = original?.$value;
+    return typeof value === "string" && TOKEN_ALIAS_PATTERN.test(value)
+        ? value
+        : undefined;
+};
+export const toTokenSummary = (row) => {
+    const alias = toTokenAlias(row.original);
+    return {
+        key: row.key,
+        name: row.name,
+        attributes: row.attributes,
+        type: toTokenType(row.$type),
+        value: row.$value,
+        cssVar: toCssVarName(row.name),
+        category: row.attributes.category,
+        path: row.path,
+        ...(row.comment === undefined ? {} : { comment: row.comment }),
+        ...(alias === undefined ? {} : { alias }),
+    };
+};
+export const toTokenRecord = (row) => {
+    return {
+        ...toTokenSummary(row),
+        ...(row.original === undefined ? {} : { original: row.original }),
+    };
+};
+export const getTokenLookupKeys = (row) => {
+    const dotPath = row.path.join(".");
+    return [
+        normalizeTokenLookupKey(row.key),
+        normalizeTokenLookupKey(dotPath),
+        normalizeTokenLookupKey(row.name),
+    ];
+};

package/dist/stores/tokens/schema.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+export const TOKEN_TYPES = [
+    "color",
+    "cubicBezier",
+    "dimension",
+    "duration",
+    "font-family",
+    "font-weight",
+    "font-size",
+    "letter-spacing",
+    "number",
+    "other",
+];
+const tokenAttributesSchema = z
+    .object({
+    category: z.string().min(1),
+})
+    .catchall(z.any());
+const tokenOriginalSchema = z
+    .object({
+    $type: z.string().min(1).optional(),
+    $value: z.json().optional(),
+    key: z.string().optional(),
+})
+    .catchall(z.json());
+export const tokenCatalogRowSchema = z
+    .object({
+    key: z.string().min(1),
+    $type: z.string().min(1).optional(),
+    $value: z.json(),
+    name: z.string().min(1),
+    comment: z.string().min(1).optional(),
+    attributes: tokenAttributesSchema,
+    path: z.array(z.string().min(1)),
+    original: tokenOriginalSchema.optional(),
+})
+    .catchall(z.any());
+export const tokenCatalogSchema = z.array(tokenCatalogRowSchema);

package/dist/stores/types.js

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

package/dist/tools/components/constants.js

@@ -0,0 +1,15 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const SEARCH_COMPONENTS_TOOL_NAME = "search_hds_components";
+export const GET_COMPONENT_TOOL_NAME = "get_hds_component";
+/**
+ * Enum sizes in the catalog are bimodal: 164 arguments carry 15 values or fewer, and the
+ * remaining 43 carry either 112 (HTML tag names) or 675 (icon names), because the generator
+ * hoists anything over 50 into a shared value set. A cap of 25 therefore never truncates a
+ * real enum, and always truncates the two reference lists that would otherwise make a single
+ * component's API 30KB.
+ */
+export const MAX_ARG_VALUES = 25;
+export const NOT_FOUND_SUGGESTION_LIMIT = 5;

package/dist/tools/components/get-component.js

@@ -0,0 +1,98 @@
+/**
+ * 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 } from "../search.js";
+import { GET_COMPONENT_TOOL_NAME, MAX_ARG_VALUES, NOT_FOUND_SUGGESTION_LIMIT, SEARCH_COMPONENTS_TOOL_NAME, } from "./constants.js";
+import { SEARCH_ICONS_TOOL_NAME } from "../hds-icons/constants.js";
+import { getOrLoadComponentStore } from "../../stores/components/index.js";
+import { toSerializableComponentApi } from "./utils.js";
+export const getComponentInputShape = {
+    name: z
+        .string()
+        .min(1)
+        .max(MAX_FILTER_LENGTH)
+        .describe("Component name. Accepts the template invocation ('Hds::Button'), the imported class name ('HdsButton'), the bare name ('button') or the module path ('hds/button'). Case-insensitive, and the Hds:: namespace is optional."),
+};
+const componentArgOutputSchema = z.object({
+    // the argument name without its `@` sigil, as it appears in the signature
+    name: z.string(),
+    type: z.string(),
+    required: z.boolean(),
+    values: z.array(z.string()).optional(),
+    // the real length when `values` was capped, so a caller knows what it is not seeing
+    valuesCount: z.number().int().optional(),
+    valuesTruncated: z.boolean().optional(),
+    // the module an inherited argument actually comes from, e.g. `hds/interactive`
+    inheritedFrom: z.string().optional(),
+});
+const componentApiOutputSchema = z.object({
+    name: z.string(),
+    modulePath: z.string(),
+    docsPath: z.string().optional(),
+    element: z.string().optional(),
+    args: z.array(componentArgOutputSchema),
+    blocks: z.array(z.object({
+        name: z.string(),
+        yields: z.array(z.object({ name: z.string(), type: z.string() })),
+    })),
+});
+export const getComponentOutputShape = {
+    found: z.boolean(),
+    requestedName: z.string(),
+    component: componentApiOutputSchema.optional(),
+    message: z.string().optional(),
+    suggestions: z.array(z.string()).optional(),
+    source: catalogSourceOutputSchema,
+};
+export const getComponentOutputSchema = z.object(getComponentOutputShape);
+const DESCRIPTION = [
+    "Read the full API of one Helios Design System component: every argument with its type, whether it is required and which values it accepts, plus the blocks it takes and the contextual components it yields.",
+    "The data is generated from the TypeScript declarations of the installed @hashicorp/design-system-components package, so it is the authoritative answer to 'what arguments does this take' — prefer it over prose documentation, which can lag the code.",
+    `Pass the template invocation, the class name, the bare name or the module path. When the name does not resolve, ${SEARCH_COMPONENTS_TOOL_NAME} results come back as suggestions rather than an error.`,
+    `An argument's \`values\` list is capped at ${MAX_ARG_VALUES}; when \`valuesTruncated\` is true, \`valuesCount\` holds the real total. In practice only icon-name and HTML-tag arguments hit the cap — use ${SEARCH_ICONS_TOOL_NAME} to pick an icon name.`,
+    "Yielded contextual components are listed by the name they take inside the block. Their own arguments are separate catalog entries, so look up 'Hds::Alert::Title' to see what [A].Title accepts.",
+    "The catalog is read from disk and never fetched.",
+].join(" ");
+export const getComponent = (store, input) => {
+    const meta = store.getMeta();
+    // bounded before it is echoed back, rather than only at the declared schema
+    const requestedName = clampFilterValue(input.name);
+    const component = store.getComponentByName(requestedName);
+    if (component === null) {
+        const suggestions = store.suggestComponentNames(requestedName, NOT_FOUND_SUGGESTION_LIMIT);
+        return {
+            found: false,
+            requestedName,
+            message: `No Helios component resolves to "${requestedName}". Use ${SEARCH_COMPONENTS_TOOL_NAME} to find the exact invocation name.`,
+            ...(suggestions.length === 0 ? {} : { suggestions }),
+            source: meta.source,
+        };
+    }
+    return {
+        found: true,
+        requestedName,
+        component: toSerializableComponentApi(component),
+        source: meta.source,
+    };
+};
+export const createGetComponentTool = (getStore) => {
+    const executeCallback = withSafeToolHandler(GET_COMPONENT_TOOL_NAME, (input) => toJsonToolResponse(getComponent(getStore(), input)));
+    return defineTool({
+        name: GET_COMPONENT_TOOL_NAME,
+        config: {
+            title: "Get an HDS component API",
+            description: DESCRIPTION,
+            inputSchema: getComponentInputShape,
+            outputSchema: getComponentOutputShape,
+            annotations: CATALOG_TOOL_ANNOTATIONS,
+        },
+        executeCallback,
+    });
+};
+const getComponentTool = createGetComponentTool(getOrLoadComponentStore);
+export default getComponentTool;

package/dist/tools/components/index.js

@@ -0,0 +1,11 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import getComponentTool from "./get-component.js";
+import searchComponentsTool from "./search-components.js";
+const COMPONENTS_TOOLS = [
+    searchComponentsTool,
+    getComponentTool,
+];
+export default COMPONENTS_TOOLS;

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

@@ -0,0 +1,75 @@
+/**
+ * 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 { toJsonToolResponse, withSafeToolHandler } from "../responses.js";
+import { clampSearchLimit, searchCountsOutputShape, searchLimitSchema, } from "../search.js";
+import catalogSourceOutputSchema from "../output-schema.js";
+import { DEFAULT_SEARCH_LIMIT, MAX_QUERY_LENGTH, MAX_SEARCH_LIMIT, } from "../constants.js";
+import { GET_COMPONENT_TOOL_NAME, SEARCH_COMPONENTS_TOOL_NAME, } from "./constants.js";
+import { SEARCH_DOCS_TOOL_NAME } from "../docs/constants.js";
+import { getOrLoadComponentStore } from "../../stores/components/index.js";
+export const searchComponentsInputShape = {
+    query: z
+        .string()
+        .min(1)
+        .describe("Component name fragment, e.g. 'button', 'advanced table', 'Hds::Flyout' or 'HdsCopyButton'. Matched as a case-insensitive substring against the invocation name, the class name, the module path and the docs route."),
+    limit: searchLimitSchema(MAX_SEARCH_LIMIT, DEFAULT_SEARCH_LIMIT),
+};
+const searchComponentsResultShape = z.object({
+    // the invocation name, as it is written in a template: Hds::AdvancedTable::Th
+    name: z.string(),
+    modulePath: z.string(),
+    docsPath: z.string().optional(),
+});
+export const searchComponentsOutputShape = {
+    query: z.string(),
+    ...searchCountsOutputShape,
+    totalComponentCount: z.number().int(),
+    results: z.array(searchComponentsResultShape),
+    source: catalogSourceOutputSchema,
+};
+export const searchComponentsOutputSchema = z.object(searchComponentsOutputShape);
+const DESCRIPTION = [
+    "Find Helios Design System components by name, from the component catalog shipped inside the installed @hashicorp/design-system-components package.",
+    "This is a name lookup, not a question answerer: it matches a substring against each component's invocation name, class name, module path and docs route. Pass 'advanced table' or 'Hds::Flyout', not 'how do I make a table sortable'.",
+    "Use it to confirm a component exists and to recover its exact invocation name and spelling before writing a template.",
+    `Results are intentionally concise. Follow up with ${GET_COMPONENT_TOOL_NAME} for a component's arguments, accepted values, blocks and yielded contextual components. Use ${SEARCH_DOCS_TOOL_NAME} with the result's docsPath for usage guidance, examples, accessibility guidance and design recommendations. Every documented component carries a docsPath; Hds::Yield is the sole exception.`,
+    "The catalog is read from disk and never fetched. Exact and prefix matches rank first, so if `truncated` is true, narrow the query or use the first results as the most relevant matches.",
+].join(" ");
+export const searchComponents = (store, input) => {
+    const meta = store.getMeta();
+    const limit = clampSearchLimit(input.limit, MAX_SEARCH_LIMIT);
+    // the query is echoed back, so it is bounded before it is repeated rather than only at the
+    // declared schema; truncating beats refusing a caller that pasted something long
+    const query = input.query.slice(0, MAX_QUERY_LENGTH);
+    const { totalMatches, hits } = store.searchComponents({ query, limit });
+    return {
+        query,
+        totalMatches,
+        returnedMatches: hits.length,
+        truncated: totalMatches > hits.length,
+        // so `totalMatches` can be read against the size of the catalog it came from
+        totalComponentCount: meta.totalComponentCount,
+        results: hits,
+        source: meta.source,
+    };
+};
+export const createSearchComponentsTool = (getStore) => {
+    const executeCallback = withSafeToolHandler(SEARCH_COMPONENTS_TOOL_NAME, (input) => toJsonToolResponse(searchComponents(getStore(), input)));
+    return defineTool({
+        name: SEARCH_COMPONENTS_TOOL_NAME,
+        config: {
+            title: "Search HDS components",
+            description: DESCRIPTION,
+            inputSchema: searchComponentsInputShape,
+            outputSchema: searchComponentsOutputShape,
+            annotations: CATALOG_TOOL_ANNOTATIONS,
+        },
+        executeCallback,
+    });
+};
+const searchComponentsTool = createSearchComponentsTool(getOrLoadComponentStore);
+export default searchComponentsTool;

package/dist/tools/components/utils.js

@@ -0,0 +1,42 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { MAX_ARG_VALUES } from "./constants.js";
+// `valuesCount` and `valuesTruncated` are only present when the cap actually bit, so the
+// common case stays as small as it reads
+export const toSerializableArg = (arg) => {
+    const isTruncated = arg.values !== undefined && arg.values.length > MAX_ARG_VALUES;
+    return {
+        name: arg.name,
+        type: arg.type,
+        required: arg.required,
+        ...(arg.values === undefined
+            ? {}
+            : { values: arg.values.slice(0, MAX_ARG_VALUES) }),
+        ...(isTruncated
+            ? { valuesCount: arg.values?.length, valuesTruncated: true }
+            : {}),
+        ...(arg.inheritedFrom === undefined
+            ? {}
+            : { inheritedFrom: arg.inheritedFrom }),
+    };
+};
+export const toSerializableComponentApi = (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) => toSerializableArg(arg)),
+        blocks: component.blocks.map((block) => ({
+            name: block.name,
+            yields: block.yields.map((blockYield) => ({
+                name: blockYield.name,
+                type: blockYield.type,
+            })),
+        })),
+    };
+};

package/dist/tools/constants.js

@@ -0,0 +1,7 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const DEFAULT_SEARCH_LIMIT = 20;
+export const MAX_SEARCH_LIMIT = 50;
+export const MAX_QUERY_LENGTH = 200;

package/dist/tools/define-tool.js

@@ -0,0 +1,17 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const defineTool = (tool) => {
+    return {
+        name: tool.name,
+        register: (server) => {
+            server.registerTool(tool.name, tool.config, tool.executeCallback);
+        },
+    };
+};
+export const CATALOG_TOOL_ANNOTATIONS = {
+    readOnlyHint: true,
+    idempotentHint: true,
+    openWorldHint: false,
+};

package/dist/tools/docs/constants.js

@@ -0,0 +1,33 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+export const SEARCH_DOCS_TOOL_NAME = "search_hds_docs";
+export const READ_DOCS_TOOL_NAME = "read_hds_docs";
+export const DEFAULT_SEARCH_LIMIT = 8;
+// cap keeps a search from ever approaching limits
+export const MAX_SEARCH_LIMIT = 25;
+export const MAX_QUERY_LENGTH = 2_000;
+export const DEFAULT_READ_MAX_BYTES = 16_000;
+export const MIN_READ_MAX_BYTES = 500;
+export const MAX_READ_MAX_BYTES = 60_000;
+export const VERSION_HISTORY_TAB = "Version history";
+export const DOCS_TABS = [
+    "Accessibility",
+    "Code",
+    "Components",
+    "Content",
+    "Core concepts",
+    "Design tokens",
+    "Figma Libraries",
+    "Flight Icons",
+    "Guidelines",
+    "Interaction concepts",
+    "Library",
+    "Palette",
+    "Research",
+    "Resources",
+    "Specifications",
+    "Validation",
+    VERSION_HISTORY_TAB,
+];

package/dist/tools/docs/index.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import readDocTool from "./read-doc.js";
+import searchDocsTool from "./search-docs.js";
+const DOCS_TOOLS = [searchDocsTool, readDocTool];
+export default DOCS_TOOLS;

package/dist/tools/docs/read-doc.js

@@ -0,0 +1,101 @@
+/**
+ * Copyright IBM Corp. 2021, 2026
+ * SPDX-License-Identifier: MPL-2.0
+ */
+import { z } from "zod";
+import { defineTool } from "../define-tool.js";
+import { toDocumentToolResponse, toJsonToolResponse, withSafeToolHandler, } from "../responses.js";
+import { clampFilterValue, MAX_FILTER_LENGTH } from "../search.js";
+import { DEFAULT_READ_MAX_BYTES, MAX_READ_MAX_BYTES, MIN_READ_MAX_BYTES, READ_DOCS_TOOL_NAME, SEARCH_DOCS_TOOL_NAME, } from "./constants.js";
+import { getOrLoadDocsStore } from "../../stores/docs/index.js";
+import { getHeadingPath } from "../../stores/docs/lookup.js";
+import { selectChunkContent, toSerializablePageLinks } from "./utils.js";
+export const readDocInputShape = {
+    id: z
+        .string()
+        .min(1)
+        .max(MAX_FILTER_LENGTH)
+        .describe(`Passage id from a ${SEARCH_DOCS_TOOL_NAME} result, e.g. 'components/button#code/how-to-use-this-component/full-width'.`),
+    includeChildren: z
+        .boolean()
+        .default(false)
+        .describe("Also return the passages nested under this heading. Use when the passage is a section header whose detail lives in its subsections."),
+    maxBytes: z
+        .number()
+        .int()
+        .min(MIN_READ_MAX_BYTES)
+        .max(MAX_READ_MAX_BYTES)
+        .default(DEFAULT_READ_MAX_BYTES)
+        .describe(`Byte cap on the returned markdown (${MIN_READ_MAX_BYTES}-${MAX_READ_MAX_BYTES}). Defaults to ${DEFAULT_READ_MAX_BYTES}.`),
+};
+const DESCRIPTION = [
+    "Read one passage of the bundled Helios Design System documentation by id, as markdown.",
+    `Ids come from ${SEARCH_DOCS_TOOL_NAME}; run that first rather than guessing an id.`,
+    "The returned markdown keeps the <Doc::*> and <Hds::*> usage examples and the inlined code snippets, which is what search snippets strip out.",
+    "The corpus is a snapshot committed into this server: nothing is fetched. The first content block carries the canonical URL and the bundledAt timestamp so a client can fetch the live page itself.",
+].join(" ");
+export const readDoc = (store, input) => {
+    const meta = store.getMeta();
+    const requestedId = clampFilterValue(input.id);
+    const chunk = store.getChunkById(requestedId);
+    if (chunk === null) {
+        return toJsonToolResponse({
+            found: false,
+            requestedId,
+            message: `No documentation passage found for id "${requestedId}". Ids come from ${SEARCH_DOCS_TOOL_NAME} results.`,
+            suggestions: store.suggestChunkIds(requestedId),
+            bundledAt: meta.bundledAt,
+            siteBaseUrl: meta.siteBaseUrl,
+        });
+    }
+    const children = store.getChildChunks(chunk.id);
+    const requested = input.includeChildren ? [chunk, ...children] : [chunk];
+    const { content, truncated, includedIds, omittedIds } = selectChunkContent(requested, input.maxBytes);
+    const page = store.getPageByRoute(chunk.route);
+    const links = page === null ? undefined : toSerializablePageLinks(page);
+    return toDocumentToolResponse({
+        found: true,
+        id: chunk.id,
+        title: chunk.pageTitle,
+        route: chunk.route,
+        docsPath: chunk.route,
+        section: chunk.section,
+        ...(chunk.tab === undefined ? {} : { tab: chunk.tab }),
+        headingPath: getHeadingPath(chunk),
+        ...(chunk.level === undefined ? {} : { level: chunk.level }),
+        url: chunk.url,
+        pageUrl: chunk.pageUrl,
+        ...(page === null || page.related.length === 0
+            ? {}
+            : { relatedDocsPaths: page.related }),
+        ...(links === undefined ? {} : { links }),
+        ...(page?.status === undefined ? {} : { status: page.status }),
+        includedChunkIds: includedIds,
+        ...(omittedIds.length === 0 ? {} : { omittedChunkIds: omittedIds }),
+        childChunkCount: children.length,
+        contentBytes: Buffer.byteLength(content, "utf8"),
+        truncated,
+        bundledAt: meta.bundledAt,
+        siteBaseUrl: meta.siteBaseUrl,
+        provenance: `Bundled snapshot of ${meta.siteBaseUrl} taken at ${meta.bundledAt}. Fetch ${chunk.url} for the live page.`,
+    }, content);
+};
+export const createReadDocTool = (getStore) => {
+    const executeCallback = withSafeToolHandler(READ_DOCS_TOOL_NAME, (input) => readDoc(getStore(), input));
+    return defineTool({
+        name: READ_DOCS_TOOL_NAME,
+        config: {
+            title: "Read an HDS documentation passage",
+            description: DESCRIPTION,
+            inputSchema: readDocInputShape,
+            annotations: {
+                readOnlyHint: true,
+                idempotentHint: true,
+                openWorldHint: false,
+            },
+        },
+        executeCallback,
+    });
+};
+const readDocTool = createReadDocTool(getOrLoadDocsStore);
+export default readDocTool;