CLAUDE.md•2.27 kB
# CLAUDE.md
This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.
## Project Overview
This is a Fortune MCP Server (Model Context Protocol) that provides horoscope calculations and tarot card readings in Japanese. The server exposes two main tools through the MCP protocol:
1. **draw_tarot**: Returns tarot card readings with Japanese card names and meanings
2. **get_horoscope**: Calculates astrological horoscopes using Swiss Ephemeris data
## Architecture
- **MCP Server Framework**: Built using FastMCP from the `mcp` library
- **Astronomical Calculations**: Uses `pyswisseph` for precise planetary position calculations
- **Timezone Handling**: Uses `pytz` for timezone conversions (defaults to JST/Tokyo)
- **Entry Point**: `fortune_mcp/server.py:main` function serves as the MCP server entry point
### Key Components
- `fortune_mcp/server.py`: Main server implementation containing:
- Tarot card data (major and minor arcana) with Japanese names and meanings
- `draw_tarot()` tool: Randomly selects cards and returns interpretations
- `get_horoscope()` tool: Calculates planetary positions, houses, and aspects
- Zodiac sign calculations and astrological aspect detection
## Common Commands
### Development Setup
```bash
# Install dependencies
uv sync
# Run the MCP server
uv run fortune-mcp-server
# Alternative direct execution
uv run python fortune_mcp/server.py
```
### MCP Configuration
The server is configured to run via `uv run fortune-mcp-server` as defined in `pyproject.toml`. The `.mcp.json` file shows the expected MCP client configuration.
## Dependencies
- `mcp[cli]>=1.12.4`: MCP protocol implementation
- `pyswisseph>=2.10.3.2`: Swiss Ephemeris library for astronomical calculations
- `pytz>=2025.2`: Timezone handling
## Development Notes
- All text output is in Japanese (card names, meanings, horoscope descriptions)
- Horoscope calculations default to Tokyo coordinates (35.6895°N, 139.6917°E)
- The server supports date/time input in 'YYYY-MM-DD HH:MM:SS' or 'YYYY-MM-DD' formats
- Aspect calculations include conjunction, sextile, square, trine, and opposition with specific orb tolerances
- Maximum of 10 tarot cards can be drawn at once, with 3 as the default