OpenGenes

opengenes-mcp

Servidor MCP (Model Context Protocol) para la base de datos OpenGenes

Este servidor implementa el Model Context Protocol (MCP) para OpenGenes, proporcionando una interfaz estandarizada para acceder a datos de investigación sobre envejecimiento y longevidad. MCP permite que asistentes de IA y agentes consulten conjuntos de datos biomédicos completos a través de interfaces estructuradas.

El servidor descarga automáticamente la base de datos y documentación más reciente de OpenGenes desde Hugging Face Hub (específicamente desde la carpeta opengenes), asegurando que siempre tengas acceso a los datos más actualizados sin gestión manual de archivos.

La base de datos de OpenGenes contiene:

• lifespan_change: Datos experimentales sobre intervenciones genéticas y sus efectos en la longevidad en organismos modelo
• gene_criteria: Clasificaciones de criterios para genes relacionados con el envejecimiento (12 categorías diferentes)
• gene_hallmarks: Marcadores del envejecimiento asociados con genes específicos
• longevity_associations: Variantes genéticas asociadas con la longevidad de estudios poblacionales

Si deseas comprender mejor qué es el Model Context Protocol y cómo usarlo de manera más eficiente, puedes tomar el Curso de DeepLearning AI o buscar videos sobre MCP en YouTube.

🏆 Parte del Framework Holy Bio MCP

Este servidor MCP es parte del proyecto Holy Bio MCP - un framework unificado para investigación bioinformática que ganó el Bio x AI Hackathon 2025 y continúa siendo desarrollado y extendido activamente después de la victoria.

El framework Holy Bio MCP reúne múltiples servidores MCP especializados en un ecosistema cohesivo para investigación biológica avanzada:

• gget-mcp - Kit de herramientas de genómica y análisis de secuencias
• opengenes-mcp - Genética del envejecimiento y longevidad (este servidor)
• synergy-age-mcp - Interacciones genéticas sinérgicas en longevidad
• biothings-mcp - Datos biológicos fundamentales de BioThings.io
• pharmacology-mcp - Datos de fármacos, dianas y ligandos

En conjunto, estos servidores proporcionan más de 50 funciones bioinformáticas especializadas que pueden trabajar de manera integrada en flujos de investigación impulsados por IA. Aprende más sobre el framework completo en github.com/longevity-genie/holy-bio-mcp.

Ejemplo de Uso

Así es como el servidor MCP de OpenGenes funciona en la práctica con asistentes de IA:

Ejemplo que muestra cómo consultar la base de datos de OpenGenes a través de un asistente de IA usando lenguaje natural, que se traduce a consultas SQL mediante el servidor MCP. Puedes usar esta base de datos tanto en interfaces de chat para preguntas de investigación como en herramientas de desarrollo basadas en IA (como Cursor, Windsurf, VS Code con Copilot) para mejorar significativamente tu productividad en bioinformática al tener acceso directo a datos de investigación sobre envejecimiento y longevidad mientras programas.

Acerca de MCP (Model Context Protocol)

MCP es un protocolo que une la brecha entre los sistemas de IA y el conocimiento especializado de dominio. Permite:

• Acceso Estructurado: Conexión directa a datos autorizados de investigación sobre envejecimiento y longevidad
• Consultas en Lenguaje Natural: Interacción simplificada con bases de datos especializadas mediante SQL
• Seguridad de Tipos: Tipado fuerte y validación a través de FastMCP
• Integración con IA: Integración perfecta con asistentes y agentes de IA

Fuente de Datos y Actualizaciones

El servidor MCP de OpenGenes descarga automáticamente datos del repositorio longevity-genie/bio-mcp-data en Hugging Face Hub. Esto asegura:

• Siempre Actualizado: Acceso automático a la base de datos más reciente de OpenGenes sin actualizaciones manuales
• Distribución Confiable: Alojamiento centralizado de datos con control de versiones y seguimiento de cambios
• Caché Eficiente: Los archivos descargados se almacenan en caché localmente para minimizar solicitudes de red
• Soporte de Respaldo: Se admiten archivos de respaldo locales para desarrollo y uso sin conexión

Los archivos de datos se almacenan en la subcarpeta opengenes del repositorio de Hugging Face e incluyen:

• open_genes.sqlite - La base de datos completa de OpenGenes
• prompt.txt - Documentación del esquema de la base de datos y pautas de uso

Herramientas Disponibles

Este servidor proporciona tres herramientas principales para interactuar con la base de datos de OpenGenes:

1. opengenes_db_query(sql: str) - Ejecutar consultas SQL de solo lectura contra la base de datos de OpenGenes
2. opengenes_get_schema_info() - Obtener información detallada del esquema, incluyendo tablas, columnas y enumeraciones
3. opengenes_example_queries() - Obtener una lista de consultas SQL de ejemplo con descripciones

Recursos Disponibles

1. resource://db-prompt - Documentación completa del esquema de la base de datos y pautas de uso
2. resource://schema-summary - Resumen formateado de las tablas y sus propósitos

Inicio Rápido

Instalación de uv

# Download and install uv
curl -LsSf https://astral.sh/uv/install.sh | sh

# Verify installation
uv --version
uvx --version

uvx es una herramienta muy útil que puede ejecutar un paquete de Python instalándolo si es necesario.

Ejecución con uvx

Puedes ejecutar el servidor opengenes-mcp directamente usando uvx sin clonar el repositorio:

# Run the server in streamed http mode (default)
uvx opengenes-mcp

# Or explicitly specify stdio mode
uvx opengenes-mcp stdio

# Run the server in streamable HTTP mode on default (3001) port
uvx opengenes-mcp server

# Run on a specific port
uvx opengenes-mcp server --port 8000

# Run the server in SSE mode
uvx opengenes-mcp sse

En casos donde hay problemas con uvx, a menudo pueden ser causados por limpiar la caché de uv:

uv cache clean

El modo HTTP iniciará un servidor web al que puedes acceder en http://localhost:3001/mcp (con documentación en http://localhost:3001/docs). El modo STDIO está diseñado para clientes MCP que se comunican mediante entrada/salida estándar, mientras que el modo SSE utiliza Server-Sent Events para comunicación en tiempo real.

Nota: Actualmente, no tenemos una interfaz Swagger/OpenAPI, por lo que acceder al servidor directamente en tu navegador no mostrará mucha información útil. Para explorar las herramientas y capacidades disponibles, debes usar el MCP Inspector (ver más abajo) o conectarte a través de un cliente MCP para ver las herramientas disponibles.

Configuración de tu Cliente de IA (Anthropic Claude Desktop, Cursor, Windsurf, etc.)

Ejemplo de Configuración Rápida

Esto es lo que puedes copiar directamente en tu configuración MCP de Claude Desktop o Cursor:

{
  "mcpServers": {
    "opengenes-mcp": {
      "command": "uvx",
      "args": ["opengenes-mcp"],
      "env": {
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}

Alternativa: Uso de Archivos Preconfigurados

También proporcionamos archivos JSON preconfigurados para diferentes casos de uso:

• Para modo STDIO (recomendado): Usa mcp-config-stdio.json
• Para modo HTTP: Usa mcp-config.json
• Para desarrollo local: Usa mcp-config-stdio-debug.json

Tutorial en Video de Configuración

Para una guía visual sobre cómo configurar servidores MCP con clientes de IA, consulta nuestro video tutorial de configuración para nuestro servidor MCP hermano (biothings-mcp). Los principios de configuración son exactamente los mismos para el servidor MCP de OpenGenes: solo usa los archivos de configuración JSON apropiados proporcionados arriba.

Inspección del servidor MCP de OpenGenes

npx @modelcontextprotocol/inspector --config mcp-config-stdio.json --server opengenes-mcp

npx @modelcontextprotocol/inspector --config mcp-config.json --server opengenes-mcp

npx @modelcontextprotocol/inspector --config mcp-config-stdio-debug.json --server opengenes-mcp

npx @modelcontextprotocol/inspector

Integración con Sistemas de IA

Simplemente apunta tu cliente de IA (como Cursor, Windsurf, ClaudeDesktop, VS Code con Copilot, u otros) para usar el archivo de configuración apropiado del repositorio.

Configuración del Repositorio

# Clone the repository
git clone https://github.com/longevity-genie/opengenes-mcp.git
cd opengenes-mcp
uv sync

Ejecución del Servidor MCP

Si ya clonaste el repositorio, puedes ejecutar el servidor con uv:

# Start the MCP server locally (HTTP mode)
uv run server

# Or start in STDIO mode  
uv run stdio

# Or start in SSE mode
uv run sse

Esquema de la Base de Datos

Consultas de Ejemplo

-- Get top genes with most lifespan experiments
SELECT HGNC, COUNT(*) as experiment_count 
FROM lifespan_change 
WHERE HGNC IS NOT NULL 
GROUP BY HGNC 
ORDER BY experiment_count DESC 
LIMIT 10;

-- Find genes that increase lifespan in mice
SELECT DISTINCT HGNC, effect_on_lifespan 
FROM lifespan_change 
WHERE model_organism = 'mouse' 
AND effect_on_lifespan = 'increases lifespan' 
AND HGNC IS NOT NULL;

-- Get hallmarks of aging for genes
SELECT HGNC, "hallmarks of aging" 
FROM gene_hallmarks 
WHERE "hallmarks of aging" LIKE '%mitochondrial%';

-- Find longevity associations by ethnicity
SELECT HGNC, "polymorphism type", "nucleotide substitution", ethnicity 
FROM longevity_associations 
WHERE ethnicity LIKE '%Italian%';

-- Find genes with both lifespan effects and longevity associations
SELECT DISTINCT lc.HGNC 
FROM lifespan_change lc 
INNER JOIN longevity_associations la ON lc.HGNC = la.HGNC 
WHERE lc.HGNC IS NOT NULL;

Características de Seguridad

• Acceso de solo lectura: Solo se permiten consultas SELECT
• Validación de entrada: Bloquea operaciones INSERT, UPDATE, DELETE, DROP, CREATE, ALTER, TRUNCATE
• Manejo de errores: Manejo integral de errores con mensajes informativos

Pruebas y Verificación

El servidor MCP se proporciona con pruebas integrales, incluidas pruebas LLM-como-juez que evalúan la calidad de las respuestas a consultas complejas. Sin embargo, las pruebas basadas en LLM están deshabilitadas por defecto en CI para ahorrar costos.

Configuración del Entorno para Pruebas de Agente LLM

Si deseas ejecutar pruebas de agente LLM que usan funciones MCP con modelos Gemini, necesitas configurar un archivo .env con tu clave API de Gemini:

# Create a .env file in the project root
echo "GEMINI_API_KEY=your-gemini-api-key-here" > .env

Nota: El archivo .env y la clave API de Gemini solo son necesarios para ejecutar pruebas de agente LLM. Todas las demás pruebas y la funcionalidad básica del servidor MCP funcionan sin claves API.

Ejecución de Pruebas

Ejecuta pruebas para el servidor MCP:

uv run pytest -vvv -s

También puedes ejecutar pruebas manuales:

uv run python test/manual_test_questions.py

Puedes usar el inspector MCP con el servidor MCP compilado localmente de la misma manera que con uvx.

Nota: El uso del MCP Inspector es opcional. La mayoría de los clientes MCP (como Cursor, Windsurf, etc.) mostrarán automáticamente las herramientas disponibles de este servidor una vez configurado. Sin embargo, el Inspector puede ser útil para pruebas detalladas y exploración.

Si eliges usar el Inspector a través de npx, asegúrate de tener Node.js y npm instalados. Se recomienda usar nvm (Node Version Manager) para gestionar las versiones de Node.js.

Preguntas de ejemplo que MCP ayuda a responder

Contribuciones

¡Agradecemos las contribuciones de la comunidad! 🎉 Ya sea que seas investigador, desarrollador o entusiasta interesado en la investigación sobre envejecimiento y longevidad, hay muchas formas de participar:

¡Especialmente te animamos a probar nuestro servidor MCP y compartir tus comentarios con nosotros! Tu experiencia usando el servidor, cualquier problema que encuentres y sugerencias de mejora son increíblemente valiosas para mejorar esta herramienta para toda la comunidad investigadora.

Formas de Contribuir

• 🐛 Informes de errores: ¿Encontraste un problema? Abre un issue en GitHub con información detallada
• 💡 Solicitudes de funciones: ¿Tienes ideas para nuevas funcionalidades? ¡Nos encantaría escucharlas!
• 📝 Documentación: Ayuda a mejorar nuestra documentación, ejemplos o tutoriales
• 🧪 Pruebas: Agrega casos de prueba, especialmente para casos límite o nuevos patrones de consulta
• 🔍 Calidad de datos: Ayuda a identificar e informar inconsistencias de datos o sugerir mejoras
• 🚀 Rendimiento: Optimiza consultas, mejora el almacenamiento en caché o mejora el rendimiento del servidor
• 🌐 Integración: Crea ejemplos para nuevos clientes MCP o sistemas de IA
• 🎥 Tutoriales y videos: Crea tutoriales, guías en video o contenido educativo que muestre cómo usar los servidores MCP
• 📖 Historias de usuarios: Comparte tus flujos de trabajo de investigación e historias de éxito usando nuestros servidores MCP
• 🤝 Alcance comunitario: Ayúdanos a promover la adopción de MCP en la comunidad bioinformática

¡Los tutoriales, videos e historias de usuarios son especialmente valiosos para nosotros! Estamos trabajando para impulsar a la comunidad bioinformática hacia la adopción de IA, y ejemplos del mundo real de cómo los investigadores usan nuestros servidores MCP (este y otros que desarrollamos) ayudan a demostrar los beneficios prácticos y fomentar una adopción más amplia.

Cómo Empezar

1. Haz un fork del repositorio
2. Crea una rama de características (git checkout -b feature/amazing-feature)
3. Haz tus cambios y agrega pruebas
4. Ejecuta el conjunto de pruebas (uv run pytest)
5. Haz commit de tus cambios (git commit -m 'Add amazing feature')
6. Haz push a tu rama (git push origin feature/amazing-feature)
7. Abre un Pull Request

Pautas de Desarrollo

• Sigue el estilo de código existente (usamos black para el formato)
• Agrega pruebas para nuevas funcionalidades
• Actualiza la documentación según sea necesario
• Mantén los commits enfocados y escribe mensajes de commit claros

¿Preguntas o Ideas?

¡No dudes en abrir un issue para discutir! Somos amigables y siempre estamos felices de ayudar a los nuevos a comenzar. Tus contribuciones ayudan a avanzar la ciencia abierta y la investigación sobre longevidad para todos. 🧬✨

Problemas Conocidos

Cobertura de la Base de Datos

Actualmente, este servidor MCP usa solo un subconjunto de la base de datos completa de OpenGenes. La base de datos completa de OpenGenes contiene tablas y datos adicionales que aún no están incluidos en nuestra implementación MCP. ¡Necesitamos contribuyentes para ayudar a extender el soporte para la base de datos completa! Si estás interesado en ayudar a expandir la cobertura de la base de datos, consulta nuestra sección Contribuciones.

Cobertura de Pruebas

Aunque proporcionamos pruebas integrales que incluyen evaluaciones de LLM-como-juez, no todos los casos de prueba han sido verificados manualmente contra la interfaz web real de OpenGenes. Algunos resultados de pruebas automatizadas pueden necesitar validación manual para garantizar precisión. Las contribuciones para mejorar la cobertura y validación de pruebas son bienvenidas.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Agradecimientos

• Base de Datos OpenGenes por los datos integrales de investigación sobre envejecimiento
  • Rafikova E, Nemirovich-Danchenko N, Ogmen A, Parfenenkova A, Velikanova A, Tikhonov S, Peshkin L, Rafikov K, Spiridonova O, Belova Y, Glinin T, Egorova A, Batin M. Open Genes-a new comprehensive database of human genes associated with aging and longevity. Nucleic Acids Res. 2024 Jan 5;52(D1):D950-D962. doi: 10.1093/nar/gkad712. PMID: 37665017; PMCID: PMC10768108.
• Model Context Protocol por la especificación del protocolo
• FastMCP por el marco del servidor MCP

Este proyecto es parte de la organización Longevity Genie, que desarrolla asistentes de IA y bibliotecas de código abierto para la investigación en salud, genética y longevidad.

Otros Servidores MCP en el Marco Holy Bio MCP

Este servidor es parte del marco completo Holy Bio MCP, que incluye:

• gget-mcp - Kit de herramientas bioinformáticas potente para consultas y análisis genómicos
• synergy-age-mcp - Base de datos de interacciones genéticas sinérgicas y antagónicas en longevidad
• biothings-mcp - Acceso a las API de BioThings.io para datos integrales de genes, variantes, químicos y taxonómicos
• pharmacology-mcp - Acceso a la base de datos Guide to PHARMACOLOGY para información sobre fármacos, dianas y ligandos

El marco proporciona archivos de configuración unificados que habilitan todos los servidores a la vez, facilitando el acceso a más de 50 funciones bioinformáticas especializadas a través de una sola configuración. Este proyecto galardonado continúa evolucionando como una plataforma integral para la investigación biológica impulsada por IA.

Contamos con el apoyo de:

HEALES - Sociedad para la Extensión de la Vida Saludable

y

IBIMA - Instituto de Bioestadística e Informática en Medicina e Investigación del Envejecimiento