[🚧 ALPHA] Agent Rules and MCP

[deebov]

Problem or use case

Warning

This is an ongoing task and isn't expected to work as expected.

Currently, when trying to build UIs using Untitled UI React components via AI agents such as Cursor or Claude Code you might run into a problem where these agents just go off the track and start pulling random components or design styles. This is quite frustrating because it discourages the usage of AI agents with Untitled UI React.

This thread is meant for building out the first working versions of our new agent rules and MCP. All feedback is very welcome 🤗.

(The MCP server is currently under private beta and will be moved into public beta soon)

Proposed solution

Copy the raw content of this gist into your CLAUDE.md / .cursor/rules/untitledui.mdc file. Feel free to make any suggestions 🤗.

https://gist.github.com/deebov/307cf9d9124e1cf98e80bda84fef2b9d

[sbilde]

This is great to see! I actually built a community MCP server for UntitledUI while waiting for an official solution:
https://github.com/sbilde/untitledui-mcp

What it currently does:

• Component discovery (search_components, list_components)
• Fetches components with automatic base dependency resolution (get_component_with_deps)
• Full page template fetching (get_example)
• Token estimates for large responses
• Works with Pro license (auto-detects from ~/.untitledui/config.json)

Happy to:

1. Share any learnings from building it
2. Contribute to the official MCP if helpful
3. Deprecate mine once the official one goes public

Feedback on the agent rules:
The gist looks solid! One thing I found useful was instructing the AI to always use the starter kits as a base — it avoids a lot of
friction with missing Tailwind tokens and providers.

Looking forward to the public beta!

[deebov]

Hey @sbilde, this is awesome to see! Thanks for the effort!

We didn't pursue to publish our MCP back then because it was struggling with very large components. For example, instead of writing the fetched content into files via bash it was reading the whole thing and wasting thousands of token. Even when we tried with strict prompt rules it would sometimes still read the whole content.

Did you also face this issue?

[deebov]

Another problem we encountered is that when the AI lists the components (which can be in the hundreds), it would usually pick only the first few variants across multiple separate sessions.

[sbilde]

Thanks Dilshod! Great to hear from the team.

On the token waste issue:

Yes, ran into this as well. My approach has been:

1. Token estimates in every response — Each response includes estimatedTokens and a per-file fileList with token
   counts. This lets the AI decide upfront whether to use the full response or fall back to individual files.

2. get_component_file tool — When a component is too large (>25K tokens), the AI can fetch individual files instead of
   the whole component. So it gets the file list first, then fetches only the files it needs.

The key insight is giving the AI the metadata to make smart decisions before it fetches the full content.

On the variant selection issue:

Haven't solved this one yet, but I think the problem is that list_components returns too many options without enough context
for the AI to differentiate.

A few ideas:

• Return a short description/preview per variant so the AI can make an informed choice
• Group variants by category (size, style, layout) so the AI understands the taxonomy
• Let the AI ask the user to pick from a curated shortlist instead of choosing on its own

Would love to collaborate on solving these problems — happy to contribute to the official MCP if that's useful, or keep
iterating on the community version. Either way, these are the right problems to solve.

[deebov]

Awesome! Though, the first issue is why I still haven't released because it can easily burn through users tokens, which happened many times while I was developing it. This might make a lot of people angry once they find out we burned their monthly tokens.

Is your MCP using bash command to write files or is it occasionally reading the whole fetched content?

[deebov]

Hey @sbilde, just a heads up — I'm going a bit different route of not returning the file content in the MCP response but rather a CLI command which install those files. I cannot find a guaranteed way that all those files will count towards the token usage so it's safe to install everything via CLI.