@omophub/omophub-mcp 1.1.0

package/dist/utils/errors.d.ts

@@ -0,0 +1,10 @@
+export declare class OmopHubApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    constructor(status: number, message: string, path: string);
+}
+export declare function formatErrorForMcp(error: unknown, toolName: string): {
+    text: string;
+    json: string;
+};
+//# sourceMappingURL=errors.d.ts.map

package/dist/utils/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/utils/errors.ts"],"names":[],"mappings":"AAAA,qBAAa,eAAgB,SAAQ,KAAK;aAEtB,MAAM,EAAE,MAAM;aAEd,IAAI,EAAE,MAAM;gBAFZ,MAAM,EAAE,MAAM,EAC9B,OAAO,EAAE,MAAM,EACC,IAAI,EAAE,MAAM;CAK/B;AAKD,wBAAgB,iBAAiB,CAC/B,KAAK,EAAE,OAAO,EACd,QAAQ,EAAE,MAAM,GACf;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAsFhC"}

package/dist/utils/errors.js

@@ -0,0 +1,95 @@
+export class OmopHubApiError extends Error {
+    status;
+    path;
+    constructor(status, message, path) {
+        super(message);
+        this.status = status;
+        this.path = path;
+        this.name = 'OmopHubApiError';
+    }
+}
+const UPGRADE_URL = 'https://omophub.com/dashboard/billing';
+const API_KEYS_URL = 'https://omophub.com/dashboard/api-keys';
+export function formatErrorForMcp(error, toolName) {
+    if (error instanceof OmopHubApiError) {
+        switch (error.status) {
+            case 401:
+                return {
+                    text: `Authentication failed for ${toolName}. ` +
+                        'Check that your OMOPHUB_API_KEY is valid. ' +
+                        `Get a new key at: ${API_KEYS_URL}`,
+                    json: JSON.stringify({ error_code: 'AUTH_FAILED' }),
+                };
+            case 403:
+                return {
+                    text: `Access denied for ${toolName}. ` +
+                        'Your API key may not have permission for this endpoint. ' +
+                        `Check your plan at: ${UPGRADE_URL}`,
+                    json: JSON.stringify({
+                        error_code: 'ACCESS_DENIED',
+                        upgrade_url: UPGRADE_URL,
+                    }),
+                };
+            case 404: {
+                const conceptIdMatch = error.path.match(/\/concepts\/(\d+)/);
+                const conceptId = conceptIdMatch ? parseInt(conceptIdMatch[1], 10) : undefined;
+                return {
+                    text: `Not found: ${error.message}. Try using search_concepts to find the correct concept_id, or get_concept_by_code if you have a vocabulary-specific code.`,
+                    json: JSON.stringify({
+                        error_code: 'NOT_FOUND',
+                        path: error.path,
+                        ...(conceptId !== undefined && { concept_id: conceptId }),
+                    }),
+                };
+            }
+            case 429:
+                return {
+                    text: `Rate limit exceeded for ${toolName}. ` +
+                        `Wait a moment and try again, or upgrade your plan at: ${UPGRADE_URL}`,
+                    json: JSON.stringify({
+                        error_code: 'RATE_LIMIT_EXCEEDED',
+                        retry_after_seconds: 3600,
+                        upgrade_url: UPGRADE_URL,
+                    }),
+                };
+            case 500:
+            case 502:
+            case 503:
+                return {
+                    text: `OMOPHub API is temporarily unavailable (${error.status}). Please try again in a moment.`,
+                    json: JSON.stringify({ error_code: 'SERVER_ERROR' }),
+                };
+            default:
+                return {
+                    text: `API error (${error.status}). Please try again or contact support if this persists.`,
+                    json: JSON.stringify({
+                        error_code: 'UNKNOWN_ERROR',
+                        status: error.status,
+                    }),
+                };
+        }
+    }
+    if (error instanceof Error) {
+        if (error.name === 'TimeoutError' || error.message.includes('timed out')) {
+            return {
+                text: `OMOPHub API request timed out for ${toolName}. The server may be slow — please try again.`,
+                json: JSON.stringify({ error_code: 'TIMEOUT_ERROR' }),
+            };
+        }
+        if (error.message.includes('fetch failed') || error.message.includes('ECONNREFUSED')) {
+            return {
+                text: `Cannot connect to OMOPHub API. Check your internet connection and that OMOPHUB_BASE_URL is correct.`,
+                json: JSON.stringify({ error_code: 'CONNECTION_ERROR' }),
+            };
+        }
+        return {
+            text: `${toolName} failed unexpectedly. Please try again.`,
+            json: JSON.stringify({ error_code: 'UNKNOWN_ERROR' }),
+        };
+    }
+    return {
+        text: `${toolName} failed with an unexpected error.`,
+        json: JSON.stringify({ error_code: 'UNKNOWN_ERROR' }),
+    };
+}
+//# sourceMappingURL=errors.js.map

package/dist/utils/errors.js.map

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

package/dist/utils/logger.d.ts

@@ -0,0 +1,18 @@
+type LogLevel = 'debug' | 'info' | 'warn' | 'error';
+interface LogEntry {
+    level: LogLevel;
+    message: string;
+    tool_name?: string;
+    api_path?: string;
+    duration_ms?: number;
+    status?: number;
+    [key: string]: unknown;
+}
+export declare const logger: {
+    debug: (message: string, fields?: Omit<LogEntry, "level" | "message">) => void;
+    info: (message: string, fields?: Omit<LogEntry, "level" | "message">) => void;
+    warn: (message: string, fields?: Omit<LogEntry, "level" | "message">) => void;
+    error: (message: string, fields?: Omit<LogEntry, "level" | "message">) => void;
+};
+export {};
+//# sourceMappingURL=logger.d.ts.map

package/dist/utils/logger.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAAA,KAAK,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,CAAC;AAEpD,UAAU,QAAQ;IAChB,KAAK,EAAE,QAAQ,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,CAAC,GAAG,EAAE,MAAM,GAAG,OAAO,CAAC;CACxB;AAuBD,eAAO,MAAM,MAAM;qBACA,MAAM,WAAW,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;oBAErD,MAAM,WAAW,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;oBAEpD,MAAM,WAAW,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;qBAEnD,MAAM,WAAW,IAAI,CAAC,QAAQ,EAAE,OAAO,GAAG,SAAS,CAAC;CAEtE,CAAC"}

package/dist/utils/logger.js

@@ -0,0 +1,24 @@
+const LOG_LEVELS = {
+    debug: 0,
+    info: 1,
+    warn: 2,
+    error: 3,
+};
+const envLevel = process.env.OMOPHUB_LOG_LEVEL;
+const currentLevel = envLevel && envLevel in LOG_LEVELS ? envLevel : 'info';
+function log(entry) {
+    if (LOG_LEVELS[entry.level] < LOG_LEVELS[currentLevel])
+        return;
+    const timestamp = new Date().toISOString();
+    const { level, message, ...fields } = entry;
+    const extra = Object.keys(fields).length > 0 ? ` ${JSON.stringify(fields)}` : '';
+    // All logs to stderr — stdout is reserved for JSON-RPC in stdio mode
+    process.stderr.write(`[${timestamp}] ${level.toUpperCase()} ${message}${extra}\n`);
+}
+export const logger = {
+    debug: (message, fields) => log({ level: 'debug', message, ...fields }),
+    info: (message, fields) => log({ level: 'info', message, ...fields }),
+    warn: (message, fields) => log({ level: 'warn', message, ...fields }),
+    error: (message, fields) => log({ level: 'error', message, ...fields }),
+};
+//# sourceMappingURL=logger.js.map

package/dist/utils/logger.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"logger.js","sourceRoot":"","sources":["../../src/utils/logger.ts"],"names":[],"mappings":"AAYA,MAAM,UAAU,GAA6B;IAC3C,KAAK,EAAE,CAAC;IACR,IAAI,EAAE,CAAC;IACP,IAAI,EAAE,CAAC;IACP,KAAK,EAAE,CAAC;CACT,CAAC;AAEF,MAAM,QAAQ,GAAG,OAAO,CAAC,GAAG,CAAC,iBAAiB,CAAC;AAC/C,MAAM,YAAY,GAAa,QAAQ,IAAI,QAAQ,IAAI,UAAU,CAAC,CAAC,CAAE,QAAqB,CAAC,CAAC,CAAC,MAAM,CAAC;AAEpG,SAAS,GAAG,CAAC,KAAe;IAC1B,IAAI,UAAU,CAAC,KAAK,CAAC,KAAK,CAAC,GAAG,UAAU,CAAC,YAAY,CAAC;QAAE,OAAO;IAE/D,MAAM,SAAS,GAAG,IAAI,IAAI,EAAE,CAAC,WAAW,EAAE,CAAC;IAC3C,MAAM,EAAE,KAAK,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,GAAG,KAAK,CAAC;IAC5C,MAAM,KAAK,GAAG,MAAM,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC,CAAC,IAAI,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;IAEjF,qEAAqE;IACrE,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,SAAS,KAAK,KAAK,CAAC,WAAW,EAAE,IAAI,OAAO,GAAG,KAAK,IAAI,CAAC,CAAC;AACrF,CAAC;AAED,MAAM,CAAC,MAAM,MAAM,GAAG;IACpB,KAAK,EAAE,CAAC,OAAe,EAAE,MAA4C,EAAE,EAAE,CACvE,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;IAC7C,IAAI,EAAE,CAAC,OAAe,EAAE,MAA4C,EAAE,EAAE,CACtE,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;IAC5C,IAAI,EAAE,CAAC,OAAe,EAAE,MAA4C,EAAE,EAAE,CACtE,GAAG,CAAC,EAAE,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;IAC5C,KAAK,EAAE,CAAC,OAAe,EAAE,MAA4C,EAAE,EAAE,CACvE,GAAG,CAAC,EAAE,KAAK,EAAE,OAAO,EAAE,OAAO,EAAE,GAAG,MAAM,EAAE,CAAC;CAC9C,CAAC"}

package/dist/version.d.ts

@@ -0,0 +1,2 @@
+export declare const VERSION: string;
+//# sourceMappingURL=version.d.ts.map

package/dist/version.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.d.ts","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,OAAO,QAAc,CAAC"}

package/dist/version.js

@@ -0,0 +1,5 @@
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const pkg = require('../package.json');
+export const VERSION = pkg.version;
+//# sourceMappingURL=version.js.map

package/dist/version.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"version.js","sourceRoot":"","sources":["../src/version.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AAE5C,MAAM,OAAO,GAAG,aAAa,CAAC,MAAM,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;AAC/C,MAAM,GAAG,GAAG,OAAO,CAAC,iBAAiB,CAAwB,CAAC;AAE9D,MAAM,CAAC,MAAM,OAAO,GAAG,GAAG,CAAC,OAAO,CAAC"}

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@omophub/omophub-mcp",
+  "version": "1.1.0",
+  "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",
+  "main": "dist/index.js",
+  "bin": {
+    "omophub-mcp": "dist/index.js"
+  },
+  "files": [
+    "dist"
+  ],
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "start:http": "node dist/index.js --transport=http",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "test:coverage": "vitest run --coverage",
+    "lint": "biome check src/ test/",
+    "lint:fix": "biome check --write src/ test/",
+    "typecheck": "tsc --noEmit",
+    "format": "biome format --write src/ test/",
+    "format:check": "biome format --check src/ test/",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "mcp-server",
+    "model-context-protocol",
+    "omop",
+    "ohdsi",
+    "medical-vocabularies",
+    "snomed",
+    "icd10",
+    "rxnorm",
+    "loinc",
+    "healthcare",
+    "clinical-data",
+    "ai-agent",
+    "vocabulary-mapping",
+    "concept-mapping",
+    "athena"
+  ],
+  "author": "OMOPHub",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/OMOPHub/omophub-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/OMOPHub/omophub-mcp/issues"
+  },
+  "homepage": "https://omophub.com",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "zod": "^4.3.6"
+  },
+  "devDependencies": {
+    "@biomejs/biome": "^2.4.4",
+    "@types/node": "^25.0.3",
+    "@vitest/coverage-v8": "^3.2.4",
+    "tsx": "^4.19.0",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  }
+}