v1.2.0 - MCP Prompts & Resources Enhancement

🚀 MCP Enhancement: Prompts and Resources for Better Discoverability

New Features

MCP Prompts System (5 New Prompts)

This release introduces Model Context Protocol (MCP) Prompts to improve user experience and discoverability, particularly for LobeHub marketplace integration.

1. check_wedding_date

Check if a specific date is auspicious for wedding ceremonies:

• Input: Date in YYYY-MM-DD format
• Returns: Detailed lunar analysis, zodiac influences, and recommendations
• Use Case: Wedding planning with traditional Chinese calendar guidance

2. calculate_bazi_chart

Calculate comprehensive BaZi (Four Pillars of Destiny) chart:

• Input: Birth datetime, timezone offset
• Returns: Four pillars, eight characters, element analysis, personality insights
• Use Case: Personal fortune analysis and life guidance

3. find_auspicious_dates

Find the most auspicious dates for specific activities:

• Input: Start date, end date, activity type
• Returns: Ranked dates with scores and detailed explanations
• Use Case: Planning important events and activities

4. get_daily_almanac

Get comprehensive daily almanac information:

• Input: Date in YYYY-MM-DD format
• Returns: Fortune, festivals, moon phase, lucky hours, recommendations
• Use Case: Daily planning and decision making

5. check_relationship_compatibility

Analyze relationship compatibility based on BaZi charts:

• Input: Two birth datetimes
• Returns: Compatibility score, element analysis, strengths, challenges
• Use Case: Relationship counseling and compatibility assessment

MCP Resources System (5 New Resources)

Structured reference data accessible via custom lunar:// URI scheme:

1. lunar://zodiac/animals

Complete information about the 12 Chinese zodiac animals:

• Characteristics and traits for each animal
• Element associations
• Cultural significance

2. lunar://elements/five

Five Elements (Wu Xing) reference data:

• Generation cycle (生): Wood→Fire→Earth→Metal→Water
• Control cycle (克): Element relationships
• Characteristics and associations

3. lunar://festivals/major

Major traditional Chinese festivals:

• Festival names and dates
• Cultural significance
• Traditional customs

4. lunar://stems-branches/heavenly

10 Heavenly Stems (天干):

• Complete list with Chinese and English names
• Element associations
• Yin/Yang polarity

5. lunar://stems-branches/earthly

12 Earthly Branches (地支):

• Complete list with Chinese and English names
• Zodiac animal associations
• Element relationships

Technical Highlights

MCP Protocol Implementation

• Prompts Handlers: list_prompts() and get_prompt() with full validation
• Resources Handlers: list_resources() and read_resource() with JSON responses
• URI Scheme: Custom lunar:// namespace for clarity and organization
• Protocol Compliance: Follows MCP specification 2024-11-05
• Type Safety: Full type hints and pydantic validation

Integration Features

• Argument Validation: Required and optional parameters with descriptive names
• Error Handling: Comprehensive error messages for missing arguments
• JSON Responses: Structured data with rich metadata
• Cross-References: Links existing 20 tools with new prompts

LobeHub Marketplace Benefits

• Enhanced Discoverability: Structured prompts help users find relevant features
• Better Onboarding: Resources provide quick reference to Chinese cultural concepts
• Improved Quality Score: MCP protocol enhancements boost marketplace rating
• Richer Context: More metadata for AI model interactions

Quality & Testing

• ✅ 210 tests passing (+48 new tests, +30% increase)
• ✅ 100% code quality: black, isort, ruff, mypy all passing
• ✅ CI/CD green: All checks passing on Python 3.11, 3.12
• ✅ 48 comprehensive tests: 15 prompt tests + 15 resource tests + 18 error handling tests
• ✅ Integration validated: All prompts and resources fully tested

Installation

# Using pip
pip install --upgrade lunar-mcp-server

# Using uvx (recommended)
uvx lunar-mcp-server

# Claude Desktop integration
# Update your claude_desktop_config.json:
{
  "mcpServers": {
    "lunar-calendar": {
      "command": "uvx",
      "args": ["lunar-mcp-server"]
    }
  }
}

Usage Examples

Using Prompts

# List available prompts
prompts = await server.list_prompts()
# Returns: 5 prompts with descriptions

# Get a specific prompt
result = await server.get_prompt(
    name="check_wedding_date",
    arguments={"date": "2024-05-20"}
)
# Returns: Detailed wedding date analysis prompt

Accessing Resources

# List available resources
resources = await server.list_resources()
# Returns: 5 resources with URIs

# Read a specific resource
data = await server.read_resource(
    uri="lunar://zodiac/animals"
)
# Returns: Complete zodiac animals data in JSON

What's Changed

Added

• 5 new MCP prompts for common use cases
• 5 new MCP resources for reference data
• Custom lunar:// URI scheme implementation
• Comprehensive prompt argument validation
• Structured JSON resource responses
• 48 new integration tests
• Enhanced MCP protocol handlers

Enhanced

• Total prompts: 0 → 5
• Total resources: 0 → 5
• Total tests: 162 → 210 (+30%)
• MCP protocol compliance: Enhanced
• Documentation: Added prompts and resources guide

Technical Details

• New handlers: 4 MCP protocol handlers (prompts + resources)
• Code additions: +630 lines in server.py
• Test coverage: +336 lines of comprehensive tests
• Type safety: Full type hints throughout
• Error handling: Graceful handling of invalid inputs

Breaking Changes

None - fully backward compatible with v1.1.0

Documentation

• CHANGELOG.md: Updated with v1.2.0 details
• Test Coverage: 48 comprehensive test cases
• MCP Protocol: Full specification compliance
• Usage Examples: Prompt and resource usage patterns

Full Changelog

See CHANGELOG.md

Contributors

Thanks to all contributors who made this release possible!

---

Previous Release: v1.1.0
Full Changelog: v1.1.0...v1.2.0