MCP - Add tokens resource

[zamoore]

📌 Summary

Adds MCP token resources on top of the shared resource infra branch by wiring in a tokens catalog index/detail API (hds://tokens and hds://tokens/{tokenKey}).

🛠️ Detailed description

• Registers token resources in packages/mcp/src/resources/index.ts.
• Introduces token resource implementation in packages/mcp/src/resources/tokens.ts:
  • get_hds_tokens for full catalog summaries
  • get_hds_token for token lookup by key/path/name
  • lazy-loaded in-memory token store and JSON-serializable payload shaping.
• Adds token store infrastructure in packages/mcp/src/resources/stores/tokens/:
  • schema.ts for Zod parsing/typing of token catalog rows
  • lookup.ts for normalization, token typing, and lookup key generation
  • store.ts for loading @hashicorp/design-system-tokens docs JSON, indexing, list/get/search support.

Copilot instructions

Focus review on:

• URI/resource contract correctness (hds://tokens, template variable handling, not-found/missing-key responses).
• Type safety and MCP SDK compatibility in withSafeResourceHandler and toJsonResourceResponse.
• Token normalization/indexing behavior (brace stripping, key/path/name lookup aliases, category/type filtering semantics).
• Serialization safety for unknown token $value / original payload shapes.

🔗 External links

Jira ticket: HDS-6483

---

💬 Please consider using conventional comments when reviewing this PR.

📋 PCI review checklist

• If applicable, I've documented a plan to revert these changes if they require more than reverting the pull request.
• If applicable, I've worked with GRC to document the impact of any changes to security controls.
  Examples of changes to controls include access controls, encryption, logging, etc.
• If applicable, I've worked with GRC to ensure compliance due to a significant change to the in-scope PCI environment.
  Examples include changes to operating systems, ports, protocols, services, cryptography-related components, PII processing code, etc.

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
hds-showcase	Ready	Preview	Aug 4, 2026 1:10am
hds-website	Ready	Preview	Aug 4, 2026 1:10am

[Copilot]

Pull request overview

Adds MCP token resources to the packages/mcp server so clients can query the HDS token catalog via hds://tokens (index) and hds://tokens/{tokenKey} (detail), backed by a lazily loaded in-memory store sourced from @hashicorp/design-system-tokens.

Changes:

• Registers new token MCP resources and wraps all resource handlers with a safe error-response wrapper.
• Implements token index/detail resources with JSON-serializable shaping for unknown $value / original token payloads.
• Adds token catalog store utilities (Zod schema parsing, lookup key normalization, indexing, and search helpers).

Reviewed changes

Copilot reviewed 6 out of 6 changed files in this pull request and generated 4 comments.

Show a summary per file

File	Description
packages/mcp/src/resources/utils.ts	Updates resource response typing to MCP SDK ReadResourceResult and standardizes safe handler wrapping.
packages/mcp/src/resources/index.ts	Registers token resources and wraps readCallbacks with withSafeResourceHandler.
packages/mcp/src/resources/tokens.ts	Introduces hds://tokens and hds://tokens/{tokenKey} resources and JSON-safe serialization helpers.
packages/mcp/src/resources/stores/tokens/store.ts	Adds loader/index for the published tokens catalog JSON plus list/get/search APIs.
packages/mcp/src/resources/stores/tokens/schema.ts	Defines Zod schemas/types for token catalog rows and token typing.
packages/mcp/src/resources/stores/tokens/lookup.ts	Adds normalization, token typing, summary/record shaping, and lookup key generation.

[Copilot]

Pull request overview

Copilot reviewed 6 out of 6 changed files in this pull request and generated 5 comments.

[Copilot]

Pull request overview

Copilot reviewed 20 out of 21 changed files in this pull request and generated 3 comments.

Files not reviewed (1)

• pnpm-lock.yaml: Generated file

[dchyun]

Tested server locally and all queries produced expected results. Note: This schema will have to be updated once the Carbonization work is merged.

[dchyun]

[Suggestion] Would it be useful to support a query being done with the cssVar name as well? We could have something here to strip out -- from the query.

I'm not sure how the AI interacts with the MCP server commands, but I'm curious if an AI ran into an HDS CSS variable if it would have the context to use the command with a properly formatted query or if it would try searching with the CSS variable name.

[zamoore]

Agreed, good call. Added -- stripping directly into normalizeTokenLookupKey alongside the existing curly brace handling, so CSS var lookup works automatically everywhere.

[dchyun]

[Suggestion] Do we want to test for other query options as well? Or is that already covered enough by the completeTokenKeys test?

Cases we could cover

• {color.foreground.action} (already tested here)
• color.foreground.action
• COLOR.FOREGROUND.ACTION
• color-foreground-action

[zamoore]

The readCallback test in this file is specifically testing URI decode behavior (the %7B...%7D → {color.foreground.action} path), so the callback test itself doesn't need to be exhaustive on query formats