recker 1.0.12-alpha.04c18a7 → 1.0.12-alpha.1ab8aa7

package/dist/mcp/server.js

@@ -1,11 +1,16 @@
 import { createServer } from 'http';
 import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
-import { join, relative } from 'path';
+import { join, relative, extname, basename, dirname } from 'path';
 import { createInterface } from 'readline';
+import { fileURLToPath } from 'url';
+import { createHybridSearch } from './search/index.js';
 export class MCPServer {
     options;
     server;
+    hybridSearch;
     docsIndex = [];
+    codeExamples = [];
+    typeDefinitions = [];
     sseClients = new Set();
     initialized = false;
     constructor(options = {}) {
@@ -13,10 +18,14 @@ export class MCPServer {
             name: options.name || 'recker-docs',
             version: options.version || '1.0.0',
             docsPath: options.docsPath || this.findDocsPath(),
+            examplesPath: options.examplesPath || this.findExamplesPath(),
+            srcPath: options.srcPath || this.findSrcPath(),
             port: options.port || 3100,
             transport: options.transport || 'stdio',
             debug: options.debug || false,
+            toolsFilter: options.toolsFilter || [],
         };
+        this.hybridSearch = createHybridSearch({ debug: this.options.debug });
         this.buildIndex();
     }
     log(message, data) {
@@ -34,9 +43,12 @@ export class MCPServer {
             join(process.cwd(), 'docs'),
             join(process.cwd(), '..', 'docs'),
         ];
-        if (typeof __dirname !== 'undefined') {
+        try {
+            const __dirname = dirname(fileURLToPath(import.meta.url));
             possiblePaths.push(join(__dirname, '..', '..', 'docs'), join(__dirname, '..', '..', '..', 'docs'));
         }
+        catch {
+        }
         for (const p of possiblePaths) {
             if (existsSync(p)) {
                 return p;
@@ -44,13 +56,56 @@ export class MCPServer {
         }
         return join(process.cwd(), 'docs');
     }
-    buildIndex() {
+    findExamplesPath() {
+        const docsPath = this.options?.docsPath || this.findDocsPath();
+        const possiblePaths = [
+            join(docsPath, 'examples'),
+            join(process.cwd(), 'examples'),
+            join(process.cwd(), 'docs', 'examples'),
+        ];
+        for (const p of possiblePaths) {
+            if (existsSync(p)) {
+                return p;
+            }
+        }
+        return join(docsPath, 'examples');
+    }
+    findSrcPath() {
+        const possiblePaths = [
+            join(process.cwd(), 'src'),
+        ];
+        try {
+            const __dirname = dirname(fileURLToPath(import.meta.url));
+            possiblePaths.push(join(__dirname, '..'), join(__dirname, '..', '..', 'src'));
+        }
+        catch {
+        }
+        for (const p of possiblePaths) {
+            if (existsSync(p)) {
+                return p;
+            }
+        }
+        return join(process.cwd(), 'src');
+    }
+    async buildIndex() {
+        await this.indexDocs();
+        this.indexCodeExamples();
+        this.indexTypeDefinitions();
+        await this.hybridSearch.initialize(this.docsIndex);
+        const stats = this.hybridSearch.getStats();
+        this.log(`Indexed ${stats.documents} docs, ${this.codeExamples.length} examples, ${this.typeDefinitions.length} types`);
+        if (stats.embeddings > 0) {
+            this.log(`Loaded ${stats.embeddings} embeddings (model: ${stats.model})`);
+        }
+    }
+    async indexDocs() {
         if (!existsSync(this.options.docsPath)) {
             this.log(`Docs path not found: ${this.options.docsPath}`);
             return;
         }
         const files = this.walkDir(this.options.docsPath);
-        for (const file of files) {
+        for (let i = 0; i < files.length; i++) {
+            const file = files[i];
             if (!file.endsWith('.md'))
                 continue;
             try {
@@ -60,6 +115,7 @@ export class MCPServer {
                 const title = this.extractTitle(content) || relativePath;
                 const keywords = this.extractKeywords(content);
                 this.docsIndex.push({
+                    id: `doc-${i}`,
                     path: relativePath,
                     title,
                     category,
@@ -71,14 +127,239 @@ export class MCPServer {
                 this.log(`Failed to index ${file}:`, err);
             }
         }
-        this.log(`Indexed ${this.docsIndex.length} documentation files`);
+    }
+    indexCodeExamples() {
+        if (!existsSync(this.options.examplesPath)) {
+            this.log(`Examples path not found: ${this.options.examplesPath}`);
+            return;
+        }
+        const files = this.walkDir(this.options.examplesPath);
+        for (let i = 0; i < files.length; i++) {
+            const file = files[i];
+            const ext = extname(file);
+            if (!['.ts', '.js', '.mjs'].includes(ext))
+                continue;
+            try {
+                const content = readFileSync(file, 'utf-8');
+                const relativePath = relative(this.options.examplesPath, file);
+                const filename = basename(file, ext);
+                const example = this.parseCodeExample(content, relativePath, filename, i);
+                if (example) {
+                    this.codeExamples.push(example);
+                }
+            }
+            catch (err) {
+                this.log(`Failed to index example ${file}:`, err);
+            }
+        }
+    }
+    parseCodeExample(content, path, filename, index) {
+        const docMatch = content.match(/^\/\*\*[\s\S]*?\*\//) || content.match(/^\/\/.*(?:\n\/\/.*)*/);
+        const docComment = docMatch ? docMatch[0] : '';
+        const titleMatch = docComment.match(/@title\s+(.+)/i) || docComment.match(/@example\s+(.+)/i);
+        const title = titleMatch ? titleMatch[1].trim() : this.humanizeFilename(filename);
+        const featureMatch = docComment.match(/@feature\s+(\w+)/i);
+        const feature = featureMatch ? featureMatch[1].toLowerCase() : this.inferFeature(path, content);
+        const complexity = this.inferComplexity(content, docComment);
+        const descMatch = docComment.match(/@description\s+(.+)/i);
+        const description = descMatch
+            ? descMatch[1].trim()
+            : docComment.replace(/^\/\*\*|\*\/|^\s*\*\s?|^\/\/\s?/gm, '').trim().split('\n')[0] || '';
+        const keywords = this.extractCodeKeywords(content, feature);
+        return {
+            id: `example-${index}`,
+            path,
+            title,
+            feature,
+            complexity,
+            code: content,
+            description,
+            keywords,
+        };
+    }
+    humanizeFilename(filename) {
+        return filename
+            .replace(/[-_]/g, ' ')
+            .replace(/([a-z])([A-Z])/g, '$1 $2')
+            .replace(/\b\w/g, c => c.toUpperCase());
+    }
+    inferFeature(path, content) {
+        const pathParts = path.toLowerCase().split('/');
+        const featureKeywords = [
+            'retry', 'cache', 'streaming', 'sse', 'websocket', 'batch',
+            'pagination', 'middleware', 'hooks', 'auth', 'proxy', 'timeout',
+            'mcp', 'ai', 'scraping', 'whois', 'dns', 'udp', 'webrtc',
+        ];
+        for (const keyword of featureKeywords) {
+            if (pathParts.some(p => p.includes(keyword))) {
+                return keyword;
+            }
+        }
+        const lowerContent = content.toLowerCase();
+        for (const keyword of featureKeywords) {
+            if (lowerContent.includes(keyword)) {
+                return keyword;
+            }
+        }
+        return 'general';
+    }
+    inferComplexity(content, docComment) {
+        if (/@complexity\s+(basic|intermediate|advanced)/i.test(docComment)) {
+            return docComment.match(/@complexity\s+(basic|intermediate|advanced)/i)[1].toLowerCase();
+        }
+        const lines = content.split('\n').length;
+        const hasAsyncAwait = /async|await/.test(content);
+        const hasClasses = /class\s+\w+/.test(content);
+        const hasComplexTypes = /\<[^>]+\>/.test(content);
+        const hasTryCatch = /try\s*\{/.test(content);
+        const hasMultipleFunctions = (content.match(/(?:function|const\s+\w+\s*=\s*(?:async\s*)?\()/g) || []).length > 2;
+        let score = 0;
+        if (lines > 50)
+            score += 2;
+        else if (lines > 20)
+            score += 1;
+        if (hasAsyncAwait)
+            score += 1;
+        if (hasClasses)
+            score += 2;
+        if (hasComplexTypes)
+            score += 1;
+        if (hasTryCatch)
+            score += 1;
+        if (hasMultipleFunctions)
+            score += 1;
+        if (score >= 5)
+            return 'advanced';
+        if (score >= 2)
+            return 'intermediate';
+        return 'basic';
+    }
+    extractCodeKeywords(content, feature) {
+        const keywords = new Set([feature]);
+        const funcMatches = content.match(/(?:function|const|let|var)\s+(\w+)/g) || [];
+        for (const m of funcMatches) {
+            const name = m.split(/\s+/)[1];
+            if (name && name.length > 2)
+                keywords.add(name.toLowerCase());
+        }
+        const importMatches = content.match(/from\s+['"]([^'"]+)['"]/g) || [];
+        for (const m of importMatches) {
+            const mod = m.match(/['"]([^'"]+)['"]/)?.[1];
+            if (mod && !mod.startsWith('.')) {
+                keywords.add(mod.split('/')[0]);
+            }
+        }
+        const methodMatches = content.match(/\.(\w+)\(/g) || [];
+        for (const m of methodMatches) {
+            const method = m.slice(1, -1);
+            if (method.length > 2)
+                keywords.add(method.toLowerCase());
+        }
+        return Array.from(keywords).slice(0, 20);
+    }
+    indexTypeDefinitions() {
+        if (!existsSync(this.options.srcPath)) {
+            this.log(`Source path not found: ${this.options.srcPath}`);
+            return;
+        }
+        const typePaths = [
+            join(this.options.srcPath, 'types'),
+            join(this.options.srcPath, 'core'),
+        ];
+        for (const typePath of typePaths) {
+            if (!existsSync(typePath))
+                continue;
+            const files = this.walkDir(typePath);
+            for (const file of files) {
+                if (!file.endsWith('.ts') || file.endsWith('.test.ts'))
+                    continue;
+                try {
+                    const content = readFileSync(file, 'utf-8');
+                    const relativePath = relative(this.options.srcPath, file);
+                    this.extractTypeDefinitions(content, relativePath);
+                }
+                catch (err) {
+                    this.log(`Failed to parse types from ${file}:`, err);
+                }
+            }
+        }
+    }
+    extractTypeDefinitions(content, path) {
+        const interfaceRegex = /(?:\/\*\*[\s\S]*?\*\/\s*)?(export\s+)?interface\s+(\w+)(?:\s+extends\s+[\w,\s<>]+)?\s*\{[^}]*\}/g;
+        let match;
+        while ((match = interfaceRegex.exec(content)) !== null) {
+            const name = match[2];
+            const fullMatch = match[0];
+            const docMatch = fullMatch.match(/\/\*\*[\s\S]*?\*\//);
+            const description = docMatch
+                ? docMatch[0].replace(/\/\*\*|\*\/|\*\s?/g, '').trim().split('\n')[0]
+                : '';
+            const propsMatch = fullMatch.match(/\{([^}]*)\}/);
+            const properties = propsMatch
+                ? this.parseInterfaceProperties(propsMatch[1])
+                : [];
+            this.typeDefinitions.push({
+                name,
+                kind: 'interface',
+                path,
+                definition: fullMatch,
+                description,
+                properties,
+            });
+        }
+        const typeRegex = /(?:\/\*\*[\s\S]*?\*\/\s*)?(export\s+)?type\s+(\w+)(?:<[^>]+>)?\s*=\s*[^;]+;/g;
+        while ((match = typeRegex.exec(content)) !== null) {
+            const name = match[2];
+            const fullMatch = match[0];
+            const docMatch = fullMatch.match(/\/\*\*[\s\S]*?\*\//);
+            const description = docMatch
+                ? docMatch[0].replace(/\/\*\*|\*\/|\*\s?/g, '').trim().split('\n')[0]
+                : '';
+            this.typeDefinitions.push({
+                name,
+                kind: 'type',
+                path,
+                definition: fullMatch,
+                description,
+            });
+        }
+        const enumRegex = /(?:\/\*\*[\s\S]*?\*\/\s*)?(export\s+)?enum\s+(\w+)\s*\{[^}]*\}/g;
+        while ((match = enumRegex.exec(content)) !== null) {
+            const name = match[2];
+            const fullMatch = match[0];
+            const docMatch = fullMatch.match(/\/\*\*[\s\S]*?\*\//);
+            const description = docMatch
+                ? docMatch[0].replace(/\/\*\*|\*\/|\*\s?/g, '').trim().split('\n')[0]
+                : '';
+            this.typeDefinitions.push({
+                name,
+                kind: 'enum',
+                path,
+                definition: fullMatch,
+                description,
+            });
+        }
+    }
+    parseInterfaceProperties(propsStr) {
+        const props = [];
+        const propRegex = /(?:\/\*\*[\s\S]*?\*\/\s*)?(?:\/\/.*\n\s*)?(\w+)(\?)?:\s*([^;]+);/g;
+        let match;
+        while ((match = propRegex.exec(propsStr)) !== null) {
+            const name = match[1];
+            const optional = !!match[2];
+            const type = match[3].trim();
+            const commentMatch = propsStr.slice(0, match.index).match(/\/\/\s*(.+)$|\/\*\*\s*(.+?)\s*\*\//);
+            const description = commentMatch ? (commentMatch[1] || commentMatch[2] || '').trim() : '';
+            props.push({ name, type, optional, description });
+        }
+        return props;
     }
     walkDir(dir) {
         const files = [];
         try {
             const entries = readdirSync(dir);
             for (const entry of entries) {
-                if (entry.startsWith('_') || entry.startsWith('.'))
+                if (entry.startsWith('_') || entry.startsWith('.') || entry === 'node_modules')
                     continue;
                 const fullPath = join(dir, entry);
                 const stat = statSync(fullPath);
@@ -115,16 +396,16 @@ export class MCPServer {
         return Array.from(keywords).slice(0, 50);
     }
     getTools() {
-        return [
+        const allTools = [
             {
                 name: 'search_docs',
-                description: 'Search Recker documentation by keyword. Returns matching doc files with titles and snippets. Use this first to find relevant documentation.',
+                description: 'Search Recker documentation using hybrid search (fuzzy + semantic). Returns matching docs with relevance scores and snippets. Use this first to find relevant documentation.',
                 inputSchema: {
                     type: 'object',
                     properties: {
                         query: {
                             type: 'string',
-                            description: 'Search query (e.g., "retry", "cache", "streaming", "websocket")',
+                            description: 'Search query (e.g., "retry with exponential backoff", "streaming SSE responses", "cache strategies")',
                         },
                         category: {
                             type: 'string',
@@ -132,7 +413,12 @@ export class MCPServer {
                         },
                         limit: {
                             type: 'number',
-                            description: 'Max results to return (default: 5)',
+                            description: 'Max results to return (default: 5, max: 10)',
+                        },
+                        mode: {
+                            type: 'string',
+                            enum: ['hybrid', 'fuzzy', 'semantic'],
+                            description: 'Search mode: hybrid (default), fuzzy (text matching), or semantic (meaning-based)',
                         },
                     },
                     required: ['query'],
@@ -152,7 +438,95 @@ export class MCPServer {
                     required: ['path'],
                 },
             },
+            {
+                name: 'code_examples',
+                description: 'Get runnable code examples for Recker features. Returns complete, working examples with explanations.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        feature: {
+                            type: 'string',
+                            description: 'Feature to get examples for (e.g., "retry", "cache", "streaming", "websocket", "mcp", "batch", "pagination", "middleware")',
+                        },
+                        complexity: {
+                            type: 'string',
+                            enum: ['basic', 'intermediate', 'advanced'],
+                            description: 'Complexity level of the example (default: all levels)',
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Max examples to return (default: 3)',
+                        },
+                    },
+                    required: ['feature'],
+                },
+            },
+            {
+                name: 'api_schema',
+                description: 'Get TypeScript types, interfaces, and API schemas for Recker. Useful for generating type-safe code.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        type: {
+                            type: 'string',
+                            description: 'Type/interface to look up (e.g., "Client", "RequestOptions", "RetryOptions", "CacheOptions", "MCPServer")',
+                        },
+                        include: {
+                            type: 'string',
+                            enum: ['definition', 'properties', 'both'],
+                            description: 'What to include: just definition, properties breakdown, or both (default: both)',
+                        },
+                    },
+                    required: ['type'],
+                },
+            },
+            {
+                name: 'suggest',
+                description: 'Get implementation suggestions based on use case description. Analyzes requirements and suggests the best Recker patterns.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        useCase: {
+                            type: 'string',
+                            description: 'Describe what you want to achieve (e.g., "call an API with retry and cache", "stream AI responses", "scrape multiple sites in parallel")',
+                        },
+                        constraints: {
+                            type: 'array',
+                            items: { type: 'string' },
+                            description: 'Any constraints or requirements (e.g., ["must handle rate limits", "need progress tracking"])',
+                        },
+                    },
+                    required: ['useCase'],
+                },
+            },
         ];
+        if (this.options.toolsFilter.length > 0) {
+            return allTools.filter(tool => this.isToolEnabled(tool.name));
+        }
+        return allTools;
+    }
+    isToolEnabled(name) {
+        const filter = this.options.toolsFilter;
+        if (!filter.length)
+            return true;
+        const positive = filter.filter(p => !p.startsWith('!'));
+        const negative = filter.filter(p => p.startsWith('!')).map(p => p.slice(1));
+        if (negative.some(p => this.matchPattern(name, p)))
+            return false;
+        if (!positive.length)
+            return true;
+        return positive.some(p => this.matchPattern(name, p));
+    }
+    matchPattern(name, pattern) {
+        if (pattern === '*')
+            return true;
+        if (pattern.endsWith('*')) {
+            return name.startsWith(pattern.slice(0, -1));
+        }
+        if (pattern.startsWith('*')) {
+            return name.endsWith(pattern.slice(1));
+        }
+        return name === pattern;
     }
     handleToolCall(name, args) {
         switch (name) {
@@ -160,6 +534,12 @@ export class MCPServer {
                 return this.searchDocs(args);
             case 'get_doc':
                 return this.getDoc(args);
+            case 'code_examples':
+                return this.getCodeExamples(args);
+            case 'api_schema':
+                return this.getApiSchema(args);
+            case 'suggest':
+                return this.getSuggestions(args);
             default:
                 return {
                     content: [{ type: 'text', text: `Unknown tool: ${name}` }],
@@ -168,22 +548,24 @@ export class MCPServer {
         }
     }
     searchDocs(args) {
-        const query = String(args.query || '').toLowerCase();
-        const category = args.category ? String(args.category).toLowerCase() : null;
+        const query = String(args.query || '');
+        const category = args.category ? String(args.category) : undefined;
         const limit = Math.min(Number(args.limit) || 5, 10);
+        const mode = args.mode || 'hybrid';
         if (!query) {
             return {
                 content: [{ type: 'text', text: 'Error: query is required' }],
                 isError: true,
             };
         }
-        const results = [];
-        for (const doc of this.docsIndex) {
-            if (category && !doc.category.toLowerCase().includes(category)) {
-                continue;
-            }
+        const searchPromise = this.hybridSearch.search(query, { limit, category, mode });
+        let results = [];
+        const queryLower = query.toLowerCase();
+        const queryTerms = queryLower.split(/\s+/);
+        const scored = this.docsIndex
+            .filter(doc => !category || doc.category.toLowerCase().includes(category.toLowerCase()))
+            .map(doc => {
             let score = 0;
-            const queryTerms = query.split(/\s+/);
             for (const term of queryTerms) {
                 if (doc.title.toLowerCase().includes(term))
                     score += 10;
@@ -194,14 +576,21 @@ export class MCPServer {
                 if (doc.content.toLowerCase().includes(term))
                     score += 1;
             }
-            if (score > 0) {
-                const snippet = this.extractSnippet(doc.content, query);
-                results.push({ doc, score, snippet });
-            }
-        }
-        results.sort((a, b) => b.score - a.score);
-        const topResults = results.slice(0, limit);
-        if (topResults.length === 0) {
+            return { doc, score };
+        })
+            .filter(r => r.score > 0)
+            .sort((a, b) => b.score - a.score)
+            .slice(0, limit);
+        results = scored.map(r => ({
+            id: r.doc.id,
+            path: r.doc.path,
+            title: r.doc.title,
+            content: r.doc.content,
+            snippet: this.extractSnippet(r.doc.content, query),
+            score: Math.min(1, r.score / 20),
+            source: 'fuzzy',
+        }));
+        if (results.length === 0) {
             return {
                 content: [{
                         type: 'text',
@@ -209,23 +598,33 @@ export class MCPServer {
                     }],
             };
         }
-        const output = topResults.map((r, i) => `${i + 1}. **${r.doc.title}**\n   Path: \`${r.doc.path}\`\n   Category: ${r.doc.category}\n   ${r.snippet}`).join('\n\n');
+        const stats = this.hybridSearch.getStats();
+        const searchMode = stats.embeddings > 0 ? mode : 'fuzzy';
+        const output = results.map((r, i) => `${i + 1}. **${r.title}** (${(r.score * 100).toFixed(0)}% match)\n   Path: \`${r.path}\`\n   ${r.snippet}`).join('\n\n');
         return {
             content: [{
                     type: 'text',
-                    text: `Found ${topResults.length} result(s) for "${query}":\n\n${output}\n\nUse get_doc with the path to read full content.`,
+                    text: `Found ${results.length} result(s) for "${query}" (${searchMode} search):\n\n${output}\n\nUse get_doc with the path to read full content.`,
                 }],
         };
     }
     extractSnippet(content, query) {
         const lowerContent = content.toLowerCase();
-        const index = lowerContent.indexOf(query.split(/\s+/)[0]);
-        if (index === -1) {
+        const queryTerms = query.toLowerCase().split(/\s+/);
+        let bestIndex = -1;
+        for (const term of queryTerms) {
+            const idx = lowerContent.indexOf(term);
+            if (idx !== -1 && (bestIndex === -1 || idx < bestIndex)) {
+                bestIndex = idx;
+                break;
+            }
+        }
+        if (bestIndex === -1) {
             const firstPara = content.split('\n\n')[1] || content.substring(0, 200);
             return firstPara.substring(0, 150).trim() + '...';
         }
-        const start = Math.max(0, index - 50);
-        const end = Math.min(content.length, index + 150);
+        const start = Math.max(0, bestIndex - 50);
+        const end = Math.min(content.length, bestIndex + 150);
         let snippet = content.substring(start, end).trim();
         if (start > 0)
             snippet = '...' + snippet;
@@ -262,6 +661,252 @@ export class MCPServer {
                 }],
         };
     }
+    getCodeExamples(args) {
+        const feature = String(args.feature || '').toLowerCase();
+        const complexity = args.complexity;
+        const limit = Math.min(Number(args.limit) || 3, 5);
+        if (!feature) {
+            return {
+                content: [{ type: 'text', text: 'Error: feature is required' }],
+                isError: true,
+            };
+        }
+        let examples = this.codeExamples.filter(ex => ex.feature === feature ||
+            ex.keywords.includes(feature) ||
+            ex.title.toLowerCase().includes(feature));
+        if (complexity) {
+            examples = examples.filter(ex => ex.complexity === complexity);
+        }
+        examples = examples.slice(0, limit);
+        if (examples.length === 0) {
+            const availableFeatures = [...new Set(this.codeExamples.map(ex => ex.feature))];
+            return {
+                content: [{
+                        type: 'text',
+                        text: `No examples found for feature "${feature}".\n\nAvailable features: ${availableFeatures.join(', ')}`,
+                    }],
+            };
+        }
+        const output = examples.map((ex, i) => {
+            return `## ${i + 1}. ${ex.title}\n\n**Complexity:** ${ex.complexity}\n**Path:** \`${ex.path}\`\n\n${ex.description ? `${ex.description}\n\n` : ''}\`\`\`typescript\n${ex.code}\n\`\`\``;
+        }).join('\n\n---\n\n');
+        return {
+            content: [{
+                    type: 'text',
+                    text: `Found ${examples.length} example(s) for "${feature}":\n\n${output}`,
+                }],
+        };
+    }
+    getApiSchema(args) {
+        const typeName = String(args.type || '');
+        const include = args.include || 'both';
+        if (!typeName) {
+            return {
+                content: [{ type: 'text', text: 'Error: type is required' }],
+                isError: true,
+            };
+        }
+        const matches = this.typeDefinitions.filter(td => td.name.toLowerCase() === typeName.toLowerCase() ||
+            td.name.toLowerCase().includes(typeName.toLowerCase()));
+        if (matches.length === 0) {
+            const availableTypes = this.typeDefinitions
+                .map(td => td.name)
+                .slice(0, 20);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Type "${typeName}" not found.\n\nAvailable types: ${availableTypes.join(', ')}`,
+                    }],
+            };
+        }
+        const output = matches.map(td => {
+            let result = `## ${td.name} (${td.kind})\n\n`;
+            if (td.description) {
+                result += `${td.description}\n\n`;
+            }
+            result += `**Path:** \`${td.path}\`\n\n`;
+            if (include === 'definition' || include === 'both') {
+                result += `### Definition\n\n\`\`\`typescript\n${td.definition}\n\`\`\`\n\n`;
+            }
+            if ((include === 'properties' || include === 'both') && td.properties && td.properties.length > 0) {
+                result += `### Properties\n\n`;
+                for (const prop of td.properties) {
+                    const optionalMark = prop.optional ? '?' : '';
+                    result += `- **${prop.name}${optionalMark}**: \`${prop.type}\``;
+                    if (prop.description) {
+                        result += ` - ${prop.description}`;
+                    }
+                    result += '\n';
+                }
+            }
+            return result;
+        }).join('\n---\n\n');
+        return {
+            content: [{
+                    type: 'text',
+                    text: output,
+                }],
+        };
+    }
+    getSuggestions(args) {
+        const useCase = String(args.useCase || '').toLowerCase();
+        const constraints = args.constraints || [];
+        if (!useCase) {
+            return {
+                content: [{ type: 'text', text: 'Error: useCase is required' }],
+                isError: true,
+            };
+        }
+        const suggestions = [];
+        const featurePatterns = [
+            { keywords: ['retry', 'fail', 'error', 'resilient', 'reliable'], feature: 'retry', reason: 'Handle transient failures' },
+            { keywords: ['cache', 'fast', 'repeated', 'memoize'], feature: 'cache', reason: 'Speed up repeated requests' },
+            { keywords: ['stream', 'sse', 'real-time', 'live', 'event'], feature: 'streaming', reason: 'Handle streaming responses' },
+            { keywords: ['parallel', 'concurrent', 'batch', 'multiple', 'bulk'], feature: 'batch', reason: 'Execute requests concurrently' },
+            { keywords: ['paginate', 'page', 'cursor', 'next', 'all'], feature: 'pagination', reason: 'Fetch paginated data' },
+            { keywords: ['websocket', 'ws', 'bidirectional', 'push'], feature: 'websocket', reason: 'Real-time bidirectional communication' },
+            { keywords: ['rate limit', 'throttle', 'limit'], feature: 'rate-limiting', reason: 'Respect API rate limits' },
+            { keywords: ['auth', 'token', 'bearer', 'api key'], feature: 'auth', reason: 'Handle authentication' },
+            { keywords: ['progress', 'download', 'upload', 'track'], feature: 'progress', reason: 'Track transfer progress' },
+            { keywords: ['timeout', 'slow', 'hang'], feature: 'timeout', reason: 'Prevent hanging requests' },
+            { keywords: ['scrape', 'html', 'parse', 'extract'], feature: 'scraping', reason: 'Parse HTML content' },
+            { keywords: ['ai', 'llm', 'openai', 'anthropic', 'gpt', 'claude'], feature: 'ai', reason: 'AI/LLM integrations' },
+        ];
+        for (const pattern of featurePatterns) {
+            if (pattern.keywords.some(k => useCase.includes(k))) {
+                suggestions.push({
+                    feature: pattern.feature,
+                    reason: pattern.reason,
+                    config: this.getFeatureConfig(pattern.feature),
+                });
+            }
+        }
+        for (const constraint of constraints) {
+            const lowerConstraint = constraint.toLowerCase();
+            for (const pattern of featurePatterns) {
+                if (pattern.keywords.some(k => lowerConstraint.includes(k))) {
+                    if (!suggestions.some(s => s.feature === pattern.feature)) {
+                        suggestions.push({
+                            feature: pattern.feature,
+                            reason: pattern.reason,
+                            config: this.getFeatureConfig(pattern.feature),
+                        });
+                    }
+                }
+            }
+        }
+        if (suggestions.length === 0) {
+            return {
+                content: [{
+                        type: 'text',
+                        text: `I couldn't identify specific features for "${useCase}".\n\nTry describing your use case with keywords like:\n- retry, fail, error (for resilience)\n- cache, fast, repeated (for caching)\n- stream, sse, live (for streaming)\n- parallel, batch, concurrent (for batching)\n- paginate, cursor, next (for pagination)`,
+                    }],
+            };
+        }
+        const output = suggestions.map((s, i) => {
+            return `### ${i + 1}. ${s.feature.charAt(0).toUpperCase() + s.feature.slice(1)}\n\n**Why:** ${s.reason}\n\n**Configuration:**\n\`\`\`typescript\n${s.config}\n\`\`\``;
+        }).join('\n\n');
+        const combinedConfig = this.getCombinedConfig(suggestions.map(s => s.feature));
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# Suggested Implementation for: "${useCase}"\n\n${output}\n\n---\n\n## Combined Configuration\n\n\`\`\`typescript\n${combinedConfig}\n\`\`\``,
+                }],
+        };
+    }
+    getFeatureConfig(feature) {
+        const configs = {
+            retry: `retry: {
+  attempts: 3,
+  backoff: 'exponential',
+  delay: 1000,
+  jitter: true
+}`,
+            cache: `cache: {
+  ttl: 60000, // 1 minute
+  strategy: 'stale-while-revalidate'
+}`,
+            streaming: `// Streaming with async iteration
+for await (const chunk of client.get('/stream')) {
+  console.log(chunk);
+}
+
+// SSE parsing
+for await (const event of client.get('/events').sse()) {
+  console.log(event.data);
+}`,
+            batch: `// Batch requests
+const { results } = await client.batch([
+  { path: '/users/1' },
+  { path: '/users/2' },
+  { path: '/users/3' }
+], { concurrency: 5 });`,
+            pagination: `// Auto-pagination
+const allItems = await client.getAll('/items', {
+  paginate: { maxPages: 10 }
+});`,
+            websocket: `const ws = await client.ws('wss://api.example.com/ws');
+ws.on('message', (data) => console.log(data));
+ws.send({ type: 'subscribe', channel: 'updates' });`,
+            'rate-limiting': `concurrency: {
+  requestsPerInterval: 100,
+  interval: 1000 // 100 req/sec
+}`,
+            auth: `headers: {
+  Authorization: 'Bearer YOUR_TOKEN'
+}
+// or use beforeRequest hook
+client.beforeRequest((req) => {
+  return req.withHeader('Authorization', getToken());
+})`,
+            progress: `const response = await client.get('/large-file', {
+  onDownloadProgress: ({ percent, rate }) => {
+    console.log(\`\${percent}% at \${rate} bytes/sec\`);
+  }
+});`,
+            timeout: `timeout: 30000, // 30 seconds`,
+            scraping: `const $ = await client.get('/page').scrape();
+const title = $('h1').text();
+const links = $('a').map((_, el) => $(el).attr('href')).get();`,
+            ai: `// OpenAI streaming
+for await (const chunk of client.get('/chat/completions').sse()) {
+  process.stdout.write(chunk.choices[0].delta.content || '');
+}`,
+        };
+        return configs[feature] || `// Configure ${feature}`;
+    }
+    getCombinedConfig(features) {
+        const parts = [
+            `import { createClient } from 'recker';
+
+const client = createClient({
+  baseUrl: 'https://api.example.com',`,
+        ];
+        if (features.includes('retry')) {
+            parts.push(`  retry: {
+    attempts: 3,
+    backoff: 'exponential',
+    delay: 1000
+  },`);
+        }
+        if (features.includes('cache')) {
+            parts.push(`  cache: {
+    ttl: 60000,
+    strategy: 'stale-while-revalidate'
+  },`);
+        }
+        if (features.includes('rate-limiting')) {
+            parts.push(`  concurrency: {
+    requestsPerInterval: 100,
+    interval: 1000
+  },`);
+        }
+        if (features.includes('timeout')) {
+            parts.push(`  timeout: 30000,`);
+        }
+        parts.push(`});`);
+        return parts.join('\n');
+    }
     handleRequest(req) {
         const { method, params, id } = req;
         this.log(`Request: ${method}`, params);
@@ -440,12 +1085,16 @@ export class MCPServer {
                     return;
                 }
                 if (req.method === 'GET' && url === '/health') {
+                    const stats = this.hybridSearch.getStats();
                     res.writeHead(200, { 'Content-Type': 'application/json' });
                     res.end(JSON.stringify({
                         status: 'ok',
                         name: this.options.name,
                         version: this.options.version,
-                        docsCount: this.docsIndex.length,
+                        docsCount: stats.documents,
+                        examplesCount: this.codeExamples.length,
+                        typesCount: this.typeDefinitions.length,
+                        embeddingsLoaded: stats.embeddings > 0,
                         sseClients: this.sseClients.size,
                     }));
                     return;
@@ -494,6 +1143,12 @@ export class MCPServer {
     getDocsCount() {
         return this.docsIndex.length;
     }
+    getExamplesCount() {
+        return this.codeExamples.length;
+    }
+    getTypesCount() {
+        return this.typeDefinitions.length;
+    }
     getTransport() {
         return this.options.transport;
     }