From 5001f2bad3e08316cee95e36b9003700f36f7e02 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 11 Nov 2025 01:09:06 +0800
Subject: [PATCH 01/11] initial setup

---
 packages/addons/mcp/AGENT.md | 23 +++++++++++++++++++++++
 packages/addons/mcp/index.ts | 12 ++++++++++++
 2 files changed, 35 insertions(+)
 create mode 100644 packages/addons/mcp/AGENT.md

diff --git a/packages/addons/mcp/AGENT.md b/packages/addons/mcp/AGENT.md
new file mode 100644
index 000000000..a6e66ff15
--- /dev/null
+++ b/packages/addons/mcp/AGENT.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.
diff --git a/packages/addons/mcp/index.ts b/packages/addons/mcp/index.ts
index 05c5f8a03..5bf09ef24 100644
--- a/packages/addons/mcp/index.ts
+++ b/packages/addons/mcp/index.ts
@@ -1,5 +1,6 @@
 import { defineAddon, defineAddonOptions } from '@sveltejs/cli-core';
 import { parseJson } from '@sveltejs/cli-core/parsers';
+import agent from './AGENT.md?raw';
 
 const options = defineAddonOptions()
 	.add('ide', {
@@ -60,6 +61,7 @@ export default defineAddon({
 			| {
 					schema?: string;
 					mcpServersKey?: string;
+					agentPath: string;
 					filePath: string;
 					typeLocal?: 'stdio' | 'local';
 					typeRemote?: 'http' | 'remote';
@@ -70,20 +72,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/AGENTS.md',
 				schema: 'https://opencode.ai/config.json',
 				mcpServersKey: 'mcp',
 				filePath: 'opencode.json',
@@ -93,6 +99,7 @@ export default defineAddon({
 				args: null
 			},
 			vscode: {
+				agentPath: 'AGENTS.md',
 				mcpServersKey: 'servers',
 				filePath: '.vscode/mcp.json'
 			},
@@ -105,6 +112,11 @@ export default defineAddon({
 			const value = configurator[ide];
 			if ('other' in value) continue;
 
+			sv.file('AGENT.md', (content) => {
+				if (content) return content;
+				return agent;
+			});
+
 			const { mcpServersKey, filePath, typeLocal, typeRemote, env, schema, command, args } = value;
 			sv.file(filePath, (content) => {
 				const { data, generateCode } = parseJson(content);

From 73ca4a60a43ce7377dc5eba252a7bb9aafee4a72 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 11 Nov 2025 01:27:44 +0800
Subject: [PATCH 02/11] add a warning

---
 packages/addons/mcp/index.ts | 25 +++++++++++++++++++++----
 1 file changed, 21 insertions(+), 4 deletions(-)

diff --git a/packages/addons/mcp/index.ts b/packages/addons/mcp/index.ts
index 5bf09ef24..a24704a5f 100644
--- a/packages/addons/mcp/index.ts
+++ b/packages/addons/mcp/index.ts
@@ -1,4 +1,5 @@
-import { defineAddon, defineAddonOptions } from '@sveltejs/cli-core';
+import { colors, defineAddon, defineAddonOptions, log } from '@sveltejs/cli-core';
+
 import { parseJson } from '@sveltejs/cli-core/parsers';
 import agent from './AGENT.md?raw';
 
@@ -112,12 +113,28 @@ export default defineAddon({
 			const value = configurator[ide];
 			if ('other' in value) continue;
 
-			sv.file('AGENT.md', (content) => {
-				if (content) return content;
+			const {
+				mcpServersKey,
+				agentPath,
+				filePath,
+				typeLocal,
+				typeRemote,
+				env,
+				schema,
+				command,
+				args
+			} = value;
+
+			sv.file(agentPath, (content) => {
+				if (content) {
+					log.warn(
+						`A ${colors.yellow(agentPath)} file already exists. Could not update. See https://svelte.dev/docs/mcp/overview#Usage on how to add the prompt manually.`
+					);
+					return content;
+				}
 				return agent;
 			});
 
-			const { mcpServersKey, filePath, typeLocal, typeRemote, env, schema, command, args } = value;
 			sv.file(filePath, (content) => {
 				const { data, generateCode } = parseJson(content);
 				if (schema) {

From 6fd61ac70df179b9b2a229b4d9f40c764c1d32e3 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 11 Nov 2025 13:05:22 +0800
Subject: [PATCH 03/11] add changeset

---
 .changeset/quick-comics-tell.md | 5 +++++
 1 file changed, 5 insertions(+)
 create mode 100644 .changeset/quick-comics-tell.md

diff --git a/.changeset/quick-comics-tell.md b/.changeset/quick-comics-tell.md
new file mode 100644
index 000000000..bd50eb75f
--- /dev/null
+++ b/.changeset/quick-comics-tell.md
@@ -0,0 +1,5 @@
+---
+'sv': patch
+---
+
+feat(mcp): include an `AGENTS.md` when using the `mcp` addon

From bfdb66549600da0530ce29230dd5ac3c416447d0 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 11 Nov 2025 16:58:42 +0800
Subject: [PATCH 04/11] fixes

---
 packages/addons/mcp/{AGENT.md => AGENTS.md} |  0
 packages/addons/mcp/index.ts                | 12 ++++++++----
 2 files changed, 8 insertions(+), 4 deletions(-)
 rename packages/addons/mcp/{AGENT.md => AGENTS.md} (100%)

diff --git a/packages/addons/mcp/AGENT.md b/packages/addons/mcp/AGENTS.md
similarity index 100%
rename from packages/addons/mcp/AGENT.md
rename to packages/addons/mcp/AGENTS.md
diff --git a/packages/addons/mcp/index.ts b/packages/addons/mcp/index.ts
index a24704a5f..aef1d6b46 100644
--- a/packages/addons/mcp/index.ts
+++ b/packages/addons/mcp/index.ts
@@ -1,7 +1,7 @@
+import fs from 'node:fs';
 import { colors, defineAddon, defineAddonOptions, log } from '@sveltejs/cli-core';
-
 import { parseJson } from '@sveltejs/cli-core/parsers';
-import agent from './AGENT.md?raw';
+import agent from './AGENTS.md?raw';
 
 const options = defineAddonOptions()
 	.add('ide', {
@@ -125,10 +125,14 @@ export default defineAddon({
 				args
 			} = value;
 
+			const placesToCheck = Object.values(configurator)
+				.filter((_) => 'agentPath' in _)
+				.map(({ agentPath }) => agentPath);
+
 			sv.file(agentPath, (content) => {
-				if (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 on how to add the prompt manually.`
+						`A ${colors.yellow(agentPath)} file already exists. Could not update. See https://svelte.dev/docs/mcp/overview#Usage for manual setup.`
 					);
 					return content;
 				}

From 3c82ca300768ebfdce8c02c374de92f5f218bcf0 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 11 Nov 2025 17:10:33 +0800
Subject: [PATCH 05/11] .

---
 packages/addons/mcp/.opencode/agent/svelte.md | 41 +++++++++++++++++++
 packages/addons/mcp/index.ts                  |  2 +-
 2 files changed, 42 insertions(+), 1 deletion(-)
 create mode 100644 packages/addons/mcp/.opencode/agent/svelte.md

diff --git a/packages/addons/mcp/.opencode/agent/svelte.md b/packages/addons/mcp/.opencode/agent/svelte.md
new file mode 100644
index 000000000..f509ca0c8
--- /dev/null
+++ b/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.
diff --git a/packages/addons/mcp/index.ts b/packages/addons/mcp/index.ts
index aef1d6b46..dac7a44a1 100644
--- a/packages/addons/mcp/index.ts
+++ b/packages/addons/mcp/index.ts
@@ -90,7 +90,7 @@ export default defineAddon({
 				filePath: '.gemini/settings.json'
 			},
 			opencode: {
-				agentPath: '.opencode/agent/AGENTS.md',
+				agentPath: '.opencode/agent/svelte.md',
 				schema: 'https://opencode.ai/config.json',
 				mcpServersKey: 'mcp',
 				filePath: 'opencode.json',

From 06cc3aed796157bc7bed3e5543be4f5707858248 Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Tue, 11 Nov 2025 17:28:33 +0800
Subject: [PATCH 06/11] update docs

---
 documentation/docs/30-add-ons/17-mcp.md | 5 ++++-
 1 file changed, 4 insertions(+), 1 deletion(-)

diff --git a/documentation/docs/30-add-ons/17-mcp.md b/documentation/docs/30-add-ons/17-mcp.md
index 333af34c4..af14e3b58 100644
--- a/documentation/docs/30-add-ons/17-mcp.md
+++ b/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
 

From 1dd610fd32b906653a75c56eb8e5ec7215e39e6f Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 18 Nov 2025 16:32:17 +0100
Subject: [PATCH 07/11] update texts

---
 .changeset/quick-comics-tell.md         | 2 +-
 documentation/docs/30-add-ons/17-mcp.md | 6 +++---
 2 files changed, 4 insertions(+), 4 deletions(-)

diff --git a/.changeset/quick-comics-tell.md b/.changeset/quick-comics-tell.md
index bd50eb75f..b02705c61 100644
--- a/.changeset/quick-comics-tell.md
+++ b/.changeset/quick-comics-tell.md
@@ -2,4 +2,4 @@
 'sv': patch
 ---
 
-feat(mcp): include an `AGENTS.md` when using the `mcp` addon
+feat(mcp): include an `AGENTS.md` or similar when using the `mcp` addon
diff --git a/documentation/docs/30-add-ons/17-mcp.md b/documentation/docs/30-add-ons/17-mcp.md
index 0dfe8d37c..52b97101d 100644
--- a/documentation/docs/30-add-ons/17-mcp.md
+++ b/documentation/docs/30-add-ons/17-mcp.md
@@ -12,10 +12,10 @@ npx sv add mcp
 
 ## What you get
 
-Depending on your IDE setup, you’ll receive:
+Depending on your IDE selection, you’ll receive:
 
-- A MCP configuration
-- A `readme` for agent, either [`AGENTS.md`](https://agents.md/), `CLAUDE.md`, or `GEMINI.md`
+- A [MCP configuration](https://svelte.dev/docs/mcp/overview#Setup)
+- A [`README for agents`](https://agents.md/)
 
 ## Options
 

From add74a445c3d214bb43e7532521a77035a578feb Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 18 Nov 2025 17:11:28 +0100
Subject: [PATCH 08/11] move files to the shared location

---
 packages/addons/mcp/.opencode/agent/svelte.md | 41 --------------
 packages/addons/mcp/index.ts                  | 54 ++++++++++++-------
 packages/create/index.ts                      |  7 ++-
 packages/create/playground.ts                 |  7 +--
 .../mcp => create/shared/+mcp}/AGENTS.md      |  0
 .../shared/+mcp/opencode-prefix-AGENTS.md     | 17 ++++++
 packages/create/utils.ts                      |  7 +++
 7 files changed, 63 insertions(+), 70 deletions(-)
 delete mode 100644 packages/addons/mcp/.opencode/agent/svelte.md
 rename packages/{addons/mcp => create/shared/+mcp}/AGENTS.md (100%)
 create mode 100644 packages/create/shared/+mcp/opencode-prefix-AGENTS.md

diff --git a/packages/addons/mcp/.opencode/agent/svelte.md b/packages/addons/mcp/.opencode/agent/svelte.md
deleted file mode 100644
index f509ca0c8..000000000
--- a/packages/addons/mcp/.opencode/agent/svelte.md
+++ /dev/null
@@ -1,41 +0,0 @@
----
-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.
diff --git a/packages/addons/mcp/index.ts b/packages/addons/mcp/index.ts
index dac7a44a1..5a6607648 100644
--- a/packages/addons/mcp/index.ts
+++ b/packages/addons/mcp/index.ts
@@ -1,7 +1,7 @@
-import fs from 'node:fs';
-import { colors, defineAddon, defineAddonOptions, log } from '@sveltejs/cli-core';
+import { defineAddon, defineAddonOptions, log } from '@sveltejs/cli-core';
 import { parseJson } from '@sveltejs/cli-core/parsers';
-import agent from './AGENTS.md?raw';
+import { getSharedFiles } from '../../create/utils.ts';
+import { getHighlighter } from '../../cli/commands/add/utils.ts';
 
 const options = defineAddonOptions()
 	.add('ide', {
@@ -63,7 +63,7 @@ export default defineAddon({
 					schema?: string;
 					mcpServersKey?: string;
 					agentPath: string;
-					filePath: string;
+					mcpPath: string;
 					typeLocal?: 'stdio' | 'local';
 					typeRemote?: 'http' | 'remote';
 					env?: boolean;
@@ -74,26 +74,26 @@ export default defineAddon({
 		> = {
 			'claude-code': {
 				agentPath: 'CLAUDE.md',
-				filePath: '.mcp.json',
+				mcpPath: '.mcp.json',
 				typeLocal: 'stdio',
 				typeRemote: 'http',
 				env: true
 			},
 			cursor: {
 				agentPath: 'AGENTS.md',
-				filePath: '.cursor/mcp.json'
+				mcpPath: '.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'
+				mcpPath: '.gemini/settings.json'
 			},
 			opencode: {
 				agentPath: '.opencode/agent/svelte.md',
 				schema: 'https://opencode.ai/config.json',
 				mcpServersKey: 'mcp',
-				filePath: 'opencode.json',
+				mcpPath: 'opencode.json',
 				typeLocal: 'local',
 				typeRemote: 'remote',
 				command: ['npx', '-y', '@sveltejs/mcp'],
@@ -102,13 +102,18 @@ export default defineAddon({
 			vscode: {
 				agentPath: 'AGENTS.md',
 				mcpServersKey: 'servers',
-				filePath: '.vscode/mcp.json'
+				mcpPath: '.vscode/mcp.json'
 			},
 			other: {
 				other: true
 			}
 		};
 
+		const alreadyExists: string[] = [];
+
+		const sharedFiles = getSharedFiles().filter((file) => file.include.includes('mcp'));
+		const agentFile = sharedFiles.find((file) => file.name === 'AGENTS.md');
+
 		for (const ide of options.ide) {
 			const value = configurator[ide];
 			if ('other' in value) continue;
@@ -116,7 +121,7 @@ export default defineAddon({
 			const {
 				mcpServersKey,
 				agentPath,
-				filePath,
+				mcpPath,
 				typeLocal,
 				typeRemote,
 				env,
@@ -125,21 +130,22 @@ export default defineAddon({
 				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.`
-					);
+				if (content) {
+					alreadyExists.push(agentPath);
 					return content;
 				}
-				return agent;
+
+				const newContent: string[] = [];
+
+				const prefixFile = sharedFiles.find((file) => file.name === `${ide}-prefix-AGENTS.md`);
+				if (prefixFile) newContent.push(prefixFile.contents);
+				if (agentFile) newContent.push(agentFile.contents);
+
+				return newContent.join('\n');
 			});
 
-			sv.file(filePath, (content) => {
+			sv.file(mcpPath, (content) => {
 				const { data, generateCode } = parseJson(content);
 				if (schema) {
 					data['$schema'] = schema;
@@ -153,6 +159,14 @@ export default defineAddon({
 				return generateCode();
 			});
 		}
+
+		if (alreadyExists.length > 0) {
+			const highlighter = getHighlighter();
+			log.warn(
+				`${alreadyExists.map((path) => highlighter.path(path)).join(', ')} already exists, we didn't touch ${alreadyExists.length > 1 ? 'them' : 'it'}. ` +
+					`See ${highlighter.website('https://svelte.dev/docs/mcp/overview#Usage')} for manual setup.`
+			);
+		}
 	},
 	nextSteps({ highlighter, options }) {
 		const steps = [];
diff --git a/packages/create/index.ts b/packages/create/index.ts
index b415953ae..59b1ba8fb 100644
--- a/packages/create/index.ts
+++ b/packages/create/index.ts
@@ -1,6 +1,6 @@
 import fs from 'node:fs';
 import path from 'node:path';
-import { mkdirp, copy, dist } from './utils.ts';
+import { mkdirp, copy, dist, getSharedFiles } from './utils.ts';
 
 export type TemplateType = (typeof templateTypes)[number];
 export type LanguageType = (typeof languageTypes)[number];
@@ -19,7 +19,7 @@ export type File = {
 	contents: string;
 };
 
-export type Condition = TemplateType | LanguageType | 'playground';
+export type Condition = TemplateType | LanguageType | 'playground' | 'mcp';
 
 export type Common = {
 	files: Array<{
@@ -66,8 +66,7 @@ function write_template_files(template: string, types: LanguageType, name: strin
 }
 
 function write_common_files(cwd: string, options: Options, name: string) {
-	const shared = dist('shared.json');
-	const { files } = JSON.parse(fs.readFileSync(shared, 'utf-8')) as Common;
+	const files = getSharedFiles();
 
 	const pkg_file = path.join(cwd, 'package.json');
 	const pkg = /** @type {any} */ JSON.parse(fs.readFileSync(pkg_file, 'utf-8'));
diff --git a/packages/create/playground.ts b/packages/create/playground.ts
index 9ab4e0ab5..0741e30d0 100644
--- a/packages/create/playground.ts
+++ b/packages/create/playground.ts
@@ -3,8 +3,7 @@ import path from 'node:path';
 import * as js from '@sveltejs/cli-core/js';
 import { parseJson, parseScript, parseSvelte } from '@sveltejs/cli-core/parsers';
 import { isVersionUnsupportedBelow } from '@sveltejs/cli-core';
-import { dist } from './utils.ts';
-import type { Common } from './index.ts';
+import { getSharedFiles } from './utils.ts';
 
 export function validatePlaygroundUrl(link: string): boolean {
 	try {
@@ -182,9 +181,7 @@ export function setupPlaygroundProject(
 
 	// add playground shared files
 	{
-		const shared = dist('shared.json');
-		const { files } = JSON.parse(fs.readFileSync(shared, 'utf-8')) as Common;
-		const playgroundFiles = files.filter((file) => file.include.includes('playground'));
+		const playgroundFiles = getSharedFiles().filter((file) => file.include.includes('playground'));
 
 		for (const file of playgroundFiles) {
 			let contentToWrite = file.contents;
diff --git a/packages/addons/mcp/AGENTS.md b/packages/create/shared/+mcp/AGENTS.md
similarity index 100%
rename from packages/addons/mcp/AGENTS.md
rename to packages/create/shared/+mcp/AGENTS.md
diff --git a/packages/create/shared/+mcp/opencode-prefix-AGENTS.md b/packages/create/shared/+mcp/opencode-prefix-AGENTS.md
new file mode 100644
index 000000000..d59301257
--- /dev/null
+++ b/packages/create/shared/+mcp/opencode-prefix-AGENTS.md
@@ -0,0 +1,17 @@
+---
+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
+---
diff --git a/packages/create/utils.ts b/packages/create/utils.ts
index bd5531a3a..08dd6891e 100644
--- a/packages/create/utils.ts
+++ b/packages/create/utils.ts
@@ -1,6 +1,7 @@
 import fs from 'node:fs';
 import path from 'node:path';
 import { fileURLToPath } from 'node:url';
+import type { Common } from './index.ts';
 
 export function mkdirp(dir: string): void {
 	try {
@@ -44,3 +45,9 @@ export function dist(path: string): string {
 		new URL(`./${!insideDistFolder ? 'dist/' : ''}${path}`, import.meta.url).href
 	);
 }
+
+export function getSharedFiles(): Common['files'] {
+	const shared = dist('shared.json');
+	const { files } = JSON.parse(fs.readFileSync(shared, 'utf-8')) as Common;
+	return files;
+}

From 1456546c45379166e645804d30874139ce8fd80a Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 18 Nov 2025 17:19:26 +0100
Subject: [PATCH 09/11] only add once each file (cuz some ide use the same)

---
 packages/addons/mcp/index.ts | 33 +++++++++++++++++++--------------
 1 file changed, 19 insertions(+), 14 deletions(-)

diff --git a/packages/addons/mcp/index.ts b/packages/addons/mcp/index.ts
index 5a6607648..41b7080f4 100644
--- a/packages/addons/mcp/index.ts
+++ b/packages/addons/mcp/index.ts
@@ -109,7 +109,8 @@ export default defineAddon({
 			}
 		};
 
-		const alreadyExists: string[] = [];
+		const filesAdded: string[] = [];
+		const filesExistingAlready: string[] = [];
 
 		const sharedFiles = getSharedFiles().filter((file) => file.include.includes('mcp'));
 		const agentFile = sharedFiles.find((file) => file.name === 'AGENTS.md');
@@ -130,20 +131,24 @@ export default defineAddon({
 				args
 			} = value;
 
-			sv.file(agentPath, (content) => {
-				if (content) {
-					alreadyExists.push(agentPath);
-					return content;
-				}
+			// We only add the agent file if it's not already added
+			if (!filesAdded.includes(agentPath)) {
+				sv.file(agentPath, (content) => {
+					if (content) {
+						filesExistingAlready.push(agentPath);
+						return content;
+					}
+					filesAdded.push(agentPath);
 
-				const newContent: string[] = [];
+					const newContent: string[] = [];
 
-				const prefixFile = sharedFiles.find((file) => file.name === `${ide}-prefix-AGENTS.md`);
-				if (prefixFile) newContent.push(prefixFile.contents);
-				if (agentFile) newContent.push(agentFile.contents);
+					const prefixFile = sharedFiles.find((file) => file.name === `${ide}-prefix-AGENTS.md`);
+					if (prefixFile) newContent.push(prefixFile.contents);
+					if (agentFile) newContent.push(agentFile.contents);
 
-				return newContent.join('\n');
-			});
+					return newContent.join('\n');
+				});
+			}
 
 			sv.file(mcpPath, (content) => {
 				const { data, generateCode } = parseJson(content);
@@ -160,10 +165,10 @@ export default defineAddon({
 			});
 		}
 
-		if (alreadyExists.length > 0) {
+		if (filesExistingAlready.length > 0) {
 			const highlighter = getHighlighter();
 			log.warn(
-				`${alreadyExists.map((path) => highlighter.path(path)).join(', ')} already exists, we didn't touch ${alreadyExists.length > 1 ? 'them' : 'it'}. ` +
+				`${filesExistingAlready.map((path) => highlighter.path(path)).join(', ')} already exists, we didn't touch ${filesExistingAlready.length > 1 ? 'them' : 'it'}. ` +
 					`See ${highlighter.website('https://svelte.dev/docs/mcp/overview#Usage')} for manual setup.`
 			);
 		}

From 8d23dec3aeb3385f39419e4e4ea15c255b4e8a89 Mon Sep 17 00:00:00 2001
From: jycouet <jycouet@gmail.com>
Date: Tue, 18 Nov 2025 17:30:53 +0100
Subject: [PATCH 10/11] tweak docs

---
 documentation/docs/30-add-ons/17-mcp.md | 6 ++----
 1 file changed, 2 insertions(+), 4 deletions(-)

diff --git a/documentation/docs/30-add-ons/17-mcp.md b/documentation/docs/30-add-ons/17-mcp.md
index 52b97101d..991c1333e 100644
--- a/documentation/docs/30-add-ons/17-mcp.md
+++ b/documentation/docs/30-add-ons/17-mcp.md
@@ -12,10 +12,8 @@ npx sv add mcp
 
 ## What you get
 
-Depending on your IDE selection, you’ll receive:
-
-- A [MCP configuration](https://svelte.dev/docs/mcp/overview#Setup)
-- A [`README for agents`](https://agents.md/)
+- A MCP configuration for [local](https://svelte.dev/docs/mcp/local-setup) or [remote](https://svelte.dev/docs/mcp/remote-setup) setup
+- A [README for agents](https://agents.md/) to help you use the MCP server effectively
 
 ## Options
 

From a15c0986df42b51390137a307a0b50283bba117e Mon Sep 17 00:00:00 2001
From: Scott Wu <sw@scottwu.ca>
Date: Thu, 20 Nov 2025 08:27:00 +0800
Subject: [PATCH 11/11] simply `opencode` setup

---
 packages/addons/mcp/index.ts                    | 13 +++----------
 .../shared/+mcp/opencode-prefix-AGENTS.md       | 17 -----------------
 2 files changed, 3 insertions(+), 27 deletions(-)
 delete mode 100644 packages/create/shared/+mcp/opencode-prefix-AGENTS.md

diff --git a/packages/addons/mcp/index.ts b/packages/addons/mcp/index.ts
index 41b7080f4..663058fc1 100644
--- a/packages/addons/mcp/index.ts
+++ b/packages/addons/mcp/index.ts
@@ -90,7 +90,7 @@ export default defineAddon({
 				mcpPath: '.gemini/settings.json'
 			},
 			opencode: {
-				agentPath: '.opencode/agent/svelte.md',
+				agentPath: 'AGENTS.md',
 				schema: 'https://opencode.ai/config.json',
 				mcpServersKey: 'mcp',
 				mcpPath: 'opencode.json',
@@ -139,14 +139,7 @@ export default defineAddon({
 						return content;
 					}
 					filesAdded.push(agentPath);
-
-					const newContent: string[] = [];
-
-					const prefixFile = sharedFiles.find((file) => file.name === `${ide}-prefix-AGENTS.md`);
-					if (prefixFile) newContent.push(prefixFile.contents);
-					if (agentFile) newContent.push(agentFile.contents);
-
-					return newContent.join('\n');
+					return agentFile?.contents ?? '';
 				});
 			}
 
@@ -155,7 +148,7 @@ export default defineAddon({
 				if (schema) {
 					data['$schema'] = schema;
 				}
-				const key = mcpServersKey || 'mcpServers';
+				const key = mcpServersKey ?? 'mcpServers';
 				data[key] ??= {};
 				data[key].svelte =
 					options.setup === 'local'
diff --git a/packages/create/shared/+mcp/opencode-prefix-AGENTS.md b/packages/create/shared/+mcp/opencode-prefix-AGENTS.md
deleted file mode 100644
index d59301257..000000000
--- a/packages/create/shared/+mcp/opencode-prefix-AGENTS.md
+++ /dev/null
@@ -1,17 +0,0 @@
----
-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
----