Skip to content

tools-reference.md

Latest commit

 

History

History
479 lines (395 loc) · 9.85 KB

tools-reference.md

File metadata and controls

479 lines (395 loc) · 9.85 KB

MCP Tools Reference

Complete reference for all 18 MCP tools across 5 categories.

Auspicious Date Tools (4 tools)

check_auspicious_date

Check if a date is favorable for specific activities.

Parameters:

  • date (string): Date in YYYY-MM-DD format
  • activity (string): Activity type (e.g., wedding, business_opening, travel)
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "date": "2024-02-14",
  "lunar_date": "2024-1-5",
  "auspicious_level": "very_good",
  "score": 8,
  "good_for": ["wedding", "business_opening", "travel"],
  "avoid": ["funeral", "major_surgery"],
  "lucky_hours": ["9:00-11:00", "13:00-15:00"],
  "zodiac_day": "dragon",
  "five_elements": "wood",
  "recommendations": "Excellent day for new beginnings"
}

find_good_dates

Find optimal dates within a date range for specific activities.

Parameters:

  • start_date (string): Start date in YYYY-MM-DD format
  • end_date (string): End date in YYYY-MM-DD format
  • activity (string): Activity type
  • culture (string, optional): Cultural tradition (default: "chinese")
  • limit (integer, optional): Maximum number of dates to return (default: 10)

Response:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "activity": "wedding",
  "good_dates": [
    {
      "date": "2024-01-15",
      "level": "very_good",
      "score": 9,
      "zodiac_day": "dragon",
      "lucky_hours": ["9:00-11:00"],
      "moon_phase": "Full Moon"
    }
  ],
  "total_found": 5,
  "best_date": {...}
}

get_daily_fortune

Get comprehensive daily fortune and luck information.

Parameters:

  • date (string): Date in YYYY-MM-DD format
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "date": "2024-01-01",
  "fortune_level": "good",
  "lucky_colors": ["red", "gold"],
  "lucky_numbers": [8, 18],
  "lucky_directions": ["East", "Southeast"],
  "zodiac_day": "rat",
  "five_elements": "wood",
  "advice": "Good day for new beginnings..."
}

check_zodiac_compatibility

Check compatibility between two dates based on zodiac systems.

Parameters:

  • date1 (string): First date in YYYY-MM-DD format
  • date2 (string): Second date in YYYY-MM-DD format
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "date1": "1990-01-01",
  "date2": "1992-01-01",
  "compatibility_level": "excellent",
  "score": 9,
  "zodiac1": "Horse",
  "zodiac2": "Monkey",
  "element_compatibility": "harmonious",
  "recommendations": "Very compatible pair..."
}

Festival Tools (4 tools)

get_lunar_festivals

Get festivals occurring on a specific date.

Parameters:

  • date (string): Date in YYYY-MM-DD format
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "date": "2024-02-10",
  "festivals": [
    {
      "name": "Spring Festival (Chinese New Year)",
      "significance": "Beginning of lunar new year",
      "traditions": ["family reunion", "fireworks"],
      "foods": ["dumplings", "fish"],
      "is_major": true
    }
  ],
  "festival_count": 1
}

get_next_festival

Find the next upcoming festival after a given date.

Parameters:

  • date (string): Starting date in YYYY-MM-DD format
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "search_date": "2024-01-01",
  "next_festival_date": "2024-02-10",
  "days_until": 40,
  "festival": {
    "name": "Spring Festival",
    "significance": "...",
    "traditions": [...]
  }
}

get_festival_details

Get detailed information about a specific festival.

Parameters:

  • festival_name (string): Name of the festival
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "festival_id": "spring_festival",
  "name": "Spring Festival (Chinese New Year)",
  "significance": "Beginning of lunar new year",
  "duration": 15,
  "traditions": ["family reunion", "fireworks"],
  "foods": ["dumplings", "fish"],
  "lucky_activities": ["visiting relatives"],
  "taboos": ["sweeping on first day"],
  "preparation_guide": {...}
}

get_annual_festivals

Get all festivals for a specific year.

Parameters:

  • year (integer): Year (e.g., 2024)
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "year": 2024,
  "culture": "chinese",
  "total_festivals": 8,
  "major_festivals": ["spring_festival", "mid_autumn"],
  "calendar": {
    "1": [...],
    "2": [...],
    ...
  }
}

Moon Phase Tools (4 tools)

get_moon_phase

Get moon phase information for a specific date and location.

Parameters:

  • date (string): Date in YYYY-MM-DD format
  • location (string, optional): Coordinates "lat,lon" (default: "0,0")

Response:

{
  "date": "2024-01-01",
  "phase_name": "Full Moon",
  "illumination": 0.98,
  "lunar_day": 15,
  "influence": {
    "good_for": ["celebrations", "completion"],
    "avoid": ["starting new projects"],
    "luck_level": "very good"
  }
}

get_moon_calendar

Get monthly calendar with moon phases.

Parameters:

  • month (integer): Month (1-12)
  • year (integer): Year
  • location (string, optional): Coordinates (default: "0,0")

Response:

{
  "month": 1,
  "year": 2024,
  "calendar": [
    {
      "date": "2024-01-01",
      "phase_name": "Waning Crescent",
      "illumination": 0.15,
      "lunar_day": 20
    },
    ...
  ]
}

get_moon_influence

Get how moon phase affects specific activities.

Parameters:

  • date (string): Date in YYYY-MM-DD format
  • activity (string): Activity type

Response:

{
  "date": "2024-01-01",
  "activity": "planting",
  "moon_phase": "New Moon",
  "influence": "favorable",
  "recommendation": "Good time for planting seeds..."
}

predict_moon_phases

Predict moon phases within a date range.

Parameters:

  • start_date (string): Start date in YYYY-MM-DD format
  • end_date (string): End date in YYYY-MM-DD format

Response:

{
  "start_date": "2024-01-01",
  "end_date": "2024-01-31",
  "phases": [
    {
      "date": "2024-01-11",
      "phase": "New Moon",
      "illumination": 0.0
    },
    {
      "date": "2024-01-25",
      "phase": "Full Moon",
      "illumination": 1.0
    }
  ]
}

Calendar Conversion Tools (3 tools)

solar_to_lunar

Convert Gregorian (solar) date to Chinese lunar date.

Parameters:

  • solar_date (string): Solar date in YYYY-MM-DD format
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "solar_date": "2024-01-01",
  "lunar_year": 2023,
  "lunar_month": 11,
  "lunar_day": 20,
  "zodiac_info": {
    "animal": "Rabbit",
    "element": "Water",
    "yin_yang": "Yin"
  }
}

lunar_to_solar

Convert Chinese lunar date to Gregorian (solar) date.

Parameters:

  • lunar_date (string): Lunar date in YYYY-MM-DD format
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "lunar_date": "2024-01-01",
  "solar_date": "2024-02-10",
  "festival": "Spring Festival",
  "zodiac_info": {...}
}

get_zodiac_info

Get detailed Chinese zodiac information for a date.

Parameters:

  • date (string): Date in YYYY-MM-DD format
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "date": "1990-01-01",
  "zodiac": {
    "animal": "Horse",
    "element": "Earth",
    "yin_yang": "Yang",
    "traits": {
      "personality": "energetic, independent",
      "strengths": ["charismatic", "confident"],
      "weaknesses": ["impatient", "stubborn"]
    },
    "compatibility": {
      "best": ["Tiger", "Dog", "Goat"],
      "challenging": ["Rat", "Ox"]
    }
  }
}

Advanced Tools (3 tools)

batch_check_dates

Check multiple dates at once for efficiency.

Parameters:

  • dates (array): List of dates in YYYY-MM-DD format (max 30)
  • activity (string): Activity type
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "total_checked": 5,
  "results": [
    {
      "date": "2024-01-01",
      "score": 7,
      "level": "good",
      "details": {...}
    },
    ...
  ],
  "best_date": "2024-01-15",
  "worst_date": "2024-01-03"
}

compare_dates

Compare multiple dates side-by-side.

Parameters:

  • dates (array): List of dates to compare (max 10)
  • activity (string, optional): Activity for context
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "comparison": {
    "2024-01-01": {
      "auspicious_level": "good",
      "score": 7,
      "moon_phase": "New Moon",
      "zodiac": {...},
      "festivals": []
    },
    "2024-01-15": {...}
  },
  "recommendation": "2024-01-15",
  "activity": "wedding"
}

get_lucky_hours

Get auspicious hours within a specific day (12 Chinese time periods).

Parameters:

  • date (string): Date in YYYY-MM-DD format
  • activity (string, optional): Activity for context
  • culture (string, optional): Cultural tradition (default: "chinese")

Response:

{
  "date": "2024-01-01",
  "activity": "signing_contract",
  "lucky_hours": [
    {
      "time_range": "07:00-09:00",
      "period": "Chen (辰)",
      "zodiac_animal": "Dragon",
      "score": 9,
      "level": "very_good",
      "suitable_for": ["business", "signing contracts"]
    },
    ...
  ],
  "best_hours": [...]
}

Error Responses

All tools return error responses in this format:

{
  "error": "Error message describing what went wrong"
}

Common errors:

  • Invalid date format
  • Missing required parameters
  • Invalid cultural tradition
  • Date out of range

See Also