feat: Improve interface, testing, defaults, add make docker-build and docker-test

Author: scottchronicity

Dockerfile

@@ -3,18 +3,23 @@ FROM python:3.11-slim AS builder
 
 WORKDIR /app
 
+# Install build dependencies for pyswisseph (C extension)
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    gcc \
+    g++ \
+    make \
+    && rm -rf /var/lib/apt/lists/*
+
 # Install uv
 COPY --from=ghcr.io/astral-sh/uv:latest /uv /bin/uv
 
-# Copy dependency files first (cache layer)
-COPY pyproject.toml uv.lock ./
+# Copy dependency files and source (needed for hatchling to build)
+COPY pyproject.toml uv.lock README.md ./
+COPY src/ src/
 
 # Install dependencies with frozen lockfile (reproducible)
 RUN uv sync --frozen --no-dev --no-editable
 
-# Copy source code
-COPY src/ src/
-
 # Stage 2: Runtime
 FROM python:3.11-slim
 

Makefile

@@ -19,8 +19,12 @@ help:
 	@echo "make test         - Run tests with coverage"
 	@echo "make validate-dev - Run development validation (install, lint, format-check, test)"
 	@echo "make clean        - Remove artifacts and cache"
-	@echo "make docker-build - Build the Docker image"
-	@echo "make docker-run   - Run the Docker container"
+	@echo "make docker-build     - Build the Docker image"
+	@echo "make docker-run       - Run the Docker container interactively"
+	@echo "make docker-happycase - Test the Docker image with a simple query"
+	@echo "make docker-dev       - Full Docker dev workflow (validate, build, test)"
+	@echo "make docker-clean     - Remove Docker images"
+	@echo "make validate-happycase - Test engine locally with a simple query"
 	@echo "make act          - Run GitHub Actions locally (requires 'act')"
 	@echo "make release-dry-run - Dry-run semantic release"
 	@echo "make audit        - Audit dependencies"
@@ -64,6 +68,12 @@ validate-dev:
 	$(MAKE) test
 	@echo "✅ Development simple validation complete!"
 
+validate-happycase:
+	@echo "🧪 Testing engine locally with planetary positions query..."
+	@echo "📍 Querying: 2025-12-16T15:28:00Z at New York (40.7128, -74.0060)"
+	@uv run python -c "from astro_mcp.engine import calculate_chart; result = calculate_chart('2025-12-16T15:28:00Z', 40.7128, -74.0060); print('✅ Engine working!\n'); print('🌟 BODIES:'); [print(f'  {name:18} {data[\"sign\"]:10} {data[\"sign_degrees\"]:6.2f}° ({data[\"motion\"]})') for name, data in result['bodies'].items()]; print('\n🏠 HOUSES:'); [print(f'  {name:18} {data[\"sign\"]:10} {data[\"sign_degrees\"]:6.2f}°') for name, data in result['houses'].items()]"
+	@echo "\n✅ Happy case test passed!"
+
 validate-dev-full: validate-dev
 	@echo "🔍 Running full development validation..."
 	$(MAKE) release-dry-run
@@ -85,11 +95,28 @@ docker-build:
 	@echo "🐳 Building Docker image..."
 	docker build -t $(IMAGE_NAME):$(VERSION) .
 	docker tag $(IMAGE_NAME):$(VERSION) $(IMAGE_NAME):latest
+	@echo "✅ Docker image built: $(IMAGE_NAME):$(VERSION) and $(IMAGE_NAME):latest"
 
 docker-run:
-	@echo "🚀 Running container..."
+	@echo "🚀 Running container interactively..."
 	docker run -it --rm $(IMAGE_NAME):latest
 
+docker-happycase:
+	@echo "🧪 Testing Docker image with planetary positions query..."
+	@echo "📍 Querying: 2025-12-16T15:28:00Z at New York (40.7128, -74.0060)"
+	@docker run --rm $(IMAGE_NAME):latest python -c "from astro_mcp.engine import calculate_chart; import json; result = calculate_chart('2025-12-16T15:28:00Z', 40.7128, -74.0060); print('✅ Docker image working!\n'); print('🌟 BODIES:'); [print(f'  {name:18} {data[\"sign\"]:10} {data[\"sign_degrees\"]:6.2f}° ({data[\"motion\"]})') for name, data in result['bodies'].items()]; print('\n🏠 HOUSES:'); [print(f'  {name:18} {data[\"sign\"]:10} {data[\"sign_degrees\"]:6.2f}°') for name, data in result['houses'].items()]"
+	@echo "\n✅ Docker test passed!"
+
+docker-dev: validate-dev docker-build docker-happycase
+	@echo "✅ Full Docker dev workflow complete!"
+	@echo "📦 Image ready: $(IMAGE_NAME):$(VERSION)"
+	@echo "🚀 To run: make docker-run"
+
+docker-clean:
+	@echo "🧹 Removing Docker images..."
+	docker rmi $(IMAGE_NAME):$(VERSION) $(IMAGE_NAME):latest || true
+	@echo "✅ Docker images removed"
+
 # --- CI/CD (Local) ---
 
 act:
@@ -111,4 +138,4 @@ act-ci:
 
 act-release:
 	@echo "🎬 Running Release workflow locally with act (dry-run)..."
-	act push --container-architecture linux/amd64 -W .github/workflows/cd-release.yml --dryrun
+	act push --container-architecture linux/amd64 -W .github/workflows/cd-release.yml --dryrun

docs/getting-started.md

@@ -38,9 +38,9 @@ docker run -i astro-mcp:latest
 AstroMCP exposes a single MCP tool: `get_planetary_positions`
 
 **Parameters:**
-- `iso_time`: ISO-8601 timestamp (e.g., `2026-01-10T15:00:00`)
-- `latitude`: Observer latitude (default: 43.8)
-- `longitude`: Observer longitude (default: -84.7)
+- `iso_time`: ISO-8601 timestamp (e.g., `2025-12-16T15:28:00`)
+- `latitude`: Observer latitude (default: 42.3314, Detroit, MI)
+- `longitude`: Observer longitude (default: -83.0458, Detroit, MI)
 
 **Returns:** JSON with planetary positions in Tropical Zodiac coordinates.
 

pyproject.toml

@@ -8,7 +8,8 @@ requires-python = ">=3.10, <3.12"
 dependencies = [
     "flatlib",
     "mcp>=0.1.0",
-    "pydantic"
+    "pydantic",
+    "structlog>=24.0.0"
 ]
 
 # This tells uv to install these tools

scaffolding.sh

@@ -98,14 +98,14 @@ from astro_mcp.engine import calculate_chart
 mcp = FastMCP("AstroMCP")
 
 @mcp.tool()
-def get_planetary_positions(iso_time: str, latitude: float = 43.8, longitude: float = -84.7) -> str:
+def get_planetary_positions(iso_time: str, latitude: float = 42.3314, longitude: float = -83.0458) -> str:
     """
     Returns precise astrological positions (Tropical Zodiac) for a given time/place.
-    
+
     Args:
-        iso_time: ISO-8601 string (e.g., '2026-01-10T15:00:00')
-        latitude: Observer latitude (default: Clare County, MI)
-        longitude: Observer longitude (default: Clare County, MI)
+        iso_time: ISO-8601 string (e.g., '2025-12-16T15:28:00')
+        latitude: Observer latitude (default: Detroit, MI)
+        longitude: Observer longitude (default: Detroit, MI)
     """
     try:
         data = calculate_chart(iso_time, latitude, longitude)
@@ -130,7 +130,7 @@ from astro_mcp.engine import calculate_chart
 
 def test_calculate_chart_structure():
     """Ensure the JSON structure matches the ADR spec."""
-    result = calculate_chart("2026-01-01T12:00:00", 43.8, -84.7)
+    result = calculate_chart("2025-12-16T15:28:00", 42.3314, -83.0458)
     
     assert "meta" in result
     assert "bodies" in result

src/astro_mcp/engine.py

@@ -1,14 +1,12 @@
 import datetime
-import logging
 
+import structlog
 from flatlib import const
 from flatlib.chart import Chart
 from flatlib.datetime import Datetime
 from flatlib.geopos import GeoPos
 
-# Configure logging
-logging.basicConfig(level=logging.INFO)
-logger = logging.getLogger(__name__)
+logger = structlog.get_logger(__name__)
 
 
 def calculate_chart(iso_date: str, lat: float, lon: float) -> dict:
@@ -29,7 +27,7 @@ def calculate_chart(iso_date: str, lat: float, lon: float) -> dict:
         pos = GeoPos(lat, lon)
 
         # Calculate the chart with all planets including outer planets
-        # Note: Angles (ASC, MC, NORTH_NODE) cannot be included in IDs parameter
+        # Note: Angles (ASC, MC) are calculated automatically and accessed via chart.get()
         chart = Chart(
             date,
             pos,
@@ -44,12 +42,16 @@ def calculate_chart(iso_date: str, lat: float, lon: float) -> dict:
                 const.URANUS,
                 const.NEPTUNE,
                 const.PLUTO,
+                const.NORTH_NODE,
+                const.SOUTH_NODE,
+                const.CHIRON,
             ],
         )
 
         output = {
             "meta": {"timestamp": iso_date, "lat": lat, "lon": lon, "system": "Geocentric Tropical Zodiac"},
             "bodies": {},
+            "houses": {},
         }
 
         # Define bodies to track
@@ -64,17 +66,38 @@ def calculate_chart(iso_date: str, lat: float, lon: float) -> dict:
             (const.URANUS, "Uranus"),
             (const.NEPTUNE, "Neptune"),
             (const.PLUTO, "Pluto"),
+            (const.NORTH_NODE, "North Node"),
+            (const.SOUTH_NODE, "South Node"),
+            (const.CHIRON, "Chiron"),
+        ]
+
+        # Define angles to track
+        angles = [
             (const.ASC, "Ascendant"),
             (const.MC, "Midheaven"),
-            (const.NORTH_NODE, "North Node"),
+            (const.DESC, "Descendant"),
+            (const.IC, "Imum Coeli"),
+        ]
+
+        # Define house cusps to track
+        houses = [
+            (const.HOUSE1, "House 1"),
+            (const.HOUSE2, "House 2"),
+            (const.HOUSE3, "House 3"),
+            (const.HOUSE4, "House 4"),
+            (const.HOUSE5, "House 5"),
+            (const.HOUSE6, "House 6"),
+            (const.HOUSE7, "House 7"),
+            (const.HOUSE8, "House 8"),
+            (const.HOUSE9, "House 9"),
+            (const.HOUSE10, "House 10"),
+            (const.HOUSE11, "House 11"),
+            (const.HOUSE12, "House 12"),
         ]
 
         for body_id, friendly_name in bodies:
             try:
                 obj = chart.get(body_id)
-
-                # Access speed directly from the object attribute
-                # Angles (ASC/MC) might not have speed, default to 0.0
                 speed = getattr(obj, "lonspeed", 0.0)
 
                 output["bodies"][friendly_name] = {
@@ -85,13 +108,64 @@ def calculate_chart(iso_date: str, lat: float, lon: float) -> dict:
                     "motion": "retrograde" if speed < 0 else "direct",
                     "speed": float(f"{speed:.4f}"),
                 }
-            except KeyError:
-                # Skip planets that couldn't be calculated
-                logger.warning(f"Could not calculate {friendly_name}")
+            except (KeyError, AttributeError) as e:
+                logger.warning(
+                    "Could not calculate body",
+                    body=friendly_name,
+                    error=str(e),
+                    error_type=type(e).__name__,
+                )
+                continue
+
+        # Process angles (ASC, MC, DESC, IC)
+        for angle_id, friendly_name in angles:
+            try:
+                obj = chart.get(angle_id)
+                output["bodies"][friendly_name] = {
+                    "longitude": float(f"{obj.lon:.4f}"),
+                    "sign": str(obj.sign),
+                    "sign_degrees": float(f"{obj.signlon:.4f}"),
+                    "declination": float(f"{obj.lat:.4f}"),
+                    "motion": "direct",
+                    "speed": 0.0,
+                }
+            except (KeyError, AttributeError) as e:
+                logger.warning(
+                    "Could not calculate angle",
+                    angle=friendly_name,
+                    error=str(e),
+                    error_type=type(e).__name__,
+                )
+                continue
+
+        # Process house cusps
+        for house_id, friendly_name in houses:
+            try:
+                obj = chart.get(house_id)
+                output["houses"][friendly_name] = {
+                    "longitude": float(f"{obj.lon:.4f}"),
+                    "sign": str(obj.sign),
+                    "sign_degrees": float(f"{obj.signlon:.4f}"),
+                }
+            except (KeyError, AttributeError) as e:
+                logger.warning(
+                    "Could not calculate house",
+                    house=friendly_name,
+                    error=str(e),
+                    error_type=type(e).__name__,
+                )
                 continue
 
         return output
 
     except Exception as e:
-        logger.error(f"Calculation failed: {e}")
+        logger.error(
+            "Calculation failed",
+            error=str(e),
+            error_type=type(e).__name__,
+            iso_date=iso_date,
+            lat=lat,
+            lon=lon,
+            exc_info=True,
+        )
         raise ValueError(f"Physics Engine Error: {str(e)}")

src/astro_mcp/logging_config.py

@@ -0,0 +1,44 @@
+# See AGENTS.md for project context and conventions
+
+"""Logging configuration for AstroMCP.
+
+This module provides structured logging setup using structlog:
+- JSON-serializable structured events
+- Context binding and processors
+- Integration with stdlib logging for compatibility
+"""
+
+import logging
+import sys
+
+import structlog
+
+
+def setup_logging(level: int = logging.INFO) -> None:
+    """Configure application-wide logging with structlog.
+
+    Args:
+        level: Logging level (default: INFO)
+    """
+    # Configure structlog processors
+    structlog.configure(
+        processors=[
+            structlog.contextvars.merge_contextvars,
+            structlog.processors.add_log_level,
+            structlog.processors.StackInfoRenderer(),
+            structlog.dev.set_exc_info,
+            structlog.processors.TimeStamper(fmt="iso", utc=True),
+            structlog.dev.ConsoleRenderer(),  # Human-readable for development
+        ],
+        wrapper_class=structlog.make_filtering_bound_logger(level),
+        context_class=dict,
+        logger_factory=structlog.PrintLoggerFactory(file=sys.stderr),
+        cache_logger_on_first_use=True,
+    )
+
+    # Also configure stdlib logging for compatibility
+    logging.basicConfig(
+        format="%(message)s",
+        level=level,
+        stream=sys.stderr,
+    )

src/astro_mcp/server.py

@@ -1,19 +1,23 @@
 from mcp.server.fastmcp import FastMCP
 
 from astro_mcp.engine import calculate_chart
+from astro_mcp.logging_config import setup_logging
+
+# Initialize logging
+setup_logging()
 
 mcp = FastMCP("AstroMCP")
 
 
 @mcp.tool()
-def get_planetary_positions(iso_time: str, latitude: float = 43.8, longitude: float = -84.7) -> dict:
+def get_planetary_positions(iso_time: str, latitude: float = 42.3314, longitude: float = -83.0458) -> dict:
     """
     Returns precise astrological positions (Tropical Zodiac) for a given time/place.
 
     Args:
-        iso_time: ISO-8601 string (e.g., '2026-01-10T15:00:00')
-        latitude: Observer latitude (default: Clare County, MI)
-        longitude: Observer longitude (default: Clare County, MI)
+        iso_time: ISO-8601 string (e.g., '2025-12-16T15:28:00')
+        latitude: Observer latitude (default: Detroit, MI)
+        longitude: Observer longitude (default: Detroit, MI)
     """
     data = calculate_chart(iso_date=iso_time, lat=latitude, lon=longitude)
     return data