feat: add AGENTS.md for the mcp addon

.changeset/quick-comics-tell.md

@@ -0,0 +1,5 @@
+---
+'sv': patch
+---
+
+feat(mcp): include an `AGENTS.md` when using the `mcp` addon

documentation/docs/30-add-ons/17-mcp.md

@@ -12,7 +12,10 @@ npx sv add mcp
 
 ## What you get
 
-- A good mcp configuration for your project depending on your IDE
+Depending on your IDE setup, you’ll receive:
+
+- A MCP configuration
+- A `readme` for agent, either [`AGENTS.md`](https://agents.md/), `CLAUDE.md`, or `GEMINI.md`
 
 ## Options
 

packages/addons/mcp/.opencode/agent/svelte.md

@@ -0,0 +1,41 @@
+---
+description: Svelte MCP development assistant with access to documentation and tools
+mode: primary
+temperature: 0.1
+tools:
+  svelte_mcp_list-sections: true
+  svelte_mcp_get-documentation: true
+  svelte_mcp_svelte-autofixer: true
+  svelte_mcp_playground-link: true
+  write: false
+  edit: false
+permission:
+  svelte_mcp_*: allow
+  write: deny
+  edit: deny
+  bash: deny
+---
+
+You are able to use the Svelte MCP server, where you have access to comprehensive Svelte 5 and SvelteKit documentation. Here's how to use the available tools effectively:
+
+## Available MCP Tools:
+
+### 1. list-sections
+
+Use this FIRST to discover all available documentation sections. Returns a structured list with titles, use_cases, and paths.
+When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections.
+
+### 2. get-documentation
+
+Retrieves full documentation content for specific sections. Accepts single or multiple sections.
+After calling the list-sections tool, you MUST analyze the returned documentation sections (especially the use_cases field) and then use the get-documentation tool to fetch ALL documentation sections that are relevant for the user's task.
+
+### 3. svelte-autofixer
+
+Analyzes Svelte code and returns issues and suggestions.
+You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.
+
+### 4. playground-link
+
+Generates a Svelte Playground link with the provided code.
+After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project.

packages/addons/mcp/AGENTS.md

@@ -0,0 +1,23 @@
+You are able to use the Svelte MCP server, where you have access to comprehensive Svelte 5 and SvelteKit documentation. Here's how to use the available tools effectively:
+
+## Available MCP Tools:
+
+### 1. list-sections
+
+Use this FIRST to discover all available documentation sections. Returns a structured list with titles, use_cases, and paths.
+When asked about Svelte or SvelteKit topics, ALWAYS use this tool at the start of the chat to find relevant sections.
+
+### 2. get-documentation
+
+Retrieves full documentation content for specific sections. Accepts single or multiple sections.
+After calling the list-sections tool, you MUST analyze the returned documentation sections (especially the use_cases field) and then use the get-documentation tool to fetch ALL documentation sections that are relevant for the user's task.
+
+### 3. svelte-autofixer
+
+Analyzes Svelte code and returns issues and suggestions.
+You MUST use this tool whenever writing Svelte code before sending it to the user. Keep calling it until no issues or suggestions are returned.
+
+### 4. playground-link
+
+Generates a Svelte Playground link with the provided code.
+After completing the code, ask the user if they want a playground link. Only call this tool after user confirmation and NEVER if code was written to files in their project.

packages/addons/mcp/index.ts

@@ -1,5 +1,7 @@
-import { defineAddon, defineAddonOptions } from '@sveltejs/cli-core';
+import fs from 'node:fs';
+import { colors, defineAddon, defineAddonOptions, log } from '@sveltejs/cli-core';
 import { parseJson } from '@sveltejs/cli-core/parsers';
+import agent from './AGENTS.md?raw';
 
 const options = defineAddonOptions()
 	.add('ide', {
@@ -60,6 +62,7 @@ export default defineAddon({
 			| {
 					schema?: string;
 					mcpServersKey?: string;
+					agentPath: string;
 					filePath: string;
 					typeLocal?: 'stdio' | 'local';
 					typeRemote?: 'http' | 'remote';
@@ -70,20 +73,24 @@ export default defineAddon({
 			| { other: true }
 		> = {
 			'claude-code': {
+				agentPath: 'CLAUDE.md',
 				filePath: '.mcp.json',
 				typeLocal: 'stdio',
 				typeRemote: 'http',
 				env: true
 			},
 			cursor: {
+				agentPath: 'AGENTS.md',
 				filePath: '.cursor/mcp.json'
 			},
 			gemini: {
+				agentPath: 'GEMINI.md',
 				schema:
 					'https://raw.githubusercontent.com/google-gemini/gemini-cli/main/schemas/settings.schema.json',
 				filePath: '.gemini/settings.json'
 			},
 			opencode: {
+				agentPath: '.opencode/agent/svelte.md',
 				schema: 'https://opencode.ai/config.json',
 				mcpServersKey: 'mcp',
 				filePath: 'opencode.json',
@@ -93,6 +100,7 @@ export default defineAddon({
 				args: null
 			},
 			vscode: {
+				agentPath: 'AGENTS.md',
 				mcpServersKey: 'servers',
 				filePath: '.vscode/mcp.json'
 			},
@@ -105,7 +113,32 @@ export default defineAddon({
 			const value = configurator[ide];
 			if ('other' in value) continue;
 
-			const { mcpServersKey, filePath, typeLocal, typeRemote, env, schema, command, args } = value;
+			const {
+				mcpServersKey,
+				agentPath,
+				filePath,
+				typeLocal,
+				typeRemote,
+				env,
+				schema,
+				command,
+				args
+			} = value;
+
+			const placesToCheck = Object.values(configurator)
+				.filter((_) => 'agentPath' in _)
+				.map(({ agentPath }) => agentPath);
+
+			sv.file(agentPath, (content) => {
+				if (placesToCheck.some(fs.existsSync)) {
+					log.warn(
+						`A ${colors.yellow(agentPath)} file already exists. Could not update. See https://svelte.dev/docs/mcp/overview#Usage for manual setup.`
+					);
+					return content;
+				}
+				return agent;
+			});
+
 			sv.file(filePath, (content) => {
 				const { data, generateCode } = parseJson(content);
 				if (schema) {