mcp-fsolar: Instructions file for Claude Code

CLAUDE.md — fsolar-mcp

Project overview

Felicity Solar battery MCP server + REST API. Exposes per-cell voltages, SOC, SOH, temperatures, BMS counters, balancing state, and computed health metrics to Claude and any MCP client.

Key documents

File	What it covers
README.md	Setup, usage modes (MCP, REST API, embedded, JS library, webhooks), env vars
CONTRIBUTING.md	Branch naming, conventional commits, PR process
SECURITY.md	Security policy and responsible disclosure
CHANGELOG.md	Release history
docs/ALGORITHMS.md	Every derived metric formula (cell delta, SOC, SOH, trend), snapshot persistence, webhook system

Running tests

npm test              # build + run all unit and security tests via node --test on dist/
npm run test:security # build + run only the live security tests (server must be running)

Security tests need a pre-started server and matching credentials:

FELICITY_USER=x FELICITY_PASS=y FELICITY_API_KEY=secret FELICITY_MODE=http node dist/server.js &
FELICITY_API_KEY=secret npm run test:security

Project structure

server.ts          Server factory (TypeScript source) — exports createServer() + startServer()
index.ts           Public API barrel (TypeScript source) — re-exports all public symbols
bin/
  fsolar-mcp.js    CLI entry point — calls dist/server.js main() after build
dist/              Compiled output (tsc → CommonJS + .d.ts); this is what npm publishes
src/
  constants.ts     all shared magic numbers and thresholds (health, autonomy, webhooks, cycles)
  errors.ts        AppError class (Error subclass with statusCode)
  logger.ts        createLogger() — injectable structured JSON logger (writes to stderr)
  middleware.ts    makeGetAllowedOrigin, makeCheckAuth, makeRateLimit, readBody factories
  hooks.ts         Webhook store, SSRF validation, event delivery, per-event cooldowns, retry
  compute.ts       Health metric derivation (computeHealth, computeAutonomy)
  analyze.ts       computeAlerts, computeEnergyHistory, computeCellStats, computePowerStats
  enums.ts         HealthStatus, HookEvent, TrendDirection, ChargingState
  client.ts        FelicityClient — auth, pagination, caching
  http.ts          felicityRequest using fetch() + AbortSignal.timeout()
  helpers.ts       sleep(), pickSnapshotFields(), pickNextSunrise() and other shared utilities
  state.ts         startPoller, readState, snapshotEmitter
  store.ts         SnapshotStore, BatterySnapshotStore, DailySnapshotStore
  battery.ts       buildBattery — raw Felicity API → typed Battery
  cache.ts         MemoryCacheAdapter, CacheAdapter interface
test/
  cache.test.ts      MemoryCacheAdapter unit tests
  client.test.ts     FelicityClient unit tests
  compute.test.ts    computeHealth + computeAutonomy unit tests
  errors.test.ts     AppError unit tests
  helpers.test.ts    nullableInt, clamp, sleep, pickSnapshotFields, pickNextSunrise
  hooks.test.ts      HookStore SSRF, cooldowns, event filtering
  logger.test.ts     createLogger JSON output
  middleware.test.ts CORS, auth, rate limit, body parsing
  snapshot.test.ts   BatterySnapshotStore trend computation
  transform.test.ts  buildBattery field mapping
  analyze.test.ts    computeAlerts, computeEnergyHistory, computeCellStats, computePowerStats unit tests
  server.test.ts     createServer HTTP route correctness and auth enforcement
  state.test.ts      startPoller, readState, snapshotEmitter unit tests
  config.test.ts     environment variable parsing and validation
  security.test.ts   Live HTTP security suite (auth, CORS, SSRF, rate limiting, webhooks)