Metadata-Version: 2.4
Name: prospector-energy-mcp
Version: 0.4.3
Summary: MCP server for Prospector Labs Energy Data API — interconnection queues, tax credits, developer intelligence, and deal sourcing. Supports agent payments via MPP.
Author: Prospector Labs
License-Expression: MIT
Requires-Python: >=3.10
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp<2,>=1.0.0
Provides-Extra: payments
Requires-Dist: pympp[mcp,tempo]<1,>=0.6.0; extra == 'payments'
Description-Content-Type: text/markdown

# Prospector Energy MCP Server

MCP (Model Context Protocol) server that gives AI agents access to the Prospector Labs Energy Data API — US interconnection queue projects with milestone tracking, distributed generation installations, developer profiles and track records, ITC/PTC tax credit calculations, and ITC deal sourcing.

Counts change daily and are not published here. For current coverage call `get_queue_stats`, `get_dg_stats` and `get_developer_stats`, or see <https://api.prospectorlabs.io/catalog>.

## Quick start

Add this to your MCP client. The package ships with the production API as its default base URL, so **the stats and summary tools work with no configuration at all**.

Everything that returns per-project rows needs an API key — get one at
<https://api.prospectorlabs.io/start> and set `PROSPECTOR_API_KEY`. Without it those
tools return a message telling you so, rather than failing obscurely:

```json
{
  "mcpServers": {
    "prospector-energy": {
      "command": "uvx",
      "args": ["prospector-energy-mcp"]
    }
  }
}
```

Try the API in one line first:

```bash
curl https://api.prospectorlabs.io/stats
```

Get a free API key in about 30 seconds, self-serve: **<https://api.prospectorlabs.io/start>**

## Tools Available (32 tools)

The **Tier** column is the plan a tool needs, as published at <https://api.prospectorlabs.io/plans>. It is a capability, not a price. Free covers every tool except bulk export, subject to a per-request row cap and a monthly query allowance.

### Projects & Search
| Tool | Description | Tier |
|------|-------------|------|
| `search_projects` | Search utility-scale energy projects by state, ISO, type, developer, capacity | Free |
| `get_project` | Full project detail with all enrichment fields | Free |
| `get_project_score` | Investability score breakdown for a project | Free |
| `get_queue_stats` | Aggregate interconnection queue statistics | Free |
| `get_milestone_summary` | Milestone and construction stage statistics | Free |
| `export_projects` | Bulk CSV export of projects | **Access** |

### Deals & Investment
| Tool | Description | Tier |
|------|-------------|------|
| `find_itc_deals` | ITC-eligible investment opportunities with scoring | Free |
| `get_itc_deal` | Detailed ITC deal profile | Free |
| `get_itc_summary` | Aggregate ITC deal pipeline statistics | Free |
| `get_investable_projects` | Pre-screened investable projects with grades | Free |
| `get_investable_summary` | Aggregate investability statistics | Free |
| `get_deal_sheet` | Formatted 1-page deal sheet (HTML, print to PDF) | Free |

### Tax Credits
| Tool | Description | Tier |
|------|-------------|------|
| `calculate_tax_credits` | ITC/PTC eligibility with all IRA bonus adders | Free |
| `check_domestic_content` | Domestic content ITC bonus eligibility (+10%) | Free |

### Developers
| Tool | Description | Tier |
|------|-------------|------|
| `search_developers` | Search developer profiles by name | Free |
| `get_developer` | Full developer profile with track record | Free |
| `get_developer_projects` | All projects by a specific developer | Free |
| `get_developer_stats` | Developer aggregate statistics | Free |

### Market Data
| Tool | Description | Tier |
|------|-------------|------|
| `get_lmp_monthly` | Monthly average LMP trends | Free |
| `get_lmp_zones` | List available LMP pricing zones | Free |
| `get_capacity_prices` | Capacity market auction prices | Free |
| `get_fuel_prices` | Fuel prices by state and type | Free |
| `get_technology_costs` | NREL ATB cost projections | Free |

### Grid Infrastructure
| Tool | Description | Tier |
|------|-------------|------|
| `get_grid_turbines` | US wind turbines (USWTDB) | Free |
| `get_grid_transmission` | Transmission lines (HIFLD) | Free |
| `get_grid_substations` | Electrical substations (HIFLD) | Free |
| `get_generators` | EIA generator inventory | Free |

### Distributed Generation
| Tool | Description | Tier |
|------|-------------|------|
| `search_dg_projects` | Search distributed generation installations | Free |
| `get_dg_stats` | DG aggregate statistics | Free |
| `get_investable_dg_projects` | Pre-screened investable DG projects | Free |
| `get_dg_investable_summary` | Aggregate investable DG statistics | Free |

### Utility
| Tool | Description | Tier |
|------|-------------|------|
| `get_pricing` | Plan tiers and, when self-hosting with MPP enabled, per-call amounts | Free |

## What's New in v0.4.3

- **Eleven filters that silently did nothing now work.** Tools were sending query
  parameter names the API does not accept, and FastAPI ignores unknown parameters —
  so the filter vanished and the tool answered on unfiltered data. `search_projects`
  sent `type`/`min_mw`/`max_mw` where the API wanted `fuel_type`/`capacity_min`/
  `capacity_max`, so *"battery storage over 100 MW in California"* returned every
  California project of every type and size. `find_itc_deals` sent
  `max_capacity_mw` where the API wanted `max_mw`, **which defaults to 5**, so
  *"deals under 20 MW"* returned only sub-5MW rows. The argument names you pass are
  unchanged; what goes over the wire was wrong.
- **`export_projects` works.** It returned CSV into a JSON parser and raised
  `JSONDecodeError` for every caller — including anyone holding the paid key it
  demands. Its `format` argument is gone; the endpoint only ever served CSV.
- **Four filters that never existed were removed** rather than faked: `state` on
  `get_grid_transmission` and `get_grid_substations` (the underlying FERC Form 1
  tables have no state column — a line spans two free-text endpoints), and
  `fuel`/`state` on `get_fuel_prices` (that endpoint takes no parameters). `region`
  was added to `/investable` on the API side, where the column existed all along.
- **`get_lmp_monthly`** takes `year` instead of `months`, and **`get_capacity_prices`**
  takes `delivery_year` as a span (`"2025/2026"`) instead of an integer year.
- A contract test now imports the API's route table and cross-checks every tool call
  against it, so this class of drift fails the build instead of shipping.

## What's New in v0.4.2

- **Installable again.** 0.4.0 declared `mcp>=1.0.0` with no upper bound; `mcp` 2.0.0
  removed `mcp.server.fastmcp` and the server died at import before serving a tool.
- **Access errors name the fix** — a 401 now says which environment variable to set
  and where to get a key, instead of surfacing an httpx traceback linking to MDN.
- **`export_projects` refuses before charging.** With MPP configured, payment settled
  before the request ran, so a keyless caller was charged and then rejected.

## What's New in v0.4.1

- **Production API is the default base URL** — `https://api.prospectorlabs.io`. Earlier versions defaulted to the Railway hostname, so no `PROSPECTOR_API_URL` env var is needed any more.
- **Two tools delisted** — `get_lmp_daily` and `get_rto_generation` were returning empty result sets because the pipelines behind them are not populated. A tool that is listed and always empty is worse than one that is absent; they will return when the data does.
- **Tiers describe capability, not price** — the tool table now matches the plans published at `/plans`. See *Plans and payments* below.

## Setup

### Claude Desktop

```json
{
  "mcpServers": {
    "prospector-energy": {
      "command": "uvx",
      "args": ["prospector-energy-mcp"]
    }
  }
}
```

### Claude Code

Add to your `.mcp.json`:

```json
{
  "mcpServers": {
    "prospector-energy": {
      "command": "uvx",
      "args": ["prospector-energy-mcp"]
    }
  }
}
```

### Cursor

Add to Cursor Settings > MCP Servers:

```json
{
  "prospector-energy": {
    "command": "uvx",
    "args": ["prospector-energy-mcp"]
  }
}
```

### Direct Install

```bash
# From PyPI
pip install prospector-energy-mcp

# With payment support
pip install prospector-energy-mcp[payments]

# Or with uv
uvx prospector-energy-mcp
```

## Configuration

| Environment Variable | Description | Default |
|---------------------|-------------|---------|
| `PROSPECTOR_API_URL` | API base URL | `https://api.prospectorlabs.io` |
| `PROSPECTOR_API_KEY` | API key. **Required by every tool that returns per-project rows** — 23 of the 32. The 8 stats/summary tools listed as Free below need no key. Without one, those 23 return a message naming this variable and linking to `/start`; `export_projects` additionally refuses *before* any MPP settlement, so an unusable call is never charged. Get a key at <https://api.prospectorlabs.io/start> | None |
| `MPP_RECIPIENT_ADDRESS` | Wallet address to receive payments (enables MPP — self-hosting only) | None (payments disabled) |
| `MPP_SECRET_KEY` | HMAC secret for payment challenge verification | Auto-generated |
| `MPP_REALM` | Server realm for payment challenges | `prospectorlabs.io` |

Get a key at <https://api.prospectorlabs.io/start>.

## Plans and payments

### Plans

Plans are published and enforced by the API, not by this package. Call <https://api.prospectorlabs.io/plans> for the current list — it is the only authoritative source.

| Tier | What it grants |
|------|----------------|
| **Free** | Full column width, a per-request row cap, a monthly query allowance. No bulk export |
| **Access** | The full daily queue — all projects, all columns, all markets, over both REST and MCP. Includes bulk CSV export |
| **Enterprise** | Bulk delivery, warehouse share, SLA, and redistribution of first-party sourced records |

Access and Enterprise are priced per engagement — <owen@prospectorlabs.io>.

### Agent payments (MPP)

This server can additionally charge per tool call in USDC over the [Machine Payments Protocol (MPP)](https://mpp.dev/), for operators who **run their own instance**.

MPP is opt-in and off by default: with `MPP_RECIPIENT_ADDRESS` unset, `paid_tool` returns the tool unwrapped and no payment challenge is ever issued. **The public `prospector-energy-mcp` package charges nothing per call** — access is governed by your API key's plan. Per-call amounts, when an operator enables MPP, are configured in `src/prospector_energy/payments.py`.

When enabled, the flow is:

1. Agent calls a paid tool (e.g., `search_projects`)
2. Server responds with a payment challenge (HTTP 402 equivalent)
3. Agent pays in USDC on the Tempo blockchain
4. Server verifies payment and returns data
5. Free tools (stats, summaries) always work without payment

### AgentCash

This server is also listed on [AgentCash](https://agentcash.dev/).

## Example Queries

Once connected, ask your AI agent:

- "How many solar projects are in the ERCOT queue?"
- "Calculate tax credits for a 2MW solar project in West Virginia"
- "Find investable ITC deals in New Jersey with credit rates above 50%"
- "Tell me about developer NextEra Energy's track record"
- "What were monthly average LMPs in PJM this year?"
- "Find battery storage projects over 100MW in California"

## Development

```bash
# Clone and install in dev mode
cd mcp-server
python3.12 -m venv .venv
source .venv/bin/activate
pip install -e ".[payments]"

# Run with stdio transport (default)
python -m prospector_energy

# Run with SSE transport
python -m prospector_energy --sse

# Test with MCP inspector
npx @modelcontextprotocol/inspector python -m prospector_energy
```
