docs: update prompts documentation

.changeset/perfect-fishes-scream.md

@@ -0,0 +1,5 @@
+---
+"@sveltejs/mcp-stdio": patch
+---
+
+fix: improve prompt to reduce token usage

.github/workflows/check.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10.26.1
+          version: 10.26.0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6

.github/workflows/lint.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10.26.1
+          version: 10.26.0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6

.github/workflows/publish-any-commit.yml

@@ -1,23 +0,0 @@
-name: Publish Any Commit
-on: [push, pull_request]
-
-permissions: {}
-
-jobs:
-  build:
-    runs-on: ubuntu-latest
-
-    steps:
-      - name: Checkout code
-        uses: actions/checkout@v6
-
-      - run: corepack enable
-      - uses: actions/setup-node@v6
-        with:
-          node-version: 24
-          cache: 'pnpm'
-
-      - name: Install dependencies
-        run: pnpm install
-
-      - run: pnpm dlx pkg-pr-new publish --compact './packages/mcp-stdio' --pnpm

.github/workflows/publish-mcp.yml

@@ -21,11 +21,11 @@ jobs:
           MCP_KEY: ${{ secrets.MCP_KEY }}
         run: |
           NAME=mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz
-          # Download MCP Publisher pinned to v1.4.0 using latest https for security and save it to a file named mcp-publisher.tar.gz
-          curl --proto '=https' --proto-redir '=https' --tlsv1.2 -fL "https://github.com/modelcontextprotocol/registry/releases/download/v1.4.0/$NAME" -O
+          # Download MCP Publisher pinned to v1.3.10 using latest https for security and save it to a file named mcp-publisher.tar.gz
+          curl --proto '=https' --proto-redir '=https' --tlsv1.2 -fL "https://github.com/modelcontextprotocol/registry/releases/download/v1.3.10/$NAME" -O
 
           # Verify the SHA256 checksum of the downloaded file
-          sha256sum --ignore-missing -c ./checksums/registry_1.4.0_checksums.txt
+          sha256sum --ignore-missing -c ./checksums/registry_1.3.10_checksums.txt
 
           # Extract the tarball
           mkdir tmp

.github/workflows/test.yml

@@ -18,7 +18,7 @@ jobs:
       - name: Setup pnpm
         uses: pnpm/action-setup@v4
         with:
-          version: 10.26.1
+          version: 10.26.0
 
       - name: Setup Node.js
         uses: actions/setup-node@v6

package.json

@@ -3,7 +3,7 @@
 	"version": "0.0.1",
 	"description": "The official Svelte MCP server implementation",
 	"type": "module",
-	"packageManager": "pnpm@10.26.1",
+	"packageManager": "pnpm@10.26.0",
 	"scripts": {
 		"build": "pnpm -r run build",
 		"dev": "pnpm --filter @sveltejs/mcp-remote run dev",

packages/mcp-server/package.json

@@ -14,8 +14,7 @@
 		"debug:generate-summaries": "DEBUG_MODE=1 node scripts/generate-summaries.ts --experimental-strip-types"
 	},
 	"exports": {
-		".": "./src/index.ts",
-		"./handlers": "./src/mcp/handlers/tools/handlers.ts"
+		".": "./src/index.ts"
 	},
 	"peerDependencies": {
 		"drizzle-orm": "^0.45.0"

packages/mcp-server/src/mcp/handlers/tools/get-documentation.ts

@@ -5,137 +5,110 @@ import { SECTIONS_LIST_INTRO, SECTIONS_LIST_OUTRO } from './prompts.js';
 import { icons } from '../../icons/index.js';
 import { tool } from 'tmcp/utils';
 
-const get_documentation_schema = v.object({
-	section: v.pipe(
-		v.union([v.string(), v.array(v.string())]),
-		v.description(
-			'The section name(s) to retrieve. Can search by title (e.g., "$state", "load functions") or file path (e.g., "cli/overview"). Supports single string and array of strings',
-		),
-	),
-});
-
-export async function get_documentation_handler({
-	section,
-}: v.InferInput<typeof get_documentation_schema>) {
-	let sections: string[];
-
-	if (Array.isArray(section)) {
-		sections = section.filter((s): s is string => typeof s === 'string');
-	} else if (
-		typeof section === 'string' &&
-		section.trim().startsWith('[') &&
-		section.trim().endsWith(']')
-	) {
-		try {
-			const parsed = JSON.parse(section);
-			if (Array.isArray(parsed)) {
-				sections = parsed.filter((s): s is string => typeof s === 'string');
-			} else {
-				sections = [section];
-			}
-		} catch {
-			sections = [section];
-		}
-	} else if (typeof section === 'string') {
-		sections = [section];
-	} else {
-		sections = [];
-	}
-
-	const available_sections = await get_sections();
-
-	const settled_results = await Promise.allSettled(
-		sections.map(async (requested_section) => {
-			const matched_section = available_sections.find(
-				(s) =>
-					s.title.toLowerCase() === requested_section.toLowerCase() ||
-					s.slug === requested_section ||
-					s.url === requested_section,
-			);
-
-			if (matched_section) {
-				try {
-					const response = await fetch_with_timeout(matched_section.url);
-					if (response.ok) {
-						const content = await response.text();
-						return { success: true, content: `## ${matched_section.title}\n\n${content}` };
-					} else {
-						return {
-							success: false,
-							content: `## ${matched_section.title}\n\nError: Could not fetch documentation (HTTP ${response.status})`,
-						};
-					}
-				} catch (error) {
-					return {
-						success: false,
-						content: `## ${matched_section.title}\n\nError: Failed to fetch documentation - ${error}`,
-					};
-				}
-			} else {
-				return {
-					success: false,
-					content: `## ${requested_section}\n\nError: Section not found.`,
-				};
-			}
-		}),
-	);
-
-	const results = settled_results.map((result) => {
-		if (result.status === 'fulfilled') {
-			return result.value;
-		} else {
-			return {
-				success: false,
-				content: `Error: Couldn't fetch - ${result.reason}`,
-			};
-		}
-	});
-
-	const has_any_success = results.some((result) => result.success);
-	let final_text = results.map((r) => r.content).join('\n\n---\n\n');
-
-	if (!has_any_success) {
-		const formatted_sections = await format_sections_list();
-
-		final_text += `\n\n---\n\n${SECTIONS_LIST_INTRO}\n\n${formatted_sections}\n\n${SECTIONS_LIST_OUTRO}`;
-	}
-
-	return final_text;
-}
-
 export function get_documentation(server: SvelteMcp) {
 	server.tool(
 		{
 			name: 'get-documentation',
 			description:
 				'Retrieves full documentation content for Svelte 5 or SvelteKit sections. Supports flexible search by title (e.g., "$state", "routing") or file path (e.g., "cli/overview"). Can accept a single section name or an array of sections. Before running this, make sure to analyze the users query, as well as the output from list-sections (which should be called first). Then ask for ALL relevant sections the user might require. For example, if the user asks to build anything interactive, you will need to fetch all relevant runes, and so on. Before calling this tool, try to implement Svelte components using your own knowledge and the `svelte-autofixer` tool, since calling this tool is token intensive.',
-			schema: get_documentation_schema,
-			annotations: {
-				title: 'Get Documentation',
-				destructiveHint: false,
-				readOnlyHint: true,
-				openWorldHint: false,
-			},
+			schema: v.object({
+				section: v.pipe(
+					v.union([v.string(), v.array(v.string())]),
+					v.description(
+						'The section name(s) to retrieve. Can search by title (e.g., "$state", "load functions") or file path (e.g., "cli/overview"). Supports single string and array of strings',
+					),
+				),
+			}),
 			icons,
 		},
 		async ({ section }) => {
 			if (server.ctx.sessionId && server.ctx.custom?.track) {
 				await server.ctx.custom?.track?.(server.ctx.sessionId, 'get-documentation');
 			}
-			try {
-				const content = await get_documentation_handler({ section });
-				return tool.text(content);
-			} catch (e) {
-				const error = e as Error;
-				if (server.ctx.sessionId && server.ctx.custom?.track) {
-					await server.ctx.custom?.track?.(
-						server.ctx.sessionId,
-						'get-documentation-error',
-						error.message,
-					);
+			let sections: string[];
+
+			if (Array.isArray(section)) {
+				sections = section.filter((s): s is string => typeof s === 'string');
+			} else if (
+				typeof section === 'string' &&
+				section.trim().startsWith('[') &&
+				section.trim().endsWith(']')
+			) {
+				try {
+					const parsed = JSON.parse(section);
+					if (Array.isArray(parsed)) {
+						sections = parsed.filter((s): s is string => typeof s === 'string');
+					} else {
+						sections = [section];
+					}
+				} catch {
+					sections = [section];
 				}
-				return tool.error(error.message);
+			} else if (typeof section === 'string') {
+				sections = [section];
+			} else {
+				sections = [];
 			}
+
+			const available_sections = await get_sections();
+
+			const settled_results = await Promise.allSettled(
+				sections.map(async (requested_section) => {
+					const matched_section = available_sections.find(
+						(s) =>
+							s.title.toLowerCase() === requested_section.toLowerCase() ||
+							s.slug === requested_section ||
+							s.url === requested_section,
+					);
+
+					if (matched_section) {
+						try {
+							const response = await fetch_with_timeout(matched_section.url);
+							if (response.ok) {
+								const content = await response.text();
+								return { success: true, content: `## ${matched_section.title}\n\n${content}` };
+							} else {
+								return {
+									success: false,
+									content: `## ${matched_section.title}\n\nError: Could not fetch documentation (HTTP ${response.status})`,
+								};
+							}
+						} catch (error) {
+							return {
+								success: false,
+								content: `## ${matched_section.title}\n\nError: Failed to fetch documentation - ${error}`,
+							};
+						}
+					} else {
+						return {
+							success: false,
+							content: `## ${requested_section}\n\nError: Section not found.`,
+						};
+					}
+				}),
+			);
+
+			const results = settled_results.map((result) => {
+				if (result.status === 'fulfilled') {
+					return result.value;
+				} else {
+					return {
+						success: false,
+						content: `Error: Couldn't fetch - ${result.reason}`,
+					};
+				}
+			});
+
+			const has_any_success = results.some((result) => result.success);
+			let final_text = results.map((r) => r.content).join('\n\n---\n\n');
+
+			if (!has_any_success) {
+				const formatted_sections = await format_sections_list();
+
+				final_text += `\n\n---\n\n${SECTIONS_LIST_INTRO}\n\n${formatted_sections}\n\n${SECTIONS_LIST_OUTRO}`;
+			}
+
+			return tool.text(final_text);
 		},
 	);
 }

packages/mcp-server/src/mcp/handlers/tools/handlers.ts

@@ -1,4 +0,0 @@
-export { get_documentation_handler } from './get-documentation.js';
-export { list_sections_handler } from './list-sections.js';
-export { svelte_autofixer_handler } from './svelte-autofixer.js';
-export { playground_link_handler } from './playground-link.js';

packages/mcp-server/src/mcp/handlers/tools/index.ts

@@ -1,4 +1,4 @@
-export { get_documentation } from './get-documentation.js';
-export { list_sections } from './list-sections.js';
-export { svelte_autofixer } from './svelte-autofixer.js';
-export { playground_link } from './playground-link.js';
+export * from './get-documentation.js';
+export * from './list-sections.js';
+export * from './svelte-autofixer.js';
+export * from './playground-link.js';

packages/mcp-server/src/mcp/handlers/tools/list-sections.ts

@@ -4,44 +4,21 @@ import { SECTIONS_LIST_INTRO, SECTIONS_LIST_OUTRO } from './prompts.js';
 import { icons } from '../../icons/index.js';
 import { tool } from 'tmcp/utils';
 
-export async function list_sections_handler() {
-	const formatted_sections = await format_sections_list();
-
-	return `${SECTIONS_LIST_INTRO}\n\n${formatted_sections}\n\n${SECTIONS_LIST_OUTRO}`;
-}
-
 export function list_sections(server: SvelteMcp) {
 	server.tool(
 		{
 			name: 'list-sections',
 			description:
 				'Lists all available Svelte 5 and SvelteKit documentation sections in a structured format. Each section includes a "use_cases" field that describes WHEN this documentation would be useful. You should carefully analyze the use_cases field to determine which sections are relevant for the user\'s query. The use_cases contain comma-separated keywords describing project types (e.g., "e-commerce", "blog"), features (e.g., "authentication", "forms"), components (e.g., "slider", "modal"), development stages (e.g., "deployment", "testing"), or "always" for fundamental concepts. Match these use_cases against the user\'s intent - for example, if building an e-commerce site, fetch sections with use_cases containing "e-commerce", "product listings", "shopping cart", etc. If building a slider, look for "slider", "carousel", "animation", etc. Returns sections as "* title: [section_title], use_cases: [use_cases], path: [file_path]". Always run list-sections FIRST for any Svelte query, then analyze ALL use_cases to identify relevant sections, and finally use get_documentation to fetch ALL relevant sections at once.',
-			annotations: {
-				title: 'List Sections',
-				destructiveHint: false,
-				readOnlyHint: true,
-				openWorldHint: false,
-			},
 			icons,
 		},
 		async () => {
 			if (server.ctx.sessionId && server.ctx.custom?.track) {
 				await server.ctx.custom?.track?.(server.ctx.sessionId, 'list-sections');
 			}
-			try {
-				const content = await list_sections_handler();
-				return tool.text(content);
-			} catch (e) {
-				const error = e as Error;
-				if (server.ctx.sessionId && server.ctx.custom?.track) {
-					await server.ctx.custom?.track?.(
-						server.ctx.sessionId,
-						'list-sections-error',
-						error.message,
-					);
-				}
-				return tool.error(error.message);
-			}
+			const formatted_sections = await format_sections_list();
+
+			return tool.text(`${SECTIONS_LIST_INTRO}\n\n${formatted_sections}\n\n${SECTIONS_LIST_OUTRO}`);
 		},
 	);
 }

packages/mcp-server/src/mcp/handlers/tools/playground-link.ts

@@ -30,126 +30,98 @@ type File = {
 	text: boolean;
 };
 
-const playground_link_schema = v.object({
-	name: v.pipe(
-		v.string(),
-		v.description('The name of the Playground, it should reflect the user task'),
-	),
-	tailwind: v.pipe(
-		v.boolean(),
-		v.description(
-			"If the code requires Tailwind CSS to work...only send true if it it's using tailwind classes in the code",
-		),
-	),
-	files: v.pipe(
-		v.record(v.string(), v.string()),
-		v.description(
-			"An object where all the keys are the filenames (with extensions) and the values are the file content. For example: { 'Component.svelte': '<script>...</script>', 'utils.js': 'export function ...' }. The playground accept multiple files so if are importing from other files just include them all at the root level.",
-		),
-	),
-});
-
-const playground_link_output_schema = v.object({
-	url: v.string(),
-});
-
-export async function playground_link_handler({
-	files,
-	name,
-	tailwind,
-}: v.InferInput<typeof playground_link_schema>) {
-	const playground_base = new URL('https://svelte.dev/playground');
-	const playground_files: File[] = [];
-
-	let has_app_svelte = false;
-
-	for (const [filename, contents] of Object.entries(files)) {
-		if (filename === 'App.svelte') has_app_svelte = true;
-		playground_files.push({
-			type: 'file',
-			name: filename,
-			basename: filename.replace(/^.*[\\/]/, ''),
-			contents,
-			text: true,
-		});
-	}
-
-	if (!has_app_svelte) {
-		throw new Error('The files must contain an App.svelte file as the entry point');
-	}
-
-	const playground_config = {
-		name,
-		tailwind: tailwind ?? false,
-		files: playground_files,
-	};
-
-	playground_base.hash = await compress_and_encode_text(JSON.stringify(playground_config));
-
-	const url = playground_base.toString();
-
-	// use the embed path to have a cleaner UI for mcp-ui
-	playground_base.pathname = '/playground/embed';
-
-	return {
-		url,
-		iframe_url: playground_base.toString(),
-	};
-}
-
 export function playground_link(server: SvelteMcp) {
 	server.tool(
 		{
 			name: 'playground-link',
 			description:
 				'Generates a Playground link given a Svelte code snippet. Once you have the final version of the code you want to send to the user, ALWAYS ask the user if it wants a playground link to allow it to quickly check the code in the playground before calling this tool. NEVER use this tool if you have written the component to a file in the user project. The playground accept multiple files so if are importing from other files just include them all at the root level.',
-			schema: playground_link_schema,
-			outputSchema: playground_link_output_schema,
-			annotations: {
-				title: 'Playground Link',
-				destructiveHint: false,
-				readOnlyHint: true,
-				openWorldHint: false,
-			},
+			schema: v.object({
+				name: v.pipe(
+					v.string(),
+					v.description('The name of the Playground, it should reflect the user task'),
+				),
+				tailwind: v.pipe(
+					v.boolean(),
+					v.description(
+						"If the code requires Tailwind CSS to work...only send true if it it's using tailwind classes in the code",
+					),
+				),
+				files: v.pipe(
+					v.record(v.string(), v.string()),
+					v.description(
+						"An object where all the keys are the filenames (with extensions) and the values are the file content. For example: { 'Component.svelte': '<script>...</script>', 'utils.js': 'export function ...' }. The playground accept multiple files so if are importing from other files just include them all at the root level.",
+					),
+				),
+			}),
+			outputSchema: v.object({
+				url: v.string(),
+			}),
 			icons,
 		},
 		async ({ files, name, tailwind }) => {
 			if (server.ctx.sessionId && server.ctx.custom?.track) {
 				await server.ctx.custom?.track?.(server.ctx.sessionId, 'playground-link');
 			}
-			try {
-				const result = await playground_link_handler({ files, name, tailwind });
-				return {
-					content: [
-						{
-							type: 'text',
-							text: JSON.stringify({ url: result.url }),
-						},
-						createUIResource({
-							uri: 'ui://svelte/playground-link',
-							content: {
-								type: 'externalUrl',
-								iframeUrl: result.iframe_url,
-							},
-							uiMetadata: {
-								'preferred-frame-size': ['100%', '1200px'],
-							},
-							encoding: 'text',
-						}),
-					],
-					structuredContent: { url: result.url },
-				};
-			} catch (e) {
-				const error = e as Error;
-				if (server.ctx.sessionId && server.ctx.custom?.track) {
-					await server.ctx.custom?.track?.(
-						server.ctx.sessionId,
-						'playground-link-error',
-						error.message,
-					);
-				}
-				return tool.error(error.message);
+			const playground_base = new URL('https://svelte.dev/playground');
+			const playground_files: File[] = [];
+
+			let has_app_svelte = false;
+
+			for (const [filename, contents] of Object.entries(files)) {
+				if (filename === 'App.svelte') has_app_svelte = true;
+				playground_files.push({
+					type: 'file',
+					name: filename,
+					basename: filename.replace(/^.*[\\/]/, ''),
+					contents,
+					text: true,
+				});
 			}
+
+			if (!has_app_svelte) {
+				if (server.ctx.sessionId && server.ctx.custom?.track) {
+					await server.ctx.custom?.track?.(server.ctx.sessionId, 'playground-link-no-app-svelte');
+				}
+
+				return tool.error('The files must contain an App.svelte file as the entry point');
+			}
+
+			const playground_config = {
+				name,
+				tailwind: tailwind ?? false,
+				files: playground_files,
+			};
+
+			playground_base.hash = await compress_and_encode_text(JSON.stringify(playground_config));
+
+			const content = {
+				url: playground_base.toString(),
+			};
+
+			// use the embed path to have a cleaner UI for mcp-ui
+			playground_base.pathname = '/playground/embed';
+
+			return {
+				content: [
+					{
+						type: 'text',
+						text: JSON.stringify(content),
+					},
+					createUIResource({
+						uri: 'ui://svelte/playground-link',
+						content: {
+							type: 'externalUrl',
+							iframeUrl: playground_base.toString(),
+						},
+						uiMetadata: {
+							'preferred-frame-size': ['100%', '1200px'],
+						},
+						encoding: 'text',
+					}),
+				],
+				structuredContent: content,
+			};
 		},
 	);
 }

packages/mcp-server/src/mcp/handlers/tools/svelte-autofixer.ts

@@ -7,95 +7,6 @@ import { add_autofixers_issues } from '../../autofixers/add-autofixers-issues.js
 import { icons } from '../../icons/index.js';
 import { tool } from 'tmcp/utils';
 
-const autofixer_schema = v.object({
-	code: v.string(),
-	desired_svelte_version: v.pipe(
-		v.union([v.string(), v.number()]),
-		v.description(
-			'The desired svelte version...if possible read this from the package.json of the user project, otherwise use some hint from the wording (if the user asks for runes it wants version 5). Default to 5 in case of doubt.',
-		),
-	),
-	async: v.pipe(
-		v.optional(v.boolean()),
-		v.description(
-			'If true the code is an async component/module and might use await in the markup or top-level awaits in the script tag. If possible check the svelte.config.js/svelte.config.ts to check if the option is enabled otherwise asks the user if they prefer using it or not. You can only use this option if the version is 5.',
-		),
-	),
-	filename: v.pipe(
-		v.optional(v.string()),
-		v.description(
-			'The filename of the component if available, it MUST be only the Component name with .svelte or .svelte.ts extension and not the entire path.',
-		),
-	),
-});
-
-const autofixer_output_schema = v.object({
-	issues: v.array(v.string()),
-	suggestions: v.array(v.string()),
-	require_another_tool_call_after_fixing: v.boolean(),
-});
-
-export async function svelte_autofixer_handler({
-	code,
-	desired_svelte_version: desired_svelte_version_unchecked,
-	async,
-	filename: filename_or_path,
-}: v.InferInput<typeof autofixer_schema>) {
-	// we validate manually because some clients don't support union in the input schema (looking at you cursor)
-	const parsed_version = v.safeParse(
-		v.union([v.literal(4), v.literal(5), v.literal('4'), v.literal('5')]),
-		desired_svelte_version_unchecked,
-	);
-	if (parsed_version.success === false) {
-		throw new Error(
-			`The desired_svelte_version MUST be either 4 or 5 but received "${desired_svelte_version_unchecked}"`,
-		);
-	}
-
-	const desired_svelte_version = parsed_version.output;
-
-	if (async && +desired_svelte_version < 5) {
-		throw new Error('The async option can only be used with Svelte version 5 or higher.');
-	}
-
-	const content: {
-		issues: string[];
-		suggestions: string[];
-		require_another_tool_call_after_fixing: boolean;
-	} = { issues: [], suggestions: [], require_another_tool_call_after_fixing: false };
-	try {
-		// just in case the LLM sends a full path we extract the filename...it's not really needed
-		// but it's nice to have a filename in the errors
-
-		const filename = filename_or_path ? basename(filename_or_path) : 'Component.svelte';
-
-		add_compile_issues(content, code, +desired_svelte_version, filename, async);
-
-		add_autofixers_issues(content, code, +desired_svelte_version, filename, async);
-
-		await add_eslint_issues(content, code, +desired_svelte_version, filename, async);
-	} catch (e: unknown) {
-		const error = e as Error & { start?: { line: number; column: number } };
-		content.issues.push(
-			`${error.message} at line ${error.start?.line}, column ${error.start?.column}`,
-		);
-		if (error.message.includes('js_parse_error')) {
-			content.suggestions.push(
-				"The code can't be compiled because a Javascript parse error. In case you are using runes like this `$state variable_name = 3;` or `$derived variable_name = 3 * count` that's not how runes are used. You need to use them as function calls without importing them: `const variable_name = $state(3)` and `const variable_name = $derived(3 * count)`.",
-			);
-		} else if (error.message.includes('css_expected_identifier')) {
-			content.suggestions.push(
-				"The code can't be compiled because a valid CSS identifier is expected. This sometimes means you are trying to use a variable in CSS like this: `color: {my_color}` but Svelte doesn't support that. You can use inline CSS variables for that `<div style:--color={my_color}></div>` and then use the variable as usual in CSS with `color: var(--color)`.",
-			);
-		}
-	}
-
-	if (content.issues.length > 0 || content.suggestions.length > 0) {
-		content.require_another_tool_call_after_fixing = true;
-	}
-	return content;
-}
-
 export function svelte_autofixer(server: SvelteMcp) {
 	server.tool(
 		{
@@ -103,8 +14,32 @@ export function svelte_autofixer(server: SvelteMcp) {
 			title: 'Svelte Autofixer',
 			description:
 				'Given a svelte component or module returns a list of suggestions to fix any issues it has. This tool MUST be used whenever the user is asking to write svelte code before sending the code back to the user',
-			schema: autofixer_schema,
-			outputSchema: autofixer_output_schema,
+			schema: v.object({
+				code: v.string(),
+				desired_svelte_version: v.pipe(
+					v.union([v.string(), v.number()]),
+					v.description(
+						'The desired svelte version...if possible read this from the package.json of the user project, otherwise use some hint from the wording (if the user asks for runes it wants version 5). Default to 5 in case of doubt.',
+					),
+				),
+				async: v.pipe(
+					v.optional(v.boolean()),
+					v.description(
+						'If true the code is an async component/module and might use await in the markup or top-level awaits in the script tag. If possible check the svelte.config.js/svelte.config.ts to check if the option is enabled otherwise asks the user if they prefer using it or not. You can only use this option if the version is 5.',
+					),
+				),
+				filename: v.pipe(
+					v.optional(v.string()),
+					v.description(
+						'The filename of the component if available, it MUST be only the Component name with .svelte or .svelte.ts extension and not the entire path.',
+					),
+				),
+			}),
+			outputSchema: v.object({
+				issues: v.array(v.string()),
+				suggestions: v.array(v.string()),
+				require_another_tool_call_after_fixing: v.boolean(),
+			}),
 			annotations: {
 				title: 'Svelte Autofixer',
 				destructiveHint: false,
@@ -122,25 +57,63 @@ export function svelte_autofixer(server: SvelteMcp) {
 			if (server.ctx.sessionId && server.ctx.custom?.track) {
 				await server.ctx.custom?.track?.(server.ctx.sessionId, 'svelte-autofixer');
 			}
-			try {
-				const content = await svelte_autofixer_handler({
-					code,
-					desired_svelte_version: desired_svelte_version_unchecked,
-					async,
-					filename: filename_or_path,
-				});
-				return tool.structured(content);
-			} catch (e) {
-				const error = e as Error;
+			// we validate manually because some clients don't support union in the input schema (looking at you cursor)
+			const parsed_version = v.safeParse(
+				v.union([v.literal(4), v.literal(5), v.literal('4'), v.literal('5')]),
+				desired_svelte_version_unchecked,
+			);
+			if (parsed_version.success === false) {
 				if (server.ctx.sessionId && server.ctx.custom?.track) {
-					await server.ctx.custom?.track?.(
-						server.ctx.sessionId,
-						'svelte-autofixer-error',
-						error.message,
+					await server.ctx.custom?.track?.(server.ctx.sessionId, 'svelte-autofixer-wrong-version');
+				}
+				return tool.error(
+					`The desired_svelte_version MUST be either 4 or 5 but received "${desired_svelte_version_unchecked}"`,
+				);
+			}
+
+			const desired_svelte_version = parsed_version.output;
+
+			if (async && +desired_svelte_version < 5) {
+				return tool.error('The async option can only be used with Svelte version 5 or higher.');
+			}
+
+			const content: {
+				issues: string[];
+				suggestions: string[];
+				require_another_tool_call_after_fixing: boolean;
+			} = { issues: [], suggestions: [], require_another_tool_call_after_fixing: false };
+			try {
+				// just in case the LLM sends a full path we extract the filename...it's not really needed
+				// but it's nice to have a filename in the errors
+
+				const filename = filename_or_path ? basename(filename_or_path) : 'Component.svelte';
+
+				add_compile_issues(content, code, +desired_svelte_version, filename, async);
+
+				add_autofixers_issues(content, code, +desired_svelte_version, filename, async);
+
+				await add_eslint_issues(content, code, +desired_svelte_version, filename, async);
+			} catch (e: unknown) {
+				const error = e as Error & { start?: { line: number; column: number } };
+				content.issues.push(
+					`${error.message} at line ${error.start?.line}, column ${error.start?.column}`,
+				);
+				if (error.message.includes('js_parse_error')) {
+					content.suggestions.push(
+						"The code can't be compiled because a Javascript parse error. In case you are using runes like this `$state variable_name = 3;` or `$derived variable_name = 3 * count` that's not how runes are used. You need to use them as function calls without importing them: `const variable_name = $state(3)` and `const variable_name = $derived(3 * count)`.",
+					);
+				} else if (error.message.includes('css_expected_identifier')) {
+					content.suggestions.push(
+						"The code can't be compiled because a valid CSS identifier is expected. This sometimes means you are trying to use a variable in CSS like this: `color: {my_color}` but Svelte doesn't support that. You can use inline CSS variables for that `<div style:--color={my_color}></div>` and then use the variable as usual in CSS with `color: var(--color)`.",
 					);
 				}
-				return tool.error(error.message);
 			}
+
+			if (content.issues.length > 0 || content.suggestions.length > 0) {
+				content.require_another_tool_call_after_fixing = true;
+			}
+
+			return tool.structured(content);
 		},
 	);
 }

packages/mcp-stdio/CHANGELOG.md

@@ -1,23 +1,5 @@
 # @sveltejs/mcp
 
-## 0.1.16
-
-### Patch Changes
-
-- feat: expose tools as JS api + cli ([#128](https://github.com/sveltejs/mcp/pull/128))
-
-## 0.1.15
-
-### Patch Changes
-
-- fix: server.json version + update publisher ([`9dfb4de`](https://github.com/sveltejs/mcp/commit/9dfb4dedb42837c40c4e660f0f816d7cf9081fc4))
-
-## 0.1.14
-
-### Patch Changes
-
-- fix: improve prompt to reduce token usage ([#124](https://github.com/sveltejs/mcp/pull/124))
-
 ## 0.1.13
 
 ### Patch Changes

packages/mcp-stdio/checksums/registry_1.3.10_checksums.txt

@@ -0,0 +1,25 @@
+aada17479e04faa55e380ae1ee0de3c5a5d86b4c0ad5dd4b64f68426f87c84e0  mcp-publisher_darwin_amd64.tar.gz
+d426c953218a61699bb47d1dae6f0b89807313f082d650f243b8a91bc7f448f3  mcp-publisher_darwin_amd64.tar.gz.sbom.json
+75a14ff2570bca0eba656dee1d4ad4b2955de67e97aacc5884bcab1793d8dd2d  mcp-publisher_darwin_arm64.tar.gz
+988adc169f9ce4cded2b08ab0df7c1738f8ea77dccb581a234f7e036ad7b478e  mcp-publisher_darwin_arm64.tar.gz.sbom.json
+dc97c003df75d40134b9bf003077ac9057187d64f8d601c4f2457980712dbb62  mcp-publisher_linux_amd64.tar.gz
+49e63cd1c1ade8988f6c6f679b3172ab28b5ae6ef92243a4f8a78c58150853c7  mcp-publisher_linux_amd64.tar.gz.sbom.json
+094e70c73ff671da69b138b448c68336f582e9245355d469c8372a48639bbc6c  mcp-publisher_linux_arm64.tar.gz
+3888ef7db7a77efeb3cfb711527a00ed93188ff3fce05468a6308ae75e2bb913  mcp-publisher_linux_arm64.tar.gz.sbom.json
+43a1f3ca680350dd898697c93e4e0a1489c2b638dc946c4ef496a815c0e46d53  mcp-publisher_windows_amd64.tar.gz
+512ac8c24275845bcc9c4c4faf4f08d950de3585e13d283e1aa48c567735ad73  mcp-publisher_windows_amd64.tar.gz.sbom.json
+739347d69d4979faf06365843c49ede92e16975cd1afe3ef627e9511459fa30b  mcp-publisher_windows_arm64.tar.gz
+b8ecb1cf98caef446447a1ad89f7259699632f09bd19d600c89fd800aa3c7698  mcp-publisher_windows_arm64.tar.gz.sbom.json
+5b4d676da2a574ee0d3cfd752d9d3a663e675d48d928706dda0084271ded1cb5  registry-1.3.10.tar.gz
+d5140c2730991dfc236305d3e6eddb6c05da9325d9803b1eaee50c06953d5991  registry_darwin_amd64.tar.gz
+fd1380e0d308a1702d040427603d203a9407603e1156cd23743a3074e1313b06  registry_darwin_amd64.tar.gz.sbom.json
+db22e6b0f518b1ccaf44f749babc28d70d2573ba5641b06ff085430826eac688  registry_darwin_arm64.tar.gz
+4415141c7b490b1c7d9643e799df5a2885f3292b4c1c3e4c71f2841aae52fdeb  registry_darwin_arm64.tar.gz.sbom.json
+8fbb607254b412513eeec45c89fb3051fe9ce623196f6361ded1d335a5348566  registry_linux_amd64.tar.gz
+c256554e7060cbfc92494f9b22c4e857b0606ca57479a29fa61649917c63c974  registry_linux_amd64.tar.gz.sbom.json
+86ff45f0c5afc674e9b30ec47815ab54401d716b12d70f27bd73f72d5b5ad2f8  registry_linux_arm64.tar.gz
+0ccb7a3d856a7951bea5d5e63314459b365199577f573c2fbcd11e7e98b9b94c  registry_linux_arm64.tar.gz.sbom.json
+f56d75a2569e6e37f44d8f7bede0bd01f8056130f8eab58b1211d55d43fa08fe  registry_windows_amd64.tar.gz
+d941a82dd69937edff791b4f84b61006d78802280fb0c06d15c07a5d90d6e0a0  registry_windows_amd64.tar.gz.sbom.json
+b2e6fff3cd9bab76d4431294b2844e1e9a399d45728e5459492b21367da62453  registry_windows_arm64.tar.gz
+1954a54f47048e1ac25c92196440f0c2b1ba2357e01720d5b14e6faf43be46b2  registry_windows_arm64.tar.gz.sbom.json

packages/mcp-stdio/checksums/registry_1.4.0_checksums.txt

@@ -1,25 +0,0 @@
-eb5f89b76fc45a97070fa481eb03977584a78e3dff2781402d43482f114e4d6a  mcp-publisher_darwin_amd64.tar.gz
-29fc1b46a6f6be2580129369a9b681204b11b425d9a44147d79c8c658c7b8474  mcp-publisher_darwin_amd64.tar.gz.sbom.json
-9eddbbb95efd54b9503f6c0668f43bab3f04c856946d3c7164f6daead232402f  mcp-publisher_darwin_arm64.tar.gz
-a8349b0ea7916f34cf4ee4e1ced5b91bc1ded6d100312cbb2095da018710da04  mcp-publisher_darwin_arm64.tar.gz.sbom.json
-c4b402b43a85166c3f840641ca1c9e6de5bfa1cf533c22576d663ccbda0711bb  mcp-publisher_linux_amd64.tar.gz
-6f21cf917055be885f16b93154e06379540236599cfad6af4404a8323bde74b7  mcp-publisher_linux_amd64.tar.gz.sbom.json
-ba5d486f86b2cef48ea506e8314d901a5169dcd56a5d6e9daf18d41244316235  mcp-publisher_linux_arm64.tar.gz
-8a0096a407b916ac7270732df017a26f6112c73a066252f6556b8956c492a0b4  mcp-publisher_linux_arm64.tar.gz.sbom.json
-59ee8c4a997f94794db8db13f8809666631686a70a8d89a9f0fea993f9aede0f  mcp-publisher_windows_amd64.tar.gz
-57d211fd9181f698d126bd773b55c98b92454d19b1e32e77860766179a8a2e8e  mcp-publisher_windows_amd64.tar.gz.sbom.json
-1410952b0a5968cbe89590e7b4ee6105147ef7267cf0cd50095c9bec2ee3b0d7  mcp-publisher_windows_arm64.tar.gz
-6cb93e118a89ed1419135bfbaa7401bd3b7a7c5680a0d8fd7c78728f9d860630  mcp-publisher_windows_arm64.tar.gz.sbom.json
-ebc17c3b7a5b86f9c036acf1d44fb904bb363bad0ac1ac37b7979eb17cf3d218  registry-1.4.0.tar.gz
-5fffe8b078513fa5fbb625a213d164bb391c7c85e216e541cab789517bc6365b  registry_darwin_amd64.tar.gz
-10a61cf4173d8b5be63044af0a10e6c809eebc1006c0c1643753a252db808ddd  registry_darwin_amd64.tar.gz.sbom.json
-437746a1045f093266ad7298a47be41dc44cc33ecaeec145449c4eefeddf8880  registry_darwin_arm64.tar.gz
-4c0cb24bcef0658540fb044d771294efd662edecd2f7fae7b1ca7ca2ae68f83a  registry_darwin_arm64.tar.gz.sbom.json
-bd77fafcc881714a63a375a9bdb53a761a2b8e367a9d2759835126c993df2356  registry_linux_amd64.tar.gz
-d62a461b174089fbcaa4f1ac096bca491d18bc7f70e93ce0824fe89dbe42e974  registry_linux_amd64.tar.gz.sbom.json
-38cb9e6112ff11544ba8ec88c5c0f44d4c851504ec2e33d497e25616a6f7a21e  registry_linux_arm64.tar.gz
-84e5a004929e7231ae35350a1fe8fb08668fc05183e13d1d78004abf08a25f3b  registry_linux_arm64.tar.gz.sbom.json
-77ca9243d2f744f282b39d07625f802d77f593850a0392debabe407643a8579c  registry_windows_amd64.tar.gz
-bb043e8a6a8d187ffab8987d36d0018024115d9217af6d2ddd233f94aea880ea  registry_windows_amd64.tar.gz.sbom.json
-e4ee50e05a95f288b874f5e24c7716a5032548feeabc83b715193298cec06890  registry_windows_arm64.tar.gz
-49f189b615bce3d09ea24ae5d80e0816ac69225b3c8901dd7be19ef9ca06830c  registry_windows_arm64.tar.gz.sbom.json

packages/mcp-stdio/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@sveltejs/mcp",
-	"version": "0.1.16",
+	"version": "0.1.13",
 	"type": "module",
 	"license": "MIT",
 	"mcpName": "dev.svelte/mcp",
@@ -19,12 +19,6 @@
 	"files": [
 		"dist"
 	],
-	"exports": {
-		".": {
-			"types": "./dist/handlers.d.mts",
-			"import": "./dist/handlers.mjs"
-		}
-	},
 	"publishConfig": {
 		"access": "public"
 	},
@@ -47,7 +41,6 @@
 	},
 	"dependencies": {
 		"eslint": "catalog:lint",
-		"sade": "catalog:tooling",
 		"tmcp": "catalog:tmcp"
 	}
 }

packages/mcp-stdio/server.json

@@ -1,5 +1,5 @@
 {
-	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-12-11/server.schema.json",
+	"$schema": "https://static.modelcontextprotocol.io/schemas/2025-10-17/server.schema.json",
 	"name": "dev.svelte/mcp",
 	"title": "Svelte MCP",
 	"description": "The official Svelte MCP server providing docs and autofixing tools for Svelte development",
@@ -9,7 +9,7 @@
 		"subfolder": "packages/mcp-stdio",
 		"source": "github"
 	},
-	"version": "0.1.16",
+	"version": "0.1.13",
 	"websiteUrl": "https://svelte.dev/docs/mcp/overview",
 	"icons": [
 		{
@@ -25,7 +25,7 @@
 		{
 			"registryType": "npm",
 			"identifier": "@sveltejs/mcp",
-			"version": "0.1.16",
+			"version": "0.1.13",
 			"runtimeHint": "npx",
 			"transport": {
 				"type": "stdio"

packages/mcp-stdio/src/handlers.ts

@@ -1,6 +0,0 @@
-export {
-	list_sections_handler as listSections,
-	get_documentation_handler as getDocumentation,
-	svelte_autofixer_handler as svelteAutofixer,
-	playground_link_handler as playgroundLink,
-} from '@sveltejs/mcp-server/handlers';

packages/mcp-stdio/src/index.ts

@@ -1,65 +1,7 @@
 #! /usr/bin/env node
 import { server } from '@sveltejs/mcp-server';
-import {
-	list_sections_handler,
-	get_documentation_handler,
-	svelte_autofixer_handler,
-} from '@sveltejs/mcp-server/handlers';
-import { readFile } from 'node:fs/promises';
-import { existsSync } from 'node:fs';
 import { StdioTransport } from '@tmcp/transport-stdio';
-import sade from 'sade';
 
-const cli = sade('svelte-mcp');
+const transport = new StdioTransport(server);
 
-cli.command('__mcp', '', { default: true }).action(() => {
-	const transport = new StdioTransport(server);
-	transport.listen();
-});
-
-cli
-	.command('list-sections')
-	.describe('List all the available documentation sections')
-	.action(async () => {
-		console.log(await list_sections_handler());
-	});
-
-cli
-	.command('get-documentation <sections>')
-	.describe('Get documentation for specified sections, separated by commas')
-	.action(async (sections) => {
-		console.log(await get_documentation_handler({ section: sections.split(',') }));
-	});
-
-cli
-	.command('svelte-autofixer <code_or_path>')
-	.describe(
-		'Detect and suggest fixes for Svelte code issues, because the terminal will substitute variables `$` should be correctly escaped',
-	)
-	.option('--async', 'Wether the project is using async svelte or not', false)
-	.option('--svelte-version', 'Which version of svelte to use...it can be 4 or 5', 5)
-	.action(async (code_or_path, { async, 'svelte-version': version }) => {
-		let code = code_or_path;
-
-		let is_path = false;
-
-		if (existsSync(code_or_path)) {
-			console.log('Detected file path, reading file...');
-			code = await readFile(code_or_path, 'utf-8');
-			is_path = true;
-		} else {
-			console.log('File not found, treating input as code...');
-		}
-
-		const desired_svelte_version = +version;
-
-		const result = await svelte_autofixer_handler({
-			code,
-			async: Boolean(async),
-			desired_svelte_version,
-			filename: is_path ? code_or_path : undefined,
-		});
-		console.log(result);
-	});
-
-cli.parse(process.argv);
+transport.listen();

packages/mcp-stdio/tsdown.config.ts

@@ -2,7 +2,7 @@ import { defineConfig } from 'tsdown';
 
 export default defineConfig([
 	{
-		entry: ['./src/index.ts', './src/handlers.ts'],
+		entry: ['./src/index.ts'],
 		platform: 'node',
 		define: {
 			// some eslint-plugin-svelte code expects __filename to exists but in an ESM environment it does not.
@@ -13,9 +13,7 @@ export default defineConfig([
 		// the require would fail once executed in a project without eslint installed.
 		external: ['eslint'],
 		publint: true,
-		dts: {
-			eager: true,
-		},
+		dts: false,
 		treeshake: true,
 		clean: true,
 		target: 'esnext',

pnpm-lock.yaml

@@ -128,9 +128,6 @@ catalogs:
     publint:
       specifier: ^0.3.13
       version: 0.3.13
-    sade:
-      specifier: 1.8.1
-      version: 1.8.1
     ts-blank-space:
       specifier: ^0.6.2
       version: 0.6.2
@@ -387,9 +384,6 @@ importers:
       eslint:
         specifier: catalog:lint
         version: 9.36.0(jiti@2.6.0)
-      sade:
-        specifier: catalog:tooling
-        version: 1.8.1
       tmcp:
         specifier: catalog:tmcp
         version: 1.19.0(typescript@5.9.2)

pnpm-workspace.yaml

@@ -48,7 +48,6 @@ catalogs:
     dotenv: ^17.2.3
     node-resolve-ts: ^1.0.2
     publint: ^0.3.13
-    sade: 1.8.1
     ts-blank-space: ^0.6.2
     tsdown: ^0.18.0
     typescript: ^5.0.0