feat: add AGENTS.md for the mcp addon

[sacrosanctic]

closes #775

@jycouet here's my initial take, feel free to guide from here.

todo / consideration

• opencode has a different setup for agents, need to read their docs
• prompt is currently hard coded, source of truth is at https://github.com/sveltejs/mcp/blob/main/documentation/docs/10-introduction/10-overview.md, not sure how to fetch it
• should we append to an existing AGENTS.md?
  • should we check for other variations? (GEMINI.md, CLAUDE.md)
• update mcp docs now that cli will handle everything
• add test
• add changeset

[changeset-bot]

🦋 Changeset detected

Latest commit: a15c098

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 1 package

Name	Type
sv	Patch

Not sure what this means? Click here to learn what changesets are.

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

[jycouet]

• opencode has a different setup for agents, need to read their docs

I let you look :)

• prompt is currently hard coded, source of truth is at sveltejs/mcp@main/documentation/docs/10-introduction/10-overview.md, not sure how to fetch it

I was thinking to hard code it here as well (as it will not change often, and if it changes, we update it here also?).
If we hardcode, I would do it like we did for the playground files.
Add them in packages/create/shared/+mcp and get them like

cli/packages/create/playground.ts

Line 187 in 6ed6ad8

const playgroundFiles = files.filter((file) => file.include.includes('playground'));

• should we append to an existing AGENTS.md?

I don't think so. A log like you did (or

cli/packages/addons/lucia/index.ts

Line 405 in 6ed6ad8

log.warn(`Existing ${colors.yellow(filePath)} file. Could not update.`);

) is good imo.

• should we check for other variations? (GEMINI.md, CLAUDE.md)

I think that if it exist, yes we should adapt. From the MCP doc it seems to be only 'AGENTS.md' and CLAUDE.md. Are you sure about GEMINI.md ? If it's the case, we should probably update the MCP doc?

Side note, in the MCP doc we should say that you can setup everything with npx sv add mcp :)

• add test

If you do: rm -rf .test-output/ && pnpm build && pnpm -F @sveltejs/addons test mcp
you will have packages/addons/_tests/mcp/test.ts running

• add changeset

It should be a patch, and you can do: pnpm changeset to generate a new changeset. Maybe start with feat(mcp): ...

---

Thx for looking at it 🎉

[sacrosanctic]

Are you sure about GEMINI.md?

Yes, I know because I use Gemini, and also this.

Add them in packages/create/shared/+mcp and get them like

Can you elaborate, mcp ins in the addons package and create is a seperate package.

I think that if it exist, yes we should adapt.

Would the logic be:

• I have CLAUDE.md
• I add mcp with vscode option
• Check if any AGENTs.md file exist
  • if true, cancel
  • if false, make file

[jycouet]

Are you sure about GEMINI.md?

Yes, I know because I use Gemini, and also this.

Ok 👍

Add them in packages/create/shared/+mcp and get them like

Can you elaborate, mcp ins in the addons package and create is a seperate package.

In the end, everything is packaged in sv, it's a good way to pack & publish things.
You can leave this on the side for now, and I will do it 👍
Put the raw content somewhere and depending on the mcp, put this content in the right file.

I think that if it exist, yes we should adapt.

Would the logic be:

• I have CLAUDE.md

• I add mcp with vscode option

• Check if any AGENTs.md file exist

  • if true, cancel
  • if false, make file

Yes, I think so 👍
Maybe not cancel, just log that something exist and skip

[sacrosanctic]

Alright, this as much as I can do.

[jycouet]

Alright, this as much as I can do.

Thx for the initial work, I'll look later 👍

[pkg-pr-new]

Open in StackBlitz

npx https://pkg.pr.new/sveltejs/cli/sv@777

npx https://pkg.pr.new/sveltejs/cli/svelte-migrate@777

commit: a15c098

[svelte-docs-bot]

Preview: https://svelte-dev-git-preview-cli-777-svelte.vercel.app/

[jycouet]

@sacrosanctic could you have a look and let me know?

[sacrosanctic]

It looks good. I didn't realize it was possible to import across packages. I thought that because they were separate packages, they had to be separated.

some thoughts:

• for opencode, its syntax is correct. But not super confident about the specifics, will have to wait for someone with more familiarity to raise an issue
• Is early return discouraged?

[jycouet]

• for opencode, it's syntax is correct. But not super confident about the specifics, will have to wait for someone with more familiarity to raise an issue

I'll try to find someone

• Is early return discouraged?

No, why? You can comment directly on the code on github to ease the conversation

[sacrosanctic]

Ok, let me try that again. Btw, what's the difference between single comment and start a review?

Never mind about the early return, I misread the code.

[jycouet]

Ok, let me try that again. Btw, what's the difference between single comment and start a review?

• Single comment, you have one simple small thing to say. (each single comment will trigger a notification)

• Start a review, you will be able to do a lot of comments... here... there... And add a final text. (1 review will trigger 1 notification :) )

[jycouet]

@sacrosanctic it seems like there is no need of a special treatment for opencode!
https://opencode.ai/docs/rules/#example

So we should remove opencode-prefix-AGENTS.md and the code associated with it.
You want to finalize the PR ?