recker 1.0.11 → 1.0.12-alpha.1ab8aa7

package/dist/mcp/server.js

@@ -0,0 +1,1158 @@
+import { createServer } from 'http';
+import { readFileSync, readdirSync, statSync, existsSync } from 'fs';
+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 = {}) {
+        this.options = {
+            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) {
+        if (this.options.debug) {
+            if (this.options.transport === 'stdio') {
+                console.error(`[MCP] ${message}`, data ? JSON.stringify(data) : '');
+            }
+            else {
+                console.log(`[MCP] ${message}`, data ? JSON.stringify(data) : '');
+            }
+        }
+    }
+    findDocsPath() {
+        const possiblePaths = [
+            join(process.cwd(), 'docs'),
+            join(process.cwd(), '..', 'docs'),
+        ];
+        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;
+            }
+        }
+        return join(process.cwd(), 'docs');
+    }
+    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 (let i = 0; i < files.length; i++) {
+            const file = files[i];
+            if (!file.endsWith('.md'))
+                continue;
+            try {
+                const content = readFileSync(file, 'utf-8');
+                const relativePath = relative(this.options.docsPath, file);
+                const category = relativePath.split('/')[0] || 'root';
+                const title = this.extractTitle(content) || relativePath;
+                const keywords = this.extractKeywords(content);
+                this.docsIndex.push({
+                    id: `doc-${i}`,
+                    path: relativePath,
+                    title,
+                    category,
+                    content,
+                    keywords,
+                });
+            }
+            catch (err) {
+                this.log(`Failed to index ${file}:`, err);
+            }
+        }
+    }
+    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('.') || entry === 'node_modules')
+                    continue;
+                const fullPath = join(dir, entry);
+                const stat = statSync(fullPath);
+                if (stat.isDirectory()) {
+                    files.push(...this.walkDir(fullPath));
+                }
+                else if (stat.isFile()) {
+                    files.push(fullPath);
+                }
+            }
+        }
+        catch {
+        }
+        return files;
+    }
+    extractTitle(content) {
+        const match = content.match(/^#\s+(.+)$/m);
+        return match ? match[1].trim() : '';
+    }
+    extractKeywords(content) {
+        const keywords = new Set();
+        const headings = content.match(/^#{1,3}\s+(.+)$/gm) || [];
+        for (const h of headings) {
+            keywords.add(h.replace(/^#+\s+/, '').toLowerCase());
+        }
+        const codePatterns = content.match(/`([a-zA-Z_][a-zA-Z0-9_]*(?:\(\))?)`/g) || [];
+        for (const c of codePatterns) {
+            keywords.add(c.replace(/`/g, '').toLowerCase());
+        }
+        const terms = content.match(/\b[A-Z][a-zA-Z]+(?:Client|Server|Error|Response|Request|Plugin|Transport)\b/g) || [];
+        for (const t of terms) {
+            keywords.add(t.toLowerCase());
+        }
+        return Array.from(keywords).slice(0, 50);
+    }
+    getTools() {
+        const allTools = [
+            {
+                name: 'search_docs',
+                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 with exponential backoff", "streaming SSE responses", "cache strategies")',
+                        },
+                        category: {
+                            type: 'string',
+                            description: 'Optional: filter by category (http, cli, ai, protocols, reference, guides)',
+                        },
+                        limit: {
+                            type: 'number',
+                            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'],
+                },
+            },
+            {
+                name: 'get_doc',
+                description: 'Get the full content of a specific documentation file. Use the path from search_docs results.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: {
+                            type: 'string',
+                            description: 'Documentation file path (e.g., "http/07-resilience.md", "cli/01-overview.md")',
+                        },
+                    },
+                    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) {
+            case 'search_docs':
+                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}` }],
+                    isError: true,
+                };
+        }
+    }
+    searchDocs(args) {
+        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 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;
+            for (const term of queryTerms) {
+                if (doc.title.toLowerCase().includes(term))
+                    score += 10;
+                if (doc.path.toLowerCase().includes(term))
+                    score += 5;
+                if (doc.keywords.some(k => k.includes(term)))
+                    score += 3;
+                if (doc.content.toLowerCase().includes(term))
+                    score += 1;
+            }
+            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',
+                        text: `No documentation found for "${query}". Try different keywords like: http, cache, retry, streaming, websocket, ai, cli, plugins`,
+                    }],
+            };
+        }
+        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 ${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 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, bestIndex - 50);
+        const end = Math.min(content.length, bestIndex + 150);
+        let snippet = content.substring(start, end).trim();
+        if (start > 0)
+            snippet = '...' + snippet;
+        if (end < content.length)
+            snippet = snippet + '...';
+        return snippet.replace(/\n/g, ' ');
+    }
+    getDoc(args) {
+        const path = String(args.path || '');
+        if (!path) {
+            return {
+                content: [{ type: 'text', text: 'Error: path is required' }],
+                isError: true,
+            };
+        }
+        const doc = this.docsIndex.find(d => d.path === path || d.path.endsWith(path));
+        if (!doc) {
+            const suggestions = this.docsIndex
+                .filter(d => d.path.includes(path.split('/').pop() || ''))
+                .slice(0, 3)
+                .map(d => d.path);
+            return {
+                content: [{
+                        type: 'text',
+                        text: `Documentation not found: ${path}${suggestions.length ? `\n\nDid you mean:\n${suggestions.map(s => `- ${s}`).join('\n')}` : ''}`,
+                    }],
+                isError: true,
+            };
+        }
+        return {
+            content: [{
+                    type: 'text',
+                    text: `# ${doc.title}\n\nPath: ${doc.path}\nCategory: ${doc.category}\n\n---\n\n${doc.content}`,
+                }],
+        };
+    }
+    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);
+        try {
+            switch (method) {
+                case 'initialize': {
+                    this.initialized = true;
+                    const response = {
+                        protocolVersion: '2024-11-05',
+                        capabilities: {
+                            tools: { listChanged: false },
+                        },
+                        serverInfo: {
+                            name: this.options.name,
+                            version: this.options.version,
+                        },
+                    };
+                    return { jsonrpc: '2.0', id: id, result: response };
+                }
+                case 'notifications/initialized': {
+                    return { jsonrpc: '2.0', id: id, result: {} };
+                }
+                case 'ping':
+                    return { jsonrpc: '2.0', id: id, result: {} };
+                case 'tools/list': {
+                    const response = { tools: this.getTools() };
+                    return { jsonrpc: '2.0', id: id, result: response };
+                }
+                case 'tools/call': {
+                    const { name, arguments: args } = params;
+                    const result = this.handleToolCall(name, args || {});
+                    return { jsonrpc: '2.0', id: id, result };
+                }
+                case 'resources/list':
+                    return { jsonrpc: '2.0', id: id, result: { resources: [] } };
+                case 'prompts/list':
+                    return { jsonrpc: '2.0', id: id, result: { prompts: [] } };
+                default:
+                    return {
+                        jsonrpc: '2.0',
+                        id: id,
+                        error: { code: -32601, message: `Method not found: ${method}` },
+                    };
+            }
+        }
+        catch (err) {
+            return {
+                jsonrpc: '2.0',
+                id: id,
+                error: { code: -32603, message: String(err) },
+            };
+        }
+    }
+    sendNotification(notification) {
+        const data = JSON.stringify(notification);
+        for (const client of this.sseClients) {
+            client.write(`data: ${data}\n\n`);
+        }
+    }
+    async startStdio() {
+        const rl = createInterface({
+            input: process.stdin,
+            output: process.stdout,
+            terminal: false,
+        });
+        this.log('Starting in stdio mode');
+        rl.on('line', (line) => {
+            if (!line.trim())
+                return;
+            try {
+                const request = JSON.parse(line);
+                const response = this.handleRequest(request);
+                process.stdout.write(JSON.stringify(response) + '\n');
+            }
+            catch (err) {
+                const errorResponse = {
+                    jsonrpc: '2.0',
+                    id: 0,
+                    error: { code: -32700, message: 'Parse error' },
+                };
+                process.stdout.write(JSON.stringify(errorResponse) + '\n');
+            }
+        });
+        rl.on('close', () => {
+            this.log('stdin closed, exiting');
+            process.exit(0);
+        });
+    }
+    async startHttp() {
+        return new Promise((resolve) => {
+            this.server = createServer((req, res) => {
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+                if (req.method === 'OPTIONS') {
+                    res.writeHead(204);
+                    res.end();
+                    return;
+                }
+                if (req.method !== 'POST') {
+                    res.writeHead(405);
+                    res.end('Method not allowed');
+                    return;
+                }
+                let body = '';
+                req.on('data', chunk => body += chunk);
+                req.on('end', () => {
+                    try {
+                        const request = JSON.parse(body);
+                        const response = this.handleRequest(request);
+                        res.writeHead(200, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify(response));
+                    }
+                    catch (err) {
+                        res.writeHead(400, { 'Content-Type': 'application/json' });
+                        res.end(JSON.stringify({
+                            jsonrpc: '2.0',
+                            id: null,
+                            error: { code: -32700, message: 'Parse error' },
+                        }));
+                    }
+                });
+            });
+            this.server.listen(this.options.port, () => {
+                this.log(`HTTP server listening on http://localhost:${this.options.port}`);
+                resolve();
+            });
+        });
+    }
+    async startSSE() {
+        return new Promise((resolve) => {
+            this.server = createServer((req, res) => {
+                res.setHeader('Access-Control-Allow-Origin', '*');
+                res.setHeader('Access-Control-Allow-Methods', 'POST, GET, OPTIONS');
+                res.setHeader('Access-Control-Allow-Headers', 'Content-Type');
+                const url = req.url || '/';
+                if (req.method === 'OPTIONS') {
+                    res.writeHead(204);
+                    res.end();
+                    return;
+                }
+                if (req.method === 'GET' && url === '/sse') {
+                    res.writeHead(200, {
+                        'Content-Type': 'text/event-stream',
+                        'Cache-Control': 'no-cache',
+                        'Connection': 'keep-alive',
+                    });
+                    res.write(`data: ${JSON.stringify({ type: 'connected' })}\n\n`);
+                    this.sseClients.add(res);
+                    this.log(`SSE client connected (${this.sseClients.size} total)`);
+                    req.on('close', () => {
+                        this.sseClients.delete(res);
+                        this.log(`SSE client disconnected (${this.sseClients.size} total)`);
+                    });
+                    return;
+                }
+                if (req.method === 'POST') {
+                    let body = '';
+                    req.on('data', chunk => body += chunk);
+                    req.on('end', () => {
+                        try {
+                            const request = JSON.parse(body);
+                            const response = this.handleRequest(request);
+                            res.writeHead(200, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify(response));
+                        }
+                        catch (err) {
+                            res.writeHead(400, { 'Content-Type': 'application/json' });
+                            res.end(JSON.stringify({
+                                jsonrpc: '2.0',
+                                id: null,
+                                error: { code: -32700, message: 'Parse error' },
+                            }));
+                        }
+                    });
+                    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: stats.documents,
+                        examplesCount: this.codeExamples.length,
+                        typesCount: this.typeDefinitions.length,
+                        embeddingsLoaded: stats.embeddings > 0,
+                        sseClients: this.sseClients.size,
+                    }));
+                    return;
+                }
+                res.writeHead(404);
+                res.end('Not found');
+            });
+            this.server.listen(this.options.port, () => {
+                this.log(`SSE server listening on http://localhost:${this.options.port}`);
+                this.log(`  POST /        - JSON-RPC endpoint`);
+                this.log(`  GET  /sse     - Server-Sent Events`);
+                this.log(`  GET  /health  - Health check`);
+                resolve();
+            });
+        });
+    }
+    async start() {
+        switch (this.options.transport) {
+            case 'stdio':
+                return this.startStdio();
+            case 'http':
+                return this.startHttp();
+            case 'sse':
+                return this.startSSE();
+            default:
+                throw new Error(`Unknown transport: ${this.options.transport}`);
+        }
+    }
+    async stop() {
+        for (const client of this.sseClients) {
+            client.end();
+        }
+        this.sseClients.clear();
+        return new Promise((resolve) => {
+            if (this.server) {
+                this.server.close(() => resolve());
+            }
+            else {
+                resolve();
+            }
+        });
+    }
+    getPort() {
+        return this.options.port;
+    }
+    getDocsCount() {
+        return this.docsIndex.length;
+    }
+    getExamplesCount() {
+        return this.codeExamples.length;
+    }
+    getTypesCount() {
+        return this.typeDefinitions.length;
+    }
+    getTransport() {
+        return this.options.transport;
+    }
+}
+export function createMCPServer(options) {
+    return new MCPServer(options);
+}