From 0fd7651cca44a0460627420cb6af2b40a05e3b5a Mon Sep 17 00:00:00 2001 From: paoloricciuti Date: Fri, 3 Oct 2025 16:51:06 +0200 Subject: [PATCH 1/5] feat: add `mcp` to `sync-docs` --- apps/svelte.dev/scripts/sync-docs/README.md | 4 ++- apps/svelte.dev/scripts/sync-docs/index.ts | 8 ++++++ apps/svelte.dev/src/routes/+layout.server.ts | 27 +++++++++++--------- 3 files changed, 26 insertions(+), 13 deletions(-) diff --git a/apps/svelte.dev/scripts/sync-docs/README.md b/apps/svelte.dev/scripts/sync-docs/README.md index 73ad236d0f..057e6369be 100644 --- a/apps/svelte.dev/scripts/sync-docs/README.md +++ b/apps/svelte.dev/scripts/sync-docs/README.md @@ -1,6 +1,6 @@ # sync-docs -Documentation lives in external repos (at the time of writing, [`sveltejs/svelte`](https://github.com/sveltejs/svelte), [`sveltejs/kit`](https://github.com/sveltejs/kit) and [`sveltejs/cli`](https://github.com/sveltejs/cli), though the plan is to add others) and synced into this repo. +Documentation lives in external repos (at the time of writing, [`sveltejs/svelte`](https://github.com/sveltejs/svelte), [`sveltejs/kit`](https://github.com/sveltejs/kit), [`sveltejs/cli`](https://github.com/sveltejs/cli) and [`sveltejs/mcp`](https://github.com/sveltejs/mcp), though the plan is to add others) and synced into this repo. The repos must be cloned (or linked — see [next section](#setup)) into the `apps/svelte.dev/repos` directory. @@ -24,6 +24,8 @@ New-Item -Path .\repos\kit -ItemType SymbolicLink -Value /path/to/wherever/you/c New-Item -Path .\repos\cli -ItemType SymbolicLink -Value /path/to/wherever/you/cloned/sveltejs/cli ``` +The path needs to be absolute to work properly. + ## Syncing To run the `sync-docs` script locally: diff --git a/apps/svelte.dev/scripts/sync-docs/index.ts b/apps/svelte.dev/scripts/sync-docs/index.ts index ae4be99692..91d024f64f 100644 --- a/apps/svelte.dev/scripts/sync-docs/index.ts +++ b/apps/svelte.dev/scripts/sync-docs/index.ts @@ -149,6 +149,14 @@ const packages: Package[] = [ pkg: 'packages/cli', docs: 'documentation/docs', types: null + }, + { + name: 'mcp', + repo: `${parsed.values.owner}/mcp`, + branch: branches['mcp'] ?? 'main', + pkg: 'packages/mcp-stdio', + docs: 'documentation/docs', + types: null } ]; diff --git a/apps/svelte.dev/src/routes/+layout.server.ts b/apps/svelte.dev/src/routes/+layout.server.ts index d5efdc2873..86d6781ab4 100644 --- a/apps/svelte.dev/src/routes/+layout.server.ts +++ b/apps/svelte.dev/src/routes/+layout.server.ts @@ -9,19 +9,22 @@ const nav_links: NavigationLink[] = [ { title: 'Docs', slug: 'docs', - sections: [docs.topics['docs/svelte'], docs.topics['docs/kit'], docs.topics['docs/cli']].map( - (topic) => ({ - title: topic.metadata.title, - path: '/' + topic.slug, // this will make the UI show a flyout menu for the docs nav entry - sections: topic.children.map((section) => ({ - title: section.metadata.title, - sections: section.children.map((page) => ({ - title: page.metadata.title, - path: '/' + page.slug - })) + sections: [ + docs.topics['docs/svelte'], + docs.topics['docs/kit'], + docs.topics['docs/cli'], + docs.topics['docs/mcp'] + ].map((topic) => ({ + title: topic.metadata.title, + path: '/' + topic.slug, // this will make the UI show a flyout menu for the docs nav entry + sections: topic.children.map((section) => ({ + title: section.metadata.title, + sections: section.children.map((page) => ({ + title: page.metadata.title, + path: '/' + page.slug })) - }) - ) + })) + })) }, { title: 'Tutorial', From ba44259f0c3df4323f88988dc6e8fd8fdf1b965f Mon Sep 17 00:00:00 2001 From: paoloricciuti Date: Fri, 3 Oct 2025 16:51:27 +0200 Subject: [PATCH 2/5] fix: ignore `##` in code blocks for table of content --- packages/site-kit/src/lib/markdown/utils.ts | 11 +++++++ .../site-kit/src/lib/server/content/index.ts | 31 ++++++++++++------- 2 files changed, 30 insertions(+), 12 deletions(-) diff --git a/packages/site-kit/src/lib/markdown/utils.ts b/packages/site-kit/src/lib/markdown/utils.ts index 559d507456..d51e2abf0a 100644 --- a/packages/site-kit/src/lib/markdown/utils.ts +++ b/packages/site-kit/src/lib/markdown/utils.ts @@ -14,6 +14,17 @@ export const SHIKI_LANGUAGE_MAP = { '': '' }; +export function is_in_code_block(body: string, index: number) { + const code_blocks = [...body.matchAll(/```.*\n(.|\n)+```/gm)].map((match) => { + return [match.index ?? 0, match[0].length + (match.index ?? 0)] as const; + }); + + return code_blocks.some(([start, end]) => { + if (index >= start && index <= end) return true; + return false; + }); +} + /** * Strip styling/links etc from markdown */ diff --git a/packages/site-kit/src/lib/server/content/index.ts b/packages/site-kit/src/lib/server/content/index.ts index a2f6defb2e..d7a70ef7bc 100644 --- a/packages/site-kit/src/lib/server/content/index.ts +++ b/packages/site-kit/src/lib/server/content/index.ts @@ -1,4 +1,4 @@ -import { extract_frontmatter, slugify, smart_quotes } from '../../markdown/utils'; +import { extract_frontmatter, is_in_code_block, slugify, smart_quotes } from '../../markdown/utils'; import type { Document } from '../../types'; export async function create_index( @@ -31,17 +31,24 @@ export async function create_index( '$1' ); - const sections = Array.from(body.matchAll(/^##\s+(.*)$/gm)).map((match) => { - const title = smart_quotes(match[1]) - // replace < and > inside code spans - .replace(/`(.+?)`/g, (_, contents) => contents.replace(//g, '>')) - // turn e.g. `class:_name_` into `class:name` - .replace(/_(.+)_/g, (_, contents) => `${contents}`); - - const slug = slugify(title); - - return { slug, title }; - }); + const sections = Array.from(body.matchAll(/^##\s+(.*)$/gm)).reduce( + (arr, match) => { + if (is_in_code_block(body, match.index || 0)) return arr; + const title = smart_quotes(match[1]) + // replace < and > inside code spans + .replace(/`(.+?)`/g, (_, contents) => + contents.replace(//g, '>') + ) + // turn e.g. `class:_name_` into `class:name` + .replace(/_(.+)_/g, (_, contents) => `${contents}`); + + const slug = slugify(title); + + arr.push({ slug, title }); + return arr; + }, + [] as Array<{ slug: string; title: string }> + ); content[slug] = { slug, From 1ca2b7bdda3402a10ce9486bf03dcd053c92db7a Mon Sep 17 00:00:00 2001 From: paoloricciuti Date: Fri, 3 Oct 2025 16:51:41 +0200 Subject: [PATCH 3/5] docs: add mcp docs --- .../docs/mcp/10-introduction/10-overview.md | 42 ++++++ .../content/docs/mcp/10-introduction/index.md | 4 + .../docs/mcp/20-setup/20-local-setup.md | 122 ++++++++++++++++++ .../docs/mcp/20-setup/30-remote-setup.md | 108 ++++++++++++++++ .../content/docs/mcp/20-setup/index.md | 4 + .../docs/mcp/30-capabilities/10-tools.md | 22 ++++ .../docs/mcp/30-capabilities/20-resources.md | 10 ++ .../docs/mcp/30-capabilities/30-prompts.md | 27 ++++ .../content/docs/mcp/30-capabilities/index.md | 4 + apps/svelte.dev/content/docs/mcp/index.md | 4 + 10 files changed, 347 insertions(+) create mode 100644 apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md create mode 100644 apps/svelte.dev/content/docs/mcp/10-introduction/index.md create mode 100644 apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md create mode 100644 apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md create mode 100644 apps/svelte.dev/content/docs/mcp/20-setup/index.md create mode 100644 apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md create mode 100644 apps/svelte.dev/content/docs/mcp/30-capabilities/20-resources.md create mode 100644 apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md create mode 100644 apps/svelte.dev/content/docs/mcp/30-capabilities/index.md create mode 100644 apps/svelte.dev/content/docs/mcp/index.md diff --git a/apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md b/apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md new file mode 100644 index 0000000000..873e6dacc0 --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md @@ -0,0 +1,42 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Overview +--- + +The official Svelte MCP (Model Context Protocol) Server can help your LLM or Agent of choice write better Svelte code by providing it with documentation and tools to get suggestions on the generated code based on static analysis. + +## Setup + +The setup differs based on the version of the MCP you prefer (either remote or local) and the MCP client of your choice (e.g. Claude Code, Codex CLI, GitHub Copilot etc.). Refer to our documentation to learn how to set those up [locally](./local-setup) and [remotely](./remote-setup) for the most common clients. + +## Usage + +To get the most out of the MCP we recommend including the following prompt in your `AGENTS.md` or `CLAUDE.md`. This will instruct the LLM on what's available and when it's appropriate to use the MCP. + +```md +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. +``` + +If your MCP client supports it, we also recommend using the [svelte-task](./prompts#svelte-task) prompt to instruct the LLM on the best way to use the MCP server. diff --git a/apps/svelte.dev/content/docs/mcp/10-introduction/index.md b/apps/svelte.dev/content/docs/mcp/10-introduction/index.md new file mode 100644 index 0000000000..ef4e6600ad --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/10-introduction/index.md @@ -0,0 +1,4 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Introduction +--- diff --git a/apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md b/apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md new file mode 100644 index 0000000000..057bd83f46 --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md @@ -0,0 +1,122 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Local setup +--- + +The STDIO (local) version of the MCP server is available as an `npm` package: `@sveltjs/mcp`. You can either install it globally and then reference it in your configuration or run it with `npx`. + +```bash +npx -y @sveltejs/mcp +``` + +Here's how to set it up in some common MCP clients: + +## Claude Code + +To include the local MCP version in Claude Code, simply run the following command: + +```bash +claude mcp add -t stdio -s [scope] [name] npx -y @sveltejs/mcp +``` + +You can choose your preferred `scope` (it must be `user`, `project` or `local`) and `name`. + +## Claude Desktop + +Open the Developer section in settings, click on `Edit Config`. It will open the folder with a `claude_desktop_config.json` file in it. Edit the file to include the following configuration: + +```json +{ + "mcpServers": { + "[name]": { + "command": "npx", + "args": ["-y", "@sveltejs/mcp"] + } + } +} +``` + +The top level must be `mcpServers` but you can choose your preferred `name`. + +## Codex CLI + +Add the following to your `config.toml` (defaults to `~/.codex/config.toml`... refer to [the configuration documentation](https://github.com/openai/codex/blob/69cb72f8422f2aa7222bea3a6ce48fd130fa76c4/docs/config.md) for more advanced setups): + +```toml +[mcp_servers.name] +command = "npx" +args = ["-y", "@sveltejs/mcp"] +``` + +The top level must be `mcp_server` but you can choose your preferred `name`. + +## Gemini CLI + +To include the local MCP version in Gemini CLI, simply run the following command: + +```bash +gemini mcp add -t stdio -s [scope] [name] npx -y @sveltejs/mcp +``` + +You can choose your preferred `scope` (it must be `user`, `project` or `local`) and `name`. + +## Opencode + +Run the command: + +```bash +opencode mcp add +``` + +and follow the instructions, selecting Local when asked for "Select MCP server type": + +```bash +opencode mcp add + +┌ Add MCP server +│ +◇ Enter MCP server name +│ [name] +│ +◇ Select MCP server type +│ Local +│ +◆ Enter command to run +│ npx -y @sveltejs/mcp +``` + +You can choose your preferred `name`. + +## VSCode + +- Open the command Palette +- Select "MCP: Add Server..." +- Select "Command (stdio)" +- Insert `npx -y @sveltejs/mcp` in the input and press `Enter` +- Insert your preferred name +- Select if you want to add it as a `Global` or `Workspace` MCP server + +## Cursor + +- Open the command Palette +- Select "View: Open MCP Settings" +- Click on "Add custom MCP" + +It will open a file with your MCP servers where you can add the following configuration: + +```json +{ + "mcpServers": { + "[name]": { + "command": "npx", + "args": ["-y", "@sveltejs/mcp"] + } + } +} +``` + +The top level must be `mcpServers` but you can choose your preferred `name`. + +## Other clients + +If we didn't include the MCP client you are using, refer to their documentation for `stdio` servers and use `npx` as the command and `-y @sveltejs/mcp` as the arguments. diff --git a/apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md b/apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md new file mode 100644 index 0000000000..63e5c46e7e --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md @@ -0,0 +1,108 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Remote setup +--- + +The remote version of the MCP server is available on `https://mcp.svelte.dev/mcp`. + +Here's how to set it up in some common MCP clients: + +## Claude Code + +To include the remote MCP version in Claude Code, simply run the following command: + +```bash +claude mcp add -t http -s [scope] [name] https://mcp.svelte.dev/mcp +``` + +You can choose your preferred `scope` (it must be `user`, `project` or `local`) and `name`. + +## Claude Desktop + +- Open `Settings > Connectors` +- Click on `Add Custom Connector` +- Insert the name you prefer most +- Insert `https://mcp.svelte.dev/mcp` as the `Remote MCP server URL` +- Click `Add` + +## Codex CLI + +Add the following to your `config.toml` (defaults to `~/.codex/config.toml`... refer to [the configuration documentation](https://github.com/openai/codex/blob/69cb72f8422f2aa7222bea3a6ce48fd130fa76c4/docs/config.md) for more advanced setups): + +```toml +experimental_use_rmcp_client = true +[mcp_servers.name] +url = "https://mcp.svelte.dev/mcp" +``` + +To use HTTP servers in Codex you need to enable `experimental_use_rmcp_client` and the top level must be `mcp_server` but you can choose your preferred `name`. + +## Gemini CLI + +To include the remote MCP version in Gemini CLI, simply run the following command: + +```bash +gemini mcp add -t http -s [scope] [name] https://mcp.svelte.dev/mcp +``` + +You can choose your preferred `scope` (it must be `user`, `project` or `local`) and `name`. + +## Opencode + +Run the command: + +```bash +opencode mcp add +``` + +and follow the instructions, selecting Remote when asked for "Select MCP server type": + +```bash +opencode mcp add + +┌ Add MCP server +│ +◇ Enter MCP server name +│ [name] +│ +◇ Select MCP server type +│ Remote +│ +◇ Enter MCP server URL +│ https://mcp.svelte.dev/mcp +``` + +You can choose your preferred `name`. + +## VSCode + +- Open the command Palette +- Select "MCP: Add Server..." +- Select "HTTP (HTTP or Server-Sent-Events)" +- Insert `https://mcp.svelte.dev/mcp` in the input and press `Enter` +- Insert your preferred name +- Select if you want to add it as a `Global` or `Workspace` MCP server + +## Cursor + +- Open the command Palette +- Select "View: Open MCP Settings" +- Click on "Add custom MCP" + +It will open a file with your MCP servers where you can add the following configuration: + +```json +{ + "mcpServers": { + "[name]": { + "url": "https://mcp.svelte.dev/mcp" + } + } +} +``` + +The top level must be `mcpServers` but you can choose your preferred `name`. + +## Other clients + +If we didn't include the MCP client you are using, refer to their documentation for `remote` servers and use `https://mcp.svelte.dev/mcp` as the URL. diff --git a/apps/svelte.dev/content/docs/mcp/20-setup/index.md b/apps/svelte.dev/content/docs/mcp/20-setup/index.md new file mode 100644 index 0000000000..9d44ee49ac --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/20-setup/index.md @@ -0,0 +1,4 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Setup +--- diff --git a/apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md b/apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md new file mode 100644 index 0000000000..44424c94df --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md @@ -0,0 +1,22 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Tools +--- + +This is the list of available tools provided by the MCP server. The list of tools is given to the model which can decide to call one or more of the tools during a session. + +## list-sections + +Provides a list of all the available documentation sections and their use cases if available. The titles of the sections will be used by the LLM to get up-to-date documentation directly from the official documentation. + +## get-documentation + +Allows the model to get the full documentation for the requested sections. The documentation is fetched on the fly from the official Svelte documentation and it will always be up to date. + +## svelte-autofixer + +Uses static analysis to provide suggestions for the generated code. It should be invoked in a loop by the model until all issues and suggestions are resolved. + +## playground-link + +Generates an ephemeral playground link with the generated code. It's useful when the generated code is not written to a file in your project and you want to quickly test the generated solution. The code is not stored anywhere, the server uses the `share-with-hash` functionality of the Svelte playground to generate the correct hash on the fly (which is also why it will generate a pretty big link). diff --git a/apps/svelte.dev/content/docs/mcp/30-capabilities/20-resources.md b/apps/svelte.dev/content/docs/mcp/30-capabilities/20-resources.md new file mode 100644 index 0000000000..54b0a837ec --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/30-capabilities/20-resources.md @@ -0,0 +1,10 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Resources +--- + +This is the list of available resources provided by the MCP server. Resources are included by the user (not by the LLM) and are useful if you want to include specific knowledge in your session. For example, if you know that the component will need to use transitions you can include the transition documentation directly without asking the LLM to do it for you. + +## doc-section + +This dynamic resource allows you to add every section of the Svelte documentation as a resource. The URI looks like this `svelte://slug-of-the-docs.md` and the returned resource will contain the `llms.txt` version of the specific page you selected. diff --git a/apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md b/apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md new file mode 100644 index 0000000000..1967df287a --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md @@ -0,0 +1,27 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Prompts +--- + +This is the list of available prompts provided by the MCP server. Prompts are selected by the user and are sent as a user message. They can be useful to write repetitive instructions for the LLM on how to properly use the MCP server. + +## svelte-task + +This prompt should be used whenever you are asking the LLM to work on some Svelte-related task. It will instruct the LLM on which documentation sections are available, which tool to invoke, when to invoke it, and how to interpret the result. It will ask you for the description of the task and the returned value will look like this: + +``` +You are a Svelte expert tasked to build components and utilities for Svelte developers. If you need documentation for anything related to Svelte you can invoke the tool \`get-documentation\` with one of the following paths: + +[all available docs] + + +Every time you write a Svelte component or a Svelte module you MUST invoke the \`svelte-autofixer\` tool providing the code. The tool will return a list of issues or suggestions. If there are any issues or suggestions you MUST fix them and call the tool again with the updated code. You MUST keep doing this until the tool returns no issues or suggestions. Only then you can return the code to the user. + +This is the task you will work on: + + +[your task here] + + +If you are not writing the code into a file, once you have the final version of the code ask the user if they want to generate a playground link to quickly check the code in it and if they answer yes call the \`playground-link\` tool and return the url to the user nicely formatted. The playground link MUST be generated only once you have the final version of the code and you are ready to share it, it MUST include an entry point file called \`App.svelte\` where the main component should live. If you have multiple files to include in the playground link you can include them all at the root. +``` diff --git a/apps/svelte.dev/content/docs/mcp/30-capabilities/index.md b/apps/svelte.dev/content/docs/mcp/30-capabilities/index.md new file mode 100644 index 0000000000..881a580c4b --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/30-capabilities/index.md @@ -0,0 +1,4 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: Capabilities +--- diff --git a/apps/svelte.dev/content/docs/mcp/index.md b/apps/svelte.dev/content/docs/mcp/index.md new file mode 100644 index 0000000000..29fa47ea19 --- /dev/null +++ b/apps/svelte.dev/content/docs/mcp/index.md @@ -0,0 +1,4 @@ +--- +NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts +title: MCP +--- From fd9270d219f749826c035782283fa8a2022b94c9 Mon Sep 17 00:00:00 2001 From: paoloricciuti Date: Fri, 3 Oct 2025 18:10:13 +0200 Subject: [PATCH 4/5] fix: push new change --- apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md b/apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md index 1967df287a..c36a6c684c 100644 --- a/apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md +++ b/apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md @@ -7,7 +7,7 @@ This is the list of available prompts provided by the MCP server. Prompts are se ## svelte-task -This prompt should be used whenever you are asking the LLM to work on some Svelte-related task. It will instruct the LLM on which documentation sections are available, which tool to invoke, when to invoke it, and how to interpret the result. It will ask you for the description of the task and the returned value will look like this: +This prompt should be used whenever you are asking the model to work on some Svelte-related task. It will instruct the LLM on which documentation sections are available, which tool to invoke, when to invoke it, and how to interpret the result. It will ask you for the description of the task and the returned value will look like this: ``` You are a Svelte expert tasked to build components and utilities for Svelte developers. If you need documentation for anything related to Svelte you can invoke the tool \`get-documentation\` with one of the following paths: From 6b5790299521e3a05558ae48b6b859ad12fbdfb9 Mon Sep 17 00:00:00 2001 From: paoloricciuti Date: Fri, 3 Oct 2025 19:54:18 +0200 Subject: [PATCH 5/5] docs: new sync --- .../docs/mcp/10-introduction/10-overview.md | 11 +++-- .../docs/mcp/20-setup/20-local-setup.md | 42 ++++++++----------- .../docs/mcp/20-setup/30-remote-setup.md | 42 ++++++++----------- .../docs/mcp/30-capabilities/10-tools.md | 8 ++-- 4 files changed, 46 insertions(+), 57 deletions(-) diff --git a/apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md b/apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md index 873e6dacc0..524834a44f 100644 --- a/apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md +++ b/apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md @@ -3,15 +3,18 @@ NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-doc title: Overview --- -The official Svelte MCP (Model Context Protocol) Server can help your LLM or Agent of choice write better Svelte code by providing it with documentation and tools to get suggestions on the generated code based on static analysis. +The Svelte MCP ([Model Context Protocol](https://modelcontextprotocol.io/docs/getting-started/intro)) server can help your LLM or agent of choice write better Svelte code. It works by providing documentation relevant to the task at hand, and statically analysing generated code so that it can suggest fixes and best practices. ## Setup -The setup differs based on the version of the MCP you prefer (either remote or local) and the MCP client of your choice (e.g. Claude Code, Codex CLI, GitHub Copilot etc.). Refer to our documentation to learn how to set those up [locally](./local-setup) and [remotely](./remote-setup) for the most common clients. +The setup varies based on the version of the MCP you prefer — remote or local — and your chosen MCP client (e.g. Claude Code, Codex CLI or GitHub Copilot): + +- [local setup](local-setup) using `@sveltejs/mcp` +- [remote setup](remote-setup) using [mcp.svelte.dev/mcp](https://mcp.svelte.dev/mcp) ## Usage -To get the most out of the MCP we recommend including the following prompt in your `AGENTS.md` or `CLAUDE.md`. This will instruct the LLM on what's available and when it's appropriate to use the MCP. +To get the most out of the MCP server we recommend including the following prompt in your `AGENTS.md` (or `CLAUDE.md`, if using Claude Code). This will tell the LLM which tools are available and when it's appropriate to use them. ```md 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: @@ -39,4 +42,4 @@ 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. ``` -If your MCP client supports it, we also recommend using the [svelte-task](./prompts#svelte-task) prompt to instruct the LLM on the best way to use the MCP server. +If your MCP client supports it, we also recommend using the [svelte-task](prompts#svelte-task) prompt to instruct the LLM on the best way to use the MCP server. diff --git a/apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md b/apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md index 057bd83f46..9ce1cd08e9 100644 --- a/apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md +++ b/apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md @@ -3,7 +3,7 @@ NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-doc title: Local setup --- -The STDIO (local) version of the MCP server is available as an `npm` package: `@sveltjs/mcp`. You can either install it globally and then reference it in your configuration or run it with `npx`. +The local (or stdio) version of the MCP server is available via the [`@sveltejs/mcp`](https://www.npmjs.com/package/@sveltejs/mcp) npm package. You can either install it globally and then reference it in your configuration or run it with `npx`: ```bash npx -y @sveltejs/mcp @@ -16,19 +16,19 @@ Here's how to set it up in some common MCP clients: To include the local MCP version in Claude Code, simply run the following command: ```bash -claude mcp add -t stdio -s [scope] [name] npx -y @sveltejs/mcp +claude mcp add -t stdio -s [scope] svelte npx -y @sveltejs/mcp ``` -You can choose your preferred `scope` (it must be `user`, `project` or `local`) and `name`. +The `[scope]` must be `user`, `project` or `local`. ## Claude Desktop -Open the Developer section in settings, click on `Edit Config`. It will open the folder with a `claude_desktop_config.json` file in it. Edit the file to include the following configuration: +In the Settings > Developer section, click on Edit Config. It will open the folder with a `claude_desktop_config.json` file in it. Edit the file to include the following configuration: ```json { "mcpServers": { - "[name]": { + "svelte": { "command": "npx", "args": ["-y", "@sveltejs/mcp"] } @@ -36,31 +36,27 @@ Open the Developer section in settings, click on `Edit Config`. It will open the } ``` -The top level must be `mcpServers` but you can choose your preferred `name`. - ## Codex CLI -Add the following to your `config.toml` (defaults to `~/.codex/config.toml`... refer to [the configuration documentation](https://github.com/openai/codex/blob/69cb72f8422f2aa7222bea3a6ce48fd130fa76c4/docs/config.md) for more advanced setups): +Add the following to your `config.toml` (which defaults to `~/.codex/config.toml`, but refer to [the configuration documentation](https://github.com/openai/codex/blob/main/docs/config.md) for more advanced setups): ```toml -[mcp_servers.name] +[mcp_servers.svelte] command = "npx" args = ["-y", "@sveltejs/mcp"] ``` -The top level must be `mcp_server` but you can choose your preferred `name`. - ## Gemini CLI To include the local MCP version in Gemini CLI, simply run the following command: ```bash -gemini mcp add -t stdio -s [scope] [name] npx -y @sveltejs/mcp +gemini mcp add -t stdio -s [scope] svelte npx -y @sveltejs/mcp ``` -You can choose your preferred `scope` (it must be `user`, `project` or `local`) and `name`. +The `[scope]` must be `user`, `project` or `local`. -## Opencode +## OpenCode Run the command: @@ -68,7 +64,7 @@ Run the command: opencode mcp add ``` -and follow the instructions, selecting Local when asked for "Select MCP server type": +and follow the instructions, selecting 'Local' under the 'Select MCP server type' prompt: ```bash opencode mcp add @@ -76,7 +72,7 @@ opencode mcp add ┌ Add MCP server │ ◇ Enter MCP server name -│ [name] +│ svelte │ ◇ Select MCP server type │ Local @@ -85,20 +81,18 @@ opencode mcp add │ npx -y @sveltejs/mcp ``` -You can choose your preferred `name`. +## VS Code -## VSCode - -- Open the command Palette +- Open the command palette - Select "MCP: Add Server..." - Select "Command (stdio)" - Insert `npx -y @sveltejs/mcp` in the input and press `Enter` -- Insert your preferred name +- When prompted for a name, insert `svelte` - Select if you want to add it as a `Global` or `Workspace` MCP server ## Cursor -- Open the command Palette +- Open the command palette - Select "View: Open MCP Settings" - Click on "Add custom MCP" @@ -107,7 +101,7 @@ It will open a file with your MCP servers where you can add the following config ```json { "mcpServers": { - "[name]": { + "svelte": { "command": "npx", "args": ["-y", "@sveltejs/mcp"] } @@ -115,8 +109,6 @@ It will open a file with your MCP servers where you can add the following config } ``` -The top level must be `mcpServers` but you can choose your preferred `name`. - ## Other clients If we didn't include the MCP client you are using, refer to their documentation for `stdio` servers and use `npx` as the command and `-y @sveltejs/mcp` as the arguments. diff --git a/apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md b/apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md index 63e5c46e7e..3b13b9f98a 100644 --- a/apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md +++ b/apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md @@ -12,42 +12,40 @@ Here's how to set it up in some common MCP clients: To include the remote MCP version in Claude Code, simply run the following command: ```bash -claude mcp add -t http -s [scope] [name] https://mcp.svelte.dev/mcp +claude mcp add -t http -s [scope] svelte https://mcp.svelte.dev/mcp ``` You can choose your preferred `scope` (it must be `user`, `project` or `local`) and `name`. ## Claude Desktop -- Open `Settings > Connectors` -- Click on `Add Custom Connector` -- Insert the name you prefer most -- Insert `https://mcp.svelte.dev/mcp` as the `Remote MCP server URL` -- Click `Add` +- Open Settings > Connectors +- Click on Add Custom Connector +- When prompted for a name, enter `svelte` +- Under the Remote MCP server URL input, use `https://mcp.svelte.dev/mcp` +- Click Add ## Codex CLI -Add the following to your `config.toml` (defaults to `~/.codex/config.toml`... refer to [the configuration documentation](https://github.com/openai/codex/blob/69cb72f8422f2aa7222bea3a6ce48fd130fa76c4/docs/config.md) for more advanced setups): +Add the following to your `config.toml` (which defaults to `~/.codex/config.toml`, but refer to [the configuration documentation](https://github.com/openai/codex/blob/main/docs/config.md) for more advanced setups): ```toml experimental_use_rmcp_client = true -[mcp_servers.name] +[mcp_servers.svelte] url = "https://mcp.svelte.dev/mcp" ``` -To use HTTP servers in Codex you need to enable `experimental_use_rmcp_client` and the top level must be `mcp_server` but you can choose your preferred `name`. - ## Gemini CLI -To include the remote MCP version in Gemini CLI, simply run the following command: +To use the remote MCP server with Gemini CLI, simply run the following command: ```bash -gemini mcp add -t http -s [scope] [name] https://mcp.svelte.dev/mcp +gemini mcp add -t http -s [scope] svelte https://mcp.svelte.dev/mcp ``` -You can choose your preferred `scope` (it must be `user`, `project` or `local`) and `name`. +The `[scope]` must be `user`, `project` or `local`. -## Opencode +## OpenCode Run the command: @@ -55,7 +53,7 @@ Run the command: opencode mcp add ``` -and follow the instructions, selecting Remote when asked for "Select MCP server type": +and follow the instructions, selecting 'Remote' under the 'Select MCP server type' prompt: ```bash opencode mcp add @@ -63,7 +61,7 @@ opencode mcp add ┌ Add MCP server │ ◇ Enter MCP server name -│ [name] +│ svelte │ ◇ Select MCP server type │ Remote @@ -72,11 +70,9 @@ opencode mcp add │ https://mcp.svelte.dev/mcp ``` -You can choose your preferred `name`. +## VS Code -## VSCode - -- Open the command Palette +- Open the command palette - Select "MCP: Add Server..." - Select "HTTP (HTTP or Server-Sent-Events)" - Insert `https://mcp.svelte.dev/mcp` in the input and press `Enter` @@ -85,7 +81,7 @@ You can choose your preferred `name`. ## Cursor -- Open the command Palette +- Open the command palette - Select "View: Open MCP Settings" - Click on "Add custom MCP" @@ -94,15 +90,13 @@ It will open a file with your MCP servers where you can add the following config ```json { "mcpServers": { - "[name]": { + "svelte": { "url": "https://mcp.svelte.dev/mcp" } } } ``` -The top level must be `mcpServers` but you can choose your preferred `name`. - ## Other clients If we didn't include the MCP client you are using, refer to their documentation for `remote` servers and use `https://mcp.svelte.dev/mcp` as the URL. diff --git a/apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md b/apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md index 44424c94df..3e2b432a75 100644 --- a/apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md +++ b/apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md @@ -3,15 +3,15 @@ NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-doc title: Tools --- -This is the list of available tools provided by the MCP server. The list of tools is given to the model which can decide to call one or more of the tools during a session. +The following tools are provided by the MCP server to the model, which can decide to call one or more of them during a session: ## list-sections -Provides a list of all the available documentation sections and their use cases if available. The titles of the sections will be used by the LLM to get up-to-date documentation directly from the official documentation. +Provides a list of all the available documentation sections. ## get-documentation -Allows the model to get the full documentation for the requested sections. The documentation is fetched on the fly from the official Svelte documentation and it will always be up to date. +Allows the model to get the full (and up-to-date) documentation for the requested sections directly from [svelte.dev/docs](/docs). ## svelte-autofixer @@ -19,4 +19,4 @@ Uses static analysis to provide suggestions for the generated code. It should be ## playground-link -Generates an ephemeral playground link with the generated code. It's useful when the generated code is not written to a file in your project and you want to quickly test the generated solution. The code is not stored anywhere, the server uses the `share-with-hash` functionality of the Svelte playground to generate the correct hash on the fly (which is also why it will generate a pretty big link). +Generates an ephemeral playground link with the generated code. It's useful when the generated code is not written to a file in your project and you want to quickly test the generated solution. The code is not stored anywhere except the URL itself (which will often, as a consequence, be quite large).