docs(AI): Adds PatternFly MCP documentation.#4857
docs(AI): Adds PatternFly MCP documentation.#4857edonehoo wants to merge 13 commits intopatternfly:mainfrom
Conversation
| ``` { | ||
| "mcpServers": { | ||
| "patternfly-docs": { | ||
| "command": "npx", | ||
| "args": [ | ||
| "-y", | ||
| "@patternfly/patternfly-mcp" | ||
| ], | ||
| "description": "PatternFly React development rules and documentation" | ||
| } | ||
| } | ||
| } | ||
| ``` |
There was a problem hiding this comment.
It looks like the very opening { got cut off and the indentation got a little thrown off following that:
| ``` { | |
| "mcpServers": { | |
| "patternfly-docs": { | |
| "command": "npx", | |
| "args": [ | |
| "-y", | |
| "@patternfly/patternfly-mcp" | |
| ], | |
| "description": "PatternFly React development rules and documentation" | |
| } | |
| } | |
| } | |
| ``` | |
| ``` | |
| { | |
| "mcpServers": { | |
| "patternfly-docs": { | |
| "command": "npx", | |
| "args": [ | |
| "-y", | |
| "@patternfly/patternfly-mcp" | |
| ], | |
| "description": "PatternFly React development rules and documentation" | |
| } | |
| } | |
| } | |
| ``` |
| For full technical documentation, setup instructions, and to contribute, visit our [PatternFly MCP GitHub Repository](https://github.com/patternfly/patternfly-mcp). | ||
|
|
||
| ## What is the PatternFly MCP? | ||
| The **PatternFly MCP** is a new tool designed to integrate our design guidelines, component documentation, and accessibility best practices directly into your AI-powered development environment. |
There was a problem hiding this comment.
Seeing "new" in our docs immediately makes me think we're building in tech debt as this becomes dated.
| The **PatternFly MCP** is a new tool designed to integrate our design guidelines, component documentation, and accessibility best practices directly into your AI-powered development environment. | |
| The **PatternFly MCP** is a tool designed to integrate our design guidelines, component documentation, and accessibility best practices directly into your AI-powered development environment. |
| - **Response:** Yes, the PatternFly MCP is running successfully. There are 2 available tools for you to use: `mcp_patternfly-docs_usePatternFlyDocs` and `mcp_patternfly-docs_fetchDocs`. | ||
|
|
||
| ### Fetching specific documentation | ||
| - **Prompt:** "Yes, fetch docs for card" |
There was a problem hiding this comment.
This was copy/pasted as a direct follow-up to the output from the "verifying installation" prompt above, but we've reframed these here as unrelated sample prompts so I'd suggest rewording this as an independent prompt:
| - **Prompt:** "Yes, fetch docs for card" | |
| - **Prompt:** "Fetch docs for PatternFly card" |
| - **Response:** “Here’s the current PatternFly card documentation, including the general design guidelines and key accessibility requirements: [documentation summary]“ | ||
|
|
||
| ### Get design guidance | ||
| - **Prompt:** "Which components should I use if we want a user to be able to select several different cards from a gallery view?" |
There was a problem hiding this comment.
User feedback indicated that the PF MCP isn't always used (the AI tool has to make that decision) so tweaking the prompt from those results to explicitly call out PatternFly could lead to more consistent results:
| - **Prompt:** "Which components should I use if we want a user to be able to select several different cards from a gallery view?" | |
| - **Prompt:** "Which PatternFly components should I use if we want a user to be able to select several different cards from a gallery view?" |
evwilkin
left a comment
evwilkin
left a comment
There was a problem hiding this comment.
Added a few small tweaks to help adopt this from our testing overview to our official docs.
One thing potentially missing here is that we're focusing on direct communication with the MCP in all examples - asking it a question and getting an answer to that question. I'd suspect the more common use case is having this work in the background as an always-on reference that's incorporated into existing workflows. For example, a designer vibe coding a design or interactive POC, or developer building/enhancing a product codebase, that automatically pulls in the correct components, props, accessibility considerations, etc. without them needing to specifically ask what that is but just for the agent to be aware of & use that information.
I originally tried to hint at this with the below statement, but not sure how to more clearly indicate the power of the MCP as the magic behind the curtain rather than just a chatbot-style interaction
Here are a few sample prompts to get you started, but the MCP tools are available for reference by your AI agent across all applicable use cases (code generation, design review, etc.):
|
|
||
| ``` { | ||
| "mcpServers": { | ||
| "patternfly-docs": { |
There was a problem hiding this comment.
it's a minor thing, can't tell if its on purpose and technically everything functions, but we flip between naming the server setup patternfly-docs for Cursor vs patternfly-mcp for Claude... we may want to be consistent... this would cause a few more updates throughout the pr if we flip to just patternfly-mcpvs flipping to patternfly-docs for everything
(the pf-mcp readme references patternfly-docs but dependent on the direction we take here we can always make sure that aligns after-the-fact)
There was a problem hiding this comment.
@evwilkin do we want to go with one or the other? or still deciding
There was a problem hiding this comment.
@edonehoo @cdcabrera I vote we stick with patternfly-mcp to match the name of the repo and the NPM package shipped that's referenced in the code just below these lines @patternfly/patternfly-mcp.
I think the consistency in name could remove one possible source of confusion 👍
There was a problem hiding this comment.
sounds good! I just updated it in my last commit, but lmk if anything looks off
|
I couldn't get the mcp set up in cursor myself until I added |
@nicolethoen it looks like I was hitting an error with @latest due to a caching issue, clearing my npm cache and trying again with @latest worked just fine 👍 |
|
This should be rebased given the nav redesign - and this page should go under |
|
@evwilkin @nicolethoen I added |
packages/documentation-site/patternfly-docs/content/AI/patternfly-mcp.md
Outdated
Show resolved
Hide resolved
packages/documentation-site/patternfly-docs/content/AI/patternfly-mcp.md
Outdated
Show resolved
Hide resolved
packages/documentation-site/patternfly-docs/content/AI/patternfly-mcp.md
Outdated
Show resolved
Hide resolved
packages/documentation-site/patternfly-docs/content/AI/patternfly-mcp.md
Outdated
Show resolved
Hide resolved
Co-authored-by: Evan <8651509+evwilkin@users.noreply.github.com>
|
@edonehoo following up on this, the tools in the MCP are being finalized in the next week or two and at that point we should be good to update the wording here and move forward - thanks for the patience! 😄 |
| ## What does the PatternFly MCP provide? | ||
| There are 2 main tools provided by the PatternFly MCP: | ||
| - `usePatternFlyDocs`: Used to answer high-level questions about components, design guidelines, and accessibility. | ||
| - `fetchDocs`: Used to retrieve the full documentation for a specific component via a URL provided by `usePatternFlyDocs`. |
There was a problem hiding this comment.
the tools and resources have evolved a bit, just need to update the names and descriptions
possible description
## What does the PatternFly MCP provide?
The PatternFly MCP provides two primary tools and a set of rich resources:
possible tool descriptions
### Tools
- `searchPatternFlyDocs`: Search for PatternFly components and guidelines. It returns names and URLs that can be used for deep-diving into specific documentation.
- `usePatternFlyDocs`: The primary tool for retrieving content. It fetches full markdown documentation and automatically attaches machine-readable JSON schemas (props, types) for React components.
possible resource description adds (MCP resources help power the MCP tools, can think of them as indexes... we have more than what's below, just a short list)
### Resources
The server exposes an indexed library via the `patternfly://` URI scheme:
- `patternfly://context`: A high-level overview of PatternFly rules and server capabilities.
- `patternfly://schemas/{name}`: Direct access to component property specifications.
- `patternfly://docs/index`: A browsable index of all available documentation.
There was a problem hiding this comment.
@edonehoo you may have overlooked this, i put 3 updates in the comment... the MCP tools have been renamed and restructured for different behavior
usePatternFlyDocsis now about retrieving contentfetchDocsdoesn't exist
### Tools
- `searchPatternFlyDocs`: Search for PatternFly components and guidelines. It returns names and URLs that can be used for deep-diving into specific documentation.
- `usePatternFlyDocs`: The primary tool for retrieving content. It fetches full markdown documentation and automatically attaches machine-readable JSON schemas (props, types) for React components.
| ### Verifying installation | ||
| - **Prompt:** "Can you see the PF MCP running? If so, what are the tools?" | ||
| - **Expected AI behavior:** The assistant will confirm it sees the PatternFly MCP and list the available tools: mcp_patternfly-mcp_usePatternFlyDocs and mcp_patternfly-mcp_fetchDocs. | ||
| - **Response:** Yes, the PatternFly MCP is running successfully. There are 2 available tools for you to use: `mcp_patternfly-mcp_usePatternFlyDocs` and `mcp_patternfly-mcp_fetchDocs`. |
There was a problem hiding this comment.
Not sure we should try to vouch for how the IDE/tooling prefixes the tools with the mcp_patternfly-mcp_, could just be Cursor/whatever, but I could also see that varying by MCP client. The actual tool names are shorter...
Possible alt
### Verifying installation
- **Prompt:** "Can you see the PatternFly MCP running? If so, what are the tools?"
- **Expected AI behavior:** The assistant will confirm it sees the PatternFly MCP and list the available tools: `searchPatternFlyDocs` and `usePatternFlyDocs`.
- **Response:** Yes, the PatternFly MCP is running successfully. There are 2 available tools: `searchPatternFlyDocs` and `usePatternFlyDocs`.
| ### Fetching specific documentation | ||
| - **Prompt:** "Fetch docs for a PatternFly card" | ||
| - **Expected AI behavior:** This will trigger the `fetchDocs` tool. The assistant will return a detailed, organized summary of the card component's documentation, including design guidelines (elements, usage, variations), accessibility guidelines (key requirements, React props), and more. | ||
| - **Response:** “Here’s the current PatternFly card documentation, including the general design guidelines and key accessibility requirements: [documentation summary]“ |
There was a problem hiding this comment.
So these days we now include "versions" in the output, also we allow a version filter to be applied through the MCP tools (in the future we'll be expanding that filtering). A default version gets applied typically "latest" or v6... these responses just need to be updated... may need to double check
### Fetching specific documentation
- **Prompt:** "Fetch docs for a PatternFly card"
- **Expected AI behavior:** This will trigger the `usePatternFlyDocs` tool. The assistant will return a detailed, organized summary of the card component's documentation from the v6 library, including design guidelines (elements, usage, variations), accessibility guidelines (key requirements, React props), and machine-readable schemas.
- **Response:** “Here’s the PatternFly v6 card documentation, including the general design guidelines and key accessibility requirements: [documentation summary]“
|
ty @cdcabrera ! I made those updates, but we can keep refining as needed |
cdcabrera
left a comment
cdcabrera
left a comment
There was a problem hiding this comment.
The MCP tools are the primary thing that need to be updated
| ## What does the PatternFly MCP provide? | ||
| There are 2 main tools provided by the PatternFly MCP: | ||
| - `usePatternFlyDocs`: Used to answer high-level questions about components, design guidelines, and accessibility. | ||
| - `fetchDocs`: Used to retrieve the full documentation for a specific component via a URL provided by `usePatternFlyDocs`. |
There was a problem hiding this comment.
@edonehoo you may have overlooked this, i put 3 updates in the comment... the MCP tools have been renamed and restructured for different behavior
usePatternFlyDocsis now about retrieving contentfetchDocsdoesn't exist
### Tools
- `searchPatternFlyDocs`: Search for PatternFly components and guidelines. It returns names and URLs that can be used for deep-diving into specific documentation.
- `usePatternFlyDocs`: The primary tool for retrieving content. It fetches full markdown documentation and automatically attaches machine-readable JSON schemas (props, types) for React components.
| "command": "npx", | ||
| "args": [ | ||
| "-y", | ||
| "@patternfly/patternfly-mcp@latest", |
There was a problem hiding this comment.
the trailing comma may actually bust the JSON here
"@patternfly/patternfly-mcp@latest"
|
|
||
| ### Get design guidance | ||
| - **Prompt:** "Which PatternFly components should I use if we want a user to be able to select several different cards from a gallery view?" | ||
| - **Expected AI behavior:** This will trigger the `usePatternFlyDocs tool`. The AI assistant will analyze your request and provide a recommendation based on PatternFly's design guidelines, likely suggesting the use of selectable cards and noting that multi-select is achieved using cards with checkboxes. |
There was a problem hiding this comment.
looks like we should update the "expected ai behavior" on line 94
// from this
This will trigger the `usePatternFlyDocs tool`. The..
// to this
This will trigger the `searchPatternFlyDocs` tool
| - `usePatternFlyDocs`: Used to answer high-level questions about components, design guidelines, and accessibility. | ||
| - `fetchDocs`: Used to retrieve the full documentation for a specific component via a URL provided by `usePatternFlyDocs`. | ||
|
|
||
| To help power `usePatternFlyDocs` and `fetchDocs`, the MCP provides the following additional resources as an indexed library via the `patternfly://` URI scheme: |
There was a problem hiding this comment.
looks like we have the old tool references here too
maybe
// from
To help power `usePatternFlyDocs` and `fetchDocs`
// to
To help power `searchPatternFlyDocs` and `usePatternFlyDocs`
5 participants
Closes #4844
This PR adds a new page to patternfly.org in the PatternFly AI section explaining & overviewing the PatternFly MCP.
Preview: https://pf-org--pr-4857-site.surge.sh/patternfly-ai/patternfly-mcp