@flexabrain/mcp-server/docs/API.md

Advanced electrical schematic analysis MCP server with rail engineering expertise

# 📚 FlexaBrain MCP Server - API Reference

Complete documentation for all MCP tools, types, and interfaces.

---

## 🛠️ **MCP Tools**

### 1. Analyze Electrical Schematic

**Primary analysis tool providing comprehensive electrical schematic assessment.**

```typescript
function analyzeElectricalSchematic(args: AnalyzeSchematicArgs): Promise<MCPToolResponse>
```

#### Parameters

```typescript
interface AnalyzeSchematicArgs {
  image_path: string;                                    // Required: Path to schematic image
  analysis_depth?: 'basic' | 'standard' | 'comprehensive'; // Analysis detail level
  focus_areas?: ('safety' | 'compliance' | 'performance' | 'maintenance')[]; // Analysis focus
  rail_system_context?: {
    system_type: 'METRO' | 'LIGHT_RAIL' | 'HEAVY_RAIL' | 'HIGH_SPEED' | 'FREIGHT';
    voltage_system: string;                              // e.g., "1500V DC", "25kV AC"
    region: string;                                      // Geographic region
    applicable_standards: string[];                      // Relevant standards
  };
  custom_standards?: string[];                           // Additional standards to check
}
```

#### Returns

**Rich markdown report including:**
- Component inventory with confidence scores
- Safety analysis (arc flash, electrical shock, grounding)
- Standards compliance assessment  
- Circuit topology analysis
- Maintenance recommendations
- Expert recommendations with priority levels
- Performance metrics and optimization opportunities

#### Example

```typescript
const result = await analyzeElectricalSchematic({
  image_path: './schematics/metro-traction.png',
  analysis_depth: 'comprehensive',
  focus_areas: ['safety', 'compliance', 'maintenance'],
  rail_system_context: {
    system_type: 'METRO',
    voltage_system: '1500V DC',
    region: 'US',
    applicable_standards: ['EN 50155', 'IEC 61375']
  }
});
```

---

### 2. Extract Component Inventory

**Generate detailed component catalogs with specifications and categorization.**

```typescript
function extractComponentInventory(args: ExtractInventoryArgs): Promise<string>
```

#### Parameters

```typescript
interface ExtractInventoryArgs {
  image_path: string;                     // Required: Path to schematic image
  output_format: 'JSON' | 'CSV' | 'PDF'; // Output format
  include_specifications?: boolean;        // Include component specs
  group_by_category?: boolean;            // Group components by category
  filter_by_type?: ComponentType[];       // Filter specific component types
  min_confidence?: number;                // Minimum confidence threshold
}
```

#### Returns

**Structured component inventory report:**
- Total component count and recognition statistics
- Components grouped by category (traction_power, protection, signaling, etc.)
- Detailed component list with specifications
- Export data in requested format
- Quality metrics and confidence scores

#### Example

```typescript
const inventory = await extractComponentInventory({
  image_path: './schematic.png',
  output_format: 'JSON',
  include_specifications: true,
  group_by_category: true,
  min_confidence: 0.8
});
```

---

### 3. Validate Electrical Standards

**Comprehensive standards compliance validation against electrical and rail regulations.**

```typescript
function validateElectricalStandards(args: ValidateStandardsArgs): Promise<string>
```

#### Parameters

```typescript
interface ValidateStandardsArgs {
  image_path: string;                     // Required: Path to schematic image
  standards: string[];                    // Required: Standards to validate against
  validation_level?: 'basic' | 'comprehensive' | 'detailed'; // Validation depth
  rail_system_type?: string;              // Rail system context
  region?: 'EU' | 'US' | 'ASIA' | 'GLOBAL'; // Regional standards focus
  custom_criteria?: string[];             // Additional validation criteria
}
```

#### Supported Standards

- **IEC Standards**: 61375, 62278, 62279, 62425
- **IEEE Standards**: 1584 (Arc Flash), 519 (Harmonics), 80 (Safety)
- **EN Standards**: 50155 (Railway Electronics), 50121 (EMC), 50126 (RAMS)
- **NFPA Standards**: 70E (Electrical Safety), 70 (NEC)
- **Rail-Specific**: TSI, ERTMS, CENELEC, FRA regulations

#### Returns

**Detailed compliance report:**
- Overall compliance score (0-100%)
- Standards analysis with pass/fail status
- Non-compliance issues with remediation suggestions
- Items requiring expert review
- Compliance trends and patterns

#### Example

```typescript
const compliance = await validateElectricalStandards({
  image_path: './schematic.png',
  standards: ['EN 50155', 'IEC 61375', 'IEEE 1584'],
  validation_level: 'comprehensive',
  rail_system_type: 'HIGH_SPEED',
  region: 'EU'
});
```

---

### 4. Analyze Power Flow

**Advanced power system analysis with efficiency calculations and optimization recommendations.**

```typescript
function analyzePowerFlow(args: PowerFlowArgs): Promise<string>
```

#### Parameters

```typescript
interface PowerFlowArgs {
  image_path: string;                     // Required: Path to schematic image
  analysis_focus?: 'traction' | 'auxiliary' | 'signaling' | 'complete'; // Analysis scope
  load_profile?: 'peak' | 'normal' | 'minimum'; // Load conditions
  include_harmonics?: boolean;            // Include harmonic analysis
  system_voltage?: number;                // System nominal voltage
  power_quality_assessment?: boolean;     // Include power quality metrics
}
```

#### Returns

**Comprehensive power analysis:**
- Power sources and load identification
- Power flow calculations and efficiency metrics
- Load balancing analysis
- Harmonic distortion assessment
- Optimization recommendations
- Energy savings opportunities

#### Example

```typescript
const powerAnalysis = await analyzePowerFlow({
  image_path: './traction-power.png',
  analysis_focus: 'traction',
  load_profile: 'peak',
  include_harmonics: true,
  system_voltage: 25000,
  power_quality_assessment: true
});
```

---

### 5. Generate Maintenance Schedule

**Intelligent maintenance scheduling based on component types and rail engineering best practices.**

```typescript
function generateMaintenanceSchedule(args: MaintenanceArgs): Promise<string>
```

#### Parameters

```typescript
interface MaintenanceArgs {
  image_path: string;                     // Required: Path to schematic image
  rail_system_type: string;               // Required: Rail system type
  maintenance_strategy: 'PREVENTIVE' | 'PREDICTIVE' | 'CONDITION_BASED'; // Strategy
  time_horizon_months: number;            // Planning horizon
  include_cost_estimates?: boolean;       // Include cost projections
  priority_components?: string[];         // Focus on specific components
}
```

#### Returns

**Detailed maintenance plan:**
- Component-specific maintenance calendars
- Priority actions with urgency levels
- Cost estimates and resource requirements
- Maintenance optimization recommendations
- Risk-based scheduling priorities

#### Example

```typescript
const schedule = await generateMaintenanceSchedule({
  image_path: './substation.png',
  rail_system_type: 'METRO',
  maintenance_strategy: 'PREDICTIVE',
  time_horizon_months: 24,
  include_cost_estimates: true
});
```

---

### 6. Check Safety Compliance

**Comprehensive safety analysis including arc flash hazard assessment and PPE requirements.**

```typescript
function checkSafetyCompliance(args: SafetyComplianceArgs): Promise<string>
```

#### Parameters

```typescript
interface SafetyComplianceArgs {
  image_path: string;                     // Required: Path to schematic image
  voltage_level: number;                  // Required: System voltage level
  safety_standards: string[];             // Safety standards to validate
  include_arc_flash_analysis?: boolean;   // Include arc flash calculations
  include_ppe_recommendations?: boolean;  // Include PPE requirements
  worker_category?: 'qualified' | 'unqualified'; // Worker qualification level
}
```

#### Returns

**Comprehensive safety assessment:**
- Overall safety level classification
- Arc flash analysis with incident energy calculations
- Electrical shock hazard assessment
- PPE category recommendations
- Safety boundary definitions
- Emergency response procedures

#### Example

```typescript
const safety = await checkSafetyCompliance({
  image_path: './hv-substation.png',
  voltage_level: 25000,
  safety_standards: ['NFPA 70E', 'IEEE 1584'],
  include_arc_flash_analysis: true,
  include_ppe_recommendations: true,
  worker_category: 'qualified'
});
```

---

### 7. Transform Schematic Image

**Advanced image preprocessing for improved OCR accuracy and analysis quality.**

```typescript
function transformSchematicImage(args: ImageTransformArgs): Promise<string>
```

#### Parameters

```typescript
interface ImageTransformArgs {
  input_path: string;                     // Required: Input image path
  output_path?: string;                   // Output path (optional)
  operations: ('enhance_contrast' | 'denoise' | 'binarize' | 'deskew' | 'resize' | 'crop' | 'rotate')[]; // Required: Operations to perform
  enhancement_level?: 'basic' | 'standard' | 'aggressive'; // Enhancement intensity
  target_dpi?: number;                    // Target resolution
  preserve_aspect_ratio?: boolean;        // Maintain aspect ratio
  output_format?: 'png' | 'jpg' | 'tiff'; // Output format
}
```

#### Available Operations

- **enhance_contrast**: Improve image contrast for better text recognition
- **denoise**: Remove noise and artifacts
- **binarize**: Convert to black and white for optimal OCR
- **deskew**: Correct image rotation and alignment
- **resize**: Scale image to optimal dimensions
- **crop**: Remove irrelevant borders and margins
- **rotate**: Correct orientation

#### Returns

**Image transformation report:**
- Processed image path and metadata
- Applied transformations and parameters
- Quality improvement metrics
- Processing statistics

#### Example

```typescript
const transformed = await transformSchematicImage({
  input_path: './raw-schematic.jpg',
  output_path: './processed-schematic.png',
  operations: ['enhance_contrast', 'denoise', 'binarize', 'deskew'],
  enhancement_level: 'standard',
  target_dpi: 300,
  output_format: 'png'
});
```

---

### 8. Batch Analyze Schematics

**Efficient batch processing with comparison analysis and consolidated reporting.**

```typescript
function batchAnalyzeSchematics(args: BatchAnalysisArgs): Promise<string>
```

#### Parameters

```typescript
interface BatchAnalysisArgs {
  input_directory: string;                // Required: Directory containing schematics
  file_pattern?: string;                  // File pattern filter (e.g., "*.png")
  analysis_depth?: 'basic' | 'standard' | 'comprehensive'; // Analysis level
  focus_areas?: ('safety' | 'compliance' | 'performance' | 'maintenance')[]; // Focus areas
  output_format?: 'JSON' | 'HTML' | 'PDF'; // Report format
  generate_comparison?: boolean;          // Generate comparison analysis
  parallel_processing?: boolean;          // Enable parallel processing
  max_concurrent?: number;                // Maximum concurrent analyses
  generate_summary_report?: boolean;      // Generate consolidated summary
}
```

#### Returns

**Comprehensive batch analysis:**
- Individual schematic analysis results
- Cross-schematic comparison and consistency analysis
- Consolidated project-level recommendations
- Batch processing statistics and performance metrics
- Summary reports and trend analysis

#### Example

```typescript
const batchResults = await batchAnalyzeSchematics({
  input_directory: './project-schematics/',
  file_pattern: '*.png',
  analysis_depth: 'standard',
  focus_areas: ['safety', 'compliance'],
  output_format: 'HTML',
  generate_comparison: true,
  parallel_processing: true,
  max_concurrent: 4
});
```

---

## 🔧 **Type Definitions**

### Core Types

```typescript
// Component Types
enum ComponentType {
  CONVERTER = 'converter',
  TRANSFORMER = 'transformer',
  CIRCUIT_BREAKER = 'circuit_breaker',
  CONTACTOR = 'contactor',
  RELAY = 'relay',
  SIGNAL_MODULE = 'signal_module',
  SIGNAL_REFERENCE = 'signal_reference',
  // ... additional types
}

// Component Categories
enum ComponentCategory {
  TRACTION_POWER = 'traction_power',
  AUXILIARY_POWER = 'auxiliary_power',
  SIGNALING = 'signaling',
  CONTROL = 'control',
  PROTECTION = 'protection',
  MEASUREMENT = 'measurement',
  COMMUNICATION = 'communication',
  UNCLASSIFIED = 'unclassified'
}

// Safety Levels
enum SafetyLevel {
  CRITICAL = 'critical',
  HIGH = 'high',
  MEDIUM = 'medium',
  LOW = 'low',
  SAFE = 'safe'
}

// Schematic Types
enum SchematicType {
  TRACTION_POWER = 'traction_power',
  SIGNALING = 'signaling',
  CONTROL = 'control',
  AUXILIARY = 'auxiliary',
  POWER_DISTRIBUTION = 'power_distribution',
  GENERAL = 'general'
}
```

### Component Specification

```typescript
interface ComponentSpecification {
  voltage_rating?: VoltageRange;
  current_rating?: CurrentRange;
  power_rating?: PowerRange;
  frequency?: FrequencyRange;
  operating_temperature?: TemperatureRange;
  standards_compliance: string[];
  safety_requirements: SafetyRequirement[];
  maintenance_intervals: MaintenanceSchedule;
  typical_applications?: string[];
}

interface VoltageRange {
  min: number;
  max: number;
  nominal?: number;
  unit: 'V_DC' | 'V_AC' | 'kV_DC' | 'kV_AC';
}

interface CurrentRange {
  min: number;
  max: number;
  nominal?: number;
  unit: 'A' | 'mA' | 'kA';
}

interface PowerRange {
  min: number;
  max: number;
  nominal?: number;
  unit: 'W' | 'kW' | 'MW' | 'VA' | 'kVA' | 'MVA';
}
```

### Analysis Results

```typescript
interface AnalysisResult {
  success: boolean;
  analysis?: SchematicAnalysis;
  errors?: AnalysisError[];
  warnings?: AnalysisWarning[];
  processing_stats: ProcessingStats;
}

interface SchematicAnalysis {
  image_path: string;
  schematic_type: SchematicType;
  analysis_timestamp: Date;
  processing_time: number;
  
  // Analysis results
  component_recognition: ComponentRecognitionResult;
  components: ElectricalComponent[];
  circuit_topology: CircuitTopology;
  safety_analysis: SafetyAnalysis;
  compliance_report: ComplianceReport;
  maintenance_guidance: MaintenanceGuidance;
  performance_analysis: PerformanceAnalysis;
  expert_recommendations: ExpertRecommendations;
  
  // Quality metrics
  overall_confidence: number;
  analysis_quality: 'EXCELLENT' | 'GOOD' | 'ACCEPTABLE' | 'POOR';
  limitations: string[];
  assumptions: string[];
}
```

---

## ⚡ **Performance Considerations**

### Response Times (Typical)

- **Basic Analysis**: 2-5 seconds
- **Standard Analysis**: 5-15 seconds  
- **Comprehensive Analysis**: 15-45 seconds
- **Batch Processing**: 30-120 seconds (depending on file count)

### Memory Usage

- **OCR Processing**: 50-200MB per image
- **Component Classification**: 10-50MB per schematic
- **Analysis Pipeline**: 100-500MB total working memory

### Optimization Tips

1. **Image Preprocessing**: Use [`transformSchematicImage`](#7-transform-schematic-image) to optimize images before analysis
2. **Batch Processing**: Use [`batchAnalyzeSchematics`](#8-batch-analyze-schematics) for multiple files
3. **Analysis Depth**: Choose appropriate depth based on requirements
4. **Focus Areas**: Limit focus areas to reduce processing time
5. **Parallel Processing**: Enable for batch operations when system resources allow

---

## 🛡️ **Error Handling**

### Common Error Codes

- **`IMAGE_NOT_FOUND`**: Image file does not exist or is not accessible
- **`INVALID_FORMAT`**: Unsupported image format
- **`OCR_FAILED`**: Text extraction failed due to poor image quality
- **`ANALYSIS_TIMEOUT`**: Analysis exceeded time limit
- **`INSUFFICIENT_CONTENT`**: No electrical components detected
- **`VALIDATION_ERROR`**: Invalid input parameters

### Error Response Format

```typescript
interface AnalysisError {
  code: string;
  message: string;
  details?: string;
  component_id?: string;
  recovery_suggestions: string[];
}
```

### Best Practices

1. **Input Validation**: Always validate file paths and parameters
2. **Error Handling**: Implement proper error handling for all tool calls
3. **Retry Logic**: Implement exponential backoff for transient failures
4. **Logging**: Log errors and processing times for debugging
5. **Resource Management**: Monitor memory and processing time limits

---

## 🔍 **Debugging**

### Debug Output

Set `DEBUG=true` environment variable to enable detailed logging:

```bash
DEBUG=true node dist/index.js
```

### Log Levels

- **ERROR**: Critical failures and exceptions
- **WARN**: Non-critical issues and warnings
- **INFO**: General processing information
- **DEBUG**: Detailed execution traces

### Performance Monitoring

```typescript
// Monitor processing times
const startTime = Date.now();
const result = await analyzeElectricalSchematic(args);
const processingTime = Date.now() - startTime;
console.log(`Analysis completed in ${processingTime}ms`);
```

---

*For additional support and examples, see the main [README](../README.md) and other documentation files.*