Ensayo clínico de mutación que coincide con MCP

Un servidor de Protocolo de Contexto Modelo (MCP) que permite a Claude Desktop buscar coincidencias en clincialtrials.gov según mutaciones.

Estado

Esta es actualmente la primera fase de desarrollo. Funciona para recuperar ensayos basados en mutaciones dadas en la consulta Claude. Sin embargo, aún existen errores y se deben implementar mejoras y adiciones.

Descripción general

Este proyecto sigue los principios de codificación Agentic para crear un sistema que integra Claude Desktop con la API de clinicaltrials.gov. El servidor permite realizar consultas en lenguaje natural sobre mutaciones genéticas y devuelve información resumida sobre ensayos clínicos relevantes.

Cada nodo del flujo sigue el patrón de nodo PocketFlow con los métodos prep , exec y post :

Estructura del proyecto

Este proyecto está organizado según el paradigma de codificación agentica:

Requisitos (dirigidos por humanos):
- Buscar y resumir ensayos clínicos relacionados con mutaciones genéticas específicas
- Proporcionar información sobre mutaciones como recursos contextuales
- Se integra perfectamente con Claude Desktop
Diseño de flujo (colaborativo):
- El usuario consulta a Claude Desktop sobre una mutación genética
- Claude llama a nuestra herramienta de servidor MCP
- El servidor consulta la API de clinicaltrials.gov
- El servidor procesa y resume los resultados
- El servidor devuelve resultados formateados a Claude
Utilidades (Colaborativas):
- clinicaltrials/query.py : gestiona las llamadas API a clinicaltrials.gov
- utils/call_llm.py : Utilidades para trabajar con Claude
Diseño de nodos (liderado por IA):
- utils/node.py : Implementa las clases base Node y BatchNode con el patrón prep/exec/post
- clinicaltrials/nodes.py : Define nodos especializados para realizar consultas y resumir
- clinicaltrials_mcp_server.py : orquesta la ejecución del flujo
Implementación (liderada por IA):
- SDK FastMCP para gestionar los detalles del protocolo
- Manejo de errores en todos los niveles
- Recursos para mutaciones comunes

Componentes

Servidor MCP ( `clinicaltrials_mcp_server.py` )

El servidor principal que implementa la interfaz del Protocolo de Contexto de Modelo, utilizando el SDK oficial de Python.

Registra y expone herramientas para que Claude las utilice
Proporciona recursos con información sobre mutaciones comunes.
Maneja la comunicación con Claude Desktop

Módulo de consulta ( `clinicaltrials/query.py` )

Responsable de consultar la API de clinicaltrials.gov con:

Manejo robusto de errores
Validación de entrada
Registro detallado

Resumidor ( `llm/summarize.py` )

Procesa y formatea los datos de ensayos clínicos:

Organiza los ensayos por fase
Extrae información clave (ID NCT, resumen, condiciones, etc.)
Crea un resumen de rebajas legible

Implementación del patrón de nodo

Este proyecto implementa el patrón PocketFlow Node, que proporciona un enfoque modular y mantenible para crear flujos de trabajo de IA:

Clases de nodo principales ( `utils/node.py` )

Nodo : clase base con métodos prep , exec y post para procesar datos
BatchNode : Extensión para el procesamiento por lotes de varios artículos
Flujo : orquesta la ejecución de nodos en secuencia

Nodos de implementación ( `clinicaltrials/nodes.py` )

ConsultaTrialsNode :
# Queries clinicaltrials.gov API def prep(self, shared): return shared["mutation"] def exec(self, mutation): return query_clinical_trials(mutation) def post(self, shared, mutation, result): shared["trials_data"] = result shared["studies"] = result.get("studies", []) return "summarize"
NodoResumirEnsayos :
# Formats trial data into readable summaries def prep(self, shared): return shared["studies"] def exec(self, studies): return format_trial_summary(studies) def post(self, shared, studies, summary): shared["summary"] = summary return None # End of flow

Ejecución de flujo

El servidor MCP crea y ejecuta el flujo:

# Create nodes
query_node = QueryTrialsNode()
summarize_node = SummarizeTrialsNode()

# Create flow
flow = Flow(start=query_node)
flow.add_node("summarize", summarize_node)

# Run flow with shared context
shared = {"mutation": mutation}
result = flow.run(shared)

Este patrón separa la preparación, la ejecución y el posprocesamiento, lo que facilita el mantenimiento y la comprobación del código. Para más detalles, consulte el documento de diseño .

Uso

Instalar dependencias con uv:
uv pip install -r requirements.txt
Configurar Claude Desktop:
- La configuración en ~/Library/Application Support/Claude/claude_desktop_config.json ya debería estar configurada
Inicie Claude Desktop y haga preguntas como:
- "¿Qué ensayos clínicos están disponibles para las mutaciones del EGFR L858R?"
- "¿Existen ensayos para las mutaciones BRAF V600E?"
- "Háblame de los ensayos para reordenamientos de ALK"
Utilice los recursos preguntando:
- "¿Puede contarme más sobre la mutación KRAS G12C?"

Integración con Claude Desktop

Puede configurar este proyecto como una herramienta MCP de Claude Desktop. Use marcadores de ruta en su configuración y sustitúyalos por sus rutas reales:

"mutation-clinical-trials-mcp": {
  "command": "{PATH_TO_VENV}/bin/python",
  "args": [
    "{PATH_TO_PROJECT}/clinicaltrials_mcp_server.py"
  ],
  "description": "Matches genetic mutations to relevant clinical trials and provides summaries."
}

Variables de ruta:

{PATH_TO_VENV} : Ruta completa a su directorio de entorno virtual.
{PATH_TO_PROJECT} : Ruta completa al directorio que contiene los archivos de su proyecto.

Instrucciones de instalación:

Clona el repositorio en tu máquina local.
Instala uv si aún no lo tienes:
curl -LsSf https://astral.sh/uv/install.sh | sh # macOS/Linux # or iwr -useb https://astral.sh/uv/install.ps1 | iex # Windows PowerShell
Cree un entorno virtual e instale dependencias en un solo paso:
uv venv .venv uv pip install -r requirements.txt
Activar el entorno virtual cuando sea necesario:
source .venv/bin/activate # macOS/Linux .venv\Scripts\activate # Windows
Determinar la ruta completa a su entorno virtual y al directorio del proyecto.
Actualice su configuración con estas rutas específicas.

Ejemplos:

En macOS/Linux:
"command": "/Users/username/projects/mutation_trial_matcher/.venv/bin/python"
En Windows:
"command": "C:\\Users\\username\\projects\\mutation_trial_matcher\\.venv\\Scripts\\python.exe"

Consejos para encontrar el camino:

Para encontrar la ruta exacta a su intérprete de Python en el entorno virtual, ejecute:
- which python (MacOS/Linux)?
- where python (Windows, después de activar el venv)
Para la ruta del proyecto, utilice la ruta completa al directorio que contiene clinicaltrials_mcp_server.py .

Mejoras futuras

Para obtener una lista completa de las mejoras planificadas y el trabajo futuro, consulte el documento future_work.md .

Dependencias

Este proyecto se basa en las siguientes dependencias clave:

Python 3.7+ - Entorno de ejecución base
PocketFlow ( pocketflow>=0.0.1 ): marco para crear flujos de trabajo de IA modulares con el patrón Node
SDK de MCP ( mcp[cli]>=1.0.0 ): SDK oficial del protocolo de contexto de modelo para crear herramientas de Claude Desktop
Solicitudes ( requests==2.31.0 ): biblioteca HTTP para realizar llamadas API a clinicaltrials.gov
Python-dotenv ( python-dotenv==1.1.0 ): para cargar variables de entorno desde archivos .env

Todas las dependencias se pueden instalar usando uv como se describe en las instrucciones de instalación.

Solución de problemas

Si Claude Desktop se desconecta del servidor MCP:

Consulte los registros en: ~/Library/Logs/Claude/mcp-server-clinicaltrials-mcp.log
Reiniciar Claude Desktop
Verifique que el servidor esté funcionando correctamente

Proceso de desarrollo

Este proyecto se desarrolló utilizando un enfoque de codificación asistida por IA, siguiendo los principios de la Codificación Agenética, donde las personas diseñan y los agentes de IA implementan. El programa original en la plataforma principal se creó el 30/04/2025. La implementación se creó mediante programación en pareja con:

Windsurf
- ChatGPT 4.1
- Soneto Claude 3.7

Estos asistentes de IA fueron fundamentales para traducir los requisitos de diseño de alto nivel en código funcional, ayudar con la integración de API y estructurar el proyecto de acuerdo con las mejores prácticas.

Manejo del límite de caracteres `.windsurfrules`

El archivo .windsurfrules de PocketFlow del repositorio de plantillas contiene reglas completas del proyecto, pero Windsurf impone un límite de 6000 caracteres en los archivos de reglas. Esto significa que no puede incluir el conjunto completo de directrices directamente en su proyecto, y es posible que se omitan o trunquen reglas importantes.

Para abordar esto, hay dos soluciones recomendadas:

1. Uso de Windsurf 🪁 Memoria para almacenar reglas

Puede aprovechar la función de memoria de Windsurf para almacenar el conjunto completo de reglas de PocketFlow, incluso si superan el límite del archivo .windsurfrules . Este enfoque le permite consultar todas las convenciones y mejores prácticas del proyecto en la comunicación con Windsurf, garantizando así que no se pierda nada por truncamiento. Para obtener instrucciones paso a paso y una comparación detallada de los archivos de memoria y de reglas, consulte docs/memory_vs_windsurfrules.md .

2. Uso de Context7 para acceder a las pautas

Nota importante : Este proyecto se basa en el repositorio PocketFlow-Template-Python , que incluye un completo archivo .windsurfrules . Sin embargo, Windsurf tiene un límite de 6000 caracteres para los archivos de reglas, lo que significa que las directrices completas de PocketFlow no se pueden cargar completamente en la memoria de Windsurf.

Para solucionar esta limitación, hemos creado instrucciones detalladas sobre el uso del servidor MCP de Context7 para acceder a las directrices de PocketFlow durante el desarrollo. Este enfoque permite aprovechar al máximo los patrones de diseño y las mejores prácticas de PocketFlow sin verse limitado por el límite de caracteres.

Para obtener instrucciones completas sobre el uso de Context7 con PocketFlow, consulte nuestra Guía de Context7 . Esta guía incluye:

Instrucciones paso a paso para configurar Context7 MCP en Windsurf
Indicaciones en lenguaje natural para acceder a la documentación de PocketFlow
Ejemplos de recuperación de patrones de implementación específicos
Cómo guardar patrones importantes como recuerdos para futuras referencias

Si sigue esta guía, podrá mantener la alineación con los principios de codificación Agentic de PocketFlow mientras desarrolla y amplía este proyecto.

Expresiones de gratitud

Este proyecto se desarrolló utilizando la plantilla PocketFlow-Template-Python como punto de partida. Agradecemos especialmente a los colaboradores originales del proyecto por proporcionar la base y la estructura que hicieron posible esta implementación.

El proyecto sigue la metodología de codificación Agentic tal como se describe en la plantilla original.

Este proyecto está licenciado bajo la licencia MIT: consulte el archivo de LICENCIA para obtener más detalles.

Mutation Clinical Trial Matching MCP