# SkyFi MCP Server

A production-ready [MCP](https://modelcontextprotocol.io/) server for [SkyFi's](https://skyfi.com) satellite imagery Platform API. Search 150+ satellites from 12+ providers, compare pricing, and order archive or tasking imagery — all through natural language with any AI agent.

SkyFi aggregates imagery from Planet, Vantor, ICEYE, Umbra, Satellogic, and others into a single API with transparent pricing and no contracts. This MCP server makes that API accessible to Claude, GPT, Gemini, LangChain, and any MCP-compatible agent.

## Architecture

```mermaid
graph LR
    A[AI Agent] -->|MCP Protocol| B[SkyFi MCP Server]
    B -->|REST API| C[SkyFi Platform API]
    B -->|Nominatim| K[OpenStreetMap]
    C --> D[Planet]
    C --> E[Vantor]
    C --> F[ICEYE]
    C --> G[Umbra]
    C --> H[Satellogic]
    C --> I[Sentinel-1/2]
    C --> J[12+ more...]
```

## Quick Start (< 5 minutes)

### 1. Install

```bash
pip install skyfi-mcp
# or from source:
git clone https://github.com/jpwilson/skyfi-mcp.git
cd skyfi-mcp && pip install -e .
```

### 2. Configure

```bash
export SKYFI_API_KEY=your_api_key  # Get one at https://app.skyfi.com
```

### 3. Run

```bash
# Remote server (production)
skyfi-mcp
# → Listening at http://localhost:8000/mcp

# Local stdio (development)
SKYFI_MCP_TRANSPORT=stdio skyfi-mcp
```

### 4. Connect your agent

**Claude Desktop** — add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "skyfi": {
      "url": "http://localhost:8000/mcp"
    }
  }
}
```

**Claude Code:**
```bash
claude mcp add skyfi http://localhost:8000/mcp
```

### 5. Try it (free)

> "Find free Sentinel-2 imagery over the Amazon basin"

This uses open data ($0) — no credit card needed.

## Tools (20)

| Tool | Description |
|---|---|
| **SkyFi API** | |
| `skyfi_whoami` | Check account status, budget, payment method |
| `skyfi_search_archives` | Search archive imagery by location, date, sensor, provider |
| `skyfi_get_archive` | Get full details for an archive image |
| `skyfi_get_pricing` | Get pricing by AOI, product type, provider |
| `skyfi_create_feasibility` | Create tasking feasibility check |
| `skyfi_get_feasibility` | Poll feasibility results and provider windows |
| `skyfi_predict_passes` | Satellite pass prediction for tasking timing |
| `skyfi_create_archive_order` | Stage an archive order (shows price, requires confirmation) |
| `skyfi_create_tasking_order` | Stage a tasking order (shows price, requires confirmation) |
| `skyfi_confirm_order` | Execute a staged order (this commits money) |
| `skyfi_list_orders` | List orders with status/type filters |
| `skyfi_get_order` | Get order details |
| `skyfi_redeliver_order` | Redeliver completed order to different cloud bucket |
| `skyfi_get_deliverables` | Get download URLs for completed orders |
| `skyfi_create_notification` | Set up AOI monitoring with webhook alerts |
| `skyfi_list_notifications` | List active monitoring notifications |
| `skyfi_manage_notification` | Get or delete a notification |
| **OpenStreetMap** | |
| `osm_geocode` | Convert place names to coordinates + SkyFi-ready WKT polygons |
| `osm_reverse_geocode` | Convert coordinates to place names and addresses |
| `osm_search_nearby` | Find features (airports, ports, etc.) near a location |

## Ordering Safety

Orders use a **two-step confirmation pattern**:

1. **Stage** — `skyfi_create_archive_order` or `skyfi_create_tasking_order` calls the API and returns a price summary
2. **Confirm** — Only `skyfi_confirm_order` marks the order as human-approved

```
Order: VANTOR 30cm DAY, 12.4 sq km, $847. Deliver to S3. Confirm?
```

Free open-data orders ($0 Sentinel-1/2) still show confirmation but note "Free — no charge."

## Tasking Workflow

```
1. skyfi_create_feasibility → get feasibility ID
2. skyfi_get_feasibility    → poll for provider windows
3. skyfi_predict_passes     → (optional) check satellite timing
4. skyfi_create_tasking_order → stage with selected provider/window
5. skyfi_confirm_order      → execute after human approval
```

Provider-specific: Planet supports `provider_window_id` selection from feasibility results.

## AI Provider Integration

| Provider | Method | Example |
|---|---|---|
| **Claude Desktop** | MCP config | [Setup guide](docs/PROVIDER_GUIDE.md#claude-desktop--claude-code) |
| **Claude Code** | `claude mcp add` | [Setup guide](docs/PROVIDER_GUIDE.md#claude-desktop--claude-code) |
| **OpenAI** | Function calling | [`examples/openai_example.py`](examples/openai_example.py) |
| **Anthropic SDK** | Tool use | [`examples/anthropic_example.py`](examples/anthropic_example.py) |
| **Google Gemini** | Function calling | [`examples/gemini_example.py`](examples/gemini_example.py) |
| **Google ADK** | MCPToolset | [`examples/adk_example.py`](examples/adk_example.py) |
| **LangChain** | MCP adapter | [`examples/langchain_example.py`](examples/langchain_example.py) |
| **Vercel AI SDK** | MCP client | [Setup guide](docs/PROVIDER_GUIDE.md#vercel-ai-sdk) |

## Deployment

### Railway (recommended for cloud)

```bash
railway login && railway init
railway variables set SKYFI_API_KEY=your_key
railway up
# → https://your-project.up.railway.app/mcp
```

### Docker

```bash
docker build -t skyfi-mcp .
docker run -p 8000:8000 -e SKYFI_API_KEY=your_key skyfi-mcp
```

Or with docker-compose:
```bash
echo "SKYFI_API_KEY=your_key" > .env
docker-compose up
```

## Configuration

Auth is resolved in priority order:
1. `X-Skyfi-Api-Key` request header (cloud deployment)
2. `SKYFI_API_KEY` environment variable
3. Config file at `~/.skyfi/config.json` (or `SKYFI_CONFIG_PATH`)

Environment variables:
| Variable | Default | Description |
|---|---|---|
| `SKYFI_API_KEY` | — | SkyFi Platform API key |
| `SKYFI_MCP_HOST` | `0.0.0.0` | Server bind host |
| `SKYFI_MCP_PORT` | `8000` | Server bind port |
| `SKYFI_MCP_TRANSPORT` | `streamable-http` | Transport: `streamable-http`, `sse`, `stdio` |
| `SKYFI_API_BASE_URL` | `https://app.skyfi.com/platform-api` | API base URL override |

## AOI Constraints

- Format: WKT `POLYGON` (convex)
- Max vertices: 500
- Max area: 500,000 sq km
- Coordinates: longitude latitude (WGS84)

## Development

```bash
# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Run with coverage
pytest --cov=skyfi_mcp --cov-report=term-missing

# Lint
ruff check src/ tests/

# Type check
mypy src/

# Security scan
bandit -r src/
```

## Documentation

- [Architecture](docs/ARCHITECTURE.md)
- [Deployment Guide](docs/DEPLOYMENT.md)
- [Provider Integration Guide](docs/PROVIDER_GUIDE.md)
- [API Mapping](docs/API_MAPPING.md)

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/amazing-feature`)
3. Write tests for new functionality
4. Run the full test suite (`pytest`)
5. Run linting and type checks (`ruff check . && mypy src/`)
6. Commit with descriptive messages
7. Open a pull request

## License

MIT — see [LICENSE](LICENSE).