A Model Context Protocol (MCP) server for validating HED (Hierarchical Event Descriptor) data. This server provides comprehensive HED validation tools through the standardized MCP interface, making HED validation accessible to any MCP-compatible client.

HED (Hierarchical Event Descriptor) is:

• A standardized vocabulary for describing experimental events
• A hierarchical system that allows for precise event annotation
• Widely used in BIDS (Brain Imaging Data Structure) datasets
• Essential for reproducible neuroscience research

Model Context Protocol (MCP) is:

• A standardized protocol for tool and resource sharing
• Enables AI assistants and applications to access external capabilities
• Provides a consistent interface across different implementations
• Facilitates integration between diverse software systems

• HED string validation: Validate individual HED tag strings against schema specifications
• TSV file validation: Validate entire BIDS TSV files containing HED annotations
• JSON sidecar validation: Parse and validate HED sidecar JSON files
• File system access: Read files from local filesystem paths
• Multi-schema support: Support for standard HED schemas and library schemas
• Definition processing: Handle HED definitions for enhanced validation
• Warning detection: Optional warning detection in addition to error reporting
• Schema caching: Intelligent caching system for optimal performance
• Multiple interfaces: MCP server (stdio/WebSocket) + HTTP REST API
• Browser compatibility: Full browser support with multiple integration options

• Understanding HED
• Installation
• Quick Start
• Server Architecture
• Available Tools
• Usage Examples
• Working with HED Data
• Browser Usage
• Configuration
• Advanced Features
• Performance Optimization
• Integration Guide
• Development
• Troubleshooting
• Testing
• Contributing
• License

HED uses a hierarchical tag structure where tags are organized from general to specific:

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

The hierarchical structure is used for search generality -- allowing a search for Event to pick up Event/Sensory-event as well as Sensory-event.

Note: All tags in the HED vocabulary are unique. It is recommended that you annotate using just the tag, not the full path.

• Path notation: Tags use forward slashes to indicate hierarchy
• Grouping: Parentheses group related tags: (Red, Large)
• Definitions: Custom definitions can be used for complex concepts
• Extension: Custom subtags can be added for specialization

Sensory-event, Property/Sensory-property/Visual/Color/Red

(Event/Sensory-event, (Property/Sensory-property/Visual/Color/Red, Property/Physical-property/Size/Large))

Def/StimulusOnset, Property/Sensory-property/Visual/Color/Blue

HED schemas evolve over time. Use the latest version whenever possible:

• Standard HED: 8.4.0 - Basic vocabulary
• Library schemas:
  • lang_1.1.0 - Language-related tags
  • score_2.1.0 - EEG features based on SCORE standard

Before using the HED MCP Server, ensure you have:

1. Node.js 18+: Download from nodejs.org
2. Basic understanding of HED: Familiarity with HED concepts is helpful
3. MCP-compatible client: Such as the MCP Inspector or custom client

npm install

npm run build

This creates the distribution files in the dist/ directory.

npx @modelcontextprotocol/inspector node dist/server.js

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
│   ├── schemaCache.ts     # Schema caching system
│   ├── definitionProcessor.ts
│   ├── fileReader.ts
│   ├── issueFormatter.ts
│   └── mcpToZod.ts
└── types/                 # TypeScript definitions

Examples (examples/)
├── http-server.ts         # HTTP REST API server example
├── hed-validator.html     # Browser validation interface
├── hed-demo.html         # Interactive demo and guide
├── mcp-client.js         # MCP protocol client example
└── ...                   # Additional examples and utilities
    └── index.ts

1. Client request → MCP server
2. Schema loading → Cache or load from network
3. Data processing → Parse and validate
4. Issue formatting → Standardize error/Warning format
5. Response → Return to client

The server implements intelligent caching:

• Schema caching: Avoids reloading schemas for repeated operations
• Definition caching: Reuses processed definitions
• Memory management: Automatic cleanup of unused cache entries

The fastest way to test the server is using the MCP Inspector:

npx @modelcontextprotocol/inspector node dist/server.js

This opens a web interface where you can interact with the server and test all available tools.

Test the server directly:

# Standard MCP server (stdio mode)
npm start

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

# HTTP REST API server
npm run start:http

Or test with the included client:

node test-mcp-client.js

1. Open the MCP Inspector in your browser
2. Initialize the server - this happens automatically
3. List available tools to see what's available
4. Try a simple validation with validateHedString

Purpose: Validates individual HED tag strings

When to use:

• Testing specific HED constructs
• Interactive validation during annotation
• Validating programmatically generated HED strings

Parameters:

• hedString (required): The HED string to validate
• hedVersion (required): Schema version (e.g., "8.4.0")
• checkForWarnings (optional): Include warnings in results
• definitions (optional): Array of definition strings

Best practices:

• Use specific schema versions in production
• Enable warnings during development
• Group related definitions together

Purpose: Validates TSV files containing HED annotations

When to use:

• Validating BIDS event files
• Checking TSV files before publication
• Automated dataset validation

Parameters:

• filePath (required): Path to TSV file
• hedVersion (required): Schema version
• checkForWarnings (optional): Include warnings
• fileData (optional): Inline TSV data
• jsonData (optional): Sidecar data as JSON string
• definitions (optional): Definition strings

Best practices:

• Use fileData for small datasets to avoid file I/O
• Include sidecar data via jsonData for complete validation
• Process files in batches for large datasets

Purpose: Validates HED sidecar JSON files

When to use:

• Validating BIDS sidecar files
• Checking JSON structure and HED content
• Converting between sidecar formats

Parameters:

• filePath (required): Path to JSON sidecar file
• hedVersion (required): Schema version
• checkForWarnings (optional): Include warnings
• fileData (optional): Inline JSON data

Best practices:

• Validate sidecar files before TSV files
• Use parsed output for debugging sidecar structure
• Check both structure and HED content validity

Purpose: Retrieves files from the local filesystem

When to use:

• Reading configuration files
• Accessing data files for validation
• File system operations

Parameters:

• filePath (required): Absolute path to the file

Best practices:

• Use absolute file paths
• Check file permissions and existence
• Handle file encoding properly (UTF-8 recommended)

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

{
  "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))"
      ]
    }
  }
}

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

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

1. Schema Selection: Choose appropriate HED schema version
2. Definition Setup: Prepare any custom definitions
3. Data Validation: Run appropriate validation tool
4. Issue Resolution: Address errors and warnings
5. Quality Assurance: Final validation with warnings enabled

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

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

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

1. TAG_INVALID: Tag not found in schema

   • Check spelling and capitalization
   • Verify tag exists in specified schema version
   • Consider using extension tags if appropriate

2. DEFINITION_INVALID: Malformed definition

   • Ensure proper parentheses around definition content
   • Check that definition name follows conventions
   • Verify definition content is valid HED

3. SCHEMA_LOAD_FAILED: Invalid schema version

   • Verify schema version exists
   • Check network connectivity for schema download
   • Use stable, released schema versions

4. FILE_READ_ERROR: Cannot read specified file

   • Verify file path and permissions
   • Check file exists and is readable
   • Consider using inline data for virtual files

1. TAG_EXTENDED: Extension tag used

   • Consider using more specific standard tags
   • Acceptable for novel experimental paradigms
   • Document extensions for reproducibility

2. DEFINITION_WARNING: Definition issues

   • Non-critical definition problems
   • May indicate style or convention issues
   • Review definition structure and content

1. Specificity: Use most specific appropriate tags
2. Consistency: Apply same annotation patterns throughout dataset
3. Completeness: Annotate all relevant aspects of events
4. Accuracy: Ensure annotations match actual experimental events

• All files validate without errors
• Warnings reviewed and addressed where appropriate
• Definitions properly documented
• Schema version appropriate for dataset
• Annotations consistent across similar events

The HED MCP server can be used in browsers through several approaches. All browser files are located in the examples/ directory.

Open examples/hed-validator.html for a full-featured web interface:

• Multiple validation modes: String, TSV, and Sidecar validation
• Modern UI: Clean, responsive design with professional styling
• Real-time feedback: Instant validation results with detailed error reporting
• Multiple HED versions: Support for different schema versions and libraries

# Serve the examples locally
npx serve examples/

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

View examples/hed-demo.html for:

• Live examples: Pre-configured validation scenarios
• Integration guide: Complete API documentation and code examples
• Developer tools: Quick validation form for testing

Include the modern browser client in your web application:

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

For complete server-based validation, run the HTTP API server:

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

The browser client automatically detects and uses the server at http://localhost:3000/api/hed/.

Quick Start: Open examples/hed-validator.html to immediately start validating HED data in your browser!

<!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>

Add to your MCP client configuration:

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

Run the server in WebSocket mode for browser-based MCP clients:

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

The server respects standard Node.js environment variables:

• NODE_ENV: Set to development for verbose logging
• DEBUG: Enable debug output for troubleshooting

Enable debug logging:

DEBUG=* node dist/server.js

Or in MCP client configuration:

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

1. Naming: Use descriptive, unique names
2. Structure: Keep definitions simple and focused
3. Reusability: Design for reuse across similar experiments
4. Documentation: Document purpose and usage

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

The server automatically caches loaded schemas to improve performance:

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

Process definitions once and reuse:

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

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

• Monitor memory usage with large datasets
• Process files in batches if memory constrained
• Clear unused schema cache entries
• Use streaming for very large files

• Reuse server connections for multiple operations
• Cache schemas and definitions between operations
• Use inline data to avoid file I/O overhead
• Disable warnings for production validation

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

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

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())

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

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

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

1. Clone and install:

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

2. Start development:

   npm run dev  # Builds in watch mode

3. Test your changes:

   npm test

4. Test with inspector:

   npx @modelcontextprotocol/inspector node dist/server.js

Symptoms: Server exits immediately or shows connection errors

Solutions:

1. Check Node.js version (requires 18+)
2. Verify build completed successfully: npm run build
3. Check for port conflicts
4. Review error messages in console

Symptoms: SCHEMA_LOAD_FAILED errors

Solutions:

1. Verify internet connectivity for schema downloads
2. Use exact schema version strings
3. Check schema cache directory permissions
4. Try clearing cache: delete node_modules and reinstall

Symptoms: FILE_READ_ERROR when accessing files

Solutions:

1. Verify file paths are absolute
2. Check file permissions and existence
3. Use inline data (fileData) for testing
4. Ensure proper file encoding (UTF-8)

Symptoms: Different results from same input

Solutions:

1. Ensure consistent schema versions
2. Clear schema cache if needed
3. Check for concurrent validation conflicts
4. Verify definition ordering and consistency

• Monitor memory usage with large datasets
• Process files in batches if memory constrained
• Clear unused schema cache entries
• Use streaming for very large files

• Reuse server connections for multiple operations
• Cache schemas and definitions between operations
• Use inline data to avoid file I/O overhead
• Disable warnings for production validation

For detailed API documentation, see API.md.

Key concepts:

• FormattedIssue: Standardized error/warning format
• HedValidationResult: Standard validation response format
• Schema Caching: Automatic caching of loaded HED schemas
• Definition Support: Process and use HED definitions during validation

The project includes comprehensive tests covering:

• Unit tests: Individual function testing
• Integration tests: Tool interaction testing
• Data validation: Real HED data file testing

# 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

Test files are located in tests/data/:

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

1. Fork the repository
2. Create a feature branch: git checkout -b feature/amazing-feature
3. Make your changes and add tests
4. Run the test suite: npm test
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to the branch: git push origin feature/amazing-feature
7. Open a Pull Request

• Use TypeScript strict mode
• Follow existing naming conventions
• Add JSDoc comments for public APIs
• Ensure all tests pass before submitting

This project is licensed under the ISC License - see the LICENSE file for details.

• HED Specification
• HED JavaScript Library
• Model Context Protocol
• BIDS Specification

• Issues
• HED homepage
• Documentation