Metadata-Version: 2.4
Name: mirror-earth-mcp
Version: 0.2.2
Summary: Model Context Protocol server for Mirror Earth weather data.
Project-URL: Homepage, https://gitee.com/gfyml/mirror-earth-mcp
Project-URL: Repository, https://gitee.com/gfyml/mirror-earth-mcp.git
Author: Mirror Earth
License: MIT
Keywords: mcp,mirror-earth,weather
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.9
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Internet
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# Mirror Earth MCP

`mirror-earth-mcp` 是镜像地球气象数据的 Python Model Context Protocol（MCP）服务，提供天气查询、模型与要素目录、地名解析、本地 Markdown 参考资料和批量导出任务管理能力。

## 使用要求

- Python 3.9 或更高版本
- [uv](https://docs.astral.sh/uv/)
- 使用需要认证的天气查询和批量导出工具时，需提供 Mirror Earth API Key。请前往[镜像地球开放平台个人中心](https://open.mirror-earth.com/account/profile)获取。

`geocode` 和 `reverse_geocode` 使用公开地名服务，不需要 API Key。

## 安装与启动

通过 `uvx` 直接运行 PyPI 中发布的包：

```powershell
uvx --from mirror-earth-mcp mirror-earth-mcp
```

在 MCP 客户端的环境变量中设置 `MIRROR_EARTH_API_KEY`。API Key 可在[镜像地球开放平台个人中心](https://open.mirror-earth.com/account/profile)获取。服务使用 stdio 传输，只会向标准输出写入 JSON-RPC 响应。

## MCP 配置

```json
{
  "mcpServers": {
    "mirror-earth": {
      "command": "uvx",
      "args": ["--from", "mirror-earth-mcp", "mirror-earth-mcp"],
      "env": {
        "MIRROR_EARTH_API_KEY": "YOUR_MIRROR_EARTH_API_KEY"
      }
    }
  }
}
```

在 Codex CLI 中添加服务：

```powershell
codex mcp add mirror-earth --env MIRROR_EARTH_API_KEY=YOUR_MIRROR_EARTH_API_KEY -- uvx --from mirror-earth-mcp mirror-earth-mcp
```

## MCP 工具

| 工具 | 用途 |
| --- | --- |
| `list_models` | 列出实时预报、历史再分析和历史预报模型。 |
| `get_model_details` | 查询模型元数据、支持的要素与等压面。 |
| `list_variables` | 列出逐小时、逐日或逐月要素。 |
| `get_forecast` | 按经纬度查询天气预报。 |
| `get_historical_weather` | 查询 ERA5 历史天气数据。 |
| `get_archive_forecast` | 查询历史模型起报的预报数据。 |
| `get_seamless_weather` | 查询连续的 ERA5 与 ECMWF 天气数据。 |
| `geocode` / `reverse_geocode` | 解析地名与经纬度。 |
| `get_batch_usage` | 查询批量导出配额和使用情况。 |
| `estimate_batch_export` / `create_batch_export` | 预估并创建批量导出任务。 |
| `get_batch_task` / `list_batch_tasks` / `cancel_batch_task` | 管理批量导出任务。 |

服务还通过 `mirror-earth://references/...` MCP 资源公开内置的 API 和模型说明文档。

## 本地开发

```powershell
uv sync
uv run pytest
uv build
```

构建产物输出到 `dist/`。发布新版本时，将 PyPI token 配置到 `UV_PUBLISH_TOKEN` 环境变量后执行：

```powershell
uv publish
```
