design-system-mcp: Add server instructions for client usage guidance#78186
Merged
Conversation
aduth
commented
May 11, 2026
| }, | ||
| { | ||
| instructions: [ | ||
| 'Provides discovery and usage information for the WordPress Design System. Covers components in `@wordpress/components` and `@wordpress/ui`, and the underlying design tokens exposed as `--wpds-*` CSS custom properties.', |
Member
Author
There was a problem hiding this comment.
These package names become something we need to keep in sync over time (e.g. as we add @wordpress/dataviews and @wordpress/admin-ui), but I think it's a worthwhile cue to agents. Maybe we need a code constant somewhere that lists the packages of the design system and I can point to that 😄
|
The following accounts have interacted with this PR and/or linked issues. I will continue to update these lists as activity occurs. You can also manually ask me to refresh this list by adding the If you're merging code through a pull request on GitHub, copy and paste the following into the bottom of the merge commit message. To understand the WordPress project's expectations around crediting contributors, please review the Contributor Attribution page in the Core Handbook. |
|
Size Change: 0 B Total Size: 7.97 MB ℹ️ View Unchanged
|
|
Flaky tests detected in cc48a45. 🔍 Workflow run URL: https://github.com/WordPress/gutenberg/actions/runs/25698044437
|
mirka
approved these changes
May 12, 2026
Member
mirka
left a comment
mirka
left a comment
There was a problem hiding this comment.
Looks like the instructions are sufficient. This is what my agent had to say:
The only MCP-usage improvements I’d suggest are small:
- Mention that
get_componentshas no arguments and returns the full component index.- Mention that
get_design_tokenshas no arguments and may return a large full reference.- Include one concrete example call sequence, like: discover
"dropdown menu"viaget_components, then callget_component_detailswith"Dropdown"or related names.- Clarify whether component names must be exact/case-sensitive.
But I wasn’t blocked. I could infer the workflow and use the tools correctly from the current instructions and schemas.
For context, it listed a good number of gaps in the content of the call results, but I understand this is not the point of this PR.
Main gaps in MCP results
It meets my baseline expectations for a small MCP server, but I’d want a bit more if the goal is reliable implementation guidance.
The main gaps I noticed:
- Component selection guidance is thin. I’d expect instructions for when to prefer
@wordpress/uiover@wordpress/components, especially since one is emerging and one is legacy. - The component list is noisy.
get_componentsreturns a lot of examples inline, and some entries are sparse or blank, so it works as discovery but not as a clean index. - Some generated examples look malformed or low-signal, especially compound component examples like
Card.Root>(<>...). That makes me less likely to trust examples blindly. - I’d expect explicit guidance to consult Storybook/component examples before implementing UI changes.
get_design_tokensis useful, but broad. Category filtering or guidance like "use color tokens for X, dimension tokens for Y" would make it easier to use correctly.
So: yes, the server is usable and the instructions are enough to start. It does not yet fully meet what I’d expect from a design-system MCP intended to steer implementation decisions. The biggest improvement would be adding opinionated usage guidance around package choice, stability, Storybook/source-of-truth expectations, and when to reach for tokens versus components.
ciampo
reviewed
May 12, 2026
| }, | ||
| { | ||
| instructions: [ | ||
| 'Provides discovery and usage information for the WordPress Design System. Covers components in `@wordpress/components` and `@wordpress/ui`, and the underlying design tokens exposed as `--wpds-*` CSS custom properties.', |
Contributor
There was a problem hiding this comment.
Should we mention the @wordpress/theme package as well, alongside ui and components ?
Member
Author
There was a problem hiding this comment.
At the moment, the MCP only includes components from @wordpress/components and @wordpress/ui (search 'manifest' in the code to see). @wordpress/admin-ui and @wordpress/dataviews were already on my radar to include. Now that you mention it, ThemeProvider from @wordpress/theme should probably be there as well.
Since this accurately reflects what it includes today, I'm inclined to keep it as-is and revise the description later when those are included.
Though maybe @wordpress/theme could be mentioned around 'underlying design tokens'. The current phrasing lists packages only for "components".
Contributor
There was a problem hiding this comment.
Yeah, my thinking is that design tokens come from @wordpress/theme, hence why I thought we could mention it. But I otherwise agree with you
Member
Author
There was a problem hiding this comment.
I added a mention of @wordpress/theme in 02206a3. I think these kinds of keyword nudges will be good for AI discovery. I was even thinking how to incorporate something about Gutenberg since it could help discovery, even if the design system itself is not inherently attached.
aduth
force-pushed
the
update/design-system-mcp-multiple-names
branch
2 times, most recently
from
5207ab9 to
d851ecb
Compare
Member
Author
This is something I'd like to improve. Right now it's just surfacing |
Improve discovery relevance
aduth
force-pushed
the
update/ds-mcp-instructions
branch
from
02206a3 to
98b9d06
Compare
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
3 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What?
Updates the WordPress Design System MCP server to provide instructions on how it should be used.
Temporarily merges to #78185 because the instructions text claims using "
get_component_detailsfor one or more of those names", which depends on the changes in #78185.Why?
get_componentscall).Testing Instructions
Verify that the agent knows about the instructions workflow:
It makes some good points about 6 and 7 😄
Use of AI Tools
Initial instructions draft was authored by Claude Code Opus 4.7, with heavy edits by me.