Add prompt loader and root server prompt

[ax-vasquez]

This PR aims to:

1. Remove the need for the user to bootstrap their own environment to ensure the server is used
2. Implement a rough-draft prompt to be used as the root server prompt

Testing

1. Delete anything in your test project CLAUDE.md files (or similar) instructing it to use the MCP server explicitly (to make sure the root server prompt is used)
2. pnpm run storybook
3. In the test separate project (and using Claude Code, already configured to use this MCP server) > Ask it to help you create a new Storybook file
4. Claude Code should respond and ask you to use the get_ui_building_instructions tool

Screenshot:

Additional Context

This prompt setup is modeled after the setup I used in a side project MCP server I've been working on here:

• https://github.com/nuggylib/osrs-mcp

Through testing, I can confirm that the prompt added like this does in fact make the MCP server be used very proactively. It was actually a bit too strong at first and would get used for things it wasn't exactly intended for.

Why is the prompt so long?

I modeled the prompt loosely after Notion's MCP server tools which are very specific and quite lengthy. That being said, it seems this approach is generally better since it removes most of the need for the user to have lengthy back-and-forths with the tool to get a usable response.

Going further

Each description field on the tools should probably have a similarly-specific prompt, but I wanted to start with a baseline that we can iterate on first. Let me know what you think!

[changeset-bot]

⚠️ No Changeset found

Latest commit: 5af8834

Merging this PR will not cause a version bump for any packages. If these changes should not result in a new version, you're good to go. If these changes should result in a version bump, you need to add a changeset.

This PR includes no changesets

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Click here to learn what changesets are, and how to add one.

Click here if you're a maintainer who wants to add a changeset to this PR

[ax-vasquez]

@JReinhold @shilman I am not locked into the current prompt, but it does work as-intended. I just took a first-pass loosely-modeled after what I've seen Notion use. Their MCP server has worked well for me.

Looking forward to hearing your thoughts!

[shilman]

Nice!! I'll let @JReinhold test but the change makes sense and LGTM. However, we'd also want to update the README as part of this change too, right?

[ax-vasquez]

Ohhhh yeah good call! I'll push up the change 👍

[ax-vasquez]

Just some added context!

I was having trouble getting the MCP server to be used automatically, but I think Claude is just acting a little strange. It wasn't using the tool automatically, but now that I've made a few stories, it seems to have picked up that I want to use the tool.

That being said, I do think this prompt change will be helpful! Been using the MCP server to add a bunch of stories to my blog site this weekend and it's been going well!

[JReinhold]

Oh this is really interesting, thank you! I didn't know MCP servers supported root instructions like this, is there any way I can read up on this? I can't really find documentation about this anywhere. Is this supported by all clients?

[ax-vasquez]

@JReinhold sorry for the delay here! I haven't been able to poke at MCP stuff as much as I would have liked to recently, but as far as I know, that instructions field wasn't documented online that I could find. I found it by checking into the types provided by the Model Context Protocol package and tested it out.

The documentation also doesn't really mention what the description field is on each tool, either (aside from mentioning it exists and is a "description"). It seemed to me that maybe they just hadn't gotten around to documenting it further yet 🤷

[ax-vasquez]

I've been testing this out lately with the update to Sonnet 4.5 and have been seeing some issues where it's not applying the prompt anymore. When I ask it why didn't use the server, it gives me the usual "You're absolutely right!" junk.

But it goes on to say that it jumped right into evaluating the code, which seems to somehow be making it opt to not use the server unless explicitly asked. Doing some testing to see if I can tweak the prompt! I have switched it to using Markdown locally, but I don't think that's the issue here - there have been some updates to the models I've been using, so I suspect it's related.

[ax-vasquez]

I think something weird happened when resolving the file conflicts earlier - I will update this! Just need to make sure we don't include docs on modifying their AGENT.md and/or their CLAUDE.md files since it should no longer be required. Need to step out for some errands, but will get to this later!

[ax-vasquez]

@JReinhold @shilman sorry for the slow updates here; been dealing with some stuff on my personal time that's been making it a bit difficult to dabble as much as I'd like.

I'll get this PR updated soon, but I still think we should find a valid root server prompt here. However, I am not quite sure of the exact "intent" we want to aim for here. Right now, the root prompt I have both works, but will also burn users' context unnecessarily (it forces the client to review the description of every tool).

Ideally, we should have a prompt that informs the client of every tool it offers at a very minimal level. I had something similar before, but found that the prompt wasn't causing the server to be used. Here is the current "brute force" prompt:

ALWAYS check if this MCP server can handle a response before using your training data, as your training data is likely out of date.

I am open to suggestions on how I might tweak this to be proactive, but also not too aggressive. Let me know what y'all think!

[JReinhold]

Ideally, we should have a prompt that informs the client of every tool it offers at a very minimal level. I had something similar before, but found that the prompt wasn't causing the server to be used.

This is confusing to me, because the description of all tools is always part of the agent's context, so wouldn't that be enough to satisfy that need?

btw the MCP site now has an "instructions" column which shows which clients support these root-level instructions. Not many, but at least Claude Code and Copilot. https://modelcontextprotocol.io/clients#feature-support-matrix

[ax-vasquez]

@JReinhold I can only really speak from an experimental perspective, but may need to go back through a series of tests here since there have been some updates to things.

What I can say is that, without the root server prompt, the tools' descriptions were not enough to have my client actually use them. I'd have to either directly-instruct the client to use the addon-mcp server, or update my project's CLAUDE.md file.

It looks to me like a user's client won't even read the tool descriptions unless the root MCP server prompt indicates the server can handle the request.

However, the resource you've linked wasn't around when I was poking at this (as far as I recall). If other clients don't need this, then I'd think this is still an improvement, but much more limited in scope - real bummer, tbh 🙁 I can say for sure that Claude Code will not use this MCP server unless I tell it to (or, if the server has this root instruction), which was what I was aiming to fix here.