Skip to content

usage-examples.md

Latest commit

 

History

History
279 lines (216 loc) · 6.58 KB

usage-examples.md

File metadata and controls

279 lines (216 loc) · 6.58 KB

Usage Examples

Complete examples for using the Lunar Calendar MCP Server.

Python API Examples

Check if a Date is Auspicious

import asyncio
from lunar_mcp_server import LunarMCPServer

async def check_wedding_date():
    server = LunarMCPServer()
    result = await server._check_auspicious_date(
        date="2024-03-15",
        activity="wedding",
        culture="chinese"
    )
    print(f"Wedding on 2024-03-15: {result['auspicious_level']}")
    print(f"Recommendations: {result['recommendations']}")

asyncio.run(check_wedding_date())

Find Good Dates for Business Opening

async def find_business_dates():
    server = LunarMCPServer()
    result = await server._find_good_dates(
        start_date="2024-04-01",
        end_date="2024-04-30",
        activity="business_opening",
        culture="chinese",
        limit=5
    )
    print("Best dates for business opening:")
    for date_info in result['good_dates']:
        print(f"- {date_info['date']}: {date_info['level']} (score: {date_info['score']})")

asyncio.run(find_business_dates())

Get Moon Phase Information

async def moon_phase_info():
    server = LunarMCPServer()
    result = await server._get_moon_phase(
        date="2024-02-14",
        location="40.7128,-74.0060"  # New York City
    )
    print(f"Moon phase on 2024-02-14: {result['phase_name']}")
    print(f"Illumination: {result['illumination']:.1%}")
    print(f"Good for: {', '.join(result['influence']['good_for'])}")

asyncio.run(moon_phase_info())

Get Festival Information

async def festival_info():
    server = LunarMCPServer()
    result = await server._get_lunar_festivals(
        date="2024-02-10",
        culture="chinese"
    )
    if result['festivals']:
        festival = result['festivals'][0]
        print(f"Festival: {festival['name']}")
        print(f"Significance: {festival['significance']}")
        print(f"Traditions: {', '.join(festival['traditions'])}")

asyncio.run(festival_info())

MCP Client Examples

Using with Claude Desktop

Add to your Claude Desktop configuration:

{
  "mcpServers": {
    "lunar-calendar": {
      "command": "uvx",
      "args": ["lunar-mcp-server"]
    }
  }
}

Then ask Claude:

  • "Check if March 15, 2024 is a good date for a wedding"
  • "Find me the best dates in April 2024 for opening a business"
  • "What's the moon phase today and what activities is it good for?"
  • "When is the next Chinese festival?"

Using MCP Inspector

# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector

# Run the server with inspector
mcp-inspector uv run lunar-mcp-server

Visit http://localhost:5173 to test all tools interactively.

Common Use Cases

Wedding Date Planning

async def plan_wedding():
    server = LunarMCPServer()

    # Find good dates
    dates = await server._find_good_dates(
        start_date="2024-06-01",
        end_date="2024-12-31",
        activity="wedding",
        culture="chinese",
        limit=10
    )

    # Check moon phase for each
    for date in dates['good_dates'][:3]:
        moon = await server._get_moon_phase(date['date'])
        print(f"\n{date['date']}:")
        print(f"  Auspiciousness: {date['level']}")
        print(f"  Moon: {moon['phase_name']}")
        print(f"  Score: {date['score']}/10")

Business Opening Consultation

async def business_consultation():
    server = LunarMCPServer()

    # Compare multiple dates
    result = await server._compare_dates(
        dates=["2024-05-01", "2024-05-08", "2024-05-15"],
        activity="business_opening",
        culture="chinese"
    )

    print(f"Best date: {result['recommendation']}")
    for date, info in result['comparison'].items():
        print(f"{date}: Score {info['score']}, {info['zodiac']['animal']}")

Festival Calendar

async def annual_festivals():
    server = LunarMCPServer()

    # Get all festivals for 2024
    festivals = await server._get_annual_festivals(
        year=2024,
        culture="chinese"
    )

    print(f"Total festivals: {festivals['total_festivals']}")
    for month, events in festivals['calendar'].items():
        print(f"\n{month}:")
        for event in events:
            print(f"  - {event['name']}")

Error Handling

async def safe_date_check():
    server = LunarMCPServer()

    try:
        result = await server._check_auspicious_date(
            date="2024-13-45",  # Invalid date
            activity="wedding",
            culture="chinese"
        )
    except ValueError as e:
        print(f"Invalid input: {e}")

    # Check for error in response
    result = await server._check_auspicious_date(
        date="2024-03-15",
        activity="wedding",
        culture="chinese"
    )

    if "error" in result:
        print(f"Error: {result['error']}")
    else:
        print(f"Success: {result['auspicious_level']}")

Advanced Usage

Batch Processing

async def batch_analysis():
    server = LunarMCPServer()

    dates = ["2024-03-01", "2024-03-15", "2024-04-01", "2024-05-01"]

    result = await server._batch_check_dates(
        dates=dates,
        activity="wedding",
        culture="chinese"
    )

    print(f"Best: {result['best_date']}")
    print(f"Worst: {result['worst_date']}")
    print(f"Checked: {result['total_checked']} dates")

Lucky Hour Analysis

async def find_lucky_hours():
    server = LunarMCPServer()

    result = await server._get_lucky_hours(
        date="2024-03-15",
        activity="signing_contract",
        culture="chinese"
    )

    print(f"Best hours on {result['date']}:")
    for hour in result['best_hours']:
        print(f"  {hour['time_range']}: {hour['level']} (score: {hour['score']})")

Integration Examples

With FastAPI

from fastapi import FastAPI
from lunar_mcp_server import LunarMCPServer

app = FastAPI()
server = LunarMCPServer()

@app.get("/check-date/{date}/{activity}")
async def check_date(date: str, activity: str):
    return await server._check_auspicious_date(date, activity, "chinese")

With Flask

from flask import Flask, jsonify
from lunar_mcp_server import LunarMCPServer
import asyncio

app = Flask(__name__)
server = LunarMCPServer()

@app.route('/moon-phase/<date>')
def moon_phase(date):
    result = asyncio.run(server._get_moon_phase(date))
    return jsonify(result)

See Also