@hashicorp/design-system-mcp 0.2.2 → 0.2.3-rc-20261030172200
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +175 -32
- package/dist/tools/docs/constants.js +0 -20
- package/dist/tools/docs/search-docs.js +4 -3
- package/docs-catalog.json +3226 -387
- package/package.json +3 -3
package/README.md
CHANGED
|
@@ -1,38 +1,87 @@
|
|
|
1
|
-
#
|
|
1
|
+
# Helios Design System MCP server
|
|
2
2
|
|
|
3
|
-
|
|
3
|
+
Give your AI assistant access to [Helios Design System](https://helios.hashicorp.design) component APIs, design tokens, icons, and usage guidance through the [Model Context Protocol (MCP)](https://modelcontextprotocol.io/).
|
|
4
4
|
|
|
5
|
-
|
|
5
|
+
The `@hashicorp/design-system-mcp` package helps your assistant:
|
|
6
6
|
|
|
7
|
-
|
|
7
|
+
- Find Ember components and look up their arguments, accepted values, blocks, and yielded components.
|
|
8
|
+
- Choose design tokens by name or value and retrieve their CSS variables.
|
|
9
|
+
- Find Flight icons by name, keyword, category, or size.
|
|
10
|
+
- Read documentation examples, accessibility guidance, and design recommendations.
|
|
11
|
+
- Follow guided workflows for choosing, implementing, reviewing, and troubleshooting Helios components.
|
|
12
|
+
|
|
13
|
+
The server runs locally over **stdio**. Its tools are read-only and query local catalogs without making network requests. No API key or account is required.
|
|
14
|
+
|
|
15
|
+
## Contents
|
|
16
|
+
|
|
17
|
+
- [Getting started](#getting-started)
|
|
18
|
+
- [Usage](#usage)
|
|
19
|
+
- [Tools, prompts, and resources](#tools-prompts-and-resources)
|
|
20
|
+
- [Data sources and configuration](#data-sources-and-configuration)
|
|
21
|
+
- [Troubleshooting](#troubleshooting)
|
|
22
|
+
- [Contributing](#contributing)
|
|
23
|
+
- [License](#license)
|
|
24
|
+
- [Versioning](#versioning)
|
|
25
|
+
|
|
26
|
+
## Getting started
|
|
27
|
+
|
|
28
|
+
### Compatibility
|
|
29
|
+
|
|
30
|
+
- [Node.js](https://nodejs.org/) 24 or later.
|
|
31
|
+
- [pnpm](https://pnpm.io/installation) for the commands below.
|
|
32
|
+
- An MCP client that supports local stdio servers, such as Claude Code, Claude Desktop, Cursor, or VS Code with GitHub Copilot.
|
|
33
|
+
|
|
34
|
+
### 1. Install in your application
|
|
35
|
+
|
|
36
|
+
Run this from the application whose Helios packages you want to query:
|
|
8
37
|
|
|
9
38
|
```bash
|
|
10
39
|
pnpm add --save-dev @hashicorp/design-system-mcp
|
|
11
40
|
```
|
|
12
41
|
|
|
13
|
-
|
|
42
|
+
Local installation records the server version in your application's lockfile and lets it resolve your installed Helios catalogs. It runs as a separate development tool; do not import it into your application or include it in your production bundle.
|
|
14
43
|
|
|
15
|
-
|
|
44
|
+
### 2. Connect your MCP client
|
|
16
45
|
|
|
17
|
-
|
|
46
|
+
Add the following server entry to your client's MCP configuration. Replace `/absolute/path/to/application` with the directory containing your application's `package.json`. In a monorepo, use the application workspace directory.
|
|
47
|
+
|
|
48
|
+
Using `--dir` makes both executable lookup and catalog resolution independent of where your client starts.
|
|
49
|
+
|
|
50
|
+
Most clients, including VS Code with GitHub Copilot, accept the portable `mcpServers` configuration format:
|
|
51
|
+
|
|
52
|
+
- **Claude Code, VS Code with GitHub Copilot:** `.mcp.json` at the root of your project.
|
|
53
|
+
- **GitHub Copilot (user-level):** `~/.copilot/mcp-config.json`.
|
|
54
|
+
- **Claude Desktop:** `claude_desktop_config.json`, accessible through **Settings → Developer → Edit Config**.
|
|
55
|
+
- **Cursor:** `.cursor/mcp.json` in your project, or `~/.cursor/mcp.json` for all projects.
|
|
18
56
|
|
|
19
57
|
```json
|
|
20
58
|
{
|
|
21
59
|
"mcpServers": {
|
|
22
60
|
"helios-design-system": {
|
|
23
61
|
"command": "pnpm",
|
|
24
|
-
"args": [
|
|
62
|
+
"args": [
|
|
63
|
+
"--dir",
|
|
64
|
+
"/absolute/path/to/application",
|
|
65
|
+
"exec",
|
|
66
|
+
"helios-design-system-mcp"
|
|
67
|
+
]
|
|
25
68
|
}
|
|
26
69
|
}
|
|
27
70
|
}
|
|
28
71
|
```
|
|
29
72
|
|
|
30
|
-
|
|
73
|
+
To share the server with your team, commit a project-level `.mcp.json` to source control. Avoid machine-specific absolute paths in shared configuration. Clients that start project servers from the project root can use `["exec", "helios-design-system-mcp"]` instead, or a relative `--dir` path to an application workspace in a monorepo.
|
|
74
|
+
|
|
75
|
+
<details>
|
|
76
|
+
<summary>VS Code with <code>.vscode/mcp.json</code></summary>
|
|
77
|
+
|
|
78
|
+
VS Code also supports its own `.vscode/mcp.json` format, which uses `servers` rather than `mcpServers`. Prefer the portable `.mcp.json` above for new configuration; use this format if your workspace already defines servers in `.vscode/mcp.json`:
|
|
31
79
|
|
|
32
80
|
```json
|
|
33
81
|
{
|
|
34
|
-
"
|
|
82
|
+
"servers": {
|
|
35
83
|
"helios-design-system": {
|
|
84
|
+
"type": "stdio",
|
|
36
85
|
"command": "pnpm",
|
|
37
86
|
"args": [
|
|
38
87
|
"--dir",
|
|
@@ -45,44 +94,138 @@ If your client does not start in the application directory, use pnpm's `--dir` o
|
|
|
45
94
|
}
|
|
46
95
|
```
|
|
47
96
|
|
|
48
|
-
|
|
97
|
+
See the [VS Code MCP documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for user-level configuration and server controls.
|
|
98
|
+
|
|
99
|
+
</details>
|
|
100
|
+
|
|
101
|
+
For other clients, configure a **stdio** server with the same command and arguments using the client's configuration format. If your client already runs in the application directory, you can shorten the arguments to `["exec", "helios-design-system-mcp"]`.
|
|
102
|
+
|
|
103
|
+
### 3. Verify the connection
|
|
104
|
+
|
|
105
|
+
Restart or reload your client's MCP connection and enable the server's tools. Ask your assistant:
|
|
106
|
+
|
|
107
|
+
> Use the Helios MCP server to look up the API for Hds::Button. Include the catalog package version and where it was resolved from.
|
|
108
|
+
|
|
109
|
+
A successful `get_hds_component` call returns `found: true`, the component's arguments and blocks, and `source.version` / `source.resolvedVia` metadata. Check this metadata to confirm which package supplied the answer; a successful connection alone does not guarantee the catalog matches your application's version.
|
|
110
|
+
|
|
111
|
+
## Usage
|
|
112
|
+
|
|
113
|
+
Try prompts such as:
|
|
114
|
+
|
|
115
|
+
> Use Helios to show me how to build an alert with a title and description. Check the component API and accessibility guidance first.
|
|
116
|
+
|
|
117
|
+
> Find the Helios foreground-action color token and give me its CSS variable and value.
|
|
118
|
+
|
|
119
|
+
> Find a warning icon available at 16px in the Helios icon catalog.
|
|
120
|
+
|
|
121
|
+
> Find the Helios guidance for form validation and cite the documentation.
|
|
122
|
+
|
|
123
|
+
For component work, the useful sequence is **find the component → inspect its API → search and read its documentation**. Component search matches names and paths; documentation search handles questions about usage and design. Read the full documentation passage to retrieve code examples, since search results contain only snippets.
|
|
124
|
+
|
|
125
|
+
If your client supports MCP prompts, you can also start one of the server's [guided workflows](#prompts) directly instead of writing the request yourself.
|
|
126
|
+
|
|
127
|
+
## Tools, prompts, and resources
|
|
128
|
+
|
|
129
|
+
### Tools
|
|
130
|
+
|
|
131
|
+
Your assistant chooses and calls these tools through the MCP client. Names may appear with a client-specific server prefix.
|
|
132
|
+
|
|
133
|
+
| Tool | Purpose | Required input | Optional inputs |
|
|
134
|
+
| ----------------------- | ------------------------------------------------------------------------------------ | --------------------------------------- | ----------------------------------------- |
|
|
135
|
+
| `search_hds_components` | Find components by invocation name, class name, module path, or documentation path. | `query` | `limit` |
|
|
136
|
+
| `get_hds_component` | Read an individual component's API, including argument types and yielded components. | `name` | — |
|
|
137
|
+
| `search_hds_tokens` | Find tokens by name or value, including CSS variables and resolved values. | `query` | `limit`, `type`, `category` |
|
|
138
|
+
| `search_hds_icons` | Find icons by name or keyword, including available sizes. | `query` | `limit`, `category`, `size`, `hasMapping` |
|
|
139
|
+
| `search_hds_docs` | Search bundled documentation for guidance and examples. | `query` | `limit`, `section`, `tab`, `docsPath` |
|
|
140
|
+
| `read_hds_docs` | Read a documentation passage with its Markdown and code examples. | `id` from a documentation search result | `includeChildren`, `maxBytes` |
|
|
141
|
+
|
|
142
|
+
Use `get_hds_component` for precise API questions; it accepts names such as `Hds::Button`, `HdsButton`, `button`, or `hds/button`. Look up yielded components separately to see their own arguments.
|
|
143
|
+
|
|
144
|
+
For documentation, scope searches with the component's `docsPath` when available. Use `tab: "Version history"` for version and changelog questions. Search results are relevance-ranked: read the passages and check `pageAnchored` and `unmatchedTerms` before treating a result as evidence of a supported feature.
|
|
145
|
+
|
|
146
|
+
### Prompts
|
|
147
|
+
|
|
148
|
+
Prompts are reusable workflows that you start from your client, which typically exposes them as slash commands or in a prompt picker. Each prompt directs your assistant to use the component and documentation tools above, check which catalog version answered, and respond in the conversation without editing files or installing dependencies.
|
|
149
|
+
|
|
150
|
+
| Prompt | Purpose | Required arguments | Optional arguments |
|
|
151
|
+
| ---------------------------- | --------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- | ------------------ |
|
|
152
|
+
| `choose_hds_component` | Recommend a component or pattern for an interaction, with rationale, alternatives, and accessibility notes. | `requirements` | `context` |
|
|
153
|
+
| `implement_hds_pattern` | Produce a focused `.gts` implementation using verified APIs, with ember-qunit integration test examples. | `requirements` | `code`, `context` |
|
|
154
|
+
| `review_hds_usage` | Review a code snippet for API usage, composition, and accessibility responsibilities, with prioritized fixes. | `code` | `context` |
|
|
155
|
+
| `troubleshoot_hds_component` | Diagnose unexpected component behavior with evidence-ranked causes, diagnostic steps, and a minimal correction. | `component`, `code`, `expectedBehavior`, `observedBehavior` | `context` |
|
|
156
|
+
|
|
157
|
+
Arguments are plain text. `code` accepts up to 20,000 characters, `component` up to 200, and other arguments up to 4,000. Include relevant template, state, and event handler code so the assistant does not have to guess at omitted behavior.
|
|
158
|
+
|
|
159
|
+
### Resources
|
|
160
|
+
|
|
161
|
+
Clients with MCP resource support can also read catalog indexes and individual records as JSON:
|
|
162
|
+
|
|
163
|
+
| Catalog | Index URI | Individual record URI template |
|
|
164
|
+
| ---------- | ------------------ | ---------------------------------- |
|
|
165
|
+
| Components | `hds://components` | `hds://components/{componentName}` |
|
|
166
|
+
| Tokens | `hds://tokens` | `hds://tokens/{tokenKey}` |
|
|
167
|
+
| Icons | `hds://icons` | `hds://icons/{iconName}` |
|
|
168
|
+
|
|
169
|
+
Use keys returned by the catalog and URL-encode them when constructing individual record URIs. Search tools are usually the most direct way to find a specific item without loading a full index.
|
|
170
|
+
|
|
171
|
+
## Data sources and configuration
|
|
49
172
|
|
|
50
173
|
### Catalog resolution
|
|
51
174
|
|
|
52
|
-
The server
|
|
175
|
+
The server looks for each catalog in this order:
|
|
53
176
|
|
|
54
|
-
|
|
177
|
+
| Catalog | Resolution order |
|
|
178
|
+
| ------------- | ----------------------------------------------------------------------------------------------------------- |
|
|
179
|
+
| Components | Application's `@hashicorp/design-system-components` → server's dependency |
|
|
180
|
+
| Tokens | Application's `@hashicorp/design-system-tokens` → application's components dependency → server's dependency |
|
|
181
|
+
| Icons | Application's `@hashicorp/flight-icons` → application's components dependency → server's dependency |
|
|
182
|
+
| Documentation | `docs-catalog.json` snapshot shipped with the MCP package |
|
|
55
183
|
|
|
56
|
-
|
|
184
|
+
If an application's catalog cannot be resolved, the server falls back to its own dependencies. Those versions may differ from your application's, including when an older Helios package does not ship a catalog.
|
|
57
185
|
|
|
58
|
-
|
|
186
|
+
Component, token, and icon responses include `source.version` and `source.resolvedVia` (`project-root`, `components`, or `default`) to identify the resolved package version and lookup location. `default` indicates the server's fallback lookup.
|
|
59
187
|
|
|
60
|
-
|
|
61
|
-
- `pnpm typecheck`
|
|
62
|
-
- `pnpm build`
|
|
63
|
-
- `pnpm test`
|
|
64
|
-
- `pnpm test:dist-files`
|
|
65
|
-
- `pnpm start`
|
|
188
|
+
Documentation is a bundled snapshot, not a live website search or documentation selected for your application's package version. Responses include a `bundledAt` timestamp and canonical URLs so you can check freshness and open the current page. For exact component arguments, prefer the component API catalog over prose documentation.
|
|
66
189
|
|
|
67
|
-
|
|
190
|
+
### Project root override
|
|
68
191
|
|
|
69
|
-
|
|
192
|
+
By default, the project root is the nearest directory containing a `package.json` at or above the server's working directory. If none is found, the server uses the working directory itself.
|
|
70
193
|
|
|
71
|
-
|
|
72
|
-
|
|
73
|
-
|
|
194
|
+
Set `HDS_MCP_PROJECT_ROOT` in the server process environment to override catalog lookup. For clients using the configuration examples above, add an `env` field alongside `command` and `args`:
|
|
195
|
+
|
|
196
|
+
```json
|
|
197
|
+
{
|
|
198
|
+
"env": {
|
|
199
|
+
"HDS_MCP_PROJECT_ROOT": "/absolute/path/to/application"
|
|
200
|
+
}
|
|
201
|
+
}
|
|
74
202
|
```
|
|
75
203
|
|
|
76
|
-
|
|
204
|
+
The override changes catalog lookup only; it does not change where pnpm looks for the executable. Use `--dir` for that.
|
|
77
205
|
|
|
78
|
-
|
|
206
|
+
Catalogs are cached in memory. Restart the MCP server after changing installed Helios packages or the project root.
|
|
79
207
|
|
|
80
|
-
|
|
81
|
-
|
|
82
|
-
|
|
208
|
+
## Troubleshooting
|
|
209
|
+
|
|
210
|
+
| Symptom | What to check |
|
|
211
|
+
| ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
|
|
212
|
+
| Client cannot find `pnpm` or Node.js | Ensure both are available to the client process and that it uses Node.js 24 or later. Desktop apps may have a different `PATH` from your terminal; use an absolute path to the pnpm executable if needed. |
|
|
213
|
+
| `helios-design-system-mcp` is not found | Confirm the development dependency is installed in the application selected by `--dir`. |
|
|
214
|
+
| Server connects, but answers reflect another Helios version | Inspect `source.version` and `source.resolvedVia`. Check the application path and whether its packages ship the requested catalogs, then restart the server. |
|
|
215
|
+
| Catalog loading fails | Check the client's server logs for the failing catalog. Reinstall dependencies if files are missing; include the package versions and error when reporting an issue. |
|
|
216
|
+
| Documentation looks outdated | Check `bundledAt` and follow the result's canonical URL for the live page. Documentation refreshes come with updated MCP snapshots. |
|
|
217
|
+
| Running the server in a terminal appears to hang | The stdio server waits for MCP messages on stdin. Connect through an MCP client or use the MCP Inspector described in [CONTRIBUTING.md](CONTRIBUTING.md). It does not serve an HTTP URL. |
|
|
218
|
+
|
|
219
|
+
Server diagnostics are written to stderr; stdout is reserved for MCP messages. If an issue persists, [open an issue](https://github.com/hashicorp/design-system/issues) with your client, Node.js and package versions, configuration, and relevant server logs.
|
|
83
220
|
|
|
84
|
-
|
|
221
|
+
## Contributing
|
|
222
|
+
|
|
223
|
+
See the [Contributing](CONTRIBUTING.md) guide for details.
|
|
85
224
|
|
|
86
225
|
## License
|
|
87
226
|
|
|
88
227
|
This project is licensed under the [Mozilla Public License 2.0](https://github.com/hashicorp/design-system/blob/main/LICENSE).
|
|
228
|
+
|
|
229
|
+
## Versioning
|
|
230
|
+
|
|
231
|
+
We use [SemVer](http://semver.org/) for versioning. See the [changelog](CHANGELOG.md) for MCP package changes.
|
|
@@ -11,23 +11,3 @@ export const MAX_QUERY_LENGTH = 2_000;
|
|
|
11
11
|
export const DEFAULT_READ_MAX_BYTES = 16_000;
|
|
12
12
|
export const MIN_READ_MAX_BYTES = 500;
|
|
13
13
|
export const MAX_READ_MAX_BYTES = 60_000;
|
|
14
|
-
export const VERSION_HISTORY_TAB = "Version history";
|
|
15
|
-
export const DOCS_TABS = [
|
|
16
|
-
"Accessibility",
|
|
17
|
-
"Code",
|
|
18
|
-
"Components",
|
|
19
|
-
"Content",
|
|
20
|
-
"Core concepts",
|
|
21
|
-
"Design tokens",
|
|
22
|
-
"Figma Libraries",
|
|
23
|
-
"Flight Icons",
|
|
24
|
-
"Guidelines",
|
|
25
|
-
"Interaction concepts",
|
|
26
|
-
"Library",
|
|
27
|
-
"Palette",
|
|
28
|
-
"Research",
|
|
29
|
-
"Resources",
|
|
30
|
-
"Specifications",
|
|
31
|
-
"Validation",
|
|
32
|
-
VERSION_HISTORY_TAB,
|
|
33
|
-
];
|
|
@@ -6,7 +6,8 @@ import { z } from "zod";
|
|
|
6
6
|
import { defineTool } from "../define-tool.js";
|
|
7
7
|
import { toJsonToolResponse, withSafeToolHandler } from "../responses.js";
|
|
8
8
|
import { clampFilterValue, clampSearchLimit, MAX_FILTER_LENGTH, } from "../search.js";
|
|
9
|
-
import { DEFAULT_SEARCH_LIMIT,
|
|
9
|
+
import { DEFAULT_SEARCH_LIMIT, MAX_QUERY_LENGTH, MAX_SEARCH_LIMIT, SEARCH_DOCS_TOOL_NAME, } from "./constants.js";
|
|
10
|
+
import { VERSION_HISTORY_TAB } from "../../stores/docs/constants.js";
|
|
10
11
|
import { getOrLoadDocsStore } from "../../stores/docs/index.js";
|
|
11
12
|
import { toSerializableSearchResult } from "./utils.js";
|
|
12
13
|
export const searchDocsInputShape = {
|
|
@@ -26,13 +27,13 @@ export const searchDocsInputShape = {
|
|
|
26
27
|
.min(1)
|
|
27
28
|
.max(MAX_FILTER_LENGTH)
|
|
28
29
|
.optional()
|
|
29
|
-
.describe("Restrict to one top-level docs section
|
|
30
|
+
.describe("Restrict to one top-level docs section, e.g. 'components', 'foundations', 'patterns' or 'getting-started'. A value the catalog does not use comes back in unknownFilters alongside the sections that exist."),
|
|
30
31
|
tab: z
|
|
31
32
|
.string()
|
|
32
33
|
.min(1)
|
|
33
34
|
.max(MAX_FILTER_LENGTH)
|
|
34
35
|
.optional()
|
|
35
|
-
.describe(`Restrict to one page tab.
|
|
36
|
+
.describe(`Restrict to one page tab, e.g. 'Guidelines', 'Code', 'Accessibility' or 'Specifications'. A value the catalog does not use comes back in unknownFilters alongside the tabs that exist. Version and changelog questions must pass tab: '${VERSION_HISTORY_TAB}', which is otherwise down-ranked.`),
|
|
36
37
|
docsPath: z
|
|
37
38
|
.string()
|
|
38
39
|
.min(1)
|