Caiyun Weather MCP Server

Instructions

Implementation Reference

• src/index.ts:73-115 (registration)

  Tool registration in ListToolsRequestSchema handler, including name, description, and input schema definition.

    name: 'get_weather_by_location',
    description: '根据经纬度获取天气信息',
    inputSchema: {
      type: 'object',
      properties: {
        longitude: {
          type: 'number',
          description: '经度',
        },
        latitude: {
          type: 'number',
          description: '纬度',
        },
        daily_steps: {
          type: 'number',
          description: '每日预报天数 (1-15)',
          minimum: 1,
          maximum: 15,
          default: 5,
        },
        hourly_steps: {
          type: 'number',
          description: '小时预报数量 (1-360)',
          minimum: 1,
          maximum: 360,
          default: 24,
        },
        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:393-418 (handler)

  MCP CallToolRequestSchema handler case for get_weather_by_location: validates args, calls CaiyunWeatherService.getWeather and formatWeatherData, returns formatted JSON as text content.

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

• src/caiyun-service.ts:165-191 (handler)

  Core implementation in CaiyunWeatherService.getWeather: makes API call to Caiyun weather endpoint with location and forecast steps, returns raw API response.

  async getWeather(
    longitude: number, 
    latitude: number, 
    dailysteps: number = 5, 
    hourlysteps: number = 24,
    alert: boolean = true
  ): Promise<CaiyunWeatherResponse> {
    try {
      const url = `${this.baseUrl}/${this.apiKey}/${longitude},${latitude}/weather`;
      const response = await axios.get<CaiyunWeatherResponse>(url, {
        params: {
          dailysteps: Math.min(Math.max(dailysteps, 1), 15),
          hourlysteps: Math.min(Math.max(hourlysteps, 1), 360),
          alert,
          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/caiyun-service.ts:468-496 (helper)

  Helper method formatWeatherData: combines and formats realtime, minutely, hourly, daily, and alert data from API response into structured output.

  formatWeatherData(data: CaiyunWeatherResponse) {
    const result: any = {
      location: data.location,
      server_time: new Date(data.server_time * 1000).toISOString(),
      forecast_keypoint: data.result.forecast_keypoint
    };
  
    if (data.result.realtime) {
      result.realtime = this.formatRealtimeData(data);
    }
  
    if (data.result.minutely) {
      result.minutely = this.formatMinutelyData(data);
    }
  
    if (data.result.hourly) {
      result.hourly = this.formatHourlyData(data);
    }
  
    if (data.result.daily) {
      result.daily = this.formatDailyData(data);
    }
  
    if (data.result.alert) {
      result.alert = this.formatAlertData(data);
    }
  
    return result;
  }

• src/index.ts:628-637 (helper)

  Validation helper isValidLocationArgs used in the tool handler to check longitude, latitude, and optional steps.

  private isValidLocationArgs(args: any): args is { longitude: number; latitude: number; daily_steps?: number; hourly_steps?: number } {
    return (
      typeof args === 'object' &&
      args !== null &&
      typeof args.longitude === 'number' &&
      typeof args.latitude === 'number' &&
      (args.daily_steps === undefined || typeof args.daily_steps === 'number') &&
      (args.hourly_steps === undefined || typeof args.hourly_steps === 'number')
    );
  }