@energyatit/mcp-server 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @energyatit/mcp-server
+
+MCP server for the EnergyAtIt energy infrastructure platform. Connect Claude, GPT, or any MCP-compatible AI client to real energy grid data — dispatch batteries, verify carbon chains, run demand response, and more.
+
+## Quick Start
+
+```bash
+npx @energyatit/mcp-server
+```
+
+## Configure with Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "energyatit": {
+      "command": "npx",
+      "args": ["-y", "@energyatit/mcp-server"],
+      "env": {
+        "ENERGYATIT_API_KEY": "eat_live_your_key_here"
+      }
+    }
+  }
+}
+```
+
+## Configure with Claude Code
+
+```bash
+claude mcp add energyatit -- npx -y @energyatit/mcp-server
+```
+
+Set your API key:
+```bash
+export ENERGYATIT_API_KEY=eat_live_your_key_here
+```
+
+## Environment Variables
+
+| Variable | Description |
+|----------|-------------|
+| `ENERGYATIT_API_KEY` | Your API key (`eat_live_xxx` or `eat_test_xxx`) |
+| `ENERGYATIT_TOKEN` | JWT token (alternative to API key) |
+| `ENERGYATIT_BASE_URL` | API base URL (default: `https://energyatit.com`) |
+
+## Available Tools
+
+### Sites & Assets
+- `list_sites` — List all energy sites
+- `get_site` — Get site details
+- `list_assets` — List assets (BESS, HVAC, Solar, EV chargers)
+- `list_grid_connections` — List grid connections
+
+### Dispatch
+- `dispatch_command` — Send commands to assets (charge, discharge, curtail, shed_load)
+- `dispatch_history` — View dispatch history
+
+### Carbon Attestation
+- `create_carbon_record` — Append to the SHA-256 hash chain
+- `verify_carbon_chain` — Verify hash chain integrity
+- `get_carbon_certificate` — Generate carbon certificates
+- `get_carbon_attestation` — Get attestation for a site
+
+### Demand Response
+- `create_dr_event` — Create DR events (shed, shift, shimmy)
+- `list_dr_events` — List DR events
+- `dispatch_dr_event` — Execute DR dispatch
+- `settle_dr_event` — Settle with carbon attestation
+
+### Settlements
+- `generate_settlement` — Generate hash-chained settlement
+- `verify_settlement` — Verify settlement integrity
+- `list_settlements` — List settlements
+
+### Compliance
+- `generate_compliance_package` — IEC 61850, ISO 50001, GHG Scope 2
+- `list_compliance_packages` — List packages
+- `generate_scope2_report` — GHG Scope 2 report
+
+### Intelligence
+- `get_asset_reliability` — Asset reliability score
+- `get_site_reliability` — Site reliability score
+- `get_grid_capacity` — Grid capacity by region
+- `get_grid_trends` — Historical grid trends
+
+### Procurement
+- `create_procurement` — PPA, REC, carbon offset requests
+- `analyze_procurement` — Run procurement analysis
+- `get_procurement_options` — Get available options
+
+### Sandbox
+- `provision_sandbox` — Get a sandbox environment with test data
+- `sandbox_status` — Check sandbox usage
+
+## Get an API Key
+
+1. Sign up at [energyatit.com](https://energyatit.com)
+2. Go to Settings > API Keys
+3. Create a new key
+4. Or provision a sandbox: use the `provision_sandbox` tool
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,494 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// ─── Config ────────────────────────────────────────────────────────────────
+const BASE_URL = (process.env.ENERGYATIT_BASE_URL ??
+    process.env.ENERGYATIT_URL ??
+    "https://energyatit.com").replace(/\/$/, "");
+const API_KEY = process.env.ENERGYATIT_API_KEY ?? "";
+const TOKEN = process.env.ENERGYATIT_TOKEN ?? "";
+function authHeaders() {
+    const h = { "Content-Type": "application/json" };
+    if (TOKEN)
+        h["Authorization"] = `Bearer ${TOKEN}`;
+    else if (API_KEY)
+        h["X-API-Key"] = API_KEY;
+    return h;
+}
+// ─── HTTP helpers ──────────────────────────────────────────────────────────
+async function apiGet(path) {
+    const res = await fetch(`${BASE_URL}${path}`, { headers: authHeaders() });
+    const json = await res.json();
+    if (json.success === false)
+        throw new Error(String(json.error ?? `API error ${res.status}`));
+    return json.data ?? json;
+}
+async function apiPost(path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: "POST",
+        headers: authHeaders(),
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const json = await res.json();
+    if (json.success === false)
+        throw new Error(String(json.error ?? `API error ${res.status}`));
+    return json.data ?? json;
+}
+async function apiPatch(path, body) {
+    const res = await fetch(`${BASE_URL}${path}`, {
+        method: "PATCH",
+        headers: authHeaders(),
+        body: body ? JSON.stringify(body) : undefined,
+    });
+    const json = await res.json();
+    if (json.success === false)
+        throw new Error(String(json.error ?? `API error ${res.status}`));
+    return json.data ?? json;
+}
+function text(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+}
+function errorResult(err) {
+    return { content: [{ type: "text", text: `Error: ${err instanceof Error ? err.message : String(err)}` }], isError: true };
+}
+// ─── MCP Server ────────────────────────────────────────────────────────────
+const server = new McpServer({
+    name: "energyatit",
+    version: "0.1.0",
+});
+// ── Sites ────────────────────────────────────────────────────────────────
+server.tool("list_sites", "List all energy sites in your tenant", {}, async () => {
+    try {
+        return text(await apiGet("/api/sites"));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("get_site", "Get details of a specific site", {
+    site_id: z.number().describe("Site ID"),
+}, async ({ site_id }) => {
+    try {
+        return text(await apiGet(`/api/sites/${site_id}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Assets ───────────────────────────────────────────────────────────────
+server.tool("list_assets", "List assets, optionally filtered by site", {
+    site_id: z.number().optional().describe("Optional site ID filter"),
+}, async ({ site_id }) => {
+    try {
+        const qs = site_id ? `?siteId=${site_id}` : "";
+        return text(await apiGet(`/api/assets${qs}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Grid Connections ─────────────────────────────────────────────────────
+server.tool("list_grid_connections", "List grid connections for a site", {
+    site_id: z.number().describe("Site ID"),
+}, async ({ site_id }) => {
+    try {
+        return text(await apiGet(`/api/grid-connections?siteId=${site_id}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Meter Readings ───────────────────────────────────────────────────────
+server.tool("get_meter_readings", "Get meter readings for a grid connection", {
+    grid_connection_id: z.number().describe("Grid connection ID"),
+}, async ({ grid_connection_id }) => {
+    try {
+        return text(await apiGet(`/api/meter-readings?gridConnectionId=${grid_connection_id}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Dispatch ─────────────────────────────────────────────────────────────
+server.tool("dispatch_command", "Send a dispatch command to an asset (battery, HVAC, EV charger, etc.)", {
+    asset_id: z.number().describe("Asset ID"),
+    command: z.string().describe("Command: charge, discharge, reduce, curtail, shed_load, restore"),
+    target_kw: z.number().optional().describe("Target power in kW"),
+    duration_minutes: z.number().optional().describe("Duration in minutes"),
+}, async ({ asset_id, command, target_kw, duration_minutes }) => {
+    try {
+        return text(await apiPost(`/api/v1/dispatch/${asset_id}/command`, {
+            command,
+            targetKw: target_kw,
+            durationMinutes: duration_minutes,
+        }));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("dispatch_history", "Get dispatch history for an asset", {
+    asset_id: z.number().describe("Asset ID"),
+}, async ({ asset_id }) => {
+    try {
+        return text(await apiGet(`/api/v1/dispatch/${asset_id}/history`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Settlements ──────────────────────────────────────────────────────────
+server.tool("list_settlements", "List settlements for a site", {
+    site_id: z.number().optional().describe("Optional site ID filter"),
+}, async ({ site_id }) => {
+    try {
+        const qs = site_id ? `?siteId=${site_id}` : "";
+        return text(await apiGet(`/api/settlements${qs}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("generate_settlement", "Generate a hash-chained settlement for a site", {
+    site_id: z.number().describe("Site ID"),
+    period_start: z.string().describe("Period start (ISO date)"),
+    period_end: z.string().describe("Period end (ISO date)"),
+}, async ({ site_id, period_start, period_end }) => {
+    try {
+        return text(await apiGet(`/api/v1/settlements/${site_id}/generate?periodStart=${period_start}&periodEnd=${period_end}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("verify_settlement", "Verify a settlement's hash chain integrity", {
+    settlement_id: z.number().describe("Settlement ID"),
+}, async ({ settlement_id }) => {
+    try {
+        return text(await apiGet(`/api/v1/settlements/${settlement_id}/verify`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Carbon Attestation ───────────────────────────────────────────────────
+server.tool("get_carbon_attestation", "Get carbon attestation for a site", {
+    site_id: z.number().describe("Site ID"),
+}, async ({ site_id }) => {
+    try {
+        return text(await apiGet(`/api/v1/settlements/${site_id}/carbon-attestation`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("create_carbon_record", "Create a carbon attestation record in the hash chain", {
+    meter_id: z.string().describe("Meter ID"),
+    facility_id: z.string().describe("Facility UUID"),
+    timestamp: z.string().describe("ISO timestamp"),
+    kwh: z.number().describe("Energy in kWh"),
+    grid_zone: z.string().optional().describe("Grid zone"),
+}, async (params) => {
+    try {
+        return text(await apiPost("/api/v1/carbon/record", {
+            meterId: params.meter_id,
+            facilityId: params.facility_id,
+            timestamp: params.timestamp,
+            kwh: params.kwh,
+            gridZone: params.grid_zone,
+        }));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("verify_carbon_chain", "Verify the SHA-256 hash chain for a meter", {
+    meter_id: z.string().describe("Meter ID"),
+}, async ({ meter_id }) => {
+    try {
+        return text(await apiGet(`/api/v1/carbon/verify/${meter_id}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("get_carbon_certificate", "Generate a carbon certificate for a facility", {
+    facility_id: z.string().describe("Facility UUID"),
+    start: z.string().describe("Period start (ISO date)"),
+    end: z.string().describe("Period end (ISO date)"),
+}, async ({ facility_id, start, end }) => {
+    try {
+        return text(await apiGet(`/api/v1/carbon/certificate/${facility_id}?start=${start}&end=${end}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Demand Response ──────────────────────────────────────────────────────
+server.tool("create_dr_event", "Create a demand response event", {
+    signal_type: z.string().describe("Signal type: shed, shift, shimmy"),
+    facility_id: z.string().describe("Facility UUID"),
+    scheduled_start: z.string().describe("Start time (ISO)"),
+    target_reduction_kw: z.number().optional().describe("Target reduction in kW"),
+    duration_minutes: z.number().optional().describe("Duration in minutes"),
+}, async (params) => {
+    try {
+        return text(await apiPost("/api/v1/dr/events", {
+            signalType: params.signal_type,
+            facilityId: params.facility_id,
+            scheduledStart: params.scheduled_start,
+            targetReductionKw: params.target_reduction_kw,
+            durationMinutes: params.duration_minutes,
+        }));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("list_dr_events", "List demand response events", {
+    status: z.string().optional().describe("Filter by status"),
+    facility_id: z.string().optional().describe("Filter by facility"),
+}, async ({ status, facility_id }) => {
+    try {
+        const qs = new URLSearchParams();
+        if (status)
+            qs.set("status", status);
+        if (facility_id)
+            qs.set("facility_id", facility_id);
+        const q = qs.toString() ? `?${qs.toString()}` : "";
+        return text(await apiGet(`/api/v1/dr/events${q}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("get_dr_event", "Get details of a DR event", {
+    event_id: z.string().describe("Event UUID"),
+}, async ({ event_id }) => {
+    try {
+        return text(await apiGet(`/api/v1/dr/events/${event_id}`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("dispatch_dr_event", "Execute dispatch for a DR event", {
+    event_id: z.string().describe("Event UUID"),
+}, async ({ event_id }) => {
+    try {
+        return text(await apiPost(`/api/v1/dr/events/${event_id}/dispatch`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("settle_dr_event", "Settle a DR event with carbon attestation", {
+    event_id: z.string().describe("Event UUID"),
+}, async ({ event_id }) => {
+    try {
+        return text(await apiPost(`/api/v1/dr/events/${event_id}/settle`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Compliance ───────────────────────────────────────────────────────────
+server.tool("generate_compliance_package", "Generate a compliance package for a site", {
+    site_id: z.number().describe("Site ID"),
+    standard: z.string().optional().describe("Standard: IEC61850, ISO50001, GHG_Scope2"),
+}, async ({ site_id, standard }) => {
+    try {
+        return text(await apiPost(`/api/v1/comply/${site_id}/generate`, { standard }));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("list_compliance_packages", "List compliance packages for a site", {
+    site_id: z.number().describe("Site ID"),
+}, async ({ site_id }) => {
+    try {
+        return text(await apiGet(`/api/v1/comply/${site_id}/packages`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("generate_scope2_report", "Generate GHG Scope 2 compliance report", {
+    facility_id: z.string().describe("Facility UUID"),
+    period_start: z.string().describe("Period start"),
+    period_end: z.string().describe("Period end"),
+    methodology: z.enum(["location-based", "market-based", "dual"]).optional(),
+}, async (params) => {
+    try {
+        return text(await apiPost("/api/v1/comply/report", {
+            facility_id: params.facility_id,
+            period_start: params.period_start,
+            period_end: params.period_end,
+            methodology: params.methodology,
+        }));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Intel ────────────────────────────────────────────────────────────────
+server.tool("get_asset_reliability", "Get reliability score for an asset", {
+    asset_id: z.number().describe("Asset ID"),
+}, async ({ asset_id }) => {
+    try {
+        return text(await apiGet(`/api/v1/intel/assets/${asset_id}/score`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("get_site_reliability", "Get reliability score for a site", {
+    site_id: z.number().describe("Site ID"),
+}, async ({ site_id }) => {
+    try {
+        return text(await apiGet(`/api/v1/intel/sites/${site_id}/score`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("get_grid_capacity", "Get grid capacity for a region", {
+    region: z.string().describe("Region code (e.g. AE-DXB, PH-LUZ)"),
+}, async ({ region }) => {
+    try {
+        return text(await apiGet(`/api/v1/intel/grid/${region}/capacity`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("get_grid_trends", "Get grid capacity trends for a region", {
+    region: z.string().describe("Region code"),
+}, async ({ region }) => {
+    try {
+        return text(await apiGet(`/api/v1/intel/grid/${region}/trends`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Procurement ──────────────────────────────────────────────────────────
+server.tool("create_procurement", "Create an energy procurement request", {
+    type: z.string().describe("Type: ppa, rec, carbon_offset"),
+    volume_kwh: z.number().describe("Volume in kWh"),
+    region: z.string().optional().describe("Region"),
+}, async (params) => {
+    try {
+        return text(await apiPost("/api/v1/procurement", params));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("analyze_procurement", "Run analysis on a procurement request", {
+    id: z.number().describe("Procurement request ID"),
+}, async ({ id }) => {
+    try {
+        return text(await apiPost(`/api/v1/procurement/${id}/analyze`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("get_procurement_options", "Get procurement options", {
+    id: z.number().describe("Procurement request ID"),
+}, async ({ id }) => {
+    try {
+        return text(await apiGet(`/api/v1/procurement/${id}/options`));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Integration Status ───────────────────────────────────────────────────
+server.tool("get_integration_status", "Get status of all integrations (Modbus, OpenADR, BESS, grid prices)", {}, async () => {
+    try {
+        return text(await apiGet("/api/v1/integrations/status"));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("get_grid_prices", "Get current grid electricity prices", {
+    region: z.string().optional().describe("Region code"),
+}, async ({ region }) => {
+    try {
+        const path = region ? `/api/v1/integrations/grid-prices/${region}` : "/api/v1/integrations/grid-prices";
+        return text(await apiGet(path));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Sandbox ──────────────────────────────────────────────────────────────
+server.tool("provision_sandbox", "Provision a developer sandbox environment with simulated data", {}, async () => {
+    try {
+        return text(await apiPost("/api/v1/sandbox/provision"));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+server.tool("sandbox_status", "Check sandbox environment status and usage", {}, async () => {
+    try {
+        return text(await apiGet("/api/v1/sandbox/status"));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ── Health ───────────────────────────────────────────────────────────────
+server.tool("health_check", "Check platform health and connectivity", {}, async () => {
+    try {
+        return text(await apiGet("/api/health"));
+    }
+    catch (e) {
+        return errorResult(e);
+    }
+});
+// ─── Resources ─────────────────────────────────────────────────────────────
+server.resource("platform-overview", "energyatit://overview", async () => ({
+    contents: [{
+            uri: "energyatit://overview",
+            mimeType: "text/plain",
+            text: [
+                "EnergyAtIt — Energy Infrastructure Platform",
+                "",
+                "Capabilities:",
+                "  - Sites & Assets: Manage energy sites, assets (BESS, HVAC, Solar, EV chargers)",
+                "  - Dispatch: Send commands to batteries, HVAC, EV chargers",
+                "  - Carbon Attestation: SHA-256 hash-chained carbon records with certificates",
+                "  - Demand Response: Create, dispatch, measure, and settle DR events",
+                "  - Settlements: Generate and verify hash-chained energy settlements",
+                "  - Compliance: Generate IEC 61850, ISO 50001, GHG Scope 2 packages",
+                "  - Intel: Reliability scores, grid capacity, load forecasting",
+                "  - Procurement: PPA, REC, and carbon offset procurement",
+                "  - Integrations: Modbus, OpenADR 2.0b, OCPP 2.0, IEC 61850",
+                "",
+                `Connected to: ${BASE_URL}`,
+                `Auth: ${TOKEN ? "JWT token" : API_KEY ? "API key" : "none (set ENERGYATIT_API_KEY)"}`,
+            ].join("\n"),
+        }],
+}));
+// ─── Start ─────────────────────────────────────────────────────────────────
+async function main() {
+    if (!API_KEY && !TOKEN) {
+        console.error("Warning: No ENERGYATIT_API_KEY or ENERGYATIT_TOKEN set. Requests will be unauthenticated.");
+        console.error("Set ENERGYATIT_API_KEY=eat_live_xxx or ENERGYATIT_TOKEN=jwt_xxx in your environment.");
+    }
+    console.error(`EnergyAtIt MCP server v0.1.0 — connecting to ${BASE_URL}`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("EnergyAtIt MCP server running on stdio");
+}
+main().catch((err) => {
+    console.error("Failed to start MCP server:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@energyatit/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for EnergyAtIt — connect Claude, GPT, or any MCP client to energy grid data",
+  "type": "module",
+  "bin": {
+    "energyatit-mcp": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp", "energy", "grid", "ai", "agent", "claude", "openai",
+    "carbon", "dispatch", "settlement", "compliance", "demand-response",
+    "openadr", "modbus", "iec61850"
+  ],
+  "author": "EnergyAtIt <dsk@energyatit.com>",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.0"
+  }
+}