fronius-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Development Commands

• Development mode: npm run dev (uses tsx with hot reload)
• Build: npm run build (compiles TypeScript to dist/)
• Start production: npm start (runs compiled JavaScript)
• Install dependencies: npm install
• Lint: npm run lint (ESLint 9.x with flat config)
• Type check: npm run typecheck (TypeScript compiler check)
• Test connection: npm run test-connection (full API connectivity test)
• Docker build: npm run docker:build (build Docker image locally)
• Docker compose: docker-compose up -d (run with docker-compose)

Architecture Overview

This is a TypeScript-based Model Context Protocol (MCP) server that provides comprehensive access to Fronius solar inverter data. The application uses a modular architecture with proper separation of concerns and is designed for Claude Desktop integration.

Project Structure

src/
├── types/           # TypeScript type definitions
│   ├── fronius.ts   # Complete Fronius API response types
│   └── config.ts    # Configuration interfaces
├── services/        # Business logic services
│   ├── fronius-api.ts  # Full Fronius API client with retry logic
│   └── config.ts    # Configuration management and validation
├── handlers/        # MCP protocol handlers
│   ├── resources.ts # Resource-based data access
│   └── tools.ts     # Tool-based interactive access
├── utils/           # Utility functions
│   └── version.ts   # Centralized version management
└── server.ts        # Main server with error handling and lifecycle

Core Components

FroniusAPIClient (src/services/fronius-api.ts)

• Complete TypeScript implementation of Fronius Solar API v1
• Supports all major endpoints including GetStorageRealtimeData and GetOhmPilotRealtimeData
• No fallback values - proper error handling so LLM understands failures
• Configurable timeouts, retry counts, and connection parameters
• Built-in connection testing and health checks
• Uses centralized User-Agent from version utility