Caiyun Weather MCP Server

Instructions

Implementation Reference

• src/caiyun-service.ts:30-47 (handler)

  Core handler function getRealtime that makes the API call to retrieve realtime weather data from Caiyun API.

  async getRealtime(longitude: number, latitude: number): Promise<CaiyunWeatherResponse> {
    try {
      const url = `${this.baseUrl}/${this.apiKey}/${longitude},${latitude}/realtime`;
      const response = await axios.get<CaiyunWeatherResponse>(url, {
        params: {
          lang: this.language,
          unit: this.unit
        }
      });
      
      return response.data;
    } catch (error) {
      if (axios.isAxiosError(error)) {
        throw new Error(`彩云天气API错误: ${error.response?.data?.error || error.message}`);
      }
      throw error;
    }
  }

• src/index.ts:450-470 (handler)

  MCP tool dispatch handler for 'get_realtime_weather': validates input, calls service, formats and returns response.

  case 'get_realtime_weather': {
    if (!this.isValidLocationArgs(args)) {
      throw new McpError(
        ErrorCode.InvalidParams,
        '无效的位置参数'
      );
    }
    
    const { longitude, latitude } = args;
    
    const weatherData = await weatherService.getRealtime(longitude, latitude);
    
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(weatherService.formatRealtimeData(weatherData), null, 2),
        },
      ],
    };
  }

• src/index.ts:157-185 (schema)

  Input schema definition for the 'get_realtime_weather' tool, specifying required longitude/latitude and optional language/unit.

    name: 'get_realtime_weather',
    description: '获取实时天气数据',
    inputSchema: {
      type: 'object',
      properties: {
        longitude: {
          type: 'number',
          description: '经度',
        },
        latitude: {
          type: 'number',
          description: '纬度',
        },
        language: {
          type: 'string',
          enum: ['zh_CN', 'en_US'],
          description: '语言',
          default: 'zh_CN',
        },
        unit: {
          type: 'string',
          enum: ['metric', 'imperial'],
          description: '单位制 (metric: 公制, imperial: 英制)',
          default: 'metric',
        },
      },
      required: ['longitude', 'latitude'],
    },
  },

• src/index.ts:156-185 (registration)

  Registration of the 'get_realtime_weather' tool in the ListToolsRequestSchema handler.

  {
    name: 'get_realtime_weather',
    description: '获取实时天气数据',
    inputSchema: {
      type: 'object',
      properties: {
        longitude: {
          type: 'number',
          description: '经度',
        },
        latitude: {
          type: 'number',
          description: '纬度',
        },
        language: {
          type: 'string',
          enum: ['zh_CN', 'en_US'],
          description: '语言',
          default: 'zh_CN',
        },
        unit: {
          type: 'string',
          enum: ['metric', 'imperial'],
          description: '单位制 (metric: 公制, imperial: 英制)',
          default: 'metric',
        },
      },
      required: ['longitude', 'latitude'],
    },
  },

• src/caiyun-service.ts:221-278 (helper)

  Helper function to format realtime weather data into a structured, human-readable JSON response.

  formatRealtimeData(data: CaiyunWeatherResponse) {
    const realtime = data.result.realtime;
    if (!realtime) {
      throw new Error('没有实时天气数据');
    }
  
    return {
      location: data.location,
      server_time: new Date(data.server_time * 1000).toISOString(),
      temperature: realtime.temperature,
      apparent_temperature: realtime.apparent_temperature,
      humidity: realtime.humidity,
      weather: this.getSkyconText(realtime.skycon),
      weather_code: realtime.skycon,
      wind: {
        speed: realtime.wind.speed,
        direction: realtime.wind.direction
      },
      pressure: realtime.pressure,
      visibility: realtime.visibility,
      precipitation: {
        local: {
          intensity: realtime.precipitation.local.intensity,
          type: this.getPrecipitationTypeText(realtime.precipitation.local.type)
        },
        nearest: realtime.precipitation.nearest ? {
          intensity: realtime.precipitation.nearest.intensity,
          type: this.getPrecipitationTypeText(realtime.precipitation.nearest.type),
          distance: realtime.precipitation.nearest.distance
        } : {
          intensity: 0,
          type: this.getPrecipitationTypeText('none'),
          distance: 0
        }
      },
      air_quality: {
        aqi: realtime.air_quality.aqi.chn,
        pm25: realtime.air_quality.pm25,
        pm10: realtime.air_quality.pm10,
        o3: realtime.air_quality.o3,
        so2: realtime.air_quality.so2,
        no2: realtime.air_quality.no2,
        co: realtime.air_quality.co,
        description: realtime.air_quality.description.chn,
        trend: realtime.air_quality.trend,
        primary_pollutant: realtime.air_quality.primary_pollutant
      },
      life_index: {
        comfort: realtime.life_index.comfort?.desc || '暂无数据',
        ultraviolet: realtime.life_index.ultraviolet?.desc || '暂无数据',
        sport: realtime.life_index.sport?.desc || '暂无数据',
        travel: realtime.life_index.travel?.desc || '暂无数据',
        cold: realtime.life_index.cold?.desc || '暂无数据',
        carWashing: realtime.life_index.carWashing?.desc || '暂无数据',
        dressing: realtime.life_index.dressing?.desc || '暂无数据'
      }
    };
  }