HED MCP Server

Um servidor MCP para Hierarchical Event Descriptors (HED) que automatiza a criação de sidecars e anotação para arquivos de eventos BIDS usando LLMs.

GitHub
2
Experimente este MCPPatrocinado

Documentação

Servidor HED MCP TypeScript

License: ISC TypeScript MCP Maintainability Code Coverage

Introdução

Um servidor Model Context Protocol (MCP) para validar dados HED (Hierarchical Event Descriptor). Este servidor fornece ferramentas abrangentes de validação HED por meio da interface padronizada MCP, tornando a validação HED acessível a qualquer cliente compatível com MCP.

O que é HED?

HED (Hierarchical Event Descriptor) é:

  • Um vocabulário padronizado para descrever eventos experimentais
  • Um sistema hierárquico que permite anotação precisa de eventos
  • Amplamente utilizado em conjuntos de dados BIDS (Brain Imaging Data Structure)
  • Essencial para pesquisa em neurociência reprodutível

O que é MCP?

Model Context Protocol (MCP) é:

  • Um protocolo padronizado para compartilhamento de ferramentas e recursos
  • Permite que assistentes de IA e aplicativos acessem capacidades externas
  • Fornece uma interface consistente entre diferentes implementações
  • Facilita a integração entre diversos sistemas de software

Recursos

  • Validação de strings HED: Valida strings de tags HED individuais conforme especificações do esquema
  • Validação de arquivos TSV: Valida arquivos TSV BIDS inteiros contendo anotações HED
  • Validação de sidecar JSON: Analisa e valida arquivos JSON sidecar HED
  • Acesso ao sistema de arquivos: Lê arquivos de caminhos do sistema de arquivos local
  • Suporte a múltiplos esquemas: Suporte para esquemas HED padrão e esquemas de biblioteca
  • Processamento de definições: Gerencia definições HED para validação aprimorada
  • Detecção de avisos: Detecção opcional de avisos além do relatório de erros
  • Cache de esquemas: Sistema inteligente de cache para desempenho otimizado
  • Múltiplas interfaces: Servidor MCP (stdio/WebSocket) + API REST HTTP
  • Compatibilidade com navegadores: Suporte completo a navegadores com múltiplas opções de integração

Sumário

Entendendo HED

Conceitos Básicos de HED

HED usa uma estrutura hierárquica de tags onde as tags são organizadas do geral para o específico:

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

A estrutura hierárquica é usada para generalidade de busca — permitindo que uma busca por Event capture também Event/Sensory-event e Sensory-event.

Nota: Todas as tags no vocabulário HED são únicas. Recomenda-se anotar usando apenas a tag, não o caminho completo.

Estrutura de Tags

  • Notação de caminho: Tags usam barras para indicar hierarquia
  • Agrupamento: Parênteses agrupam tags relacionadas: (Red, Large)
  • Definições: Definições personalizadas podem ser usadas para conceitos complexos
  • Extensão: Subtags personalizadas podem ser adicionadas para especialização

Padrões Comuns de HED

Descrição básica de evento

Sensory-event, Red

Tags Agrupadas

Sensory-event, (Red, Square)

Usando Definições

Você pode criar definições para representar strings de tags que usa com frequência:

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

A anotação:

Def/BlueSquare

pode aparecer em qualquer lugar onde uma tag HED normal apareceria. As ferramentas podem substituir a anotação completa quando necessário.

Versões de Esquema

Os esquemas HED evoluem ao longo do tempo. Use a versão mais recente sempre que possível:

  • HED Padrão: 8.4.0 - Vocabulário básico
  • Esquemas de biblioteca:
    • lang_1.1.0 - Tags relacionadas a idiomas
    • score_2.1.0 - Recursos de EEG baseados no padrão SCORE

Instalação

Pré-requisitos

Antes de usar o HED MCP Server, certifique-se de ter:

  1. Node.js 22+: Baixe em nodejs.org
  2. Conhecimento básico de HED: Familiaridade com conceitos HED é útil
  3. Cliente compatível com MCP: Como o MCP Inspector ou um cliente personalizado

Instalar Dependências

npm install

Compilar o Servidor

npm run build

Isso cria os arquivos de distribuição no diretório dist/.

Testar a Instalação

npx @modelcontextprotocol/inspector node dist/server.js

Arquitetura do Servidor

Componentes Principais

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

Fluxo de Dados

  1. Solicitação do cliente → servidor MCP
  2. Carregamento do esquema → Cache ou carregamento da rede
  3. Processamento de dados → Analisar e validar
  4. Formatação de problemas → Padronizar formato de erros/avisos
  5. Resposta → Retornar ao cliente

Sistema de Cache

O servidor implementa cache inteligente:

  • Cache de esquemas: Evita recarregar esquemas para operações repetidas
  • Cache de definições: Reutiliza definições processadas
  • Gerenciamento de memória: Limpeza automática de entradas de cache não utilizadas

Início Rápido

Executar com MCP Inspector

A maneira mais rápida de testar o servidor é usando o MCP Inspector:

npx @modelcontextprotocol/inspector node dist/server.js

Isso abre uma interface web onde você pode interagir com o servidor e testar todas as ferramentas disponíveis.

Teste básico do servidor

Teste o servidor diretamente:

# Standard MCP server (stdio mode)
npm start

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

# HTTP REST API server
npm run start:http

Ou teste com o cliente incluído:

node test-mcp-client.js

Primeiros passos

  1. Abra o MCP Inspector no seu navegador
  2. Inicialize o servidor - isso acontece automaticamente
  3. Liste as ferramentas disponíveis para ver o que está disponível
  4. Tente uma validação simples com validateHedString

Ferramentas disponíveis

FerramentaDescriçãoParâmetros obrigatóriosParâmetros opcionais
validateHedStringValida strings de tags HEDhedString, hedVersioncheckForWarnings, definitions
validateHedTsvValida arquivos TSV com HEDfilePath, hedVersioncheckForWarnings, fileData, jsonData, definitions
validateHedSidecarValida arquivos JSON sidecar HEDfilePath, hedVersioncheckForWarnings, fileData
getFileFromPathLê arquivos do sistema de arquivosfilePath

Referência de ferramentas

validateHedString

Finalidade: Valida strings de tags HED individuais

Quando usar:

  • Testar construções HED específicas
  • Validação interativa durante a anotação
  • Validar strings HED geradas programaticamente

Parâmetros:

  • hedString (obrigatório): A string HED a ser validada
  • hedVersion (obrigatório): Versão do esquema (ex.: "8.4.0")
  • checkForWarnings (opcional): Incluir avisos nos resultados
  • definitions (opcional): Matriz de strings de definição

Melhores práticas:

  • Use versões específicas do esquema em produção
  • Ative avisos durante o desenvolvimento
  • Agrupe definições relacionadas

validateHedTsv

Finalidade: Valida arquivos TSV contendo anotações HED

Quando usar:

  • Validar arquivos de eventos BIDS
  • Verificar arquivos TSV antes da publicação
  • Validação automatizada de conjuntos de dados

Parâmetros:

  • filePath (obrigatório): Caminho para o arquivo TSV
  • hedVersion (obrigatório): Versão do esquema
  • checkForWarnings (opcional): Incluir avisos
  • fileData (opcional): Dados TSV inline
  • jsonData (opcional): Dados sidecar como string JSON
  • definitions (opcional): Strings de definição

Melhores práticas:

  • Use fileData para conjuntos de dados pequenos para evitar E/S de arquivo
  • Inclua dados sidecar via jsonData para validação completa
  • Processe arquivos em lotes para conjuntos de dados grandes

validateHedSidecar

Finalidade: Valida arquivos JSON sidecar HED

Quando usar:

  • Validar arquivos sidecar BIDS
  • Verificar estrutura JSON e conteúdo HED
  • Converter entre formatos sidecar

Parâmetros:

  • filePath (obrigatório): Caminho para o arquivo JSON sidecar
  • hedVersion (obrigatório): Versão do esquema
  • checkForWarnings (opcional): Incluir avisos
  • fileData (opcional): Dados JSON inline

Melhores práticas:

  • Valide arquivos sidecar antes dos arquivos TSV
  • Use a saída analisada para depurar a estrutura sidecar
  • Verifique tanto a estrutura quanto a validade do conteúdo HED

getFileFromPath

Finalidade: Recupera arquivos do sistema de arquivos local

Quando usar:

  • Ler arquivos de configuração
  • Acessar arquivos de dados para validação
  • Operações do sistema de arquivos

Parâmetros:

  • filePath (obrigatório): Caminho absoluto para o arquivo

Melhores práticas:

  • Use caminhos absolutos de arquivo
  • Verifique permissões e existência do arquivo
  • Gerencie a codificação do arquivo adequadamente (UTF-8 recomendado)

Exemplos de uso

Validar uma string HED

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

Validar um arquivo 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 um sidecar JSON BIDS

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

Ler um arquivo

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

Trabalhando com Dados HED

Fluxo de Validação

  1. Seleção do Esquema: Escolha a versão apropriada do esquema HED
  2. Configuração de Definições: Prepare quaisquer definições personalizadas
  3. Validação de Dados: Execute a ferramenta de validação apropriada
  4. Resolução de Problemas: Aborde erros e avisos
  5. Garantia de Qualidade: Validação final com avisos ativados

Cenários Comuns de Validação

Cenário 1: Validação de Novo Conjunto de Dados

// 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
  }
}

Cenário 2: Anotação Interativa

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

Cenário 3: Desenvolvimento de Definições

// 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
  }
}

Interpretação de Erros

Tipos comuns de erro

  1. TAG_INVALID: Tag não encontrada no esquema

    • Verifique ortografia e capitalização
    • Confirme se a tag existe na versão especificada do esquema
    • Considere usar tags de extensão quando apropriado

  2. DEFINITION_INVALID: Definição malformada

    • Garanta parênteses adequados ao redor do conteúdo da definição
    • Verifique se o nome da definição segue as convenções
    • Confirme se o conteúdo da definição é HED válido

  3. SCHEMA_LOAD_FAILED: Versão de esquema inválida

    • Verifique se a versão do esquema existe
    • Verifique a conectividade de rede para download do esquema
    • Use versões estáveis e publicadas do esquema

  4. FILE_READ_ERROR: Não foi possível ler o arquivo especificado

    • Verifique o caminho do arquivo e as permissões
    • Confirme se o arquivo existe e é legível
    • Considere usar dados inline para arquivos virtuais

Tipos de aviso

  1. TAG_EXTENDED: Tag de extensão usada

    • Considere usar tags padrão mais específicas
    • Aceitável para paradigmas experimentais novos
    • Documente extensões para reprodutibilidade

  2. DEFINITION_WARNING: Problemas de definição

    • Problemas de definição não críticos
    • Pode indicar problemas de estilo ou convenção
    • Revise a estrutura e o conteúdo da definição

Diretrizes de qualidade de dados

Anotações HED de alta qualidade

  1. Especificidade: Use as tags específicas mais apropriadas
  2. Consistência: Aplique os mesmos padrões de anotação em todo o conjunto de dados
  3. Completude: Anote todos os aspectos relevantes dos eventos
  4. Precisão: Garanta que as anotações correspondam aos eventos experimentais reais

Lista de verificação de qualidade

  • Todos os arquivos validam sem erros
  • Avisos revisados e abordados quando apropriado
  • Definições devidamente documentadas
  • Versão do esquema apropriada para o conjunto de dados
  • Anotações consistentes entre eventos semelhantes

Uso no navegador

O servidor HED MCP pode ser usado em navegadores por meio de várias abordagens. Todos os arquivos do navegador estão localizados no diretório examples/.

Opção 1: Interface de Validação Completa

Abra examples/hed-validator.html para uma interface web completa:

  • Múltiplos modos de validação: Validação de String, TSV e Sidecar
  • Interface moderna: Design limpo e responsivo com estilo profissional
  • Feedback em tempo real: Resultados de validação instantâneos com relatório detalhado de erros
  • Múltiplas versões HED: Suporte para diferentes versões de esquema e bibliotecas
# Serve the examples locally
npx serve examples/

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

Opção 2: Demonstração Interativa e Guia de Integração

Veja examples/hed-demo.html para:

  • Exemplos ao vivo: Cenários de validação pré-configurados
  • Guia de integração: Documentação completa da API e exemplos de código
  • Ferramentas para desenvolvedores: Formulário rápido de validação para testes

Opção 3: Biblioteca de Cliente para Navegador

Inclua o cliente moderno para navegador no seu aplicativo 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>

Opção 4: Integração completa com API HTTP

Para validação completa baseada em servidor, execute o servidor de API HTTP:

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

O cliente do navegador detecta e usa automaticamente o servidor em http://localhost:3000/api/hed/.

Início Rápido: Abra examples/hed-validator.html para começar a validar dados HED imediatamente no seu navegador!

Integração com aplicação 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>

Configuração

Configuração do cliente MCP

Adicione à configuração do seu cliente MCP:

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

Modo WebSocket

Execute o servidor em modo WebSocket para clientes MCP baseados em navegador:

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

Variáveis de ambiente

O servidor respeita as variáveis de ambiente padrão do Node.js:

  • NODE_ENV: Defina como development para registro detalhado (verbose logging)
  • DEBUG: Ative a saída de depuração para solução de problemas

Modo de depuração

Ative o registro de depuração:

DEBUG=* node dist/server.js

Ou na configuração do cliente MCP:

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

Gerenciamento de definições

Melhores práticas para definições

  1. Nomenclatura: Use nomes descritivos e únicos
  2. Estrutura: Mantenha as definições simples e focadas
  3. Reutilização: Projete para reutilização em experimentos semelhantes
  4. Documentação: Documente o propósito e o uso

Exemplos de definições

// 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))"

Otimização de desempenho

Cache de esquemas

O servidor armazena automaticamente em cache os esquemas carregados para melhorar o desempenho:

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

Reutilização de definições

Processe as definições uma vez e reutilize:

// 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
  });
}

Operações em lote

// 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();
}

Dicas de desempenho

Uso de memória

  • Monitore o uso de memória com conjuntos de dados grandes
  • Processe arquivos em lotes se houver restrição de memória
  • Limpe entradas de cache de esquemas não utilizadas
  • Use streaming para arquivos muito grandes

Otimização de velocidade

  • Reutilize conexões do servidor para múltiplas operações
  • Armazene em cache esquemas e definições entre operações
  • Use dados inline para evitar sobrecarga de E/S de arquivos
  • Desative avisos para validação em produção

Guia de integração

Integração com cliente MCP

Configuração básica do 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();

Tratamento de erros

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: []
    };
  }
}

Integração com 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())

Integração com linha de comando

#!/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!"

Desenvolvimento

Estrutura do projeto

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 disponíveis

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

Fluxo de trabalho de desenvolvimento

  1. Clone e instale:

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

  2. Inicie o desenvolvimento:

    npm run dev  # Builds in watch mode

  3. Teste suas alterações:

    npm test

  4. Teste com o inspetor:

    npx @modelcontextprotocol/inspector node dist/server.js

Solução de problemas

Problemas comuns

Problema: O servidor não inicia

Sintomas: O servidor sai imediatamente ou mostra erros de conexão

Soluções:

  1. Verifique a versão do Node.js (requer 18+)
  2. Verifique se o build foi concluído com sucesso: npm run build
  3. Verifique conflitos de porta
  4. Revise as mensagens de erro no console

Problema: Falhas no carregamento de esquemas

Sintomas: erros de SCHEMA_LOAD_FAILED

Soluções:

  1. Verifique a conectividade com a internet para downloads de esquemas
  2. Use strings de versão de esquema exatas
  3. Verifique as permissões do diretório de cache de esquemas
  4. Tente limpar o cache: exclua node_modules e reinstale

Problema: Erros de leitura de arquivos

Sintomas: FILE_READ_ERROR ao acessar arquivos

Soluções:

  1. Verifique se os caminhos dos arquivos são absolutos
  2. Verifique as permissões e a existência dos arquivos
  3. Use dados inline (fileData) para testes
  4. Garanta a codificação adequada dos arquivos (UTF-8)

Problema: Inconsistências de validação

Sintomas: Resultados diferentes para a mesma entrada

Soluções:

  1. Garanta versões de esquema consistentes
  2. Limpe o cache de esquemas se necessário
  3. Verifique conflitos de validação concorrente
  4. Verifique a ordem e a consistência das definições

Problemas de desempenho

Uso de memória

  • Monitore o uso de memória com conjuntos de dados grandes
  • Processe arquivos em lotes se houver restrição de memória
  • Limpe entradas de cache de esquemas não utilizadas
  • Use streaming para arquivos muito grandes

Otimização de velocidade

  • Reutilize conexões do servidor para múltiplas operações
  • Armazene em cache esquemas e definições entre operações
  • Use dados inline para evitar sobrecarga de E/S de arquivos
  • Desative avisos para validação em produção

Documentação da API

Para documentação detalhada da API, consulte API.md.

Conceitos-chave:

  • FormattedIssue: Formato padronizado de erros/avisos
  • HedValidationResult: Formato padrão de resposta de validação
  • Cache de Esquemas: Armazenamento automático em cache de esquemas HED carregados
  • Suporte a Definições: Processe e use definições HED durante a validação

Testes

O projeto inclui testes abrangentes que cobrem:

  • Testes unitários: Teste de funções individuais
  • Testes de integração: Teste de interação entre ferramentas
  • Validação de dados: Teste com arquivos de dados HED reais

Executar testes

# 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

Dados de teste

Os arquivos de teste estão localizados em tests/data/:

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

Contribuindo

  1. Faça um fork do repositório
  2. Crie um branch de funcionalidade: git checkout -b feature/amazing-feature
  3. Faça suas alterações e adicione testes
  4. Execute a suíte de testes: npm test
  5. Faça commit das suas alterações: git commit -m 'Add amazing feature'
  6. Envie para o branch: git push origin feature/amazing-feature
  7. Abra um Pull Request

Estilo de código

  • Use o modo estrito do TypeScript
  • Siga as convenções de nomenclatura existentes
  • Adicione comentários JSDoc para APIs públicas
  • Garanta que todos os testes passem antes de enviar

Licença

Este projeto é licenciado sob a Licença ISC - consulte o arquivo LICENSE para obter detalhes.

Projetos relacionados

📞 Suporte