使用说明

SkyFi MCP服务器

用于将SkyFi卫星图像功能与AI应用程序集成的模型上下文协议（MCP）服务器。

概述

此MCP服务器为AI应用程序提供了对SkyFi卫星图像平台的访问，从而实现了：

卫星图像搜索和订购：搜索和订购高分辨率卫星图像
存档数据访问：查阅历史卫星图像档案
实时监控：对特定关注领域进行监测
多源集成：与OpenStreetMap和天气数据集成

快速开始

先决条件

Python 3.11+
SkyFi API证书
可选：用于天气集成的OpenWeatherMap API密钥

安装

# Clone the repository
git clone https://github.com/PSkinnerTech/SkyFi-MCP.git
cd SkyFi-MCP

# Install dependencies
pip install -e .

MCP客户端设置

使用您偏好的AI开发环境配置SkyFi MCP服务器：

🖥️ 克劳德桌面

添加到配置文件(~/Library/Application Support/Claude/claude_desktop_config.json 在 macOS 上， %APPDATA%\Claude\claude_desktop_config.json 在Windows上）：

{
  "mcpServers": {
    "skyfi": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["-m", "mcp_skyfi"],
      "env": {
        "SKYFI_API_KEY": "your-email@example.com:your-api-key-hash",
        "SKYFI_URL": "https://app.skyfi.com/platform-api/pricing"
      },
      "cwd": "/path/to/your/project"
    }
  }
}

⚡ 光标AI

安装MCP扩展 在游标中
添加服务器配置 到您的光标设置(Cmd/Ctrl + , → 扩展→ MCP):

{
  "mcp.servers": {
    "skyfi": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["-m", "mcp_skyfi"],
      "cwd": "/path/to/your/project",
      "env": {
        "SKYFI_API_KEY": "your-email@example.com:your-api-key-hash",
        "SKYFI_URL": "https://app.skyfi.com/platform-api/pricing"
      }
    }
  }
}

替代方案：使用.cursorules文件 在项目根目录中：

{
  "mcp_servers": {
    "skyfi": {
      "command": "python",
      "args": ["-m", "mcp_skyfi"],
      "env": {
        "SKYFI_API_KEY": "your-email@example.com:your-api-key-hash",
        "SKYFI_URL": "https://app.skyfi.com/platform-api/pricing"
      }
    }
  }
}

🏄 风帆冲浪（Codeium）

打开风帆设置 (Ctrl/Cmd + ,)
导航到扩展 → MCP服务器
添加新服务器 使用这些设置：

{
  "name": "skyfi",
  "command": "/path/to/your/project/venv/bin/python",
  "args": ["-m", "mcp_skyfi"],
  "working_directory": "/path/to/your/project",
  "environment": {
    "SKYFI_API_KEY": "your-email@example.com:your-api-key-hash",
    "SKYFI_URL": "https://app.skyfi.com/platform-api/pricing"
  }
}

备选方案：项目级配置 (.windsurf/mcp.json):

{
  "servers": {
    "skyfi": {
      "command": "python",
      "args": ["-m", "mcp_skyfi"],
      "env": {
        "SKYFI_API_KEY": "your-email@example.com:your-api-key-hash",
        "SKYFI_URL": "https://app.skyfi.com/platform-api/pricing"
      }
    }
  }
}

📝 VSCode（带MCP扩展）

安装MCP扩展 来自VSCode市场
添加到VSCode设置 (Ctrl/Cmd + , → 搜索“mcp”）：

{
  "mcp.servers": {
    "skyfi": {
      "command": "/path/to/your/project/venv/bin/python",
      "args": ["-m", "mcp_skyfi"],
      "cwd": "/path/to/your/project",
      "env": {
        "SKYFI_API_KEY": "your-email@example.com:your-api-key-hash",
        "SKYFI_URL": "https://app.skyfi.com/platform-api/pricing"
      }
    }
  }
}

备选方案：工作区设置 (.vscode/settings.json):

{
  "mcp.servers": {
    "skyfi": {
      "command": "python",
      "args": ["-m", "mcp_skyfi"],
      "env": {
        "SKYFI_API_KEY": "your-email@example.com:your-api-key-hash",
        "SKYFI_URL": "https://app.skyfi.com/platform-api/pricing"
      }
    }
  }
}

🔧 配置说明

🚨 重要路径要求：

完整Python路径：使用Python可执行文件的绝对路径（使用查找 which python 或 where python)
工作目录：必须指向项目根目录 mcp_skyfi 模块已定位
API密钥格式：必须是 email:hash 从您的SkyFi帐户格式化

🔍 找到你的Python路径：

# On macOS/Linux
which python
# Or for virtual environments
which python3

# On Windows
where python
# Or
python -c "import sys; print(sys.executable)"

📦 虚拟环境路径：

康达: ~/miniconda3/envs/your-env/bin/python
虚拟环境: ./venv/bin/python （macOS/Linux）或 .\venv\Scripts\python.exe （Windows）
诗歌: ~/.cache/pypoetry/virtualenvs/your-project-*/bin/python

🧪 测试您的设置

配置后，在AI助手中使用以下任何命令进行测试：

Use the osm_forward_geocode tool to find coordinates for "Empire State Building, New York"

Search for recent satellite images of Central Park using skyfi_archive_search

Get a pricing quote for satellite tasking over downtown Austin, Texas

预期结果：您应该看到21个可用工具（13个SkyFi+8个OSM工具）

环境变量

服务器支持以下环境变量：

变量	必填	描述	示例
`SKYFI_API_KEY`	是	您的SkyFi API证书	`your-email@example.com:api-key-hash`
`SKYFI_URL`	是	SkyFi API端点	`https://app.skyfi.com/platform-api/pricing`
`OPENWEATHER_API_KEY`	否	OpenWeatherMap API密钥	`your-openweather-key`
`MCP_LOG_LEVEL`	否	日志记录级别	`INFO`, `DEBUG`, `WARNING`
`MCP_LOG_FORMAT`	否	日志格式	`console`, `json`, `simple`

这些设置在MCP客户端配置（Claude Desktop等）中或作为系统环境变量。

HTTP传输

python -m mcp_skyfi --transport http --port 8000

可用工具

MCP服务器提供 21工具 分为三类：

🛰️ SkyFi卫星图像工具（13个工具）

存档和搜索工具

skyfi_archive_search -使用地理空间、时间和质量过滤器搜索卫星图像档案
skyfi_archive_details -获取特定存档映像的详细信息，包括元数据和下载选项

订购工具

skyfi_get_tasking_quote -获取卫星任务请求的详细报价和可行性分析（订购前需要）
skyfi_create_archive_order -为现有的存档卫星图像创建订单，并提供交付选项
skyfi_create_tasking_order -使用之前生成的报价确认并创建任务订单（需要报价确认）
skyfi_get_order_status -获取现有订单的当前状态和进度信息

监控和通知

skyfi_create_webhook_subscription -为SkyFi通知和警报创建webhook订阅
skyfi_setup_area_monitoring -为特定区域的新图像设置自动监控
skyfi_get_notification_status -检查webhook通知的状态和传递历史

定价与分析

skyfi_calculate_archive_pricing -计算存档卫星图像订单的定价
skyfi_estimate_tasking_cost -估算新卫星图像任务订单的成本
skyfi_analyze_capture_feasibility -分析特定区域和时间段卫星图像捕获的可行性
skyfi_predict_satellite_passes -预测特定区域的卫星通过和最佳捕获窗口

🗺️ OpenStreetMap（OSM）工具（8个工具）

地理编码工具

osm_forward_geocode -使用OpenStreetMap地理编码将地址或地名转换为坐标
osm_reverse_geocode -使用OpenStreetMap将坐标转换为地址和位置信息
osm_batch_geocode -在单个请求中对多个地址或地名进行地理编码

搜索与发现

osm_search_nearby_pois -搜索特定位置附近的兴趣点（POI）
osm_search_businesses -在给定区域按名称或类型搜索特定企业

几何与分析

osm_generate_aoi -在卫星图像搜索的位置周围生成感兴趣区域（AOI）
osm_create_bounding_box -从一组坐标点创建边界框几何图形
osm_calculate_distance -使用各种方法计算两个地理点之间的距离

工具使用示例

示例1：搜索卫星图像

# Use osm_forward_geocode to get coordinates
geocode_result = osm_forward_geocode(query="Central Park, New York")

# Use skyfi_archive_search to find satellite images
images = skyfi_archive_search(
    geometry=geocode_result.geometry,
    start_date="2024-01-01",
    end_date="2024-12-31",
    cloud_cover_max=20,
    limit=10
)

示例2：监视一个区域以获取新图像

# Create an AOI around a location
aoi = osm_generate_aoi(
    center_point=[40.7829, -73.9654],  # Central Park coordinates
    radius_meters=5000
)

# Set up monitoring for the area
monitor = skyfi_setup_area_monitoring(
    geometry=aoi.geometry,
    monitor_name="Central Park Monitoring",
    notification_settings={
        "email": "your-email@example.com",
        "webhook_url": "https://your-app.com/webhook"
    },
    frequency="daily"
)

示例3：获取定价并下存档订单

# Calculate pricing for archive images
pricing = skyfi_calculate_archive_pricing(
    image_ids=["img_123", "img_456"],
    processing_level="L1C",
    output_format="GeoTIFF"
)

# Create an order if pricing is acceptable
if pricing.total_cost < 1000:
    order = skyfi_create_archive_order(
        image_ids=["img_123", "img_456"],
        delivery_method="download",
        output_format="GeoTIFF"
    )

示例4：两步任务订单（报价+确认）

# Step 1: Get detailed pricing quote (MANDATORY)
quote = skyfi_get_tasking_quote(
    geometry='{"type":"Polygon","coordinates":[[[-97.75,30.25],[-97.73,30.25],[-97.73,30.27],[-97.75,30.27],[-97.75,30.25]]]}',
    start_date="2025-02-01",
    end_date="2025-02-15",
    max_cloud_cover=15.0,
    priority="standard"
)

# Review the quote details:
# - Total cost: $120.50 USD
# - Capture probability: 75%
# - Quote expires in 24 hours

# Step 2: Confirm the order (required for security)
if quote.pricing_breakdown.total_cost_usd <= 150:
    order = skyfi_create_tasking_order(
        quote_id=quote.quote_id,
        confirm="yes"  # Explicit confirmation required
    )
    # Order created and payment processed

集成

SkyFi平台：提供档案搜索、订购和任务分配的主要卫星图像提供商
开放街道图：地理数据、地理编码和制图服务
气象服务：图像分析的天气背景（未来增强）

认证

支持多种身份验证方法：

API密钥（建议开发）
OAuth 2.0（用于生产部署）
个人访问令牌（用于企业）

建筑

服务器遵循分层架构模式：

MCP传输层：协议处理（STDIO、HTTP、SSE）
服务层：卫星图像操作的业务逻辑
数据处理层：模型转换和验证
认证层：多方法安全处理
网络层：HTTP客户端和外部API管理

文档

docs/ -全面的文件包括：
- docs/ARCHITECTURE.md -系统架构概述
- docs/OAUTH21_COMPLIANCE.md -OAuth 2.1实现细节
- docs/SECURITY_AUDIT_FINAL_REPORT.md -安全审计结果
- docs/MCP-Development-Philosophy.md -发展理念
- docs/PRD/ -产品要求和开发清单
tests/ -包含单元、集成和协议测试的全面测试套件
CLAUDE.md -Claude代码配置和开发说明

发展

项目结构

src/mcp_skyfi/
├── __init__.py           # CLI entry point
├── exceptions.py         # Custom exceptions
├── servers/              # Main server implementation
├── skyfi/                # SkyFi service integration
├── models/               # Data models
├── middleware/           # Authentication middleware  
└── utils/                # Utility functions

测试

# Run all tests
python -m pytest tests/

# Run specific test categories
python -m pytest tests/unit/
python -m pytest tests/integration/
python -m pytest tests/mcp_protocol/

Docker支持

# Build container
docker build -t skyfi-mcp .

# Run with STDIO
docker run -it skyfi-mcp

# Run with HTTP
docker run -p 8000:8000 skyfi-mcp --transport http

故障排除

常见问题

1. “ENOENT Python 生成” 错误

问题：Claude Desktop找不到Python可执行文件。

解决方案：在配置中使用Python可执行文件的完整路径：

{
  "command": "/Users/your-username/path/to/project/venv/bin/python",
  "cwd": "/Users/your-username/path/to/project"
}

2.“服务器断开连接”或JSON解析错误

问题：控制台输出干扰MCP协议。

解决方案：服务器会自动抑制STDIO传输的视觉输出。如果您仍然看到问题，请确保您使用的是最新版本。

3.Claude Desktop中的“0工具已启用”

问题：服务器启动问题或缺少依赖项。

解决方案:

直接测试服务器： python -m mcp_skyfi --config-check
检查是否安装了所有依赖项： pip install -e .
验证您的API凭据是否正确

4.身份验证错误

问题：API密钥格式或凭据无效。