From 5001f2bad3e08316cee95e36b9003700f36f7e02 Mon Sep 17 00:00:00 2001 From: Scott Wu Date: Tue, 11 Nov 2025 01:09:06 +0800 Subject: [PATCH 1/6] 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 00000000..a6e66ff1 --- /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 05c5f8a0..5bf09ef2 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 Date: Tue, 11 Nov 2025 01:27:44 +0800 Subject: [PATCH 2/6] 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 5bf09ef2..a24704a5 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 Date: Tue, 11 Nov 2025 13:05:22 +0800 Subject: [PATCH 3/6] 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 00000000..bd50eb75 --- /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 Date: Tue, 11 Nov 2025 16:58:42 +0800 Subject: [PATCH 4/6] 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 a24704a5..aef1d6b4 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 Date: Tue, 11 Nov 2025 17:10:33 +0800 Subject: [PATCH 5/6] . --- 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 00000000..f509ca0c --- /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 aef1d6b4..dac7a44a 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 Date: Tue, 11 Nov 2025 17:28:33 +0800 Subject: [PATCH 6/6] 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 333af34c..af14e3b5 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