From 41eae3164f80c9570cce5503e3fc39ad0e320ecd Mon Sep 17 00:00:00 2001 From: Rich Harris Date: Fri, 3 Oct 2025 11:55:12 -0400 Subject: [PATCH] Revert "docs: add mcp to docs (#1585)" This reverts commit 38a794b33a4c4c6bd87c01939cffa89e06cd4768. --- .../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 - 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 ++-- packages/site-kit/src/lib/markdown/utils.ts | 11 -- .../site-kit/src/lib/server/content/index.ts | 31 ++--- 15 files changed, 25 insertions(+), 403 deletions(-) delete mode 100644 apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md delete mode 100644 apps/svelte.dev/content/docs/mcp/10-introduction/index.md delete mode 100644 apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md delete mode 100644 apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md delete mode 100644 apps/svelte.dev/content/docs/mcp/20-setup/index.md delete mode 100644 apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md delete mode 100644 apps/svelte.dev/content/docs/mcp/30-capabilities/20-resources.md delete mode 100644 apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md delete mode 100644 apps/svelte.dev/content/docs/mcp/30-capabilities/index.md delete 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 deleted file mode 100644 index 873e6dacc0..0000000000 --- a/apps/svelte.dev/content/docs/mcp/10-introduction/10-overview.md +++ /dev/null @@ -1,42 +0,0 @@ ---- -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 deleted file mode 100644 index ef4e6600ad..0000000000 --- a/apps/svelte.dev/content/docs/mcp/10-introduction/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -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 deleted file mode 100644 index 057bd83f46..0000000000 --- a/apps/svelte.dev/content/docs/mcp/20-setup/20-local-setup.md +++ /dev/null @@ -1,122 +0,0 @@ ---- -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 deleted file mode 100644 index 63e5c46e7e..0000000000 --- a/apps/svelte.dev/content/docs/mcp/20-setup/30-remote-setup.md +++ /dev/null @@ -1,108 +0,0 @@ ---- -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 deleted file mode 100644 index 9d44ee49ac..0000000000 --- a/apps/svelte.dev/content/docs/mcp/20-setup/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -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 deleted file mode 100644 index 44424c94df..0000000000 --- a/apps/svelte.dev/content/docs/mcp/30-capabilities/10-tools.md +++ /dev/null @@ -1,22 +0,0 @@ ---- -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 deleted file mode 100644 index 54b0a837ec..0000000000 --- a/apps/svelte.dev/content/docs/mcp/30-capabilities/20-resources.md +++ /dev/null @@ -1,10 +0,0 @@ ---- -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 deleted file mode 100644 index 1967df287a..0000000000 --- a/apps/svelte.dev/content/docs/mcp/30-capabilities/30-prompts.md +++ /dev/null @@ -1,27 +0,0 @@ ---- -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 deleted file mode 100644 index 881a580c4b..0000000000 --- a/apps/svelte.dev/content/docs/mcp/30-capabilities/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -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 deleted file mode 100644 index 29fa47ea19..0000000000 --- a/apps/svelte.dev/content/docs/mcp/index.md +++ /dev/null @@ -1,4 +0,0 @@ ---- -NOTE: do not edit this file, it is generated in apps/svelte.dev/scripts/sync-docs/index.ts -title: MCP ---- diff --git a/apps/svelte.dev/scripts/sync-docs/README.md b/apps/svelte.dev/scripts/sync-docs/README.md index 057e6369be..73ad236d0f 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), [`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. +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. The repos must be cloned (or linked — see [next section](#setup)) into the `apps/svelte.dev/repos` directory. @@ -24,8 +24,6 @@ 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 91d024f64f..ae4be99692 100644 --- a/apps/svelte.dev/scripts/sync-docs/index.ts +++ b/apps/svelte.dev/scripts/sync-docs/index.ts @@ -149,14 +149,6 @@ 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 86d6781ab4..d5efdc2873 100644 --- a/apps/svelte.dev/src/routes/+layout.server.ts +++ b/apps/svelte.dev/src/routes/+layout.server.ts @@ -9,22 +9,19 @@ const nav_links: NavigationLink[] = [ { title: 'Docs', slug: 'docs', - 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 + 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 + })) })) - })) - })) + }) + ) }, { title: 'Tutorial', diff --git a/packages/site-kit/src/lib/markdown/utils.ts b/packages/site-kit/src/lib/markdown/utils.ts index d51e2abf0a..559d507456 100644 --- a/packages/site-kit/src/lib/markdown/utils.ts +++ b/packages/site-kit/src/lib/markdown/utils.ts @@ -14,17 +14,6 @@ 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 d7a70ef7bc..a2f6defb2e 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, is_in_code_block, slugify, smart_quotes } from '../../markdown/utils'; +import { extract_frontmatter, slugify, smart_quotes } from '../../markdown/utils'; import type { Document } from '../../types'; export async function create_index( @@ -31,24 +31,17 @@ export async function create_index( '$1' ); - 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 }> - ); + 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 }; + }); content[slug] = { slug,