@omophub/omophub-mcp 1.1.0 → 1.2.2

package/README.md

@@ -50,7 +50,7 @@ Claude: Found it - E11.9 (Type 2 diabetes mellitus without complications)
 
 ### 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).
+Sign up at [omophub.com](https://omophub.com) → create an API key in your [dashboard](https://dashboard.omophub.com/api-keys).
 
 ### 2. Add to Your AI Client
 
@@ -177,6 +177,9 @@ docker run -i -e OMOPHUB_API_KEY=oh_your_key_here omophub/omophub-mcp --transpor
 | `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 |
+| `semantic_search` | Search using natural language with neural embeddings (understands clinical meaning) |
+| `find_similar_concepts` | Find concepts similar to a reference concept, name, or description |
+| `explore_concept` | Get concept details, hierarchy, and cross-vocabulary mappings in one call |
 
 ### Resources
 
@@ -208,6 +211,15 @@ docker run -i -e OMOPHUB_API_KEY=oh_your_key_here omophub/omophub-mcp --transpor
 **Validate a code →** `get_concept_by_code` → `map_concept`
 > "Is ICD-10 code E11.9 valid? What does it map to in SNOMED?"
 
+**Semantic search →** `semantic_search`
+> "Find concepts related to 'heart attack'"
+
+**Explore a concept →** `explore_concept`
+> "Give me everything about SNOMED concept 201826"
+
+**Find similar →** `find_similar_concepts`
+> "What concepts are similar to 'Type 2 diabetes mellitus'?"
+
 ---
 
 ## Configuration
@@ -244,7 +256,7 @@ In **HTTP mode**, the health endpoint is available at `/health` on the same port
 ```bash
 npx @omophub/omophub-mcp --transport=http --port=3100 --api-key=oh_your_key
 curl http://localhost:3100/health
-# → {"status":"ok","version":"1.1.0","uptime_seconds":42}
+# → {"status":"ok","version":"1.2.2","uptime_seconds":42}
 ```
 
 In **stdio mode**, use `--health-port` for a standalone health endpoint:
@@ -281,8 +293,8 @@ OMOPHUB_API_KEY=oh_your_key npx tsx src/index.ts
 | 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) |
+| `Authentication failed` | API key may be invalid or expired - [generate a new one](https://dashboard.omophub.com/api-keys) |
+| `Rate limit exceeded` | Automatic retries are built in. For higher limits, [upgrade your plan](https://dashboard.omophub.com/billing) |
 | Tools not appearing | Restart your AI client, verify `npx @omophub/omophub-mcp` runs without errors, check config path |
 
 ---
@@ -290,7 +302,7 @@ OMOPHUB_API_KEY=oh_your_key npx tsx src/index.ts
 ## Links
 
 - [Documentation](https://docs.omophub.com)
-- [Get an API Key](https://omophub.com/dashboard/api-keys)
+- [Get an API Key](https://dashboard.omophub.com/api-keys)
 - [Python SDK](https://github.com/OMOPHub/omophub-python)
 - [Community & Support](https://github.com/OMOPHub/omophub-mcp/issues)
 

package/dist/server.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAcpE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CA4BxE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAiBpE,wBAAgB,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,CAAC,EAAE,MAAM,GAAG,SAAS,CA+BxE"}

package/dist/server.js

@@ -2,7 +2,7 @@ import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { OmopHubClient } from './client/api.js';
 import { registerPrompts } from './prompts/index.js';
 import { registerResources } from './resources/index.js';
-import { registerConceptTools, registerHierarchyTools, registerMappingTools, registerSearchTools, registerVocabularyTools, } from './tools/index.js';
+import { registerConceptTools, registerExploreTools, registerHierarchyTools, registerMappingTools, registerSearchTools, registerSemanticSearchTools, registerSimilarTools, registerVocabularyTools, } from './tools/index.js';
 import { logger } from './utils/logger.js';
 import { VERSION } from './version.js';
 export function createServer(apiKey, baseUrl) {
@@ -12,9 +12,12 @@ export function createServer(apiKey, baseUrl) {
         description: 'Access OHDSI standardized medical vocabularies — search concepts, navigate hierarchies, and map between clinical coding systems like SNOMED CT, ICD-10, RxNorm, and LOINC.',
     });
     const client = new OmopHubClient(apiKey, baseUrl);
-    // Register all Phase 1 tools
+    // Register tools
     registerSearchTools(server, client);
+    registerSemanticSearchTools(server, client);
+    registerSimilarTools(server, client);
     registerConceptTools(server, client);
+    registerExploreTools(server, client);
     registerMappingTools(server, client);
     registerHierarchyTools(server, client);
     registerVocabularyTools(server, client);
@@ -22,7 +25,7 @@ export function createServer(apiKey, baseUrl) {
     registerResources(server, client);
     registerPrompts(server);
     logger.info('OMOPHub MCP server initialized', {
-        tools: 6,
+        tools: 9,
         resources: 2,
         prompts: 2,
     });

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EACL,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,OAAgB;IAC3D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;QAChB,WAAW,EACT,4KAA4K;KAC/K,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElD,6BAA6B;IAC7B,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC,iCAAiC;IACjC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,eAAe,CAAC,MAAM,CAAC,CAAC;IAExB,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE;QAC5C,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;KACX,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../src/server.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACpE,OAAO,EAAE,aAAa,EAAE,MAAM,iBAAiB,CAAC;AAChD,OAAO,EAAE,eAAe,EAAE,MAAM,oBAAoB,CAAC;AACrD,OAAO,EAAE,iBAAiB,EAAE,MAAM,sBAAsB,CAAC;AACzD,OAAO,EACL,oBAAoB,EACpB,oBAAoB,EACpB,sBAAsB,EACtB,oBAAoB,EACpB,mBAAmB,EACnB,2BAA2B,EAC3B,oBAAoB,EACpB,uBAAuB,GACxB,MAAM,kBAAkB,CAAC;AAC1B,OAAO,EAAE,MAAM,EAAE,MAAM,mBAAmB,CAAC;AAC3C,OAAO,EAAE,OAAO,EAAE,MAAM,cAAc,CAAC;AAEvC,MAAM,UAAU,YAAY,CAAC,MAAc,EAAE,OAAgB;IAC3D,MAAM,MAAM,GAAG,IAAI,SAAS,CAAC;QAC3B,IAAI,EAAE,SAAS;QACf,OAAO,EAAE,OAAO;QAChB,WAAW,EACT,4KAA4K;KAC/K,CAAC,CAAC;IAEH,MAAM,MAAM,GAAG,IAAI,aAAa,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;IAElD,iBAAiB;IACjB,mBAAmB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACpC,2BAA2B,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC5C,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,oBAAoB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACrC,sBAAsB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACvC,uBAAuB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAExC,iCAAiC;IACjC,iBAAiB,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,eAAe,CAAC,MAAM,CAAC,CAAC;IAExB,MAAM,CAAC,IAAI,CAAC,gCAAgC,EAAE;QAC5C,KAAK,EAAE,CAAC;QACR,SAAS,EAAE,CAAC;QACZ,OAAO,EAAE,CAAC;KACX,CAAC,CAAC;IAEH,OAAO,MAAM,CAAC;AAChB,CAAC"}

package/dist/tools/explore.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { OmopHubClient } from '../client/api.js';
+export declare function registerExploreTools(server: McpServer, client: OmopHubClient): void;
+//# sourceMappingURL=explore.d.ts.map

package/dist/tools/explore.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"explore.d.ts","sourceRoot":"","sources":["../../src/tools/explore.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAsBtD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CA0OnF"}

package/dist/tools/explore.js

@@ -0,0 +1,182 @@
+import { z } from 'zod';
+import { formatErrorForMcp } from '../utils/errors.js';
+export function registerExploreTools(server, client) {
+    server.tool('explore_concept', 'Get a comprehensive view of a medical concept in one call: detailed info, ancestors/descendants hierarchy, and cross-vocabulary mappings. Use this instead of calling get_concept + get_hierarchy + map_concept separately. Ideal for understanding what a concept is, where it sits in the classification tree, and how it maps to other coding systems.', {
+        concept_id: z.number().describe('The OMOP concept_id to explore'),
+        include_hierarchy: z
+            .boolean()
+            .default(true)
+            .describe('Include ancestors and descendants. Default true.'),
+        hierarchy_levels: z
+            .number()
+            .min(1)
+            .max(5)
+            .default(2)
+            .describe('How many hierarchy levels to fetch (1-5, default 2)'),
+        include_mappings: z
+            .boolean()
+            .default(true)
+            .describe('Include cross-vocabulary mappings. Default true.'),
+        target_vocabularies: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("Comma-separated vocabulary IDs to filter mappings. Examples: 'ICD10CM', 'SNOMED'."),
+    }, async ({ concept_id, include_hierarchy, include_mappings, hierarchy_levels, target_vocabularies, }) => {
+        try {
+            // Build parallel requests
+            const requests = [];
+            // 1. Always fetch concept details
+            const conceptReq = client.request(`/concepts/${concept_id}`, {}, 'explore_concept');
+            requests.push(conceptReq);
+            // 2. Optionally fetch hierarchy
+            let hierarchyReq = null;
+            if (include_hierarchy !== false) {
+                const levels = hierarchy_levels ?? 2;
+                hierarchyReq = client.request(`/concepts/${concept_id}/hierarchy`, { max_levels: levels }, 'explore_concept');
+                requests.push(hierarchyReq);
+            }
+            // 3. Optionally fetch mappings via relationships endpoint
+            // (The /mappings endpoint has a schema resolution bug — using /relationships instead)
+            let mappingsReq = null;
+            if (include_mappings !== false) {
+                mappingsReq = client.request(`/concepts/${concept_id}/relationships`, { page_size: 100 }, 'explore_concept');
+                requests.push(mappingsReq);
+            }
+            // Execute all in parallel
+            const settled = await Promise.allSettled(requests);
+            // Extract results
+            const conceptResult = settled[0];
+            const concept = conceptResult.status === 'fulfilled'
+                ? conceptResult.value.data
+                : null;
+            let hierarchy = null;
+            let relationshipsData = null;
+            let idx = 1;
+            if (hierarchyReq) {
+                const r = settled[idx++];
+                if (r.status === 'fulfilled') {
+                    hierarchy = r.value.data;
+                }
+            }
+            if (mappingsReq) {
+                const r = settled[idx];
+                if (r.status === 'fulfilled') {
+                    relationshipsData = r.value.data;
+                }
+            }
+            if (!concept) {
+                // If the request was rejected, propagate the original error
+                if (conceptResult.status === 'rejected') {
+                    const { text, json } = formatErrorForMcp(conceptResult.reason, 'explore_concept');
+                    return {
+                        content: [
+                            { type: 'text', text },
+                            { type: 'text', text: json },
+                        ],
+                        isError: true,
+                    };
+                }
+                return {
+                    content: [{ type: 'text', text: `Concept ${concept_id} not found.` }],
+                    isError: true,
+                };
+            }
+            // Build human-readable output
+            const sections = [];
+            // Concept info
+            const std = concept.standard_concept === 'S'
+                ? ' [Standard]'
+                : concept.standard_concept === 'C'
+                    ? ' [Classification]'
+                    : '';
+            sections.push(`## ${concept.concept_name}${std}\n` +
+                `- **Concept ID:** ${concept.concept_id}\n` +
+                `- **Vocabulary:** ${concept.vocabulary_id}\n` +
+                `- **Domain:** ${concept.domain_id}\n` +
+                `- **Class:** ${concept.concept_class_id}\n` +
+                `- **Code:** ${concept.concept_code}`);
+            // Hierarchy
+            if (hierarchy) {
+                const ancestors = hierarchy.ancestors ?? [];
+                const descendants = hierarchy.descendants ?? [];
+                if (ancestors.length > 0 || descendants.length > 0) {
+                    const hierarchyLines = ['## Hierarchy'];
+                    if (ancestors.length > 0) {
+                        hierarchyLines.push(`\n### Ancestors (${ancestors.length})`);
+                        for (const a of ancestors.slice(0, 10)) {
+                            const level = a.min_levels_of_separation ?? a.level ?? '';
+                            hierarchyLines.push(`  ${'  '.repeat(Number(level) || 0)}↑ ${a.concept_name} (${a.vocabulary_id}, ID: ${a.concept_id})`);
+                        }
+                        if (ancestors.length > 10)
+                            hierarchyLines.push(`  ... and ${ancestors.length - 10} more`);
+                    }
+                    if (descendants.length > 0) {
+                        hierarchyLines.push(`\n### Descendants (${descendants.length})`);
+                        for (const d of descendants.slice(0, 10)) {
+                            const level = d.min_levels_of_separation ?? d.level ?? '';
+                            hierarchyLines.push(`  ${'  '.repeat(Number(level) || 0)}↓ ${d.concept_name} (${d.vocabulary_id}, ID: ${d.concept_id})`);
+                        }
+                        if (descendants.length > 10)
+                            hierarchyLines.push(`  ... and ${descendants.length - 10} more`);
+                    }
+                    sections.push(hierarchyLines.join('\n'));
+                }
+            }
+            // Mappings — extracted from relationships with "Maps to" type
+            if (relationshipsData) {
+                const allRels = relationshipsData.relationships ?? [];
+                // Filter for mapping relationships
+                const mappingRels = allRels.filter((r) => r.relationship_id === 'Maps to' || r.relationship_id === 'Mapped from');
+                // Optionally filter by target vocabularies
+                const vocabFilter = target_vocabularies
+                    ? target_vocabularies
+                        .split(',')
+                        .map((v) => v.trim())
+                        .filter(Boolean)
+                    : null;
+                const filtered = vocabFilter
+                    ? mappingRels.filter((r) => vocabFilter.includes(r.concept_2?.vocabulary_id ?? ''))
+                    : mappingRels;
+                if (filtered.length > 0) {
+                    const mapLines = [`## Cross-Vocabulary Mappings (${filtered.length})`];
+                    for (const r of filtered.slice(0, 15)) {
+                        const c2 = r.concept_2;
+                        if (c2) {
+                            mapLines.push(`- **${c2.concept_name}** → ${c2.vocabulary_id} (${c2.concept_code}) via _${r.relationship_id}_`);
+                        }
+                    }
+                    if (filtered.length > 15)
+                        mapLines.push(`... and ${filtered.length - 15} more`);
+                    sections.push(mapLines.join('\n'));
+                }
+                else {
+                    const isStandard = concept.standard_concept === 'S';
+                    const hint = isStandard
+                        ? ' Standard concepts are typically the *target* of mappings, not the source. To find what maps to this concept, try searching for a non-standard source concept (e.g., an ICD-10 code) and use explore_concept on that.'
+                        : '';
+                    sections.push(`## Mappings\n\nNo cross-vocabulary mappings found.${hint}`);
+                }
+            }
+            const text = sections.join('\n\n');
+            const jsonData = { concept, hierarchy, relationships: relationshipsData };
+            return {
+                content: [
+                    { type: 'text', text },
+                    { type: 'text', text: JSON.stringify(jsonData) },
+                ],
+            };
+        }
+        catch (error) {
+            const { text, json } = formatErrorForMcp(error, 'explore_concept');
+            return {
+                content: [
+                    { type: 'text', text },
+                    { type: 'text', text: json },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=explore.js.map

package/dist/tools/explore.js.map

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

package/dist/tools/index.d.ts

@@ -1,6 +1,9 @@
 export { registerConceptTools } from './concepts.js';
+export { registerExploreTools } from './explore.js';
 export { registerHierarchyTools } from './hierarchy.js';
 export { registerMappingTools } from './mappings.js';
 export { registerSearchTools } from './search.js';
+export { registerSemanticSearchTools } from './semantic-search.js';
+export { registerSimilarTools } from './similar.js';
 export { registerVocabularyTools } from './vocabularies.js';
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/tools/index.js

@@ -1,6 +1,9 @@
 export { registerConceptTools } from './concepts.js';
+export { registerExploreTools } from './explore.js';
 export { registerHierarchyTools } from './hierarchy.js';
 export { registerMappingTools } from './mappings.js';
 export { registerSearchTools } from './search.js';
+export { registerSemanticSearchTools } from './semantic-search.js';
+export { registerSimilarTools } from './similar.js';
 export { registerVocabularyTools } from './vocabularies.js';
 //# sourceMappingURL=index.js.map

package/dist/tools/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/tools/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,sBAAsB,EAAE,MAAM,gBAAgB,CAAC;AACxD,OAAO,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AACrD,OAAO,EAAE,mBAAmB,EAAE,MAAM,aAAa,CAAC;AAClD,OAAO,EAAE,2BAA2B,EAAE,MAAM,sBAAsB,CAAC;AACnE,OAAO,EAAE,oBAAoB,EAAE,MAAM,cAAc,CAAC;AACpD,OAAO,EAAE,uBAAuB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/tools/semantic-search.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { OmopHubClient } from '../client/api.js';
+export declare function registerSemanticSearchTools(server: McpServer, client: OmopHubClient): void;
+//# sourceMappingURL=semantic-search.d.ts.map

package/dist/tools/semantic-search.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"semantic-search.d.ts","sourceRoot":"","sources":["../../src/tools/semantic-search.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AAStD,wBAAgB,2BAA2B,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAyG1F"}

package/dist/tools/semantic-search.js

@@ -0,0 +1,92 @@
+import { z } from 'zod';
+import { formatErrorForMcp } from '../utils/errors.js';
+export function registerSemanticSearchTools(server, client) {
+    server.tool('semantic_search', "Search for medical concepts using natural language with neural embeddings. Unlike keyword search, semantic search understands clinical meaning — 'heart attack' finds 'Myocardial infarction', 'high blood sugar' finds 'Hyperglycemia'. Returns concepts ranked by similarity score. Use this when the user describes symptoms, conditions, or treatments in everyday language rather than exact medical terminology.", {
+        query: z
+            .string()
+            .trim()
+            .min(1)
+            .max(500)
+            .describe('Natural language description of the medical concept to find'),
+        vocabulary_ids: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("Comma-separated vocabulary IDs to filter by. Examples: 'SNOMED', 'ICD10CM', 'RxNorm'."),
+        domain_ids: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("Comma-separated domain IDs to filter by. Examples: 'Condition', 'Drug', 'Measurement'."),
+        standard_concept: z
+            .enum(['S', 'C'])
+            .optional()
+            .describe("Filter by standard concept status: 'S' for Standard, 'C' for Classification."),
+        threshold: z
+            .number()
+            .min(0)
+            .max(1)
+            .default(0.5)
+            .describe('Minimum similarity score (0.0-1.0). Higher = stricter matching. Default 0.5.'),
+        page_size: z
+            .number()
+            .min(1)
+            .max(50)
+            .default(10)
+            .describe('Number of results to return (1-50, default 10)'),
+    }, async ({ query, vocabulary_ids, domain_ids, standard_concept, threshold, page_size }) => {
+        try {
+            const params = {
+                query,
+                page_size: page_size ?? 10,
+                threshold: threshold ?? 0.5,
+            };
+            if (vocabulary_ids)
+                params.vocabulary_ids = vocabulary_ids;
+            if (domain_ids)
+                params.domain_ids = domain_ids;
+            if (standard_concept)
+                params.standard_concept = standard_concept;
+            const response = await client.request('/concepts/semantic-search', params, 'semantic_search');
+            const results = response.data?.results ?? [];
+            if (results.length === 0) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No semantic matches found for "${query}". Try different wording or lower the similarity threshold.`,
+                        },
+                        { type: 'text', text: JSON.stringify({ results: [], query, threshold }) },
+                    ],
+                };
+            }
+            const lines = results.map((r, i) => {
+                const std = r.standard_concept === 'S'
+                    ? ' [Standard]'
+                    : r.standard_concept === 'C'
+                        ? ' [Classification]'
+                        : '';
+                const score = Number.isFinite(r.similarity_score) ? r.similarity_score.toFixed(2) : 'N/A';
+                return `${i + 1}. **${r.concept_name}** (ID: ${r.concept_id}) — similarity: ${score}\n   ${r.vocabulary_id} | ${r.domain_id} | Code: ${r.concept_code}${std}`;
+            });
+            const text = `Found ${results.length} semantic matches for "${query}":\n\n${lines.join('\n\n')}`;
+            return {
+                content: [
+                    { type: 'text', text },
+                    { type: 'text', text: JSON.stringify({ results, query, threshold }) },
+                ],
+            };
+        }
+        catch (error) {
+            const { text, json } = formatErrorForMcp(error, 'semantic_search');
+            return {
+                content: [
+                    { type: 'text', text },
+                    { type: 'text', text: json },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=semantic-search.js.map

package/dist/tools/semantic-search.js.map

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

package/dist/tools/similar.d.ts

@@ -0,0 +1,4 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { OmopHubClient } from '../client/api.js';
+export declare function registerSimilarTools(server: McpServer, client: OmopHubClient): void;
+//# sourceMappingURL=similar.d.ts.map

package/dist/tools/similar.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"similar.d.ts","sourceRoot":"","sources":["../../src/tools/similar.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AAEzE,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AA2BtD,wBAAgB,oBAAoB,CAAC,MAAM,EAAE,SAAS,EAAE,MAAM,EAAE,aAAa,GAAG,IAAI,CAmKnF"}

package/dist/tools/similar.js

@@ -0,0 +1,139 @@
+import { z } from 'zod';
+import { formatErrorForMcp } from '../utils/errors.js';
+export function registerSimilarTools(server, client) {
+    server.tool('find_similar_concepts', "Find medical concepts similar to a reference concept, name, or natural language query. Supports three algorithms: 'semantic' (neural embeddings — best for meaning), 'lexical' (text matching — best for typos), 'hybrid' (combined — default). Provide exactly ONE of: concept_id, concept_name, or query. Use this to explore related concepts, find alternative codes, or build phenotype concept sets. Tip: For drug vocabularies like RxNorm, use drug class names ('ACE inhibitors', 'beta blockers', 'antihypertensives') rather than symptom descriptions ('medications for high blood pressure') — the embedding model aligns better with clinical terminology than lay language.", {
+        concept_id: z.number().optional().describe('Find concepts similar to this OMOP concept ID'),
+        concept_name: z
+            .string()
+            .max(500)
+            .optional()
+            .describe('Find concepts similar to this concept name'),
+        query: z
+            .string()
+            .max(500)
+            .optional()
+            .describe('Find concepts matching this natural language description'),
+        algorithm: z
+            .enum(['semantic', 'lexical', 'hybrid'])
+            .default('hybrid')
+            .describe("Similarity algorithm: 'semantic' (meaning), 'lexical' (text), 'hybrid' (both). Default 'hybrid'."),
+        similarity_threshold: z
+            .number()
+            .min(0)
+            .max(1)
+            .default(0.7)
+            .describe('Minimum similarity score (0.0-1.0). Default 0.7.'),
+        page_size: z
+            .number()
+            .min(1)
+            .max(100)
+            .default(20)
+            .describe('Number of results (1-100, default 20)'),
+        vocabulary_ids: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("Comma-separated vocabulary IDs to filter results. Examples: 'SNOMED', 'ICD10CM'."),
+        domain_ids: z
+            .string()
+            .max(200)
+            .optional()
+            .describe("Comma-separated domain IDs to filter results. Examples: 'Condition', 'Drug'."),
+    }, async ({ concept_id, concept_name, query, algorithm, similarity_threshold, page_size, vocabulary_ids, domain_ids, }) => {
+        try {
+            // Validate exactly one input source
+            const provided = [concept_id, concept_name, query].filter((v) => v !== undefined).length;
+            if (provided !== 1) {
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: 'Error: Provide exactly one of concept_id, concept_name, or query.',
+                        },
+                    ],
+                    isError: true,
+                };
+            }
+            const body = {
+                algorithm: algorithm ?? 'hybrid',
+                similarity_threshold: similarity_threshold ?? 0.7,
+                page_size: page_size ?? 20,
+            };
+            if (concept_id !== undefined)
+                body.concept_id = concept_id;
+            if (concept_name !== undefined)
+                body.concept_name = concept_name;
+            if (query !== undefined)
+                body.query = query;
+            if (vocabulary_ids)
+                body.vocabulary_ids = vocabulary_ids
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+            if (domain_ids)
+                body.domain_ids = domain_ids
+                    .split(',')
+                    .map((s) => s.trim())
+                    .filter(Boolean);
+            const response = await client.post('/search/similar', body, 'find_similar_concepts');
+            const data = response.data;
+            const concepts = data?.similar_concepts ?? [];
+            const meta = data?.search_metadata;
+            if (concepts.length === 0) {
+                const source = concept_id ? `concept ${concept_id}` : (concept_name ?? query ?? '');
+                return {
+                    content: [
+                        {
+                            type: 'text',
+                            text: `No similar concepts found for ${source}. Try lowering the similarity threshold or using a different algorithm.`,
+                        },
+                        {
+                            type: 'text',
+                            text: JSON.stringify({ similar_concepts: [], search_metadata: meta }),
+                        },
+                    ],
+                };
+            }
+            const source = concept_id
+                ? `concept ID ${concept_id}`
+                : concept_name
+                    ? `"${concept_name}"`
+                    : `"${query}"`;
+            const lines = concepts.map((c, i) => {
+                const std = c.standard_concept === 'S'
+                    ? ' [Standard]'
+                    : c.standard_concept === 'C'
+                        ? ' [Classification]'
+                        : '';
+                const score = Number.isFinite(c.similarity_score) ? c.similarity_score.toFixed(2) : 'N/A';
+                let line = `${i + 1}. **${c.concept_name}** (ID: ${c.concept_id}) — score: ${score}\n   ${c.vocabulary_id} | ${c.domain_id} | Code: ${c.concept_code}${std}`;
+                if (c.similarity_explanation) {
+                    line += `\n   _${c.similarity_explanation}_`;
+                }
+                return line;
+            });
+            const algoLabel = meta?.algorithm_used ?? algorithm ?? 'hybrid';
+            const text = `Found ${concepts.length} concepts similar to ${source} (${algoLabel} algorithm):\n\n${lines.join('\n\n')}`;
+            return {
+                content: [
+                    { type: 'text', text },
+                    {
+                        type: 'text',
+                        text: JSON.stringify({ similar_concepts: concepts, search_metadata: meta }),
+                    },
+                ],
+            };
+        }
+        catch (error) {
+            const { text, json } = formatErrorForMcp(error, 'find_similar_concepts');
+            return {
+                content: [
+                    { type: 'text', text },
+                    { type: 'text', text: json },
+                ],
+                isError: true,
+            };
+        }
+    });
+}
+//# sourceMappingURL=similar.js.map

package/dist/tools/similar.js.map

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

package/dist/utils/auth.js

@@ -2,7 +2,7 @@ export function resolveApiKey(cliKey) {
     const key = cliKey || process.env.OMOPHUB_API_KEY;
     if (!key) {
         throw new Error('OMOPHub API key required. Set OMOPHUB_API_KEY environment variable or pass --api-key=KEY.\n' +
-            'Get your free API key at: https://omophub.com/dashboard/api-keys');
+            'Get your free API key at: https://dashboard.omophub.com/api-keys');
     }
     return key;
 }

package/dist/utils/errors.js

@@ -8,8 +8,8 @@ export class OmopHubApiError extends Error {
         this.name = 'OmopHubApiError';
     }
 }
-const UPGRADE_URL = 'https://omophub.com/dashboard/billing';
-const API_KEYS_URL = 'https://omophub.com/dashboard/api-keys';
+const UPGRADE_URL = 'https://dashboard.omophub.com/billing';
+const API_KEYS_URL = 'https://dashboard.omophub.com/api-keys';
 export function formatErrorForMcp(error, toolName) {
     if (error instanceof OmopHubApiError) {
         switch (error.status) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@omophub/omophub-mcp",
-  "version": "1.1.0",
+  "version": "1.2.2",
   "mcpName": "io.github.OMOPHub/omophub-mcp",
   "description": "MCP server for OHDSI OMOP standardized medical vocabularies — search, lookup, map, and navigate concepts via AI agents",
   "type": "module",