<!-- mcp-name: com.mireye/earth -->

# mireye-mcp

> Developed in a private monorepo. This repository
> ([Mireye-Labs/mireye-earth-mcp](https://github.com/Mireye-Labs/mireye-earth-mcp))
> is the published source of the `mireye-mcp` PyPI package, snapshot-synced
> on every release. Issues and PRs are welcome here (changes are applied upstream
> and re-synced; the test suite runs in the monorepo); releases land via PyPI.

Expose Mireye Earth's `/v1/ask` and `/v1/fetch` endpoints to MCP clients
that need a local stdio adapter (Claude Desktop, Cursor, custom agents
built on the `mcp` Python SDK) as native tools — no HTTP wiring required.

This is a standalone PyPI package (`mireye-mcp`) with only two
runtime dependencies — `httpx` and `mcp`. It does not pull in the
geospatial backend, so there's no GDAL / rasterio / DuckDB build step.

The server is a local stdio adapter with no geospatial business logic:
tool handlers POST to the deployed Mireye HTTP API, while read-only MCP
resources fetch and cache the public field catalog.

Mireye also exposes a hosted remote MCP endpoint at
`https://api.mireye.com/mcp` for clients that support Streamable
HTTP and native OAuth. Use that hosted endpoint for Claude Code so `/mcp`
opens the browser sign-in flow. This package remains the local stdio path;
it uses `mireye-mcp login` or `MIREYE_BEARER_TOKEN` for credentials.

---

## What the agent gets

Six tools, all prefixed `mireye_` so they sort together and don't
collide with generic `ask` / `fetch` tools from other MCP servers:

| Tool             | When the agent should call it                                                                  |
|------------------|------------------------------------------------------------------------------------------------|
| `mireye_ask`     | The caller asked a question about a US place ("is this in a flood zone?", "wildfire risk?").   |
| `mireye_fetch`   | The caller wants specific named fields ("elevation and slope here") or is powering a workflow. |
| `mireye_geocode` | The caller gave an address and just wants the coordinate + its quality, nothing else. |
| `mireye_lookup` | The input might be ambiguous, isn't a clean address (a coordinate or an APN), or a parcel is wanted. |
| `mireye_request_field` | The catalog doesn't have the field the caller needs — describe it in plain language plus example locations and either get a live match now or a `request_id` to build it. |
| `mireye_field_request_status` | Poll a `request_id` from `mireye_request_field` for status, queue position, ETA, and (once `live`) the `resume` call. |

Catalog context is exposed as MCP resources instead of extra tools:

| Resource | What it returns |
|----------|-----------------|
| `mireye://catalog/fields` | Full field catalog. |
| `mireye://catalog/presets` | Preset names and field expansions. |
| `mireye://catalog/us-envelope` | Supported coordinate bounds. |
| `mireye://field/{name}` | One field definition. |
| `mireye://preset/{name}` | One preset expansion. |

Workflow prompts are also registered — 22 in total. Claude Code surfaces
MCP prompts as slash commands under the form `/mcp__<server>__<prompt>`.

| Prompt | What it does |
|--------|--------------|
| `mireye_ask` | Call `mireye_ask` with a lat/lng and question. |
| `mireye_fetch` | Call `mireye_fetch` with a lat/lng and optional fields/preset. |
| `mireye_lookup` | Call `mireye_lookup` with an address/`lat,lng`/APN, noting the `disposition` handling. |
| `mireye_request_field` | File a field request with `mireye_request_field`, noting the `disposition` handling. |
| `mireye_field_request_status` | Poll a field request's status with `mireye_field_request_status`. |
| `mireye_fields` | Browse or search the field catalog. |
| `mireye_pick_fields` | Choose the smallest useful field set for a free-text question. |
| `mireye_site_report` | Site report via the `site_selection` preset. |
| `mireye_flood_check` | Flood-relevant signals via the `flood_risk` preset. |
| `mireye_wildfire_underwrite` | Wildfire underwriting signals via the `wildfire_underwrite` preset. |
| `mireye_terrain_report` | Terrain signals via the `terrain` preset. |
| `mireye_land_cover_report` | Land cover signals via the `land_cover` preset. |
| `mireye_building_lookup_report` | Primary building details via the `building_lookup` preset. |
| `mireye_points_of_interest_report` | Nearby amenities via the `points_of_interest` preset. |
| `mireye_utilities_report` | Utility infrastructure via the `utilities` preset. |
| `mireye_boundaries_report` | Political/census boundaries via the `boundaries` preset. |
| `mireye_solar_siting_report` | Solar siting signals via the `solar_siting` preset. |
| `mireye_wind_siting_report` | Wind siting signals via the `wind_siting` preset. |
| `mireye_storage_siting_report` | Battery storage siting signals via the `storage_siting` preset. |
| `mireye_data_center_siting_report` | Data center siting signals via the `data_center_siting` preset. |
| `mireye_grid_interconnect_report` | Interconnection signals via the `grid_interconnect` preset. |
| `mireye_natural_hazard_report` | Natural hazard signals via the `natural_hazard` preset. |

There is no third `list_fields` tool. Agents that need the catalog should
read the MCP resources above; the stdio adapter backs them with
`GET /v1/meta/fields` and a 1-hour ETag-aware cache.

---

## Install local stdio — one command with `uvx`

```bash
uvx mireye-mcp
```

That's it. `uvx` (bundled with [`uv`](https://docs.astral.sh/uv/))
downloads the package into a managed cache, runs the entry point, and
the next invocation is instant. No venv to manage, no `pip install`,
no native builds.

If you don't have `uv`:

```bash
curl -LsSf https://astral.sh/uv/install.sh | sh
```

Plain pip also works:

```bash
pip install mireye-mcp
mireye-mcp  # entry point
```

---

## Official MCP Registry

This server is published to the
[Official MCP Registry](https://registry.modelcontextprotocol.io) as
**`com.mireye/earth`** — the entry is live (the publish job ships from
`release.yml`), and `mireye-mcp` 0.2.0 is on PyPI. The registry entry
carries both distributions:

- the **PyPI package** `mireye-mcp` (local stdio, run via `uvx`), and
- the **hosted remote** `https://api.mireye.com/mcp` (Streamable HTTP +
  OAuth) for clients that prefer a remote server.

Because the entry is live, registry-aware clients (VS Code, the GitHub MCP
Registry, and anything else that reads the official registry) can
discover and install it from there — no manual config required.

---

## Wire it into Claude Desktop

First authenticate the local adapter:

```bash
mireye-mcp login
```

For non-interactive hosts, set `MIREYE_BEARER_TOKEN` instead.

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`
(macOS) or `%APPDATA%\Claude\claude_desktop_config.json` (Windows):

```json
{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-mcp"]
    }
  }
}
```

Restart Claude Desktop. The six tools (`mireye_ask`, `mireye_fetch`,
`mireye_geocode`, `mireye_lookup`, `mireye_request_field`,
`mireye_field_request_status`)
appear under the 🔌 menu, with catalog resources and prompts available to
clients that surface those MCP primitives.

To point at a self-hosted deployment instead of the default Fly URL:

```json
{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-mcp"],
      "env": {
        "MIREYE_BASE_URL": "https://your-deploy.example.com"
      }
    }
  }
}
```

---

## Wire it into Claude Code

Use the hosted HTTP MCP endpoint instead of this local stdio package:

```bash
claude mcp remove mireye-earth -s user   # only needed if an old stdio entry exists
claude mcp add --transport http --scope user mireye-earth https://api.mireye.com/mcp
```

Restart Claude Code, run `/mcp`, and follow the browser OAuth flow.
Slash commands appear as:

- `/mcp__mireye-earth__mireye_ask <lat> <lng> <question>`
- `/mcp__mireye-earth__mireye_fetch <lat> <lng> [fields] [preset]`

Or just chat naturally — Claude Code will call the tool when relevant.

---

## Wire it into Cursor

Cursor's MCP config lives at `~/.cursor/mcp.json` (global) or
`<repo>/.cursor/mcp.json` (workspace). Same shape as Claude Desktop:

```json
{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-mcp"]
    }
  }
}
```

Open **Cursor → Settings → MCP** and confirm `mireye-earth` shows the two
green tools. Catalog resources and prompts appear when the client supports
those MCP primitives.

---

## Wire it into a custom agent

If you're building an MCP client with the `mcp` Python SDK, point its
`StdioServerParameters` at the installed entry point:

```python
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

params = StdioServerParameters(command="uvx", args=["mireye-mcp"])

async with stdio_client(params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()
        tools = await session.list_tools()
        # tools.tools is [mireye_ask, mireye_fetch]
        resources = await session.list_resources()
        prompts = await session.list_prompts()

        result = await session.call_tool(
            "mireye_ask",
            {"lat": 40.7128, "lng": -74.0060, "question": "elevation?"},
        )
```

---

## Configuration

| Env var            | Default                          | Purpose                          |
|--------------------|----------------------------------|----------------------------------|
| `MIREYE_BASE_URL`  | `https://api.mireye.com`   | HTTP base URL the tools POST to. Stored login credentials only attach when they were created against this same URL. |
| `MIREYE_TIMEOUT_S` | `120`                            | Per-request timeout in seconds (must exceed the ~110 s `/v1/ask` deadline). |
| `MIREYE_BEARER_TOKEN` | unset | Optional Mireye bearer token. Overrides stored credentials for tool calls; `status` reports on the stored login first. |
| `MIREYE_MCP_CREDENTIALS_FILE` | `~/.config/mireye-mcp/credentials.json` | Stored token path used by `login` / `status` / `logout`. |

## Authentication

The local stdio adapter does not perform native MCP OAuth discovery.
The HTTP API requires bearer auth for `/v1/ask` and `/v1/fetch`, so run
the device login helper once:

```bash
mireye-mcp login
```

The command prints a verification URL and code, waits for approval in
the Mireye account page, and stores a Mireye API token locally. You can
also provide a token directly:

```json
{
  "mcpServers": {
    "mireye-earth": {
      "command": "uvx",
      "args": ["mireye-mcp"],
      "env": {
        "MIREYE_BEARER_TOKEN": "eyJ..."
      }
    }
  }
}
```

Check or remove local credentials:

```bash
mireye-mcp status
mireye-mcp logout
mireye-mcp logout --revoke
```

### Credentials are bound to their base URL

`login` records the `MIREYE_BASE_URL` it ran against, and the stored
token is only ever sent to that same URL. If `MIREYE_BASE_URL` later
points somewhere else, tool calls behave as logged out and the error
names both URLs — re-run `mireye-mcp login` against the new URL,
or set `MIREYE_BEARER_TOKEN` explicitly. Credentials files without a
recorded `base_url` (e.g. hand-written) are treated as bound to the
default `https://api.mireye.com`.

Two more guardrails:

- Tokens of any kind are never sent over plain `http://`, except to
  loopback hosts (`localhost` / `127.0.0.1` / `[::1]`) for local
  development.
- `status` and `logout --revoke` operate on the **stored** base URL, so
  you can always inspect or revoke a stored login even while
  `MIREYE_BASE_URL` points elsewhere.

For native MCP OAuth, configure your client to use the hosted remote MCP
URL `https://api.mireye.com/mcp` instead of launching this stdio
binary. The remote endpoint advertises OAuth metadata and uses browser
OAuth 2.1 + PKCE.

---

## Troubleshooting

**Server doesn't appear in Claude Desktop.** Check that `uvx` resolves
on the PATH used by the GUI app (macOS launches GUI apps with a minimal
PATH). Test from a terminal: `which uvx`. If empty, install `uv`:
`curl -LsSf https://astral.sh/uv/install.sh | sh`. If `uvx` lives at
`/Users/you/.local/bin/uvx`, use the absolute path in `command`.

**Tools not appearing under the 🔌 menu after restart.** Watch
`~/Library/Logs/Claude/mcp-server-mireye-earth.log`. The server logs to
stderr on startup; you should see `[mireye-mcp] starting
base_url=…`. If there's no log, `uvx` isn't being invoked — usually a
PATH issue.

**`ConnectError` / `ReadTimeout`** on the first tool call. The hosted
API keeps its machines running, but calls right after a backend deploy
can be slow while geospatial sources warm in the background, and some
fields depend on slow upstream federal services. The default
`MIREYE_TIMEOUT_S` (120 s) already exceeds the ~110 s `/v1/ask` deadline, so a
cold start fits; only raise it further (never below 120) if you still time out.

**HTTP 400 `coord_out_of_bounds`.** Mireye is US-only in V1. The accepted
envelope is `lat ∈ [18, 72]`, `lng ∈ [-180, -65]` — covering the lower 48,
Alaska, Hawaii, and US territories.

**HTTP 400 `fields_unknown`.** The field name is not in the catalog. Hit
`https://api.mireye.com/v1/meta/fields` to see the canonical list.
Common surprises: `elevation_m` is `elevation`, `floodplain` is
`within_floodplain_polygon`.

**HTTP 4xx/5xx in general.** Tool errors include actionable JSON fields
such as `code`, `message`, `http_status`, `request_id`, `tool`, and
`retryable`. Agents should retry only when `retryable` is true.

**Auth errors.** `401` means the MCP server has no token, the token
expired, or the token was revoked. Run `mireye-mcp login` again,
or set `MIREYE_BEARER_TOKEN`. `403` means the signed-in account is not
allowed by the backend account policy.

---

## What this server does NOT do

- **No data-result caching.** The HTTP API has its own response cache
  (local disk, plus a shared Redis tier in production). The stdio adapter
  only caches the public field catalog resource.
- **No geospatial business logic.** The adapter validates obvious MCP input
  bounds and field-count limits, but source orchestration stays in the API.
- **No streaming.** MCP streaming responses are V1.5.
- **No Firebase validation in MCP.** The MCP package forwards bearer
  tokens; the HTTP API owns token verification and account policy.
- **No in-process imports of `mireye_earth`.** The server talks to the API
  over HTTP only, so it ships as a separate slim PyPI package
  (`mireye-mcp`) and can be installed without the data backend.

---

## Releasing

This package is published from this directory on every `v*` tag on the
main repo. To release locally:

```bash
cd mcp_server
python -m build
twine upload dist/*
```