Metadata-Version: 2.4
Name: w8s-astro-mcp
Version: 0.11.1
Summary: Personal astrological MCP server — natal charts, transits, aspects, composite & Davison relationship charts, backed by SQLite
Project-URL: Homepage, https://github.com/w8s/w8s-astro-mcp
Project-URL: Repository, https://github.com/w8s/w8s-astro-mcp
Project-URL: Issues, https://github.com/w8s/w8s-astro-mcp/issues
Author: Todd Waits
License: AGPL-3.0-or-later
License-File: LICENSE_NOTICE.md
Keywords: astro,astrology,mcp,natal-chart,swiss-ephemeris,tarot,transits
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: End Users/Desktop
Classifier: License :: OSI Approved :: GNU Affero General Public License v3 or later (AGPLv3+)
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Astronomy
Requires-Python: >=3.10
Requires-Dist: matplotlib>=3.5.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: numpy>=1.21.0
Requires-Dist: pysweph>=2.10.3.3
Requires-Dist: python-dateutil>=2.8.0
Requires-Dist: sqlalchemy>=2.0.0
Requires-Dist: timezonefinder<8.0.0,>=6.0.0
Provides-Extra: dev
Requires-Dist: black>=23.0.0; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=7.0.0; extra == 'dev'
Description-Content-Type: text/markdown

<!-- mcp-name: io.github.w8s/w8s-astro-mcp -->
# w8s-astro-mcp

[![Tests](https://github.com/w8s/w8s-astro-mcp/actions/workflows/tests.yml/badge.svg)](https://github.com/w8s/w8s-astro-mcp/actions/workflows/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/w8s-astro-mcp)](https://pypi.org/project/w8s-astro-mcp/)
[![Python versions](https://img.shields.io/pypi/pyversions/w8s-astro-mcp)](https://pypi.org/project/w8s-astro-mcp/)
[![License: AGPL-3.0](https://img.shields.io/badge/License-AGPL--3.0-blue.svg)](LICENSE)

Personal astrological MCP server using the Swiss Ephemeris via pysweph. Provides natal charts, transit calculations, aspect analysis, chart visualization, and relationship chart support (composite & Davison) — all backed by a queryable SQLite database.

## Features

- **Natal charts** — planetary positions, houses, and angles at birth
- **Transit calculations** — current sky positions auto-logged to history
- **Transit history** — query logged transits by date, planet, or sign
- **Ingress forecasting** — upcoming or past sign ingresses and stations; supports far-future and historical windows
- **Aspect analysis** — compare any two charts (natal vs natal, natal vs transits, natal vs event)
- **House placements** — determine which house each planet occupies
- **Chart visualization** — render natal chart wheels as PNG
- **Multi-profile** — manage charts for multiple people
- **Relationship charts** — composite and Davison charts for any group of 2+ people
- **Event charts** — cast charts for any moment and place; optionally save and compare
- **Electional astrology** — scan a time window for auspicious moments against configurable criteria

## Installation

### Add to Claude Desktop

Edit `~/Library/Application Support/Claude/claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "w8s-astro-mcp": {
      "command": "uvx",
      "args": ["w8s-astro-mcp"]
    }
  }
}
```

`uvx` pulls the package from PyPI and runs it in an isolated environment — no manual install needed. If you don't have `uv`, install it with:

```bash
brew install uv
```

### Alternative: pip install

```bash
pip install w8s-astro-mcp
```

Then use `"command": "w8s-astro-mcp"` (no `args`) in your Claude Desktop config.

## First-Time Setup

On first use, create your profile:

> "Create an astro profile for me — my name is [Name], born [date] at [time] in [city, state]."

Claude will use `create_profile` to set up your birth data and set you as the active profile. Everything is stored in `~/.w8s-astro-mcp/astro.db`.

## Tools

### Core (9)

| Tool | Description |
|------|-------------|
| `check_ephemeris` | Report ephemeris mode (Moshier/Swiss Ephemeris), pysweph version, and precision |
| `download_ephemeris_files` | Download Swiss Ephemeris .se1 files for higher precision (optional) |
| `setup_astro_config` | *(deprecated)* Legacy config wizard |
| `view_config` | Show current profile and saved locations |
| `get_natal_chart` | Planetary positions, houses, and angles at birth |
| `get_transits` | Current sky positions (auto-logged to history) |
| `compare_charts` | Aspects between any two charts |
| `find_house_placements` | Which house each planet occupies |
| `visualize_natal_chart` | Render natal chart wheel as PNG |

### Transit History & Forecasting — Phase 4 (3)

| Tool | Description |
|------|-------------|
| `get_transit_history` | Query logged transits by date range, planet, or sign |
| `find_last_transit` | Most recent logged transit matching planet + sign/retrograde/house |
| `get_ingresses` | Ephemeris-backed sign ingress and station forecast; supports offset, future/past, and extended mode for historical or far-future windows |

### Profile Management (7)

| Tool | Description |
|------|-------------|
| `list_profiles` | All profiles in the database |
| `create_profile` | Add a new person's birth data |
| `update_profile` | Edit name, birth date, or birth time |
| `delete_profile` | Remove a profile (must leave connections first) |
| `set_current_profile` | Switch the active profile |
| `add_location` | Save a named location to a profile |
| `remove_location` | Delete a saved location |

### Connection Management — Phase 7 (6)

| Tool | Description |
|------|-------------|
| `create_connection` | Name a group of 2+ profiles |
| `list_connections` | All connections in the database |
| `add_connection_member` | Add a profile to a connection |
| `remove_connection_member` | Remove a profile (invalidates cached charts) |
| `get_connection_chart` | Calculate or retrieve composite/Davison chart |
| `delete_connection` | Remove a connection and all its charts |

### Event Charts & Electional Astrology — Phase 8 (4)

| Tool | Description |
|------|-------------|
| `cast_event_chart` | Cast a chart for any date/time/location; optionally save by label for later reference |
| `list_event_charts` | List all saved event charts; filter by associated profile |
| `delete_event_chart` | Remove a saved event chart and all its positions |
| `find_electional_windows` | Scan a time window (up to 90 days) and return candidate moments scored against criteria: Moon not void, planets direct, benefics angular, Moon waxing/waning, ASC not late degree |

`compare_charts` also accepts `event:<label>` as a chart source, enabling comparisons like `compare_charts(chart1_date="natal", chart2_date="event:wedding-2026")`.

## Database

All data lives in `~/.w8s-astro-mcp/astro.db` — a standard SQLite file you can query directly.

```bash
sqlite3 ~/.w8s-astro-mcp/astro.db

# Most-checked transit planets
SELECT planet, COUNT(*) AS checks
FROM transit_planets GROUP BY planet ORDER BY checks DESC;

# All connections
SELECT c.label, c.type FROM connections c;
```

See `docs/DATABASE_SCHEMA.md` for the full schema with ERDs and example queries.

## Architecture

See `docs/ARCHITECTURE.md` for data flow diagrams, design decisions, and the full directory structure.

**Key design choices:**
- Natal and transit positions stored as normalized rows (not JSON blobs) — fully queryable
- Every `get_transits` call auto-logs to history with a denormalized location snapshot (saved locations only — ad-hoc geocoded locations are not persisted)
- `get_transits` accepts any city name inline — geocoded via Nominatim with accurate IANA timezone lookup via `timezonefinder`
- Connection charts cached with an `is_valid` flag — invalidated when members change, recalculated on next access
- Position format normalized at write time via `_normalize_position()` — both composite math output and pysweph decimal-degree output coerced to `degree/minutes/seconds/absolute_position`

## Testing

```bash
# Full suite
pytest

# By domain
pytest tests/models/                          # ORM model tests
pytest tests/test_connection_calculator.py    # Composite & Davison math
pytest tests/test_connection_db_helpers.py    # Integration tests (real SQLite)

# With coverage
pytest --cov=src/w8s_astro_mcp
```

302 tests. See `docs/ARCHITECTURE.md` for the full test command reference.

## Roadmap

See `docs/ROADMAP.md` for planned phases including database self-healing tools (Phase 9).

## Questions, Bugs, Ideas

Open an issue on [GitHub](https://github.com/w8s/w8s-astro-mcp/issues) — that's the best place for bug reports, feature requests, or questions.

## License

AGPL-3.0
