Qweather

This project is an MCP (Model Context Protocol) server for the QWeather API. The API tools were generated from the provided openapi.yml file with the help from Gemini and supports both standard API Key authentication and JWT-based authentication for specific endpoints.

Features

• Flexible Authentication: Prioritizes JWT authentication if configured. Falls back to API Key if JWT is not available.
• Environment-based Configuration: All sensitive data and settings are managed via a .env file.
• Deployment Ready: Includes configurations for easy deployment using both uv and Docker.

English Instructions

Prerequisites

• Python 3.11+
• uv (or pip) for package management
• Docker and Docker Compose (for containerized deployment)

Configuration

1. Copy the example environment file:

   cp .env.example .env
   

2. Edit the .env file:

   • QWEATHER_API_KEY: Your standard API key from the QWeather Console.
   • For JWT authentication (Recommend):
     • Go to Authentication | QWeather Developers to understand how to get your credentials.
     • QWEATHER_JWT_SUB: Your Project ID (sub).
     • QWEATHER_JWT_KID: Your Credential ID (kid).
     • QWEATHER_JWT_PRIVATE_KEY_PATH: The path to your Ed25519 private key file (e.g., ./ed25519-private.pem). Make sure this file is present in the project directory.

Running with uv (Recommended for Development Environment)

1. Install dependencies by uv sync:

   uv sync
   

2. Run the server using the 'start' script:

   uv run ./main.py
   

   The server will be available at http://localhost:8000.

Running with Docker

1. Build and run the container:

   docker-compose up --build
   

   The server will be available at http://localhost:8000 (or the port you specified in docker-compose.yml).

中文说明

项目简介

本项目是一个针对和风天气 API 的 MCP (Model Context Protocol) 服务器。它在 Gemini 的帮助下由项目中的 openapi.yml 文件生成而来，并支持标准的 API Key 认证以及针对特定接口的 JWT 认证。

功能特性

• 灵活的认证机制: 如果配置了 JWT，则优先使用 JWT 进行认证。如果 JWT 未配置，则自动回退到使用 API Key。
• 环境变量配置: 所有敏感数据和配置均通过 .env 文件管理。
• 易于部署: 提供了使用 uv 和 Docker 两种方式的部署配置。

环境准备

• Python 3.11+
• uv (或 pip) 用于包管理
• Docker 和 Docker Compose (用于容器化部署)

配置步骤

1. 复制环境变量文件范例:

   cp .env.example .env
   

2. 编辑 .env 文件:

   • QWEATHER_API_KEY: 你在 和风天气控制台 获取的标准 API Key。
   • 对于 JWT 认证 (推荐使用):
     • 请参考 身份认证 | 和风天气开发服务 来获取认证所需信息。
     • QWEATHER_JWT_SUB: 你的项目 ID (sub)。
     • QWEATHER_JWT_KID: 你的凭据 ID (kid)。
     • QWEATHER_JWT_PRIVATE_KEY_PATH: 你的 Ed25519 私钥文件路径 (例如 ./ed25519-private.pem)。请确保该文件存在于项目目录中。

使用 uv 运行 (推荐开发环境使用)

1. 使用 uv sync 安装依赖:

   uv sync
   

2. 使用 'start' 脚本运行服务器:

   uv run ./main.py
   

   服务器将在 http://localhost:8000 上可用。

使用 Docker 运行

1. 构建并运行容器:

   docker-compose up --build
   

   服务器将在 http://localhost:8000 (或你在 docker-compose.yml 文件中指定的端口) 上可用。