react-docs-mcp 1.0.0

package/dist/embeddingService.js

@@ -0,0 +1,113 @@
+/**
+ * embeddingService.ts
+ * Generate embeddings using transformers.js for semantic search
+ */
+import { pipeline, env } from '@xenova/transformers';
+// Configure transformers.js
+env.allowLocalModels = true;
+env.allowRemoteModels = true;
+/**
+ * Embedding service using all-MiniLM-L6-v2 model
+ * This is a lightweight model (23MB) optimized for semantic similarity
+ */
+export class EmbeddingService {
+    pipeline = null;
+    initialized = false;
+    modelName = 'Xenova/all-MiniLM-L6-v2';
+    /**
+     * Initialize the embedding pipeline
+     * Downloads model on first run (~23MB)
+     */
+    async initialize() {
+        if (this.initialized)
+            return;
+        console.log('Initializing embedding model (first run may take a moment)...');
+        try {
+            this.pipeline = await pipeline('feature-extraction', this.modelName);
+            this.initialized = true;
+            console.log('Embedding model initialized successfully');
+        }
+        catch (error) {
+            console.error('Failed to initialize embedding model:', error);
+            throw new Error(`Embedding initialization failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Generate embedding for a text
+     * @param text - Text to embed
+     * @returns Vector embedding (384 dimensions for all-MiniLM-L6-v2)
+     */
+    async generateEmbedding(text) {
+        if (!this.initialized) {
+            await this.initialize();
+        }
+        try {
+            // Truncate text to reasonable length (512 tokens max)
+            const truncated = text.slice(0, 2000);
+            const output = await this.pipeline(truncated, {
+                pooling: 'mean',
+                normalize: true,
+            });
+            // Convert tensor to array
+            const embedding = Array.from(output.data);
+            return embedding;
+        }
+        catch (error) {
+            console.error('Failed to generate embedding:', error);
+            throw new Error(`Embedding generation failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    /**
+     * Generate embeddings for multiple texts (batch processing)
+     * @param texts - Array of texts to embed
+     * @returns Array of vector embeddings
+     */
+    async generateEmbeddings(texts) {
+        const embeddings = [];
+        for (const text of texts) {
+            const embedding = await this.generateEmbedding(text);
+            embeddings.push(embedding);
+        }
+        return embeddings;
+    }
+    /**
+     * Calculate cosine similarity between two vectors
+     * @param a - First vector
+     * @param b - Second vector
+     * @returns Similarity score (0-1, higher is more similar)
+     */
+    cosineSimilarity(a, b) {
+        if (a.length !== b.length) {
+            throw new Error('Vectors must have same length');
+        }
+        let dotProduct = 0;
+        let normA = 0;
+        let normB = 0;
+        for (let i = 0; i < a.length; i++) {
+            dotProduct += a[i] * b[i];
+            normA += a[i] * a[i];
+            normB += b[i] * b[i];
+        }
+        const magnitude = Math.sqrt(normA) * Math.sqrt(normB);
+        if (magnitude === 0)
+            return 0;
+        return dotProduct / magnitude;
+    }
+    /**
+     * Find most similar vectors to a query vector
+     * @param queryEmbedding - Query vector
+     * @param docEmbeddings - Array of document vectors with metadata
+     * @param topK - Number of results to return
+     * @returns Array of {index, similarity} sorted by similarity desc
+     */
+    findMostSimilar(queryEmbedding, docEmbeddings, topK) {
+        const similarities = docEmbeddings.map(({ embedding, index }) => ({
+            index,
+            similarity: this.cosineSimilarity(queryEmbedding, embedding),
+        }));
+        // Sort by similarity descending
+        similarities.sort((a, b) => b.similarity - a.similarity);
+        return similarities.slice(0, topK);
+    }
+}
+//# sourceMappingURL=embeddingService.js.map

package/dist/embeddingService.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embeddingService.js","sourceRoot":"","sources":["../src/embeddingService.ts"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+#!/usr/bin/env node
+/**
+ * index.ts
+ * MCP server entry point implementing the protocol
+ */
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":";AAEA;;;GAGG"}

package/dist/index.js

@@ -0,0 +1,272 @@
+#!/usr/bin/env node
+/**
+ * index.ts
+ * MCP server entry point implementing the protocol
+ */
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { DocsManager } from './docsManager.js';
+import { SearchEngine } from './searchEngine.js';
+import { summarizeContent, extractStructure } from './summarizer.js';
+import CONFIG from './config.js';
+// Initialize components
+const docsManager = new DocsManager();
+const searchEngine = new SearchEngine(docsManager);
+// Create MCP server
+const server = new Server({
+    name: CONFIG.server.name,
+    version: CONFIG.server.version,
+}, {
+    capabilities: {
+        resources: {},
+        tools: {},
+    },
+});
+// Tool input schemas
+const searchDocsSchema = z.object({
+    query: z.string().describe('Search query string'),
+    section: z.string().optional().describe('Filter by section (learn, reference, blog, community)'),
+    limit: z.number().min(1).max(CONFIG.search.maxLimit).optional().describe('Maximum number of results'),
+});
+const getDocSchema = z.object({
+    path: z.string().describe('Document path (e.g., "learn/hooks/useState")'),
+});
+// Register list resources handler
+server.setRequestHandler(ListResourcesRequestSchema, async () => {
+    return {
+        resources: [
+            {
+                uri: 'react-docs://learn',
+                name: 'React Learn Documentation',
+                description: 'Interactive React tutorial and learning materials',
+                mimeType: 'text/plain',
+            },
+            {
+                uri: 'react-docs://reference',
+                name: 'React API Reference',
+                description: 'Complete React API reference documentation',
+                mimeType: 'text/plain',
+            },
+            {
+                uri: 'react-docs://blog',
+                name: 'React Blog',
+                description: 'React team blog posts and announcements',
+                mimeType: 'text/plain',
+            },
+        ],
+    };
+});
+// Register read resource handler
+server.setRequestHandler(ReadResourceRequestSchema, async (request) => {
+    const uri = request.params.uri.toString();
+    // Parse URI: react-docs://{section}/{path}
+    const match = uri.match(/^react-docs:\/\/(.+)$/);
+    if (!match) {
+        throw new Error(`Invalid resource URI: ${uri}`);
+    }
+    const resourcePath = match[1];
+    // If requesting just a section, list docs in that section
+    if (CONFIG.sections.includes(resourcePath)) {
+        const docs = await searchEngine.getDocsBySection(resourcePath);
+        const docList = docs
+            .map(doc => `- ${doc.metadata.title} (${doc.path})`)
+            .join('\n');
+        return {
+            contents: [
+                {
+                    uri,
+                    mimeType: 'text/plain',
+                    text: `# ${resourcePath} Documentation\n\nAvailable documents:\n\n${docList}`,
+                },
+            ],
+        };
+    }
+    // Otherwise, fetch specific document
+    const doc = await searchEngine.getDocByPath(resourcePath);
+    if (!doc) {
+        throw new Error(`Document not found: ${resourcePath}`);
+    }
+    return {
+        contents: [
+            {
+                uri,
+                mimeType: 'text/markdown',
+                text: `# ${doc.metadata.title}\n\n${doc.content}`,
+            },
+        ],
+    };
+});
+// Register list tools handler
+server.setRequestHandler(ListToolsRequestSchema, async () => {
+    return {
+        tools: [
+            {
+                name: 'search_react_docs',
+                description: 'Search across React documentation. Returns relevant documentation pages with snippets.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        query: {
+                            type: 'string',
+                            description: 'Search query string',
+                        },
+                        section: {
+                            type: 'string',
+                            description: 'Filter by section (learn, reference, blog, community)',
+                            enum: [...CONFIG.sections],
+                        },
+                        limit: {
+                            type: 'number',
+                            description: 'Maximum number of results',
+                            minimum: 1,
+                            maximum: CONFIG.search.maxLimit,
+                        },
+                    },
+                    required: ['query'],
+                },
+            },
+            {
+                name: 'list_sections',
+                description: 'List all available documentation sections',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+            {
+                name: 'get_doc',
+                description: 'Get a concise summary of a documentation page (~1500 chars). Use search_react_docs first - only call this if you need more detail than the search snippet provides.',
+                inputSchema: {
+                    type: 'object',
+                    properties: {
+                        path: {
+                            type: 'string',
+                            description: 'Document path (e.g., "learn/hooks/useState")',
+                        },
+                    },
+                    required: ['path'],
+                },
+            },
+            {
+                name: 'update_docs',
+                description: 'Pull latest documentation from Git repository',
+                inputSchema: {
+                    type: 'object',
+                    properties: {},
+                },
+            },
+        ],
+    };
+});
+// Register call tool handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case 'search_react_docs': {
+                const { query, section, limit } = searchDocsSchema.parse(args);
+                const results = await searchEngine.search(query, { section, limit });
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(results.map(r => ({
+                                path: r.doc.path,
+                                title: r.doc.metadata.title,
+                                snippet: r.snippet,
+                                score: r.score,
+                                url: `https://react.dev/${r.doc.path}`,
+                            })), null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'list_sections': {
+                const sections = searchEngine.getSections();
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify(sections, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'get_doc': {
+                const { path } = getDocSchema.parse(args);
+                const doc = await searchEngine.getDocByPath(path);
+                if (!doc) {
+                    throw new Error(`Document not found: ${path}`);
+                }
+                // Return concise summary instead of full content
+                const summary = summarizeContent(doc.content, 1500);
+                const structure = extractStructure(doc.content);
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                path: doc.path,
+                                section: doc.section,
+                                title: doc.metadata.title,
+                                description: doc.metadata.description,
+                                summary,
+                                structure,
+                                url: `https://react.dev/${doc.path}`,
+                                note: 'This is a summary. Visit the URL for full documentation.',
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            case 'update_docs': {
+                const updated = await docsManager.updateRepo();
+                if (updated) {
+                    // Re-index documents after update
+                    await searchEngine.indexDocuments();
+                }
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: JSON.stringify({
+                                updated,
+                                message: updated
+                                    ? 'Documentation updated successfully'
+                                    : 'Documentation already up to date',
+                            }, null, 2),
+                        },
+                    ],
+                };
+            }
+            default:
+                throw new Error(`Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        if (error instanceof z.ZodError) {
+            throw new Error(`Invalid arguments: ${error.message}`);
+        }
+        throw error;
+    }
+});
+// Start server
+async function main() {
+    console.error('Initializing React Docs MCP Server...');
+    try {
+        // Initialize repository
+        await docsManager.initialize();
+        // Start server with stdio transport
+        const transport = new StdioServerTransport();
+        await server.connect(transport);
+        console.error('React Docs MCP Server running');
+    }
+    catch (error) {
+        console.error('Failed to start server:', error);
+        process.exit(1);
+    }
+}
+main();
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/dist/markdownParser.d.ts

@@ -0,0 +1,25 @@
+/**
+ * markdownParser.ts
+ * Parse markdown files and extract metadata and content
+ */
+import type { ParsedDoc } from './types.js';
+/**
+ * Parse a markdown file
+ * @param content - Raw markdown content
+ * @param path - File path for context
+ * @returns Parsed document with metadata and content
+ */
+export declare function parseMarkdown(content: string, path: string): Promise<ParsedDoc>;
+/**
+ * Strip markdown formatting to plain text
+ * Used for search indexing
+ * @param markdown - Markdown content
+ * @returns Plain text
+ */
+export declare function markdownToPlainText(markdown: string): Promise<string>;
+/**
+ * Extract section from file path
+ * E.g., "learn/hooks/useState.md" -> "learn"
+ */
+export declare function extractSection(path: string): string;
+//# sourceMappingURL=markdownParser.d.ts.map

package/dist/markdownParser.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownParser.d.ts","sourceRoot":"","sources":["../src/markdownParser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAKH,OAAO,KAAK,EAAe,SAAS,EAAE,MAAM,YAAY,CAAC;AAEzD;;;;;GAKG;AACH,wBAAsB,aAAa,CACjC,OAAO,EAAE,MAAM,EACf,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,SAAS,CAAC,CA2BpB;AAED;;;;;GAKG;AACH,wBAAsB,mBAAmB,CAAC,QAAQ,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAQ3E;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAInD"}

package/dist/markdownParser.js

@@ -0,0 +1,85 @@
+/**
+ * markdownParser.ts
+ * Parse markdown files and extract metadata and content
+ */
+import matter from 'gray-matter';
+import { remark } from 'remark';
+import stripMarkdown from 'strip-markdown';
+/**
+ * Parse a markdown file
+ * @param content - Raw markdown content
+ * @param path - File path for context
+ * @returns Parsed document with metadata and content
+ */
+export async function parseMarkdown(content, path) {
+    // Parse frontmatter
+    const { data, content: markdownContent } = matter(content);
+    // Extract metadata
+    const metadata = {
+        title: data.title || extractTitleFromPath(path),
+        description: data.description,
+        date: data.date,
+        author: data.author,
+        tags: data.tags,
+        ...data,
+    };
+    // Convert to plain text for search
+    const plainText = await markdownToPlainText(markdownContent);
+    // Extract section from path
+    const section = extractSection(path);
+    return {
+        path: normalizePath(path),
+        section,
+        metadata,
+        content: markdownContent,
+        plainText,
+    };
+}
+/**
+ * Strip markdown formatting to plain text
+ * Used for search indexing
+ * @param markdown - Markdown content
+ * @returns Plain text
+ */
+export async function markdownToPlainText(markdown) {
+    const result = await remark()
+        .use(stripMarkdown)
+        .process(markdown);
+    return String(result)
+        .replace(/\s+/g, ' ') // Normalize whitespace
+        .trim();
+}
+/**
+ * Extract section from file path
+ * E.g., "learn/hooks/useState.md" -> "learn"
+ */
+export function extractSection(path) {
+    const normalized = normalizePath(path);
+    const parts = normalized.split('/');
+    return parts[0] || 'unknown';
+}
+/**
+ * Normalize path (forward slashes, no leading slash, no .md extension for display)
+ */
+function normalizePath(filePath) {
+    return filePath
+        .replace(/\\/g, '/') // Convert backslashes to forward slashes
+        .replace(/^\/+/, '') // Remove leading slashes
+        .replace(/\.md$/, ''); // Remove .md extension for cleaner paths
+}
+/**
+ * Extract title from path if not in frontmatter
+ * E.g., "learn/hooks/useState" -> "useState"
+ */
+function extractTitleFromPath(filePath) {
+    const normalized = normalizePath(filePath);
+    const parts = normalized.split('/');
+    const filename = parts[parts.length - 1] || 'Untitled';
+    // Convert kebab-case or snake_case to Title Case
+    return filename
+        .replace(/[-_]/g, ' ')
+        .split(' ')
+        .map(word => word.charAt(0).toUpperCase() + word.slice(1))
+        .join(' ');
+}
+//# sourceMappingURL=markdownParser.js.map

package/dist/markdownParser.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"markdownParser.js","sourceRoot":"","sources":["../src/markdownParser.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,MAAM,MAAM,aAAa,CAAC;AACjC,OAAO,EAAE,MAAM,EAAE,MAAM,QAAQ,CAAC;AAChC,OAAO,aAAa,MAAM,gBAAgB,CAAC;AAG3C;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,aAAa,CACjC,OAAe,EACf,IAAY;IAEZ,oBAAoB;IACpB,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,eAAe,EAAE,GAAG,MAAM,CAAC,OAAO,CAAC,CAAC;IAE3D,mBAAmB;IACnB,MAAM,QAAQ,GAAgB;QAC5B,KAAK,EAAE,IAAI,CAAC,KAAK,IAAI,oBAAoB,CAAC,IAAI,CAAC;QAC/C,WAAW,EAAE,IAAI,CAAC,WAAW;QAC7B,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,MAAM,EAAE,IAAI,CAAC,MAAM;QACnB,IAAI,EAAE,IAAI,CAAC,IAAI;QACf,GAAG,IAAI;KACR,CAAC;IAEF,mCAAmC;IACnC,MAAM,SAAS,GAAG,MAAM,mBAAmB,CAAC,eAAe,CAAC,CAAC;IAE7D,4BAA4B;IAC5B,MAAM,OAAO,GAAG,cAAc,CAAC,IAAI,CAAC,CAAC;IAErC,OAAO;QACL,IAAI,EAAE,aAAa,CAAC,IAAI,CAAC;QACzB,OAAO;QACP,QAAQ;QACR,OAAO,EAAE,eAAe;QACxB,SAAS;KACV,CAAC;AACJ,CAAC;AAED;;;;;GAKG;AACH,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAgB;IACxD,MAAM,MAAM,GAAG,MAAM,MAAM,EAAE;SAC1B,GAAG,CAAC,aAAa,CAAC;SAClB,OAAO,CAAC,QAAQ,CAAC,CAAC;IAErB,OAAO,MAAM,CAAC,MAAM,CAAC;SAClB,OAAO,CAAC,MAAM,EAAE,GAAG,CAAC,CAAC,uBAAuB;SAC5C,IAAI,EAAE,CAAC;AACZ,CAAC;AAED;;;GAGG;AACH,MAAM,UAAU,cAAc,CAAC,IAAY;IACzC,MAAM,UAAU,GAAG,aAAa,CAAC,IAAI,CAAC,CAAC;IACvC,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,OAAO,KAAK,CAAC,CAAC,CAAC,IAAI,SAAS,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,SAAS,aAAa,CAAC,QAAgB;IACrC,OAAO,QAAQ;SACZ,OAAO,CAAC,KAAK,EAAE,GAAG,CAAC,CAAC,yCAAyC;SAC7D,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC,CAAC,yBAAyB;SAC7C,OAAO,CAAC,OAAO,EAAE,EAAE,CAAC,CAAC,CAAC,yCAAyC;AACpE,CAAC;AAED;;;GAGG;AACH,SAAS,oBAAoB,CAAC,QAAgB;IAC5C,MAAM,UAAU,GAAG,aAAa,CAAC,QAAQ,CAAC,CAAC;IAC3C,MAAM,KAAK,GAAG,UAAU,CAAC,KAAK,CAAC,GAAG,CAAC,CAAC;IACpC,MAAM,QAAQ,GAAG,KAAK,CAAC,KAAK,CAAC,MAAM,GAAG,CAAC,CAAC,IAAI,UAAU,CAAC;IAEvD,iDAAiD;IACjD,OAAO,QAAQ;SACZ,OAAO,CAAC,OAAO,EAAE,GAAG,CAAC;SACrB,KAAK,CAAC,GAAG,CAAC;SACV,GAAG,CAAC,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,CAAC,CAAC,WAAW,EAAE,GAAG,IAAI,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;SACzD,IAAI,CAAC,GAAG,CAAC,CAAC;AACf,CAAC"}

package/dist/searchEngine.d.ts

@@ -0,0 +1,66 @@
+/**
+ * searchEngine.ts
+ * Implement search functionality over documentation
+ */
+import { DocsManager } from './docsManager.js';
+import type { ParsedDoc, SearchOptions, SearchResult } from './types.js';
+export declare class SearchEngine {
+    private docsManager;
+    private embeddingService;
+    private documentIndex;
+    private indexed;
+    private embeddingsGenerated;
+    /**
+     * Initialize search engine
+     * @param docsManager - Instance of DocsManager
+     */
+    constructor(docsManager: DocsManager);
+    /**
+     * Index all documents for searching
+     * Should be called after repo update
+     */
+    indexDocuments(): Promise<void>;
+    /**
+     * Generate embeddings for all documents
+     * Called lazily when semantic search is first used
+     */
+    generateEmbeddings(): Promise<void>;
+    /**
+     * Search documents
+     * @param query - Search query string
+     * @param options - Search options (section filter, limit, etc.)
+     * @returns Ranked search results
+     */
+    search(query: string, options?: SearchOptions): Promise<SearchResult[]>;
+    /**
+     * Keyword-based search
+     */
+    private keywordSearch;
+    /**
+     * Semantic search using embeddings (hybrid with keyword search)
+     */
+    private semanticSearch;
+    /**
+     * Score a document based on query terms
+     */
+    private scoreDocument;
+    /**
+     * Generate context snippet showing matched text
+     */
+    private generateSnippet;
+    /**
+     * Get document by exact path
+     * @param path - Document path relative to content root
+     * @returns Parsed document or null if not found
+     */
+    getDocByPath(path: string): Promise<ParsedDoc | null>;
+    /**
+     * List all available sections
+     */
+    getSections(): string[];
+    /**
+     * Get all documents in a section
+     */
+    getDocsBySection(section: string): Promise<ParsedDoc[]>;
+}
+//# sourceMappingURL=searchEngine.d.ts.map

package/dist/searchEngine.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"searchEngine.d.ts","sourceRoot":"","sources":["../src/searchEngine.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AAI/C,OAAO,KAAK,EAAE,SAAS,EAAE,aAAa,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAEzE,qBAAa,YAAY;IACvB,OAAO,CAAC,WAAW,CAAc;IACjC,OAAO,CAAC,gBAAgB,CAAmB;IAC3C,OAAO,CAAC,aAAa,CAAqC;IAC1D,OAAO,CAAC,OAAO,CAAkB;IACjC,OAAO,CAAC,mBAAmB,CAAkB;IAE7C;;;OAGG;gBACS,WAAW,EAAE,WAAW;IAKpC;;;OAGG;IACG,cAAc,IAAI,OAAO,CAAC,IAAI,CAAC;IAoBrC;;;OAGG;IACG,kBAAkB,IAAI,OAAO,CAAC,IAAI,CAAC;IA6BzC;;;;;OAKG;IACG,MAAM,CACV,KAAK,EAAE,MAAM,EACb,OAAO,CAAC,EAAE,aAAa,GACtB,OAAO,CAAC,YAAY,EAAE,CAAC;IAsB1B;;OAEG;YACW,aAAa;IAsC3B;;OAEG;YACW,cAAc;IA0D5B;;OAEG;IACH,OAAO,CAAC,aAAa;IAkCrB;;OAEG;IACH,OAAO,CAAC,eAAe;IAkCvB;;;;OAIG;IACG,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,GAAG,IAAI,CAAC;IAY3D;;OAEG;IACH,WAAW,IAAI,MAAM,EAAE;IAIvB;;OAEG;IACG,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,EAAE,CAAC;CAiB9D"}