{"id":30732421,"url":"https://github.com/pskinnertech/skyfi-mcp-server","last_synced_at":"2025-09-03T17:08:56.866Z","repository":{"id":306548527,"uuid":"1026415072","full_name":"PSkinnerTech/SkyFi-MCP-server","owner":"PSkinnerTech","description":"Enterprise-grade MCP server for SkyFi satellite imagery platform - secure ordering, archive    search, and tasking workflows with multi-service authentication, mandatory pricing confirmation, and comprehensive API integration.","archived":false,"fork":false,"pushed_at":"2025-07-26T06:22:09.000Z","size":1048,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"CAFO","last_synced_at":"2025-07-26T12:06:35.417Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"https://sky-fi-mcp-server.vercel.app","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/PSkinnerTech.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2025-07-25T21:09:55.000Z","updated_at":"2025-07-26T06:22:12.000Z","dependencies_parsed_at":"2025-07-26T12:06:42.235Z","dependency_job_id":"5a717cf9-87f4-4077-9260-b9d278ee7dc3","html_url":"https://github.com/PSkinnerTech/SkyFi-MCP-server","commit_stats":null,"previous_names":["pskinnertech/skyfi-mcp-server"],"tags_count":null,"template":false,"template_full_name":null,"purl":"pkg:github/PSkinnerTech/SkyFi-MCP-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PSkinnerTech%2FSkyFi-MCP-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PSkinnerTech%2FSkyFi-MCP-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PSkinnerTech%2FSkyFi-MCP-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PSkinnerTech%2FSkyFi-MCP-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/PSkinnerTech","download_url":"https://codeload.github.com/PSkinnerTech/SkyFi-MCP-server/tar.gz/refs/heads/CAFO","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/PSkinnerTech%2FSkyFi-MCP-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":273477127,"owners_count":25112618,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-09-03T02:00:09.631Z","response_time":76,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-09-03T17:06:35.900Z","updated_at":"2025-09-03T17:08:56.851Z","avatar_url":"https://github.com/PSkinnerTech.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"![SkyFi Logo](public/Skyfi%20Logo.jpg)\n\n# SkyFi MCP Server\n\nA Model Context Protocol (MCP) server for integrating SkyFi satellite imagery capabilities with AI applications.\n\n## Overview\n\nThis MCP server provides AI applications with access to SkyFi's satellite imagery platform, enabling:\n\n- **Satellite Image Search \u0026 Ordering**: Search and order high-resolution satellite imagery\n- **Archive Data Access**: Access to historical satellite imagery archives  \n- **Real-time Monitoring**: Set up monitoring for specific areas of interest\n- **Multi-source Integration**: Integration with OpenStreetMap and weather data\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.11+\n- SkyFi API credentials\n- Optional: OpenWeatherMap API key for weather integration\n\n### Installation\n\n```bash\n# Clone the repository\ngit clone https://github.com/PSkinnerTech/SkyFi-MCP.git\ncd SkyFi-MCP\n\n# Install dependencies\npip install -e .\n```\n\n## MCP Client Setup\n\nConfigure the SkyFi MCP server with your preferred AI development environment:\n\n### 🖥️ Claude Desktop\n\nAdd to your configuration file (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS, `%APPDATA%\\Claude\\claude_desktop_config.json` on Windows):\n\n```json\n{\n  \"mcpServers\": {\n    \"skyfi\": {\n      \"command\": \"/path/to/your/project/venv/bin/python\",\n      \"args\": [\"-m\", \"mcp_skyfi\"],\n      \"env\": {\n        \"SKYFI_API_KEY\": \"your-email@example.com:your-api-key-hash\",\n        \"SKYFI_URL\": \"https://app.skyfi.com/platform-api/pricing\"\n      },\n      \"cwd\": \"/path/to/your/project\"\n    }\n  }\n}\n```\n\n### ⚡ Cursor AI\n\n1. **Install the MCP extension** in Cursor\n2. **Add server configuration** to your Cursor settings (`Cmd/Ctrl + ,` → Extensions → MCP):\n\n```json\n{\n  \"mcp.servers\": {\n    \"skyfi\": {\n      \"command\": \"/path/to/your/project/venv/bin/python\",\n      \"args\": [\"-m\", \"mcp_skyfi\"],\n      \"cwd\": \"/path/to/your/project\",\n      \"env\": {\n        \"SKYFI_API_KEY\": \"your-email@example.com:your-api-key-hash\",\n        \"SKYFI_URL\": \"https://app.skyfi.com/platform-api/pricing\"\n      }\n    }\n  }\n}\n```\n\n3. **Alternative: Use .cursorrules file** in your project root:\n```json\n{\n  \"mcp_servers\": {\n    \"skyfi\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_skyfi\"],\n      \"env\": {\n        \"SKYFI_API_KEY\": \"your-email@example.com:your-api-key-hash\",\n        \"SKYFI_URL\": \"https://app.skyfi.com/platform-api/pricing\"\n      }\n    }\n  }\n}\n```\n\n### 🏄 Windsurf (Codeium)\n\n1. **Open Windsurf Settings** (`Ctrl/Cmd + ,`)\n2. **Navigate to Extensions** → **MCP Servers**\n3. **Add New Server** with these settings:\n\n```json\n{\n  \"name\": \"skyfi\",\n  \"command\": \"/path/to/your/project/venv/bin/python\",\n  \"args\": [\"-m\", \"mcp_skyfi\"],\n  \"working_directory\": \"/path/to/your/project\",\n  \"environment\": {\n    \"SKYFI_API_KEY\": \"your-email@example.com:your-api-key-hash\",\n    \"SKYFI_URL\": \"https://app.skyfi.com/platform-api/pricing\"\n  }\n}\n```\n\n**Alternative: Project-level configuration** (`.windsurf/mcp.json`):\n```json\n{\n  \"servers\": {\n    \"skyfi\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_skyfi\"],\n      \"env\": {\n        \"SKYFI_API_KEY\": \"your-email@example.com:your-api-key-hash\",\n        \"SKYFI_URL\": \"https://app.skyfi.com/platform-api/pricing\"\n      }\n    }\n  }\n}\n```\n\n### 📝 VSCode (with MCP Extension)\n\n1. **Install the MCP Extension** from VSCode Marketplace\n2. **Add to VSCode settings** (`Ctrl/Cmd + ,` → Search \"mcp\"):\n\n```json\n{\n  \"mcp.servers\": {\n    \"skyfi\": {\n      \"command\": \"/path/to/your/project/venv/bin/python\",\n      \"args\": [\"-m\", \"mcp_skyfi\"],\n      \"cwd\": \"/path/to/your/project\",\n      \"env\": {\n        \"SKYFI_API_KEY\": \"your-email@example.com:your-api-key-hash\",\n        \"SKYFI_URL\": \"https://app.skyfi.com/platform-api/pricing\"\n      }\n    }\n  }\n}\n```\n\n3. **Alternative: Workspace settings** (`.vscode/settings.json`):\n```json\n{\n  \"mcp.servers\": {\n    \"skyfi\": {\n      \"command\": \"python\",\n      \"args\": [\"-m\", \"mcp_skyfi\"],\n      \"env\": {\n        \"SKYFI_API_KEY\": \"your-email@example.com:your-api-key-hash\",\n        \"SKYFI_URL\": \"https://app.skyfi.com/platform-api/pricing\"\n      }\n    }\n  }\n}\n```\n\n### 🔧 Configuration Notes\n\n**🚨 Important Path Requirements:**\n- **Full Python Path**: Use absolute path to your Python executable (find with `which python` or `where python`)\n- **Working Directory**: Must point to the project root where `mcp_skyfi` module is located\n- **API Key Format**: Must be `email:hash` format from your SkyFi account\n\n**🔍 Finding Your Python Path:**\n```bash\n# On macOS/Linux\nwhich python\n# Or for virtual environments\nwhich python3\n\n# On Windows\nwhere python\n# Or\npython -c \"import sys; print(sys.executable)\"\n```\n\n**📦 Virtual Environment Paths:**\n- **Conda**: `~/miniconda3/envs/your-env/bin/python`\n- **venv**: `./venv/bin/python` (macOS/Linux) or `.\\venv\\Scripts\\python.exe` (Windows)\n- **Poetry**: `~/.cache/pypoetry/virtualenvs/your-project-*/bin/python`\n\n### 🧪 Testing Your Setup\n\nAfter configuration, test with any of these commands in your AI assistant:\n\n```\nUse the osm_forward_geocode tool to find coordinates for \"Empire State Building, New York\"\n```\n\n```\nSearch for recent satellite images of Central Park using skyfi_archive_search\n```\n\n```\nGet a pricing quote for satellite tasking over downtown Austin, Texas\n```\n\n**Expected Result**: You should see 21 tools available (13 SkyFi + 8 OSM tools)\n\n#### Environment Variables\n\nThe server supports these environment variables:\n\n| Variable | Required | Description | Example |\n|----------|----------|-------------|---------|\n| `SKYFI_API_KEY` | Yes | Your SkyFi API credentials | `your-email@example.com:api-key-hash` |\n| `SKYFI_URL` | Yes | SkyFi API endpoint | `https://app.skyfi.com/platform-api/pricing` |\n| `OPENWEATHER_API_KEY` | No | OpenWeatherMap API key | `your-openweather-key` |\n| `MCP_LOG_LEVEL` | No | Logging level | `INFO`, `DEBUG`, `WARNING` |\n| `MCP_LOG_FORMAT` | No | Log format | `console`, `json`, `simple` |\n\nThese are set in your MCP client configuration (Claude Desktop, etc.) or as system environment variables.\n\n#### HTTP Transport\n\n```bash\npython -m mcp_skyfi --transport http --port 8000\n```\n\n## Available Tools\n\nThe MCP server provides **21 tools** across three categories:\n\n### 🛰️ SkyFi Satellite Imagery Tools (13 tools)\n\n#### **Archive \u0026 Search Tools**\n- **`skyfi_archive_search`** - Search satellite imagery archive with geospatial, temporal, and quality filters\n- **`skyfi_archive_details`** - Get detailed information about a specific archive image including metadata and download options\n\n#### **Ordering Tools**  \n- **`skyfi_get_tasking_quote`** - Get detailed pricing quote and feasibility analysis for satellite tasking request (REQUIRED before ordering)\n- **`skyfi_create_archive_order`** - Create an order for existing archive satellite imagery with delivery options\n- **`skyfi_create_tasking_order`** - Confirm and create a tasking order using a previously generated quote (requires quote confirmation)\n- **`skyfi_get_order_status`** - Get current status and progress information for an existing order\n\n#### **Monitoring \u0026 Notifications**\n- **`skyfi_create_webhook_subscription`** - Create a webhook subscription for SkyFi notifications and alerts\n- **`skyfi_setup_area_monitoring`** - Set up automated monitoring for new imagery in a specific area\n- **`skyfi_get_notification_status`** - Check the status and delivery history of webhook notifications\n\n#### **Pricing \u0026 Analysis**\n- **`skyfi_calculate_archive_pricing`** - Calculate pricing for archive satellite imagery orders\n- **`skyfi_estimate_tasking_cost`** - Estimate costs for new satellite imagery tasking orders\n- **`skyfi_analyze_capture_feasibility`** - Analyze the feasibility of satellite imagery capture for a specific area and time period\n- **`skyfi_predict_satellite_passes`** - Predict satellite passes and optimal capture windows for a specific area\n\n### 🗺️ OpenStreetMap (OSM) Tools (8 tools)\n\n#### **Geocoding Tools**\n- **`osm_forward_geocode`** - Convert address or place name to coordinates using OpenStreetMap geocoding\n- **`osm_reverse_geocode`** - Convert coordinates to address and location information using OpenStreetMap\n- **`osm_batch_geocode`** - Geocode multiple addresses or place names in a single request\n\n#### **Search \u0026 Discovery**\n- **`osm_search_nearby_pois`** - Search for Points of Interest (POIs) near a specific location\n- **`osm_search_businesses`** - Search for specific businesses by name or type in a given area\n\n#### **Geometry \u0026 Analysis**\n- **`osm_generate_aoi`** - Generate an Area of Interest (AOI) around a location for satellite imagery search\n- **`osm_create_bounding_box`** - Create a bounding box geometry from a set of coordinate points\n- **`osm_calculate_distance`** - Calculate distance between two geographic points using various methods\n\n## Tool Usage Examples\n\n### Example 1: Search for Satellite Images\n\n```python\n# Use osm_forward_geocode to get coordinates\ngeocode_result = osm_forward_geocode(query=\"Central Park, New York\")\n\n# Use skyfi_archive_search to find satellite images\nimages = skyfi_archive_search(\n    geometry=geocode_result.geometry,\n    start_date=\"2024-01-01\",\n    end_date=\"2024-12-31\",\n    cloud_cover_max=20,\n    limit=10\n)\n```\n\n### Example 2: Monitor an Area for New Imagery\n\n```python\n# Create an AOI around a location\naoi = osm_generate_aoi(\n    center_point=[40.7829, -73.9654],  # Central Park coordinates\n    radius_meters=5000\n)\n\n# Set up monitoring for the area\nmonitor = skyfi_setup_area_monitoring(\n    geometry=aoi.geometry,\n    monitor_name=\"Central Park Monitoring\",\n    notification_settings={\n        \"email\": \"your-email@example.com\",\n        \"webhook_url\": \"https://your-app.com/webhook\"\n    },\n    frequency=\"daily\"\n)\n```\n\n### Example 3: Get Pricing and Place Archive Order\n\n```python\n# Calculate pricing for archive images\npricing = skyfi_calculate_archive_pricing(\n    image_ids=[\"img_123\", \"img_456\"],\n    processing_level=\"L1C\",\n    output_format=\"GeoTIFF\"\n)\n\n# Create an order if pricing is acceptable\nif pricing.total_cost \u003c 1000:\n    order = skyfi_create_archive_order(\n        image_ids=[\"img_123\", \"img_456\"],\n        delivery_method=\"download\",\n        output_format=\"GeoTIFF\"\n    )\n```\n\n### Example 4: Two-Step Tasking Order (Quote + Confirmation)\n\n```python\n# Step 1: Get detailed pricing quote (MANDATORY)\nquote = skyfi_get_tasking_quote(\n    geometry='{\"type\":\"Polygon\",\"coordinates\":[[[-97.75,30.25],[-97.73,30.25],[-97.73,30.27],[-97.75,30.27],[-97.75,30.25]]]}',\n    start_date=\"2025-02-01\",\n    end_date=\"2025-02-15\",\n    max_cloud_cover=15.0,\n    priority=\"standard\"\n)\n\n# Review the quote details:\n# - Total cost: $120.50 USD\n# - Capture probability: 75%\n# - Quote expires in 24 hours\n\n# Step 2: Confirm the order (required for security)\nif quote.pricing_breakdown.total_cost_usd \u003c= 150:\n    order = skyfi_create_tasking_order(\n        quote_id=quote.quote_id,\n        confirm=\"yes\"  # Explicit confirmation required\n    )\n    # Order created and payment processed\n```\n\n## Integrations\n\n- **SkyFi Platform**: Primary satellite imagery provider with archive search, ordering, and tasking\n- **OpenStreetMap**: Geographic data, geocoding, and mapping services\n- **Weather Services**: Weather context for imagery analysis (future enhancement)\n\n### Authentication\n\nSupports multiple authentication methods:\n\n- API Key (recommended for development)\n- OAuth 2.0 (for production deployments)\n- Personal Access Tokens (for enterprise)\n\n## Architecture\n\nThe server follows a layered architecture pattern:\n\n- **MCP Transport Layer**: Protocol handling (STDIO, HTTP, SSE)\n- **Service Layer**: Business logic for satellite imagery operations\n- **Data Processing Layer**: Model transformation and validation\n- **Authentication Layer**: Multi-method security handling\n- **Network Layer**: HTTP clients and external API management\n\n## Documentation\n\n- [`docs/`](./docs/) - Comprehensive documentation including:\n  - [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) - System architecture overview\n  - [`docs/OAUTH21_COMPLIANCE.md`](./docs/OAUTH21_COMPLIANCE.md) - OAuth 2.1 implementation details\n  - [`docs/SECURITY_AUDIT_FINAL_REPORT.md`](./docs/SECURITY_AUDIT_FINAL_REPORT.md) - Security audit results\n  - [`docs/MCP-Development-Philosophy.md`](./docs/MCP-Development-Philosophy.md) - Development philosophy\n  - [`docs/PRD/`](./docs/PRD/) - Product requirements and development checklists\n- [`tests/`](./tests/) - Comprehensive test suite with unit, integration, and protocol tests\n- [`CLAUDE.md`](./CLAUDE.md) - Claude Code configuration and development instructions\n\n## Development\n\n### Project Structure\n\n```\nsrc/mcp_skyfi/\n├── __init__.py           # CLI entry point\n├── exceptions.py         # Custom exceptions\n├── servers/              # Main server implementation\n├── skyfi/                # SkyFi service integration\n├── models/               # Data models\n├── middleware/           # Authentication middleware  \n└── utils/                # Utility functions\n```\n\n### Testing\n\n```bash\n# Run all tests\npython -m pytest tests/\n\n# Run specific test categories\npython -m pytest tests/unit/\npython -m pytest tests/integration/\npython -m pytest tests/mcp_protocol/\n```\n\n### Docker Support\n\n```bash\n# Build container\ndocker build -t skyfi-mcp .\n\n# Run with STDIO\ndocker run -it skyfi-mcp\n\n# Run with HTTP\ndocker run -p 8000:8000 skyfi-mcp --transport http\n```\n\n## Troubleshooting\n\n### Common Issues\n\n#### 1. \"spawn python ENOENT\" Error\n**Problem**: Claude Desktop can't find the Python executable.\n\n**Solution**: Use the full path to your Python executable in the configuration:\n```json\n{\n  \"command\": \"/Users/your-username/path/to/project/venv/bin/python\",\n  \"cwd\": \"/Users/your-username/path/to/project\"\n}\n```\n\n#### 2. \"Server disconnected\" or JSON Parsing Errors\n**Problem**: Console output interfering with MCP protocol.\n\n**Solution**: The server automatically suppresses visual output for STDIO transport. If you still see issues, ensure you're using the latest version.\n\n#### 3. \"0 tools enabled\" in Claude Desktop\n**Problem**: Server startup issues or missing dependencies.\n\n**Solution**: \n1. Test the server directly: `python -m mcp_skyfi --config-check`\n2. Check that all dependencies are installed: `pip install -e .`\n3. Verify your API credentials are correct\n\n#### 4. Authentication Errors\n**Problem**: Invalid API key format or credentials.\n\n**Solution**: \n1. Check your SkyFi account for the correct API key format (`email:hash`)\n2. Ensure the SKYFI_URL points to the correct endpoint\n3. Test your credentials with a direct API call\n\n### Testing Configuration\n\nYou can test your MCP server configuration:\n\n```bash\n# Validate configuration\npython -m mcp_skyfi --config-check\n\n# Test STDIO transport\necho '{\"jsonrpc\": \"2.0\", \"id\": 1, \"method\": \"initialize\", \"params\": {\"protocolVersion\": \"2024-11-05\", \"capabilities\": {}, \"clientInfo\": {\"name\": \"test\", \"version\": \"1.0\"}}}' | python -m mcp_skyfi\n\n# Test tool listing\npython -c \"import asyncio; from mcp_skyfi.servers.main import main_mcp; print('Tools available:', len(main_mcp.list_tools()))\"\n```\n\n### Debug Mode\n\nEnable debug logging for troubleshooting:\n\n```bash\npython -m mcp_skyfi --log-level DEBUG --transport stdio\n```\n\n### Quick Verification\n\nTo verify your MCP server is working correctly:\n\n1. **Test server startup:**\n   ```bash\n   python -m mcp_skyfi --config-check\n   ```\n   Should show: `✅ Configuration is valid`\n\n2. **Test in Claude Desktop:**\n   After adding the server to Claude Desktop, try this command in Claude:\n   ```\n   Use the osm_forward_geocode tool to find the coordinates of \"Empire State Building, New York\"\n   ```\n\n3. **Verify tool count:**\n   You should see **21 tools** available (13 SkyFi + 8 OSM tools)\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Add tests\n5. Submit a pull request\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Support\n\n- [SkyFi Platform Documentation](https://docs.skyfi.com)\n- [MCP Protocol Specification](https://modelcontextprotocol.io)\n- [Issue Tracker](https://github.com/PSkinnerTech/SkyFi-MCP/issues)\n\n## Acknowledgments\n\n- SkyFi for providing satellite imagery platform access\n- Anthropic for the Model Context Protocol specification\n- The MCP community for tools and best practices ","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpskinnertech%2Fskyfi-mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fpskinnertech%2Fskyfi-mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fpskinnertech%2Fskyfi-mcp-server/lists"}