HED MCP Server

Un servidor MCP para Descriptores Jerárquicos de Eventos (HED) que automatiza la creación de sidecars y la anotación de archivos de eventos BIDS utilizando LLMs.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor HED MCP TypeScript

Introducción

Un servidor de Protocolo de Contexto de Modelo (MCP) para validar datos HED (Descriptor Jerárquico de Eventos). Este servidor proporciona herramientas integrales de validación HED a través de la interfaz MCP estandarizada, haciendo que la validación HED sea accesible para cualquier cliente compatible con MCP.

¿Qué es HED?

HED (Descriptor Jerárquico de Eventos) es:

Un vocabulario estandarizado para describir eventos experimentales
Un sistema jerárquico que permite la anotación precisa de eventos
Ampliamente utilizado en conjuntos de datos BIDS (Estructura de Datos de Imágenes Cerebrales)
Esencial para la investigación en neurociencia reproducible

¿Qué es MCP?

El Protocolo de Contexto de Modelo (MCP) es:

Un protocolo estandarizado para compartir herramientas y recursos
Permite que asistentes de IA y aplicaciones accedan a capacidades externas
Proporciona una interfaz consistente entre diferentes implementaciones
Facilita la integración entre diversos sistemas de software

Características

Validación de cadenas HED: Valida cadenas de etiquetas HED individuales contra especificaciones de esquema
Validación de archivos TSV: Valida archivos TSV BIDS completos que contienen anotaciones HED
Validación de sidecar JSON: Analiza y valida archivos JSON sidecar HED
Acceso al sistema de archivos: Lee archivos desde rutas del sistema de archivos local
Soporte multi-esquema: Soporte para esquemas HED estándar y esquemas de biblioteca
Procesamiento de definiciones: Maneja definiciones HED para una validación mejorada
Detección de advertencias: Detección opcional de advertencias además del informe de errores
Caché de esquemas: Sistema de caché inteligente para un rendimiento óptimo
Múltiples interfaces: Servidor MCP (stdio/WebSocket) + API REST HTTP
Compatibilidad con navegadores: Soporte completo de navegador con múltiples opciones de integración

Tabla de contenidos

Entendiendo HED
Instalación
Inicio Rápido
Arquitectura del Servidor
Herramientas Disponibles
Ejemplos de Uso
Trabajando con Datos HED
Uso en Navegador
Configuración
Características Avanzadas
Optimización del Rendimiento
Guía de Integración
Desarrollo
Solución de Problemas
Pruebas
Contribuciones
Licencia

Entendiendo HED

Conceptos Básicos de HED

HED utiliza una estructura de etiquetas jerárquica donde las etiquetas se organizan de lo general a lo específico:

Event                 # General event type
Event/Sensory-event   # More specific
Sensory-event         # Same as Event/Sensory-event

La estructura jerárquica se utiliza para la generalidad de búsqueda -- permitiendo que una búsqueda de Event capture Event/Sensory-event así como Sensory-event.

Nota: Todas las etiquetas en el vocabulario HED son únicas. Se recomienda anotar usando solo la etiqueta, no la ruta completa.

Estructura de Etiquetas

Notación de ruta: Las etiquetas usan barras diagonales para indicar jerarquía
Agrupación: Los paréntesis agrupan etiquetas relacionadas: (Red, Large)
Definiciones: Se pueden usar definiciones personalizadas para conceptos complejos
Extensión: Se pueden agregar subetiquetas personalizadas para especialización

Patrones Comunes de HED

Descripción básica de eventos

Sensory-event, Red

Etiquetas Agrupadas

Sensory-event, (Red, Square)

Usando Definiciones

Puede crear definiciones para representar cadenas de etiquetas que usa con frecuencia:

(Definition/BlueSquare, ((Background-view, Black), ((Blue, Square), (Center-of, Computer-Screen))))

La anotación:

Def/BlueSquare

puede aparecer en cualquier lugar donde lo haría una etiqueta HED normal. Las herramientas pueden sustituir la anotación completa cuando sea necesario.

Versiones de Esquema

Los esquemas HED evolucionan con el tiempo. Use la versión más reciente siempre que sea posible:

HED estándar: 8.4.0 - Vocabulario básico
Esquemas de biblioteca:
- lang_1.1.0 - Etiquetas relacionadas con el lenguaje
- score_2.1.0 - Características de EEG basadas en el estándar SCORE

Instalación

Requisitos Previos

Antes de usar el Servidor HED MCP, asegúrese de tener:

Node.js 22+: Descargue desde nodejs.org
Conocimiento básico de HED: La familiaridad con los conceptos de HED es útil
Cliente compatible con MCP: Como el MCP Inspector o un cliente personalizado

Instalar Dependencias

npm install

Compilar el Servidor

npm run build

Esto crea los archivos de distribución en el directorio dist/.

Probar la Instalación

npx @modelcontextprotocol/inspector node dist/server.js

Arquitectura del Servidor

Componentes Principales

HED MCP Server (src)
├── server.ts              # Main MCP server (stdio/WebSocket modes)
├── tools/                 # Validation functions
│   ├── validateHedString.ts
│   ├── validateHedTsv.ts
│   ├── validateHedSidecar.ts
│   └── getFileFromPath.ts
├── resources/             # Schema Information
│   └── hedSchema.ts
├── utils/                 # Utilities
│   ├── definitionProcessor.ts
│   ├── fileReader.ts
│   ├── issueFormatter.ts
│   ├── mcpToZod.ts
│   └── schemaCache.ts     # Schema caching system
└── types/                 # TypeScript definitions

Examples (examples/)
├── definition-usage.ts    # Example of HED definition processing
├── hed-demo.html          # Interactive demo and integration guide
├── hed-validator-client.js # Modern browser client for HED validation
├── hed-validator.css      # Styles for the browser interface
├── hed-validator.html     # Full-featured browser validation interface
├── http-server.ts         # HTTP REST API server example
├── mcp-client.js          # Interactive MCP client example
├── README.md              # README for the examples
└── test-server.js         # Automated server testing script

Flujo de Datos

Solicitud del cliente → Servidor MCP
Carga del esquema → Caché o carga desde la red
Procesamiento de datos → Analizar y validar
Formato de problemas → Estandarizar el formato de errores/advertencias
Respuesta → Devolver al cliente

Sistema de Caché

El servidor implementa caché inteligente:

Caché de esquemas: Evita recargar esquemas para operaciones repetidas
Caché de definiciones: Reutiliza definiciones procesadas
Gestión de memoria: Limpieza automática de entradas de caché no utilizadas

Inicio Rápido

Ejecutar con MCP Inspector

La forma más rápida de probar el servidor es usando el MCP Inspector:

npx @modelcontextprotocol/inspector node dist/server.js

Esto abre una interfaz web donde puede interactuar con el servidor y probar todas las herramientas disponibles.

Prueba básica del servidor

Pruebe el servidor directamente:

# Standard MCP server (stdio mode)
npm start

# WebSocket mode  
node dist/server.js --websocket --port=8080

# HTTP REST API server
npm run start:http

O pruebe con el cliente incluido:

node test-mcp-client.js

Primeros pasos

Abra el MCP Inspector en su navegador
Inicialice el servidor - esto ocurre automáticamente
Liste las herramientas disponibles para ver qué está disponible
Pruebe una validación simple con validateHedString

Herramientas disponibles

Herramienta	Descripción	Parámetros requeridos	Parámetros opcionales
`validateHedString`	Valida cadenas de etiquetas HED	`hedString`, `hedVersion`	`checkForWarnings`, `definitions`
`validateHedTsv`	Valida archivos TSV con HED	`filePath`, `hedVersion`	`checkForWarnings`, `fileData`, `jsonData`, `definitions`
`validateHedSidecar`	Valida archivos JSON sidecar HED	`filePath`, `hedVersion`	`checkForWarnings`, `fileData`
`getFileFromPath`	Lee archivos del sistema de archivos	`filePath`

Referencia de herramientas

validateHedString

Propósito: Valida cadenas de etiquetas HED individuales

Cuándo usar:

Probando construcciones HED específicas
Validación interactiva durante la anotación
Validando cadenas HED generadas programáticamente

Parámetros:

hedString (requerido): La cadena HED a validar
hedVersion (requerido): Versión del esquema (ej., "8.4.0")
checkForWarnings (opcional): Incluir advertencias en los resultados
definitions (opcional): Matriz de cadenas de definición

Mejores prácticas:

Use versiones de esquema específicas en producción
Habilite advertencias durante el desarrollo
Agrupe definiciones relacionadas juntas

validateHedTsv

Propósito: Valida archivos TSV que contienen anotaciones HED

Cuándo usar:

Validando archivos de eventos BIDS
Verificando archivos TSV antes de la publicación
Validación automatizada de conjuntos de datos

Parámetros:

filePath (requerido): Ruta al archivo TSV
hedVersion (requerido): Versión del esquema
checkForWarnings (opcional): Incluir advertencias
fileData (opcional): Datos TSV en línea
jsonData (opcional): Datos sidecar como cadena JSON
definitions (opcional): Cadenas de definición

Mejores prácticas:

Use fileData para conjuntos de datos pequeños para evitar E/S de archivos
Incluya datos sidecar a través de jsonData para una validación completa
Procese archivos en lotes para conjuntos de datos grandes

validateHedSidecar

Propósito: Valida archivos JSON sidecar HED

Cuándo usar:

Validando archivos sidecar BIDS
Verificando la estructura JSON y el contenido HED
Convirtiendo entre formatos sidecar

Parámetros:

filePath (requerido): Ruta al archivo JSON sidecar
hedVersion (requerido): Versión del esquema
checkForWarnings (opcional): Incluir advertencias
fileData (opcional): Datos JSON en línea

Mejores prácticas:

Valide archivos sidecar antes que archivos TSV
Use la salida analizada para depurar la estructura sidecar
Verifique tanto la estructura como la validez del contenido HED

getFileFromPath

Propósito: Recupera archivos del sistema de archivos local

Cuándo usar:

Leyendo archivos de configuración
Accediendo a archivos de datos para validación
Operaciones del sistema de archivos

Parámetros:

filePath (requerido): Ruta absoluta al archivo

Mejores prácticas:

Use rutas de archivo absolutas
Verifique los permisos y la existencia del archivo
Maneje la codificación de archivos adecuadamente (UTF-8 recomendado)

Ejemplos de uso

Validar una cadena HED

{
  "method": "tools/call",
  "params": {
    "name": "validateHedString",
    "arguments": {
      "hedString": "Event/Sensory-event, Red, Blue, (Green, Large)",
      "hedVersion": "8.4.0",
      "checkForWarnings": true
    }
  }
}

Validar un archivo TSV

{
  "method": "tools/call",
  "params": {
    "name": "validateHedTsv",
    "arguments": {
      "filePath": "/tests/data/sub-002_ses-1_task-FacePerception_run-1_events.tsv",
      "hedVersion": "8.4.0",
      "checkForWarnings": true,
      "definitions": [
        "(Definition/Fixation, (Sensory-event, Visual-presentation, (Image, Cross))",
        "(Definition/ButtonPress, (Press, Mouse-button))"
      ]
    }
  }
}

Validar un sidecar JSON BIDS

{
  "method": "tools/call",
  "params": {
    "name": "validateHedSidecar",
    "arguments": {
      "filePath": "/tests/data/task-FacePerception_events.json",
      "hedVersion": "8.4.0",
      "checkForWarnings": false
    }
  }
}

Leer un archivo

{
  "method": "tools/call",
  "params": {
    "name": "getFileFromPath",
    "arguments": {
      "filePath": "/path/to/data/events.tsv"
    }
  }
}

Trabajando con Datos HED

Flujo de Trabajo de Validación

Selección de Esquema: Elija la versión de esquema HED apropiada
Configuración de Definiciones: Prepare cualquier definición personalizada
Validación de Datos: Ejecute la herramienta de validación apropiada
Resolución de Problemas: Aborde errores y advertencias
Aseguramiento de Calidad: Validación final con advertencias habilitadas

Escenarios Comunes de Validación

Escenario 1: Validación de Nuevo Conjunto de Datos

// 1. First validate sidecar files
{
  "name": "validateHedSidecar",
  "arguments": {
    "filePath": "/data/task-rest_events.json",
    "hedVersion": "8.4.0",
    "checkForWarnings": true
  }
}

// 2. Then validate TSV files with sidecar data
{
  "name": "validateHedTsv", 
  "arguments": {
    "filePath": "/data/sub-01_task-rest_events.tsv",
    "hedVersion": "8.4.0",
    "jsonData": "{...sidecar content...}",
    "checkForWarnings": true
  }
}

Escenario 2: Anotación Interactiva

// Test individual HED strings during annotation
{
  "name": "validateHedString",
  "arguments": {
    "hedString": "Event/Sensory-event, (Red, Large)",
    "hedVersion": "8.4.0",
    "checkForWarnings": true
  }
}

Escenario 3: Desarrollo de Definiciones

// Test definitions before using in datasets
{
  "name": "validateHedString",
  "arguments": {
    "hedString": "Def/MyStimulus, Blue",
    "hedVersion": "8.4.0", 
    "definitions": [
      "(Definition/MyStimulus, (Event/Sensory-event, (Onset)))"
    ],
    "checkForWarnings": true
  }
}

Interpretación de Errores

Tipos de errores comunes

TAG_INVALID: Etiqueta no encontrada en el esquema
- Verifique la ortografía y las mayúsculas
- Confirme que la etiqueta existe en la versión de esquema especificada
- Considere usar etiquetas de extensión si es apropiado
DEFINITION_INVALID: Definición malformada
- Asegure paréntesis adecuados alrededor del contenido de la definición
- Verifique que el nombre de la definición siga las convenciones
- Confirme que el contenido de la definición sea HED válido
SCHEMA_LOAD_FAILED: Versión de esquema inválida
- Verifique que la versión del esquema exista
- Compruebe la conectividad de red para la descarga del esquema
- Use versiones de esquema estables y publicadas
FILE_READ_ERROR: No se puede leer el archivo especificado
- Verifique la ruta del archivo y los permisos
- Compruebe que el archivo exista y sea legible
- Considere usar datos en línea para archivos virtuales

Tipos de advertencias

TAG_EXTENDED: Etiqueta de extensión utilizada
- Considere usar etiquetas estándar más específicas
- Aceptable para paradigmas experimentales novedosos
- Documente las extensiones para reproducibilidad
DEFINITION_WARNING: Problemas de definición
- Problemas de definición no críticos
- Puede indicar problemas de estilo o convención
- Revise la estructura y el contenido de la definición

Directrices de calidad de datos

Anotaciones HED de alta calidad

Especificidad: Use las etiquetas específicas más apropiadas
Consistencia: Aplique los mismos patrones de anotación en todo el conjunto de datos
Completitud: Anote todos los aspectos relevantes de los eventos
Precisión: Asegure que las anotaciones coincidan con los eventos experimentales reales

Lista de verificación de calidad

Todos los archivos se validan sin errores
Advertencias revisadas y abordadas donde corresponda
Definiciones documentadas adecuadamente
Versión de esquema apropiada para el conjunto de datos
Anotaciones consistentes en eventos similares

Uso en navegador

El servidor HED MCP se puede usar en navegadores a través de varios enfoques. Todos los archivos de navegador se encuentran en el directorio examples/.

Opción 1: Interfaz de Validación Completa

Abra examples/hed-validator.html para una interfaz web con todas las funciones:

Múltiples modos de validación: Validación de cadenas, TSV y sidecar
UI moderna: Diseño limpio y receptivo con estilo profesional
Retroalimentación en tiempo real: Resultados de validación instantáneos con informes de errores detallados
Múltiples versiones de HED: Soporte para diferentes versiones de esquema y bibliotecas

# Serve the examples locally
npx serve examples/

# Or open directly in browser
open examples/hed-validator.html

Opción 2: Demo Interactiva y Guía de Integración

Vea examples/hed-demo.html para:

Ejemplos en vivo: Escenarios de validación preconfigurados
Guía de integración: Documentación completa de API y ejemplos de código
Herramientas de desarrollador: Formulario de validación rápida para pruebas

Opción 3: Biblioteca de Cliente para Navegador

Incluya el cliente de navegador moderno en su aplicación web:

<link rel="stylesheet" href="examples/hed-validator.css">
<script src="examples/hed-validator-client.js"></script>
<script>
  // Create validator client (auto-detects server availability)
  const validator = new HEDValidatorClient();
  
  // Validate HED string
  const result = await validator.validateString('Event/Sensory-event, Red');
  
  // Or create a pre-built validation form
  HEDValidatorClient.createValidationForm('my-container');
</script>

Opción 4: Integración completa con API HTTP

Para una validación completa basada en servidor, ejecute el servidor de API HTTP:

npm run build
node dist/examples/http-server.js

El cliente del navegador detecta y utiliza automáticamente el servidor en http://localhost:3000/api/hed/.

Inicio rápido: Abra examples/hed-validator.html para comenzar a validar datos HED inmediatamente en su navegador.

Integración con aplicaciones web

<!DOCTYPE html>
<html>
<head>
    <title>HED Validator</title>
</head>
<body>
    <textarea id="hedInput" placeholder="Enter HED string..."></textarea>
    <button onclick="validateHED()">Validate</button>
    <div id="results"></div>

    <script>
        async function validateHED() {
            const hedString = document.getElementById('hedInput').value;
            
            try {
                const response = await fetch('/api/validate', {
                    method: 'POST',
                    headers: { 'Content-Type': 'application/json' },
                    body: JSON.stringify({
                        hedString,
                        hedVersion: '8.4.0',
                        checkForWarnings: true
                    })
                });
                
                const result = await response.json();
                displayResults(result);
            } catch (error) {
                console.error('Validation failed:', error);
            }
        }
        
        function displayResults(result) {
            const resultsDiv = document.getElementById('results');
            
            if (result.errors.length === 0) {
                resultsDiv.innerHTML = '<p style="color: green;">Valid HED string!</p>';
            } else {
                resultsDiv.innerHTML = '<p style="color: red;">Validation errors:</p>';
                result.errors.forEach(error => {
                    resultsDiv.innerHTML += `<p>• ${error.message}</p>`;
                });
            }
            
            if (result.warnings.length > 0) {
                resultsDiv.innerHTML += '<p style="color: orange;">Warnings:</p>';
                result.warnings.forEach(warning => {
                    resultsDiv.innerHTML += `<p>• ${warning.message}</p>`;
                });
            }
        }
    </script>
</body>
</html>

Configuración

Configuración del cliente MCP

Agregue a la configuración de su cliente MCP:

{
  "servers": {
    "hed-mcp": {
      "command": "node",
      "args": ["dist/server.js"],
      "cwd": "/path/to/hed-mcp-typescript"
    }
  }
}

Modo WebSocket

Ejecute el servidor en modo WebSocket para clientes MCP basados en navegador:

node dist/server.js --websocket --port=8080

Variables de entorno

El servidor respeta las variables de entorno estándar de Node.js:

NODE_ENV: Establézcalo en development para registro detallado
DEBUG: Habilite la salida de depuración para solucionar problemas

Modo de depuración

Habilite el registro de depuración:

DEBUG=* node dist/server.js

O en la configuración del cliente MCP:

{
  "servers": {
    "hed-mcp": {
      "command": "node",
      "args": ["dist/server.js"],
      "env": {
        "DEBUG": "*"
      }
    }
  }
}

Gestión de definiciones

Mejores prácticas para definiciones

Nomenclatura: Utilice nombres descriptivos y únicos
Estructura: Mantenga las definiciones simples y enfocadas
Reutilización: Diseñe para reutilizar en experimentos similares
Documentación: Documente el propósito y el uso

Ejemplos de definiciones

// Simple stimulus definition
"(Definition/RedCircle, (Event/Sensory-event, (Red, Circle)))"

// Complex behavioral definition  
"(Definition/CorrectResponse, (Action/Move, Agent/Human, (Correct-action, (Voluntary))))"

// Hierarchical definitions
"(Definition/VisualStimulus, (Event/Sensory-event, Property/Sensory-property/Visual))"
"(Definition/RedVisualStimulus, (Def/VisualStimulus, Red))"

Optimización del rendimiento

Caché de esquemas

El servidor almacena automáticamente en caché los esquemas cargados para mejorar el rendimiento:

// Schemas are cached by version string
const schema1 = await schemaCache.getOrCreateSchema('8.4.0');
const schema2 = await schemaCache.getOrCreateSchema('8.4.0'); // Uses cache

Reutilización de definiciones

Procese las definiciones una vez y reutilícelas:

// Define once, use multiple times
const definitions = [
  "(Definition/Fixation, (Event/Sensory-event, (Onset)))",
  "(Definition/Response, (Action/Move, Agent/Human))"
];

// Use in multiple validations
for (const hedString of hedStrings) {
  const result = await validate({
    hedString,
    hedVersion: '8.4.0',
    definitions  // Reuse same definitions
  });
}

Operaciones por lotes

// Efficient batch processing
const server = new MCPServer();
await server.connect();

try {
  const results = await Promise.all(
    files.map(file => 
      server.call('validateHedTsv', {
        filePath: file,
        hedVersion: '8.4.0'
      })
    )
  );
} finally {
  await server.disconnect();
}

Consejos de rendimiento

Uso de memoria

Supervise el uso de memoria con conjuntos de datos grandes
Procese archivos por lotes si la memoria es limitada
Limpie las entradas de caché de esquemas no utilizadas
Utilice transmisión para archivos muy grandes

Optimización de velocidad

Reutilice las conexiones del servidor para múltiples operaciones
Almacene en caché esquemas y definiciones entre operaciones
Utilice datos en línea para evitar la sobrecarga de E/S de archivos
Desactive las advertencias para la validación en producción

Guía de integración

Integración con cliente MCP

Configuración básica del cliente

import { MCPClient } from '@modelcontextprotocol/client';

const client = new MCPClient({
  server: {
    command: 'node',
    args: ['dist/server.js'],
    cwd: '/path/to/hed-mcp-typescript'
  }
});

await client.connect();

Manejo de errores

async function safeValidation(hedString, hedVersion) {
  try {
    const response = await client.call('tools/call', {
      name: 'validateHedString',
      arguments: { hedString, hedVersion }
    });
    
    const result = JSON.parse(response.content[0].text);
    
    return {
      success: result.errors.length === 0,
      errors: result.errors,
      warnings: result.warnings
    };
  } catch (error) {
    return {
      success: false,
      errors: [{ 
        code: 'CLIENT_ERROR',
        message: error.message,
        severity: 'error'
      }],
      warnings: []
    };
  }
}

Integración con Python

import asyncio
import json
from mcp_client import MCPClient

class HEDValidator:
    def __init__(self, server_path):
        self.client = MCPClient(server_path)
    
    async def __aenter__(self):
        await self.client.connect()
        return self
    
    async def __aexit__(self, exc_type, exc_val, exc_tb):
        await self.client.disconnect()
    
    async def validate_string(self, hed_string, hed_version="8.4.0", check_warnings=True):
        """Validate a HED string."""
        response = await self.client.call('tools/call', {
            'name': 'validateHedString',
            'arguments': {
                'hedString': hed_string,
                'hedVersion': hed_version,
                'checkForWarnings': check_warnings
            }
        })
        
        return json.loads(response['content'][0]['text'])
    
    async def validate_file(self, file_path, hed_version="8.4.0", definitions=None):
        """Validate a TSV file."""
        args = {
            'filePath': file_path,
            'hedVersion': hed_version,
            'checkForWarnings': True
        }
        
        if definitions:
            args['definitions'] = definitions
        
        response = await self.client.call('tools/call', {
            'name': 'validateHedTsv',
            'arguments': args
        })
        
        return json.loads(response['content'][0]['text'])

# Usage example
async def main():
    async with HEDValidator('/path/to/hed-mcp-typescript/dist/server.js') as validator:
        # Validate a HED string
        result = await validator.validate_string(
            "Event/Sensory-event, Red, Blue",
            hed_version="8.4.0"
        )
        
        if result['errors']:
            print("Validation errors found:")
            for error in result['errors']:
                print(f"  - {error['message']}")
        else:
            print("HED string is valid!")

if __name__ == "__main__":
    asyncio.run(main())

Integración con línea de comandos

#!/bin/bash
# validate-dataset.sh - Validate all HED files in a BIDS dataset

DATASET_DIR="$1"
HED_VERSION="8.4.0"

echo "Validating BIDS dataset: $DATASET_DIR"

# Validate sidecar files
find "$DATASET_DIR" -name "*_events.json" | while read file; do
    echo "Validating sidecar: $file"
    # Call validateHedSidecar via MCP client
    validate_sidecar "$file" "$HED_VERSION"
done

# Validate TSV files  
find "$DATASET_DIR" -name "*_events.tsv" | while read file; do
    echo "Validating TSV: $file"
    # Call validateHedTsv via MCP client
    validate_tsv "$file" "$HED_VERSION"
done

echo "Dataset validation complete!"

Desarrollo

Estructura del proyecto

src/
├── server.ts              # Main MCP server (stdio/WebSocket)
├── tools/                 # MCP tools (validation functions)
│   ├── validateHedString.ts
│   ├── validateHedTsv.ts
│   ├── validateHedSidecar.ts
│   └── getFileFromPath.ts
├── resources/             # MCP resources (schema info)
│   └── hedSchema.ts
├── utils/                 # Utility functions
│   ├── mcpToZod.ts
│   ├── definitionProcessor.ts
│   ├── fileReader.ts
│   ├── issueFormatter.ts
│   └── schemaCache.ts
└── types/                 # TypeScript type definitions
    └── index.ts

Scripts disponibles

npm run build        # Build the TypeScript project
npm run dev          # Build in watch mode
npm run test         # Run the test suite
npm run test:watch   # Run tests in watch mode
npm run test:coverage # Generate test coverage report
npm run clean        # Clean build artifacts
npm start           # Run stdio MCP server
npm run start:http  # Run HTTP API server

Flujo de trabajo de desarrollo

Clonar e instalar:

git clone <repository-url>
cd hed-mcp-typescript
npm install

Iniciar el desarrollo:
```
npm run dev  # Builds in watch mode
```
Probar sus cambios:
```
npm test
```

Probar con el inspector:

npx @modelcontextprotocol/inspector node dist/server.js

Solución de problemas

Problemas comunes

Problema: El servidor no se inicia

Síntomas: El servidor se cierra inmediatamente o muestra errores de conexión

Soluciones:

Verifique la versión de Node.js (requiere 18+)
Verifique que la compilación se completó correctamente: npm run build
Verifique conflictos de puertos
Revise los mensajes de error en la consola

Problema: Fallos al cargar esquemas

Síntomas: Errores de SCHEMA_LOAD_FAILED

Soluciones:

Verifique la conectividad a Internet para descargas de esquemas
Utilice cadenas de versión de esquema exactas
Verifique los permisos del directorio de caché de esquemas
Intente limpiar la caché: elimine node_modules y reinstale

Problema: Errores al leer archivos

Síntomas: FILE_READ_ERROR al acceder a archivos

Soluciones:

Verifique que las rutas de archivo sean absolutas
Verifique los permisos y la existencia de los archivos
Utilice datos en línea (fileData) para pruebas
Asegure la codificación adecuada de archivos (UTF-8)

Problema: Inconsistencias en la validación

Síntomas: Resultados diferentes de la misma entrada

Soluciones:

Asegure versiones de esquema consistentes
Limpie la caché de esquemas si es necesario
Verifique conflictos de validación concurrente
Verifique el orden y la consistencia de las definiciones

Problemas de rendimiento

Uso de memoria

Supervise el uso de memoria con conjuntos de datos grandes
Procese archivos por lotes si la memoria es limitada
Limpie las entradas de caché de esquemas no utilizadas
Utilice transmisión para archivos muy grandes

Optimización de velocidad

Reutilice las conexiones del servidor para múltiples operaciones
Almacene en caché esquemas y definiciones entre operaciones
Utilice datos en línea para evitar la sobrecarga de E/S de archivos
Desactive las advertencias para la validación en producción

Documentación de la API

Para documentación detallada de la API, consulte API.md.

Conceptos clave:

FormattedIssue: Formato estandarizado de errores/advertencias
HedValidationResult: Formato estándar de respuesta de validación
Schema Caching: Almacenamiento automático en caché de esquemas HED cargados
Definition Support: Procesar y utilizar definiciones HED durante la validación

Pruebas

El proyecto incluye pruebas integrales que cubren:

Pruebas unitarias: Pruebas de funciones individuales
Pruebas de integración: Pruebas de interacción de herramientas
Validación de datos: Pruebas con archivos de datos HED reales

Ejecutar pruebas

# Run all tests
npm test

# Run with coverage
npm run test:coverage

# Run in watch mode during development
npm run test:watch

# Run only integration tests
npm test -- --testPathPattern=integration

Datos de prueba

Los archivos de prueba se encuentran en tests/data/:

sub-002_ses-1_task-FacePerception_run-1_events.tsv
task-FacePerception_events.json
participants_bad.json
participants_bad.tsv

Contribuciones

Haga un fork del repositorio
Cree una rama de características: git checkout -b feature/amazing-feature
Realice sus cambios y agregue pruebas
Ejecute la suite de pruebas: npm test
Confirme sus cambios: git commit -m 'Add amazing feature'
Empuje a la rama: git push origin feature/amazing-feature
Abra una Solicitud de Extracción (Pull Request)

Estilo de código

Utilice el modo estricto de TypeScript
Siga las convenciones de nomenclatura existentes
Agregue comentarios JSDoc para APIs públicas
Asegúrese de que todas las pruebas pasen antes de enviar

Licencia

Este proyecto está licenciado bajo la Licencia ISC - consulte el archivo LICENSE para más detalles.