feat: Enhance documentation and definitions for Svelte 5

- Added comprehensive definitions for common mistakes, custom events, event delegation, event modifiers, global state, lifecycle equivalents, migration patterns, snapshots, and snippets.
- Updated README to reflect new features and improved architecture.
- Improved database loading and querying logic in build and loader scripts.
- Refactored code for better readability and maintainability.

Author: spences10

.changeset/full-times-trade.md

@@ -0,0 +1,5 @@
+---
+'mcp-svelte-docs': patch
+---
+
+add more defintions update readme

README.md

@@ -1,93 +1,105 @@
 # mcp-svelte-docs
 
-A Model Context Protocol (MCP) server that provides a comprehensive
-reference guide for Svelte 5 and SvelteKit, helping LLMs provide
-accurate guidance when users are working with Svelte. It includes
-detailed documentation for:
-
-- **Svelte 5 core features** (runes, components, events)
-- **Modern async patterns** (await expressions, loading states)
-- **SvelteKit remote functions** (type-safe client-server
+A Model Context Protocol (MCP) server providing authoritative Svelte 5
+and SvelteKit definitions extracted directly from TypeScript
+declarations. Get precise syntax, parameters, and examples for all
+Svelte 5 concepts through a single, unified interface.
+
+## Architecture
+
+**Definition-First Approach**: Rather than multiple specialized tools,
+this server provides one powerful `svelte_definition` tool that
+accesses 28+ comprehensive definitions covering:
+
+- **All Svelte 5 runes** ($state, $derived, $props, $effect variants)
+- **Modern features** (snippets, await expressions, remote functions)
+- **Event handling** (DOM events, custom events, component
   communication)
-- **Migration patterns** from Svelte 4 to Svelte 5
-- **Common mistakes** and best practices
-- **Advanced patterns** for state management and data flow
+- **Migration guidance** (Svelte 4 to 5 patterns and best practices)
+- **TypeScript interfaces** (Snippet, Snapshot types)
+- **Advanced patterns** (global state, common mistakes, lifecycle
+  equivalents)
 
-## Available Tools
+## Available Tool
 
-This MCP server provides 16 specialized tools for Svelte 5 and
-SvelteKit development:
+### `svelte_definition`
 
-### Core Svelte 5 Runes
+**Single, powerful tool** for all Svelte 5 and SvelteKit concepts:
 
-- `svelte5_state` - Documentation for `$state` rune (reactive state)
-- `svelte5_derived` - Documentation for `$derived` rune (computed
-  values)
-- `svelte5_props` - Documentation for `$props` rune (component
-  properties)
-- `svelte5_effect` - Documentation for `$effect` rune (side effects)
+```typescript
+svelte_definition(identifier: string, format?: "syntax"|"quick"|"full")
+```
+
+**Examples:**
 
-### Svelte 5 Features
+- `svelte_definition("$state")` - Complete $state documentation
+- `svelte_definition("snippets", "quick")` - Snippet overview with
+  example
+- `svelte_definition("onclick", "syntax")` - Just the TypeScript
+  signature
+- `svelte_definition("migration-patterns")` - Svelte 4 → 5 migration
+  guide
 
-- `svelte5_snippets` - Documentation for snippets (replacement for
-  slots)
-- `svelte5_events` - Event handling patterns in Svelte 5
-- `svelte5_component_events` - Component event patterns and best
-  practices
-- `svelte5_global_state` - Global state management patterns
+**Response Formats:**
 
-### Modern Async Features ✨ NEW
+- `"syntax"` - TypeScript signature only (~50 words)
+- `"quick"` - Definition + minimal example (~200 words)
+- `"full"` - Complete documentation with examples (~500-1000 words,
+  default)
 
-- `svelte5_await_expressions` - Await expressions for async operations
-  (experimental)
-- `sveltekit_remote_functions` - Remote functions for type-safe
-  client-server communication (experimental)
+### Available Identifiers (28+)
 
-### Migration & Guidance
+**Core Runes:** `$state`, `$state.raw`, `$state.snapshot`, `$derived`,
+`$derived.by`, `$props`, `$bindable`, `$effect`, `$effect.pre`,
+`$effect.root`, `$effect.pending`, `$effect.tracking`
 
-- `svelte5_migration` - Migration patterns from Svelte 4 to Svelte 5
-- `svelte5_mistakes` - Common mistakes and how to avoid them
-- `svelte5_overview` - General overview of Svelte 5 features
-- `svelte5_runes_overview` - Comprehensive overview of all runes
+**Development Tools:** `$inspect`, `$host`
 
-### Tool Parameters
+**Features & Patterns:** `snippets`, `onclick`, `component-events`,
+`migration-patterns`, `await-expressions`, `remote-functions`,
+`global-state`, `common-mistakes`, `lifecycle-equivalents`
 
-All tools support an optional `includeExamples` parameter:
+**Event Handling:** `custom-events`, `event-delegation`,
+`event-modifiers`
 
-- `includeExamples: true` (default) - Include code examples and
-  demonstrations
-- `includeExamples: false` - Return documentation without code
-  examples for concise reference
+**TypeScript Interfaces:** `snippet`, `snapshot`
 
 ## Key Features
 
-### 🚀 Experimental Async Support
-
-- **Await Expressions**: Use `await` directly in components,
-  `$derived`, and markup
-- **Boundaries**: Error handling and loading states with
-  `<svelte:boundary>`
-- **Synchronized Updates**: Consistent UI updates during async
-  operations
-- **Performance Patterns**: Avoid waterfalls, optimize concurrent
-  requests
-
-### ⚡ Remote Functions
-
-- **Type-safe Communication**: Full TypeScript support between client
-  and server
-- **Four Function Types**: Query (read), Form (submit), Command
-  (execute), Prerender (static)
-- **Optimistic Updates**: Immediate UI feedback with server
-  synchronization
-- **Progressive Enhancement**: Works with and without JavaScript
-
-### 📚 Comprehensive Documentation
-
-- **Real-world Examples**: Patterns from core maintainer projects
-- **Migration Guidance**: Step-by-step Svelte 4 to 5 migration
-- **Error Prevention**: Common mistakes and corrections
-- **Best Practices**: Production-ready patterns and recommendations
+### 🎯 **Authoritative & TypeScript-First**
+
+- **Direct from Source**: Definitions extracted from official Svelte 5
+  TypeScript declarations
+- **Always Current**: Reflects the actual API, not outdated tutorials
+- **Type-Safe**: Includes precise parameter types, return values, and
+  constraints
+
+### ⚡ **Single Interface, Complete Coverage**
+
+- **One Tool**: `svelte_definition` replaces 16+ specialized tools
+- **28+ Definitions**: Every Svelte 5 rune, feature, and pattern
+  covered
+- **Consistent Responses**: Same interface whether you need `$state`
+  or `remote-functions`
+
+### 🚀 **Modern Svelte 5 & SvelteKit Support**
+
+- **Await Expressions**: Async operations directly in templates
+  (`await-expressions`)
+- **Remote Functions**: Type-safe client-server communication
+  (`remote-functions`)
+- **All Runes**: Complete `$effect` family, `$state` variants,
+  `$derived.by`, `$bindable`
+- **Advanced Patterns**: Event handling, global state, component
+  communication
+
+### 📚 **Smart Error Recovery**
+
+- **Fuzzy Matching**: Suggests correct identifiers for typos
+- **Related Concepts**: Points to similar definitions when searches
+  fail
+- **Migration Help**: Converts Svelte 4 patterns to Svelte 5
+  equivalents
 
 ## Config
 

definitions/common-mistakes.md

@@ -0,0 +1,61 @@
+# common-mistakes Definition
+
+**Definition:** Anti-patterns and debugging guide for common Svelte 5
+mistakes  
+**Syntax:** Patterns to avoid and correct alternatives  
+**Categories:**
+
+- Reactivity pitfalls with `$state` and `$derived`
+- Improper `$effect` usage and cleanup
+- Migration errors from Svelte 4 patterns  
+  **Returns:** Understanding of correct Svelte 5 patterns  
+  **Purpose:** Debugging guide and best practice reference
+
+## Examples
+
+```js
+// ❌ MISTAKE: Destructuring $state loses reactivity
+let user = $state({ name: 'Alice' });
+let { name } = user; // 'name' is not reactive!
+
+// ✅ CORRECT: Access properties directly
+user.name; // Reactive access
+
+// ❌ MISTAKE: Using $effect for derived values
+let count = $state(0);
+let double = $state(0);
+$effect(() => {
+	double = count * 2; // Wrong - use $derived instead
+});
+
+// ✅ CORRECT: Use $derived for computed values
+let double = $derived(count * 2);
+
+// ❌ MISTAKE: Missing cleanup in $effect
+$effect(() => {
+	let interval = setInterval(() => {}, 1000);
+	// Missing cleanup causes memory leak!
+});
+
+// ✅ CORRECT: Return cleanup function
+$effect(() => {
+	let interval = setInterval(() => {}, 1000);
+	return () => clearInterval(interval);
+});
+
+// ❌ MISTAKE: Using $state.raw unnecessarily
+let items = $state.raw([1, 2, 3]);
+items.push(4); // No reactivity!
+
+// ✅ CORRECT: Use regular $state for arrays/objects
+let items = $state([1, 2, 3]);
+items.push(4); // Reactive
+```
+
+## Related
+
+- `$state` - For reactive state management
+- `$derived` - For computed values, not `$effect`
+- `$effect` - For side effects, not derived values
+- `$state.raw` - Only when you need non-reactive state
+- `migration-patterns` - Svelte 4 to 5 conversion guide

definitions/custom-events.md

@@ -0,0 +1,88 @@
+# custom-events Definition
+
+**Definition:** Creating and dispatching custom events for
+component-to-component communication in Svelte 5  
+**Syntax:** Event callback props or direct event dispatching
+patterns  
+**Methods:**
+
+- Callback props: `onclick: (event) => void` prop pattern
+- Direct dispatch: Using native `dispatchEvent()` with custom events
+- Event forwarding: `on:event` forwarding to parent components  
+  **Returns:** Custom event communication between components  
+  **Replaces:** Svelte 4's `createEventDispatcher()` function
+
+## Examples
+
+```svelte
+<!-- Child component with callback props -->
+<script>
+  let { onUserSelect, onItemClick } = $props();
+
+  function handleClick(user) {
+    // Call parent's callback with event data
+    onUserSelect?.(user);
+  }
+</script>
+
+<button on:click={() => handleClick({ id: 1, name: 'Alice' })}>
+  Select User
+</button>
+
+<!-- Parent component receiving custom events -->
+<script>
+  function handleUserSelect(user) {
+    console.log('User selected:', user);
+  }
+
+  function handleItemClick(item) {
+    console.log('Item clicked:', item);
+  }
+</script>
+
+<ChildComponent
+  onUserSelect={handleUserSelect}
+  onItemClick={handleItemClick}
+/>
+
+<!-- Alternative: Direct event dispatching -->
+<script>
+  import { createEventDispatcher } from 'svelte';
+
+  // For components that need DOM event dispatching
+  let element;
+
+  function dispatchCustom(data) {
+    element?.dispatchEvent(new CustomEvent('customEvent', {
+      detail: data,
+      bubbles: true
+    }));
+  }
+</script>
+
+<div bind:this={element} on:click={() => dispatchCustom({ value: 42 })}>
+  Click to dispatch custom event
+</div>
+
+<!-- Event forwarding pattern -->
+<script>
+  let { onButtonClick } = $props();
+</script>
+
+<!-- Forward built-in events -->
+<button on:click on:mouseenter>
+  Forwarded events
+</button>
+
+<!-- Forward with custom logic -->
+<button on:click={(e) => onButtonClick?.(e.target.textContent)}>
+  Custom forwarding
+</button>
+```
+
+## Related
+
+- `component-events` - Patterns for component communication
+- `onclick` - Basic event handling
+- `event-modifiers` - Modifying event behavior
+- `$props` - Receiving event callback props