feat: simplified documentation listing

.prettierignore

@@ -8,4 +8,7 @@ bun.lockb
 # Miscellaneous
 /static/
 /drizzle/
-/**/.svelte-kit/*
+/**/.svelte-kit/*
+
+# Claude Code
+.claude/

CLAUDE.md

@@ -90,12 +90,12 @@ When connected to the svelte-llm MCP server, you have access to comprehensive Sv
 
 ## Available MCP Tools:
 
-### 1. list_sections
+### 1. list-sections
 
 Use this FIRST to discover all available documentation sections. Returns a structured list with titles 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
+### 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 and then use the get_documentation tool to fetch ALL documentation sections that are relevant for the users task.
+After calling the list-sections tool, you MUST analyze the returned documentation sections and then use the get_documentation tool to fetch ALL documentation sections that are relevant for the users task.

README.md

@@ -6,7 +6,7 @@ Repo for the official Svelte MCP server.
 
 ```
 pnpm i
-cp .env.example .env
+cp apps/mcp-remote/.env.example apps/mcp-remote/.env
 pnpm dev
 ```
 

eslint.config.js

@@ -12,6 +12,9 @@ const gitignore_path = fileURLToPath(new URL('./.gitignore', import.meta.url));
 
 export default /** @type {import("eslint").Linter.Config} */ ([
 	includeIgnoreFile(gitignore_path),
+	{
+		ignores: ['.claude/**/*'],
+	},
 	js.configs.recommended,
 	...ts.configs.recommended,
 	...svelte.configs.recommended,

package.json

@@ -5,6 +5,7 @@
 	"type": "module",
 	"scripts": {
 		"build": "pnpm -r run build",
+		"dev": "pnpm --filter @sveltejs/mcp-remote run dev",
 		"check": "pnpm -r run check",
 		"format": "prettier --write .",
 		"lint": "prettier --check . && eslint .",

packages/mcp-server/src/mcp/handlers/prompts/svelte-task.ts

@@ -1,5 +1,6 @@
 import type { SvelteMcp } from '../../index.js';
 import * as v from 'valibot';
+import { get_sections } from '../../utils.js';
 
 export function setup_svelte_task(server: SvelteMcp) {
 	server.prompt(
@@ -13,8 +14,7 @@ export function setup_svelte_task(server: SvelteMcp) {
 			}),
 		},
 		async ({ task }) => {
-			// TODO: implement logic to fetch the available docs paths to return in the prompt
-			const available_docs: string[] = [];
+			const available_docs: string[] = (await get_sections()).map((s) => s.title);
 
 			return {
 				messages: [

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

@@ -1,22 +1,61 @@
 import type { SvelteMcp } from '../../index.js';
+import { get_sections, fetch_with_timeout } from '../../utils.js';
 
-export function list_sections(server: SvelteMcp) {
-	server.resource(
+export async function list_sections(server: SvelteMcp) {
+	const sections = await get_sections();
+
+	server.template(
 		{
-			name: 'list-sections',
-			enabled: () => false,
-			description:
-				'The list of all the available Svelte 5 and SvelteKit documentation sections in a structured format.',
-			uri: 'svelte://list-sections',
-			title: 'Svelte Documentation Section',
+			name: 'Svelte Doc Section',
+			description: 'A single documentation section',
+			list() {
+				return sections.map((section) => {
+					const section_name = section.slug;
+					const resource_name = section_name;
+					const resource_uri = `svelte://${section_name}.md`;
+					return {
+						name: resource_name,
+						description: section.use_cases,
+						uri: resource_uri,
+						title: section.title,
+					};
+				});
+			},
+			complete: {
+				slug: (query) => {
+					const values = sections
+						.reduce<string[]>((acc, section) => {
+							const section_name = section.slug;
+							const resource_name = section_name;
+							if (section_name.includes(query.toLowerCase())) {
+								acc.push(resource_name);
+							}
+							return acc;
+						}, [])
+						// there's a hard limit of 100 for completions
+						.slice(0, 100);
+					return {
+						completion: {
+							values,
+						},
+					};
+				},
+			},
+			uri: 'svelte://{/slug*}.md',
 		},
-		async (uri) => {
+		async (uri, { slug }) => {
+			const section = sections.find((section) => {
+				return slug === section.slug;
+			});
+			if (!section) throw new Error(`Section not found: ${slug}`);
+			const response = await fetch_with_timeout(section.url);
+			const content = await response.text();
 			return {
 				contents: [
 					{
 						uri,
 						type: 'text',
-						text: 'resource list-sections called',
+						text: content,
 					},
 				],
 			};

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

@@ -1,13 +1,14 @@
 import type { SvelteMcp } from '../../index.js';
 import * as v from 'valibot';
+import { get_sections, fetch_with_timeout } from '../../utils.js';
+import { SECTIONS_LIST_INTRO, SECTIONS_LIST_OUTRO } from './prompts.js';
 
 export function get_documentation(server: SvelteMcp) {
 	server.tool(
 		{
 			name: 'get-documentation',
-			enabled: () => false,
 			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., "docs/svelte/state.md"). 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.',
+				'Retrieves full documentation content for Svelte 5 or SvelteKit sections. Supports flexible search by title (e.g., "$state", "routing") or file path (e.g., "docs/svelte/state.md"). 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.',
 			schema: v.object({
 				section: v.pipe(
 					v.union([v.string(), v.array(v.string())]),
@@ -17,7 +18,7 @@ export function get_documentation(server: SvelteMcp) {
 				),
 			}),
 		},
-		({ section }) => {
+		async ({ section }) => {
 			let sections: string[];
 
 			if (Array.isArray(section)) {
@@ -43,13 +44,73 @@ export function get_documentation(server: SvelteMcp) {
 				sections = [];
 			}
 
-			const sections_list = sections.length > 0 ? sections.join(', ') : 'no 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.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 = available_sections
+					.map(
+						(section) =>
+							`* title: ${section.title}, use_cases: ${section.use_cases}, path: ${section.url}`,
+					)
+					.join('\n');
+
+				final_text += `\n\n---\n\n${SECTIONS_LIST_INTRO}\n\n${formatted_sections}\n\n${SECTIONS_LIST_OUTRO}`;
+			}
 
 			return {
 				content: [
 					{
 						type: 'text',
-						text: `called for sections: ${sections_list}`,
+						text: final_text,
 					},
 				],
 			};

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

@@ -1,19 +1,28 @@
 import type { SvelteMcp } from '../../index.js';
+import { get_sections } from '../../utils.js';
+import { SECTIONS_LIST_INTRO, SECTIONS_LIST_OUTRO } from './prompts.js';
 
 export function list_sections(server: SvelteMcp) {
 	server.tool(
 		{
 			name: 'list-sections',
-			enabled: () => false,
 			description:
-				'Lists all available Svelte 5 and SvelteKit documentation sections in a structured format. Returns sections as a list of "* title: [section_title], path: [file_path]" - you can use either the title or path when querying a specific section via the get_documentation tool. Always run list_sections first for any query related to Svelte development to discover available content.',
+				'Lists all available Svelte 5 and SvelteKit documentation sections in a structured format. Returns sections as a list of "* title: [section_title], use_cases: [use_cases], path: [file_path]" - you can use either the title or path when querying a specific section via the get_documentation tool. Always run list-sections first for any query related to Svelte development to discover available content.',
 		},
-		() => {
+		async () => {
+			const sections = await get_sections();
+			const formatted_sections = sections
+				.map(
+					(section) =>
+						`* title: ${section.title}, use_cases: ${section.use_cases}, path: ${section.url}`,
+				)
+				.join('\n');
+
 			return {
 				content: [
 					{
 						type: 'text',
-						text: 'tool list_sections called',
+						text: `${SECTIONS_LIST_INTRO}\n\n${formatted_sections}\n\n${SECTIONS_LIST_OUTRO}`,
 					},
 				],
 			};

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

@@ -0,0 +1,5 @@
+export const SECTIONS_LIST_INTRO =
+	'List of available Svelte documentation sections and its inteneded uses:';
+
+export const SECTIONS_LIST_OUTRO =
+	'Use the title or path with the get-documentation tool to get more details about a specific section.';

packages/mcp-server/src/mcp/schemas/index.ts

@@ -0,0 +1,12 @@
+import * as v from 'valibot';
+
+export const documentation_sections_schema = v.record(
+	v.string(),
+	v.object({
+		metadata: v.object({
+			title: v.string(),
+			use_cases: v.optional(v.string()),
+		}),
+		slug: v.string(),
+	}),
+);

packages/mcp-server/src/mcp/utils.ts

@@ -0,0 +1,31 @@
+import * as v from 'valibot';
+import { documentation_sections_schema } from '../mcp/schemas/index.js';
+
+export async function fetch_with_timeout(
+	url: string,
+	timeout_ms: number = 10000,
+): Promise<Response> {
+	try {
+		const response = await fetch(url, { signal: AbortSignal.timeout(timeout_ms) });
+		return response;
+	} catch (error) {
+		if (error instanceof Error && error.name === 'AbortError') {
+			throw new Error(`Request timed out after ${timeout_ms}ms`);
+		}
+		throw error;
+	}
+}
+
+export async function get_sections() {
+	const sections = await fetch_with_timeout(
+		'https://svelte.dev/docs/experimental/sections.json',
+	).then((res) => res.json());
+	const validated_sections = v.safeParse(documentation_sections_schema, sections);
+	if (!validated_sections.success) return [];
+	return Object.entries(validated_sections.output).map(([, section]) => ({
+		title: section.metadata.title,
+		use_cases: section.metadata.use_cases ?? 'read document for use cases',
+		slug: section.slug,
+		url: `https://svelte.dev/${section.slug}/llms.txt`,
+	}));
+}