omophub-mcp 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024-2026 OMOPHub
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,265 @@
+<h1>OMOPHub MCP Server</h1>
+
+<p>
+  <strong>Medical vocabularies for AI agents.</strong><br/>
+  Search, map, and navigate 5M+ OMOP concepts: SNOMED CT, ICD-10, RxNorm, LOINC, and more. Directly from Claude, Cursor, VS Code, or any MCP-compatible client.
+</p>
+
+<p>
+  <a href="https://www.npmjs.com/package/omophub-mcp"><img src="https://img.shields.io/npm/v/omophub-mcp?style=flat-square&color=cb3837&label=npm" alt="npm version" /></a>
+  <a href="https://www.npmjs.com/package/omophub-mcp"><img src="https://img.shields.io/npm/dm/omophub-mcp?style=flat-square&color=blue" alt="npm downloads" /></a>
+  <a href="https://github.com/OMOPHub/omophub-mcp/blob/main/LICENSE"><img src="https://img.shields.io/github/license/OMOPHub/omophub-mcp?style=flat-square" alt="License" /></a>
+  <a href="https://github.com/OMOPHub/omophub-mcp"><img src="https://img.shields.io/badge/TypeScript-5.x-3178c6?style=flat-square&logo=typescript&logoColor=white" alt="TypeScript" /></a>
+  <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-compatible-green?style=flat-square" alt="MCP Compatible" /></a>
+</p>
+
+<p>
+  <a href="#quick-start">Quick Start</a> ·
+  <a href="#available-tools">Tools</a> ·
+  <a href="#example-prompts">Examples</a> ·
+  <a href="https://docs.omophub.com">Docs</a> ·
+  <a href="https://omophub.com">Website</a>
+</p>
+
+---
+
+## Why OMOPHub MCP?
+
+Working with medical vocabularies today means downloading multi-gigabyte CSV files, loading them into a local database, and writing SQL to find what you need. Every time.
+
+**OMOPHub MCP Server gives your AI assistant instant access to the entire OHDSI ATHENA vocabulary**. No database setup, no CSV wrangling, no context switching. Just ask.
+
+```
+You: "Map ICD-10 code E11.9 to SNOMED"
+
+Claude: Found it - E11.9 (Type 2 diabetes mellitus without complications)
+        maps to SNOMED concept 201826 (Type 2 diabetes mellitus)
+        via standard 'Maps to' relationship.
+```
+
+**Use cases:**
+- **Concept lookup** - Find OMOP concept IDs for clinical terms in seconds
+- **Cross-vocabulary mapping** - Map between ICD-10, SNOMED, RxNorm, LOINC, and 100+ vocabularies
+- **Hierarchy navigation** - Explore ancestors and descendants for phenotype definitions
+- **Concept set building** - Let your AI agent assemble complete concept sets for cohort definitions
+- **Code validation** - Verify medical codes and check their standard mappings
+
+---
+
+## Quick Start
+
+### 1. Get an API Key
+
+Sign up at [omophub.com](https://omophub.com) → create an API key in your [dashboard](https://omophub.com/dashboard/api-keys).
+
+### 2. Add to Your AI Client
+
+<details open>
+<summary><strong>Claude Desktop</strong></summary>
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "omophub": {
+      "command": "npx",
+      "args": ["-y", "omophub-mcp"],
+      "env": {
+        "OMOPHUB_API_KEY": "oh_your_key_here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Claude Code</strong></summary>
+
+```bash
+claude mcp add omophub -- npx -y omophub-mcp
+# Then set OMOPHUB_API_KEY in your environment
+```
+
+</details>
+
+<details>
+<summary><strong>Cursor</strong></summary>
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "omophub": {
+      "command": "npx",
+      "args": ["-y", "omophub-mcp"],
+      "env": {
+        "OMOPHUB_API_KEY": "oh_your_key_here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>VS Code</strong></summary>
+
+Add to `.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "omophub": {
+      "command": "npx",
+      "args": ["-y", "omophub-mcp"],
+      "env": {
+        "OMOPHUB_API_KEY": "oh_your_key_here"
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+<summary><strong>Docker</strong></summary>
+
+```bash
+docker run -i -e OMOPHUB_API_KEY=oh_your_key_here -p 8080:8080 omophub/omophub-mcp
+```
+
+</details>
+
+### 3. Start Asking
+
+> "What's the OMOP concept ID for type 2 diabetes?"
+
+> "Map ICD-10 code E11.9 to SNOMED"
+
+> "Show me all descendants of Diabetes mellitus in SNOMED"
+
+---
+
+## Available Tools
+
+| Tool | What it does |
+| :--- | :--- |
+| `search_concepts` | Search for medical concepts by name or clinical term across all vocabularies |
+| `get_concept` | Get detailed info about a specific OMOP concept by `concept_id` |
+| `get_concept_by_code` | Look up a concept using a vocabulary-specific code (e.g., ICD-10 `E11.9`) |
+| `map_concept` | Map a concept to equivalent concepts in other vocabularies |
+| `get_hierarchy` | Navigate concept hierarchy - ancestors, descendants, or both |
+| `list_vocabularies` | List available medical vocabularies with statistics |
+
+### Resources
+
+| URI | Description |
+| :--- | :--- |
+| `omophub://vocabularies` | Full vocabulary catalog with statistics |
+| `omophub://vocabularies/{vocabulary_id}` | Details for a specific vocabulary |
+
+### Prompts
+
+| Prompt | Description |
+| :--- | :--- |
+| `phenotype-concept-set` | Guided workflow to build a concept set for a clinical phenotype |
+| `code-lookup` | Look up and validate a medical code with mappings and hierarchy |
+
+---
+
+## Example Prompts
+
+**Find a concept →** `search_concepts`
+> "Search for metformin in RxNorm"
+
+**Cross-vocabulary mapping →** `map_concept`
+> "I have SNOMED concept 201826 - what's the ICD-10 code?"
+
+**Build a concept set →** `search_concepts` → `get_hierarchy` → `map_concept`
+> "Help me build a concept set for Type 2 diabetes including all descendants"
+
+**Validate a code →** `get_concept_by_code` → `map_concept`
+> "Is ICD-10 code E11.9 valid? What does it map to in SNOMED?"
+
+---
+
+## Configuration
+
+### Environment Variables
+
+| Variable | Required | Description |
+| :--- | :---: | :--- |
+| `OMOPHUB_API_KEY` | ✅ | Your OMOPHub API key |
+| `OMOPHUB_BASE_URL` | | Custom API base URL (default: `https://api.omophub.com/v1`) |
+| `OMOPHUB_LOG_LEVEL` | | `debug` · `info` · `warn` · `error` (default: `info`) |
+| `OMOPHUB_ANALYTICS_OPTOUT` | | Set to `true` to disable analytics headers |
+| `HEALTH_PORT` | | Port for HTTP health endpoint (default: disabled) |
+
+### CLI Arguments
+
+```bash
+npx omophub-mcp --api-key=oh_your_key --base-url=https://custom.api.com/v1 --health-port=8080
+```
+
+### Health Endpoint (Docker / Kubernetes)
+
+```bash
+# Enable health checks
+HEALTH_PORT=8080 OMOPHUB_API_KEY=oh_your_key npx omophub-mcp
+
+# Test it
+curl http://localhost:8080/health
+# → {"status":"ok","version":"1.0.0","uptime_seconds":42}
+```
+
+The Docker image enables the health endpoint on port 8080 by default.
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/OMOPHub/omophub-mcp.git
+cd omophub-mcp
+npm install
+npm run build
+npm test
+```
+
+Run locally:
+
+```bash
+OMOPHUB_API_KEY=oh_your_key npx tsx src/index.ts
+```
+
+---
+
+## Troubleshooting
+
+| Error | Solution |
+| :--- | :--- |
+| `API key required` | Set `OMOPHUB_API_KEY` in your environment or MCP config |
+| `Authentication failed` | API key may be invalid or expired - [generate a new one](https://omophub.com/dashboard/api-keys) |
+| `Rate limit exceeded` | Automatic retries are built in. For higher limits, [upgrade your plan](https://omophub.com/dashboard/billing) |
+| Tools not appearing | Restart your AI client, verify `npx omophub-mcp` runs without errors, check config path |
+
+---
+
+## Links
+
+- [Documentation](https://docs.omophub.com)
+- [Get an API Key](https://omophub.com/dashboard/api-keys)
+- [Python SDK](https://github.com/OMOPHub/omophub-python)
+- [Community & Support](https://github.com/OMOPHub/omophub-mcp/issues)
+
+---
+
+## License
+
+MIT - see [LICENSE](LICENSE)

package/dist/client/api.d.ts

@@ -0,0 +1,10 @@
+import type { ApiResponse } from './types.js';
+export declare class OmopHubClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly analyticsOptout;
+    constructor(apiKey: string, baseUrl?: string);
+    request<T>(path: string, params?: Record<string, string | number | boolean | undefined>, toolName?: string): Promise<ApiResponse<T>>;
+    post<T>(path: string, body: Record<string, unknown>, toolName?: string): Promise<ApiResponse<T>>;
+}
+//# sourceMappingURL=api.d.ts.map

package/dist/client/api.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"api.d.ts","sourceRoot":"","sources":["../../src/client/api.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAkB9C,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAU;gBAE9B,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM;IAUtC,OAAO,CAAC,CAAC,EACb,IAAI,EAAE,MAAM,EACZ,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,SAAS,CAAC,EAC9D,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;IAqFpB,IAAI,CAAC,CAAC,EACV,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,EAC7B,QAAQ,CAAC,EAAE,MAAM,GAChB,OAAO,CAAC,WAAW,CAAC,CAAC,CAAC,CAAC;CA0E3B"}

package/dist/client/api.js

@@ -0,0 +1,168 @@
+import { OmopHubApiError } from '../utils/errors.js';
+import { logger } from '../utils/logger.js';
+import { VERSION } from '../version.js';
+const MAX_RETRIES = 2;
+/** Parse Retry-After header (seconds or HTTP-date), returning wait time in ms. */
+function parseRetryAfter(header, fallbackMs) {
+    const seconds = parseInt(header, 10);
+    if (!Number.isNaN(seconds) && seconds >= 0)
+        return seconds * 1000;
+    const date = Date.parse(header);
+    if (!Number.isNaN(date)) {
+        const delayMs = date - Date.now();
+        return delayMs > 0 ? delayMs : fallbackMs;
+    }
+    return fallbackMs;
+}
+export class OmopHubClient {
+    baseUrl;
+    apiKey;
+    analyticsOptout;
+    constructor(apiKey, baseUrl) {
+        this.apiKey = apiKey;
+        this.baseUrl = (baseUrl ||
+            process.env.OMOPHUB_BASE_URL ||
+            'https://api.omophub.com/v1').replace(/\/$/, '');
+        this.analyticsOptout = process.env.OMOPHUB_ANALYTICS_OPTOUT === 'true';
+    }
+    async request(path, params, toolName) {
+        const url = new URL(`${this.baseUrl}${path}`);
+        if (params) {
+            for (const [key, value] of Object.entries(params)) {
+                if (value !== undefined && value !== '') {
+                    url.searchParams.set(key, String(value));
+                }
+            }
+        }
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'User-Agent': `omophub-mcp/${VERSION}`,
+            Accept: 'application/json',
+        };
+        if (!this.analyticsOptout) {
+            headers['X-MCP-Client'] = 'true';
+            if (toolName) {
+                headers['X-MCP-Tool'] = toolName;
+            }
+        }
+        let lastError = null;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            const start = Date.now();
+            try {
+                const response = await fetch(url.toString(), {
+                    headers,
+                    signal: AbortSignal.timeout(30_000),
+                });
+                const duration = Date.now() - start;
+                logger.debug('API request', {
+                    tool_name: toolName,
+                    api_path: path,
+                    duration_ms: duration,
+                    status: response.status,
+                });
+                if (response.status === 429 && attempt < MAX_RETRIES) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    const fallbackMs = 1000 * (attempt + 1);
+                    const waitMs = retryAfter ? parseRetryAfter(retryAfter, fallbackMs) : fallbackMs;
+                    logger.warn(`Rate limited, retrying in ${waitMs}ms`, {
+                        tool_name: toolName,
+                        api_path: path,
+                    });
+                    await new Promise((resolve) => setTimeout(resolve, waitMs));
+                    continue;
+                }
+                if (!response.ok) {
+                    const body = await response.text();
+                    let message;
+                    try {
+                        const parsed = JSON.parse(body);
+                        message = parsed.error?.message || parsed.message || body;
+                    }
+                    catch {
+                        message = body || response.statusText;
+                    }
+                    throw new OmopHubApiError(response.status, message, path);
+                }
+                return (await response.json());
+            }
+            catch (error) {
+                if (error instanceof OmopHubApiError)
+                    throw error;
+                lastError = error instanceof Error ? error : new Error(String(error));
+                if (attempt < MAX_RETRIES) {
+                    logger.warn(`Request failed, retrying (attempt ${attempt + 1})`, {
+                        tool_name: toolName,
+                        api_path: path,
+                    });
+                    await new Promise((resolve) => setTimeout(resolve, 1000 * (attempt + 1)));
+                }
+            }
+        }
+        throw lastError || new Error('Request failed after retries');
+    }
+    async post(path, body, toolName) {
+        const url = `${this.baseUrl}${path}`;
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            'User-Agent': `omophub-mcp/${VERSION}`,
+            'Content-Type': 'application/json',
+            Accept: 'application/json',
+        };
+        if (!this.analyticsOptout) {
+            headers['X-MCP-Client'] = 'true';
+            if (toolName) {
+                headers['X-MCP-Tool'] = toolName;
+            }
+        }
+        const lastError = null;
+        for (let attempt = 0; attempt <= MAX_RETRIES; attempt++) {
+            const start = Date.now();
+            try {
+                const response = await fetch(url, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(body),
+                    signal: AbortSignal.timeout(30_000),
+                });
+                logger.debug('API POST request', {
+                    tool_name: toolName,
+                    api_path: path,
+                    duration_ms: Date.now() - start,
+                    status: response.status,
+                });
+                if (response.status === 429 && attempt < MAX_RETRIES) {
+                    const retryAfter = response.headers.get('Retry-After');
+                    const fallbackMs = 1000 * (attempt + 1);
+                    const waitMs = retryAfter ? parseRetryAfter(retryAfter, fallbackMs) : fallbackMs;
+                    logger.warn(`Rate limited, retrying in ${waitMs}ms`, {
+                        tool_name: toolName,
+                        api_path: path,
+                    });
+                    await new Promise((resolve) => setTimeout(resolve, waitMs));
+                    continue;
+                }
+                if (!response.ok) {
+                    const text = await response.text();
+                    let message;
+                    try {
+                        const parsed = JSON.parse(text);
+                        message = parsed.error?.message || parsed.message || text;
+                    }
+                    catch {
+                        message = text || response.statusText;
+                    }
+                    throw new OmopHubApiError(response.status, message, path);
+                }
+                return (await response.json());
+            }
+            catch (error) {
+                if (error instanceof OmopHubApiError)
+                    throw error;
+                // Do not retry POST on network errors — could cause duplicate mutations
+                throw error instanceof Error ? error : new Error(String(error));
+            }
+        }
+        throw lastError || new Error('POST request failed after retries');
+    }
+}
+//# sourceMappingURL=api.js.map

package/dist/client/api.js.map

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

package/dist/client/types.d.ts

@@ -0,0 +1,86 @@
+export interface PaginationMeta {
+    page: number;
+    page_size: number;
+    total_items: number;
+    total_pages: number;
+    has_next: boolean;
+    has_previous: boolean;
+}
+export interface ApiResponse<T> {
+    success: boolean;
+    data: T;
+    meta?: {
+        pagination?: PaginationMeta;
+        execution_time_ms?: number;
+        version?: string;
+    };
+}
+export interface Concept {
+    concept_id: number;
+    concept_name: string;
+    domain_id: string;
+    vocabulary_id: string;
+    concept_class_id: string;
+    standard_concept: string | null;
+    concept_code: string;
+    valid_start_date?: string;
+    valid_end_date?: string;
+    invalid_reason?: string | null;
+    synonyms?: string[];
+}
+export interface SearchResult extends Concept {
+    score?: number;
+}
+export interface Mapping {
+    concept_id: number;
+    concept_name: string;
+    vocabulary_id: string;
+    concept_code: string;
+    domain_id: string;
+    standard_concept: string | null;
+    concept_class_id: string;
+    relationship_id: string;
+    relationship_name?: string;
+}
+export interface HierarchyNode extends Concept {
+    level?: number;
+    min_levels_of_separation?: number;
+    max_levels_of_separation?: number;
+}
+export interface HierarchyResponse {
+    concept: Concept;
+    ancestors?: HierarchyNode[];
+    descendants?: HierarchyNode[];
+    total_ancestors?: number;
+    total_descendants?: number;
+}
+/** Raw hierarchy shape from the API (flat concept fields, no nested `concept` object) */
+export interface RawHierarchyResponse {
+    concept_id: number;
+    concept_name?: string;
+    vocabulary_id?: string;
+    ancestors?: HierarchyNode[];
+    descendants?: HierarchyNode[];
+    total_ancestors?: number;
+    total_descendants?: number;
+    hierarchy_summary?: {
+        total_ancestors?: number;
+        total_descendants?: number;
+    };
+}
+export interface Vocabulary {
+    vocabulary_id: string;
+    vocabulary_name: string;
+    vocabulary_reference?: string;
+    vocabulary_version?: string;
+    vocabulary_concept_id?: number;
+    concept_count?: number;
+    standard_concept_count?: number;
+    domain_coverage?: Record<string, number>;
+}
+export interface MappingsResponse {
+    source_concept: Concept;
+    mappings: Mapping[];
+    total_mappings: number;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/client/types.d.ts.map

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

package/dist/client/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/dist/client/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":""}

package/dist/formatters/index.d.ts

@@ -0,0 +1,26 @@
+import type { ApiResponse, Concept, HierarchyResponse, MappingsResponse, SearchResult, Vocabulary } from '../client/types.js';
+export declare function formatConceptList(response: ApiResponse<SearchResult[]>, query: string): {
+    text: string;
+    json: string;
+};
+export declare function formatConcept(concept: Concept): {
+    text: string;
+    json: string;
+};
+export declare function formatMappings(response: ApiResponse<MappingsResponse>, conceptId: number): {
+    text: string;
+    json: string;
+};
+export declare function formatHierarchy(response: ApiResponse<HierarchyResponse>, direction: 'up' | 'down' | 'both'): {
+    text: string;
+    json: string;
+};
+export declare function formatVocabularyList(response: ApiResponse<Vocabulary[]>, search?: string): {
+    text: string;
+    json: string;
+};
+export declare function formatError(error: string): {
+    text: string;
+    json: string;
+};
+//# sourceMappingURL=index.d.ts.map

package/dist/formatters/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/formatters/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,WAAW,EACX,OAAO,EAEP,iBAAiB,EAEjB,gBAAgB,EAChB,YAAY,EACZ,UAAU,EACX,MAAM,oBAAoB,CAAC;AAa5B,wBAAgB,iBAAiB,CAC/B,QAAQ,EAAE,WAAW,CAAC,YAAY,EAAE,CAAC,EACrC,KAAK,EAAE,MAAM,GACZ;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAyChC;AAED,wBAAgB,aAAa,CAAC,OAAO,EAAE,OAAO,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAgC9E;AAED,wBAAgB,cAAc,CAC5B,QAAQ,EAAE,WAAW,CAAC,gBAAgB,CAAC,EACvC,SAAS,EAAE,MAAM,GAChB;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAyChC;AAED,wBAAgB,eAAe,CAC7B,QAAQ,EAAE,WAAW,CAAC,iBAAiB,CAAC,EACxC,SAAS,EAAE,IAAI,GAAG,MAAM,GAAG,MAAM,GAChC;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAsDhC;AAED,wBAAgB,oBAAoB,CAClC,QAAQ,EAAE,WAAW,CAAC,UAAU,EAAE,CAAC,EACnC,MAAM,CAAC,EAAE,MAAM,GACd;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAwChC;AAED,wBAAgB,WAAW,CAAC,KAAK,EAAE,MAAM,GAAG;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAKzE"}