# eco2mix-mcp — Carbon-Aware Kiro 🌱⚡

eco2mix-mcp is a custom **MCP server** that connects Kiro to the **French
power grid in real time** (RTE éCO2mix open data: carbon intensity,
consumption, generation mix — no API key needed). Paired with a steering
rule, it makes Kiro **carbon-aware**: before launching a heavy job (test
suite, docker build, batch), Kiro checks the live grid and answers GO or
DEFER. Run your builds when the electrons are clean.

Built for **Day 5 of the Kiro Birthday challenge**
(https://kiro.dev/birthday/): *"Build a custom MCP integration"*.

## How Kiro was used

Kiro was used end-to-end, **spec-first**. The [`.kiro/specs/eco2mix-mcp/`](.kiro/specs/eco2mix-mcp/)
folder contains the requirements (EARS-style acceptance criteria), the
design (architecture, thresholds, error handling), and the task list that
drove the build — from validating the ODRE open-data API (including its
trap: future 15-minute slots exist with null values and must be filtered)
to implementing and testing the server.

The MCP server is built with the official Python MCP SDK (FastMCP, stdio
transport). The pure logic is covered by 8 unit tests; the MCP handshake
and each tool were verified against the real API before wiring anything
into Kiro.

The integration is registered in [`.kiro/settings/mcp.json`](.kiro/settings/mcp.json),
so Kiro spawns the server automatically. The interesting part is
[`.kiro/steering/carbon-aware.md`](.kiro/steering/carbon-aware.md): it
instructs Kiro to call `should_i_run_now` before launching any heavy
command (full test suite, docker build, batch job, model training) and to
act on the verdict — GO when the grid is CLEAN, defer when fossil peakers
push the intensity up. In the demo, Kiro is asked whether it should run a
full test suite and docker build now: it calls the tool, reads
11 gCO2/kWh (CLEAN, stable trend over the last 2 hours), and answers GO
with its reasoning. This is something Kiro fundamentally could not do
without the integration: no training data can know the state of the power
grid *right now*.

## What it connects to

[RTE éCO2mix](https://www.rte-france.com/eco2mix) real-time national data,
served by the [ODRE open-data platform](https://opendata.reseaux-energies.fr)
(dataset `eco2mix-national-tr`). Live, 15-minute resolution:
electricity consumption, **carbon intensity (gCO2eq/kWh)**, and the full
generation mix (nuclear, wind, solar, hydro, gas, coal, oil, bioenergy).

**No API key. No secrets. Public open data** (Etalab open licence).

Why it matters: an LLM's training data can never know that the French grid
is at 11 gCO2/kWh *right now* because solar is peaking. This integration
gives Kiro that knowledge — and something it genuinely could not do
without it.

## Tools

| Tool | What Kiro gets |
|------|----------------|
| `get_current_grid` | Full live snapshot: consumption, intensity, generation mix |
| `get_carbon_intensity` | gCO2/kWh + verdict: CLEAN / MODERATE / DIRTY |
| `get_mix_breakdown` | Generation by source (MW), low-carbon & renewable shares |
| `should_i_run_now` | GO / GO_WITH_CAUTION / DEFER for a heavy job + 2h trend |

## What I built with it: a carbon-aware Kiro

`.kiro/steering/carbon-aware.md` instructs Kiro to call `should_i_run_now`
**before launching any heavy command** (full test suite, docker build,
batch job, model training) and to act on the recommendation:

- 🟢 `GO` — grid is clean, run it (and say the current intensity)
- 🟡 `GO_WITH_CAUTION` — urgent work only
- 🔴 `DEFER` — fossil peakers running; Kiro proposes to wait for a
  cleaner window using the 2-hour trend

Shifting deferrable compute to low-carbon windows is one of the simplest
green-IT practices. This project makes Kiro apply it automatically.

**Beyond the demo**: a local build is just the illustration — its footprint
is symbolic. The pattern is what scales: CI/CD farms, data batch jobs, ML
training, any deferrable workload that can slide a few hours into a
low-carbon window. This is the core idea of carbon-aware computing,
applied to a coding agent.

## Setup

```bash
git clone https://github.com/el-pedrito/eco2mix-mcp.git
cd eco2mix-mcp
python3 -m venv .venv
./.venv/bin/pip install -r requirements.txt
./.venv/bin/pytest tests/    # 8 tests, no network needed
```

The server is registered for Kiro in `.kiro/settings/mcp.json` (stdio):

```json
{
  "mcpServers": {
    "eco2mix": {
      "command": ".venv/bin/python",
      "args": ["server/eco2mix_mcp.py"]
    }
  }
}
```

Open Kiro in this folder and ask:

> *"Should I run my full test suite and docker build now?"*

Kiro calls the MCP server, which queries the live grid, and answers with
the current carbon intensity, the trend, and a go/defer recommendation.

## Configuration (optional, no secrets)

See `.env.example`. Everything works with zero configuration; you can
tune thresholds and timeouts via environment variables:

| Variable | Default | Purpose |
|----------|---------|---------|
| `ECO2MIX_CLEAN_THRESHOLD` | `25` | Max gCO2/kWh for a CLEAN verdict |
| `ECO2MIX_MODERATE_THRESHOLD` | `60` | Max gCO2/kWh for MODERATE |
| `ECO2MIX_TIMEOUT_S` | `15` | HTTP timeout |
| `ECO2MIX_API_BASE` | ODRE endpoint | Override the data endpoint |

## Demo

![eco2mix-mcp demo — Kiro checks the live grid before running a heavy build](demo/eco2mix-demo.gif)

Kiro calls the `eco2mix` MCP server, which queries the live French grid,
and decides whether to run the heavy job — end-to-end (MCP server → ODRE
API → live grid data → Kiro's decision).
[Full-quality video (mp4, 65s)](demo/eco2mix-demo.mp4).

## Project structure

```
server/eco2mix_mcp.py     # the MCP server (FastMCP, stdio, ~180 lines)
tests/test_eco2mix.py     # unit tests on the pure logic
.kiro/settings/mcp.json   # Kiro wiring
.kiro/steering/carbon-aware.md   # the carbon-aware behavior
.kiro/specs/eco2mix-mcp/  # the Kiro spec that drove the build
```

## Data & licence

Data: RTE éCO2mix via ODRE, [Etalab open licence](https://www.etalab.gouv.fr/licence-ouverte-open-licence).
Scope: France national grid. Carbon intensity method: RTE.