ResearchTwin MCP Server

ResearchTwin MCP Server es la capa de acción persistente para ResearchTwin, un agente de proyectos de investigación de largo alcance. Proporciona a un agente alojado en OpenTrek herramientas MCP reales para registrar el trabajo de investigación, conservar el estado del proyecto y los requisitos del asesor, y producir informes de progreso basados en evidencia.

El repositorio está diseñado como una implementación de referencia de calidad competitiva: RAG responde preguntas a partir del material de investigación, mientras que MCP realiza cambios explícitos y auditables en el registro del proyecto.

Todos los ejemplos incluidos son ficticios y anónimos. Los datos operativos pertenecen a runtime_data/ y se excluyen intencionalmente de Git.

Descripción general

Un asistente de investigación debería hacer más que responder una sola pregunta. ResearchTwin mantiene un registro duradero de lo que sucedió en un proyecto en evolución:

• actividades concretas, resultados, bloqueos y próximos pasos;

• la etapa actual del proyecto, tareas, riesgos y decisiones;

• requisitos estructurados del asesor;

• informes semanales, de reuniones o de etapa ensamblados a partir de evidencia persistida.

El servidor está pensado para ser llamado por el Agente ResearchTwin en OpenTrek. No reemplaza al agente, a un LLM ni a la base de conocimiento existente de ResearchTwin_Docs.

Related MCP server: AgentBase

Por qué MCP

RAG y MCP tienen responsabilidades distintas:

Esta separación mantiene el registro del proyecto determinista y revisable. El servidor MCP no necesita ejecutar otro LLM solo para almacenar una actividad estructurada o crear un informe a partir de hechos almacenados.

Arquitectura

flowchart LR
    U[Researcher] --> A[OpenTrek ResearchTwin Agent]
    A -->|retrieve and reason| R[ResearchTwin_Docs RAG]
    R --> K[Research papers and technical material]
    A -->|MCP function calls| M[ResearchTwin MCP Server]
    M --> T[Six research-management tools]
    T --> S[JSON persistence layer]
    S --> D[Runtime research records and reports]

Consulte docs/architecture.md para conocer los límites de los componentes, las reglas de persistencia y los puntos de extensión.

Características

• Integración oficial con el SDK de Python para MCP.

• HTTP transmisible (Streamable HTTP) como transporte MCP principal en /mcp.

• Transporte de compatibilidad SSE por línea de comandos opcional, cuando se selecciona al inicio.

• Seis herramientas enfocadas en lugar de un script de servidor monolítico.

• Persistencia JSON UTF-8 con reemplazo atómico y bloqueo en proceso.

• Identificadores de registro UUID y marcas de tiempo ISO 8601 con zona horaria.

• Respuestas estructuradas de éxito y error adecuadas para el manejo de herramientas del agente.

• Guía de inicio, prueba, prueba de humo e integración con OpenTrek en Windows PowerShell.

Herramientas MCP

El contrato completo de entrada, salida y error está en docs/mcp_tools.md.

Estructura del proyecto

ResearchTwin-MCP-Server/
├── server.py                         # Repository-root launch entry point
├── src/researchtwin_mcp/
│   ├── config.py                     # RESEARCHTWIN_* settings validation
│   ├── server.py                     # MCP server and transport startup
│   ├── models/                       # Validation helpers and schemas
│   ├── storage/                      # Shared JSON persistence layer
│   └── tools/                        # Activity, status, advisor, and report tools
├── scripts/
│   ├── start_server.ps1
│   └── smoke_test.py
├── tests/
├── docs/
├── examples/sample_data/             # Fictional, commit-safe demo data
└── runtime_data/                     # Local operational data; ignored by Git

Requisitos

• Windows PowerShell (el flujo de trabajo documentado)

• Python 3.11 o superior; Python 3.11.x es el entorno recomendado para la competencia

• Acceso a red solo cuando OpenTrek se ejecuta desde otro dispositivo en la LAN

Instalación

Desde una nueva sesión de Windows PowerShell:

Set-Location C:\work\OpenTrek\ResearchTwin-MCP-Server
python --version
where.exe python

python -m venv .venv
.\.venv\Scripts\Activate.ps1

python --version
where.exe python
python -m pip install --upgrade pip setuptools wheel
python -m pip install -e ".[dev]"

El primer resultado de where.exe python debe ser el intérprete del entorno virtual después de la activación. Si PowerShell bloquea la activación para la sesión actual, use su procedimiento documentado de política de ejecución limitada al proceso y luego active el entorno nuevamente; no debilite la política del sistema innecesariamente.

Configuración

El servidor lee estas variables de entorno del entorno del proceso:

.env.example es solo una referencia/plantilla; el servidor no carga automáticamente un archivo .env. Establezca los valores en la sesión de PowerShell, o use un cargador de entorno externo si su implementación ya tiene uno:

$env:RESEARCHTWIN_HOST = "0.0.0.0"
$env:RESEARCHTWIN_PORT = "8000"
$env:RESEARCHTWIN_DATA_DIR = "runtime_data"
$env:RESEARCHTWIN_LOG_LEVEL = "INFO"

No ponga claves, identificadores personales ni una dirección IP específica de usuario en el código fuente o en la configuración confirmada.

Ejecución

Con el entorno virtual activo:

python server.py

El punto final principal predeterminado es:

http://<LAN_IPV4>:8000/mcp

Para la máquina local únicamente, sustituya 127.0.0.1 por <LAN_IPV4>. Para OpenTrek en otro dispositivo LAN de confianza, use la dirección IPv4 aplicable del host de Windows. El script auxiliar también está disponible:

.\scripts\start_server.ps1

HTTP transmisible es el modo normal. Para compatibilidad SSE explícita, ejecute python server.py --transport sse y registre el punto final /sse resultante como se documenta en Guía de integración con OpenTrek. SSE es un modo de transporte seleccionado por separado, no una URL alternativa para registrar junto a /mcp.

Pruebas

Ejecute las pruebas unitarias desde la raíz del repositorio:

pytest -v

Ejecute la prueba de humo local de MCP Streamable HTTP después de instalar las dependencias:

python scripts\smoke_test.py

La prueba de humo verifica la conectividad real del protocolo, el descubrimiento de herramientas y un ciclo de ida y vuelta de registro/listado de actividades. Utiliza datos temporales aislados en lugar de su directorio runtime_data/.

Integración con OpenTrek

El registro en OpenTrek debe usar la opción STREAMABLE de la interfaz y esta forma de URL:

http://<LAN_IPV4>:8000/mcp

No invente manualmente un valor JSON de transportType. Seleccione STREAMABLE en la página de registro MCP de OpenTrek, ingrese la URL, guarde y verifique que se descubran las seis herramientas. Consulte docs/open_trek_integration.md para el descubrimiento de IPv4 en LAN, compatibilidad SSE, comprobaciones de VPN y un proceso seguro de solución de problemas de firewall.

Escenario de demostración

Una demostración de extremo a extremo puede mostrar la diferencia entre la recuperación de conocimiento y la acción persistente:

1. El agente usa RAG para explicar un artículo ficticio de RNN-PPO o una nota de métodos.

2. El investigador dice que se completó un experimento de RNN-PPO pero el entrenamiento sigue siendo inestable.

3. El agente llama a record_research_activity con el resultado, el problema y el siguiente paso.

4. Se registra un requisito ficticio del asesor para centrarse en la generalización con record_advisor_instruction.

5. El agente verifica el estado del proyecto y luego llama a generate_research_report para una reunión de grupo.

El informe Markdown resultante se basa en registros persistidos, no en una respuesta de un solo turno. Hay un runbook narrado en docs/demo_flow.md.

Privacidad y seguridad de Git

El .gitignore del repositorio excluye .venv/, pycache/, bytecode de Python, .env, cachés de pytest y Ruff, runtime_data/ y archivos de registro. Estas rutas pueden contener actividad de investigación local, contexto del asesor, informes, credenciales o datos específicos de la máquina.

Solo los accesorios ficticios y anónimos en examples/sample_data/ son seguros para confirmar. Antes de cualquier confirmación o push, inspeccione:

git status
git diff --check

Nunca confirme mensajes reales de asesores, contenido real de artículos, transcripciones de chat, claves, detalles de VPN o información de identificación personal.

Hoja de ruta

• Migrar de archivos JSON a un backend de almacenamiento multiusuario duradero cuando sea necesario.

• Agregar puntos de integración con ResearchTwin Memory y ResearchTwin_Core.

• Agregar flujos de trabajo de inteligencia de artículos y citas alrededor de la capa RAG existente.

• Agregar un panel protegido para revisar el historial del proyecto y los informes.

• Mejorar la historia de demostración de la competencia sin exponer datos de investigación reales.

Documentación

• Arquitectura

• Referencia de herramientas MCP

• Integración con OpenTrek

• Flujo de demostración

• Datos de muestra ficticios