mingli-mcp: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Quick Start

# Activate virtual environment
source venv/bin/activate

# Install development dependencies
pip install -e ".[dev]"

# Run the server (stdio mode for MCP)
python -m mingli_mcp

# Run HTTP transport (for Docker/server deployments)
TRANSPORT_TYPE=http HTTP_PORT=8080 python -m mingli_mcp

Common Development Commands

Testing

# Run all tests
pytest

# Run with verbose output
pytest -v

# Test with coverage
pytest --cov=. --cov-report=term-missing --cov-report=html
open htmlcov/index.html

# Run specific test file
pytest tests/test_bazi.py

# Run specific test function
pytest tests/test_ziwei.py::test_ziwei_chart

Code Quality

# Format code
black .

# Check import sorting
isort .

# Lint with flake8
flake8 .

# Type check with mypy
mypy .

# Run all quality checks at once
black --check . && isort --check-only . && flake8 . && pytest

Building and Publishing

# Clean build artifacts
rm -rf build/ dist/ *.egg-info

# Build package
python -m build

# Check package
twine check dist/*

# Publish to PyPI
twine upload dist/*

Development Workflow

# Debug with logging
LOG_LEVEL=DEBUG python -m mingli_mcp

Code Architecture

This is a Model Context Protocol (MCP) server for Chinese fortune telling systems with a modular, plugin-based architecture.

Core Structure

ziwei_mcp/
├── pyproject.toml                 # Project metadata and dependencies
├── mingli_mcp/                    # The installable package (single top-level namespace)
│   ├── __init__.py               # Package version (__version__)
│   ├── cli.py                    # Console entry point (mingli-mcp / python -m mingli_mcp)
│   ├── config.py                 # Configuration management
│   │
│   ├── mcp_server/               # MCP protocol implementation
│   │   ├── server.py             # MingliMCPServer: request routing
│   │   ├── protocol.py           # ProtocolHandler: initialize/prompts/resources, version negotiation
│   │   ├── resources.py          # Resource contents
│   │   └── tools/                # Tool definitions and handlers
│   │
│   ├── core/                      # Abstract base layer
│   │   ├── base_system.py        # BaseFortuneSystem abstract class
│   │   ├── birth_info.py         # BirthInfo data model
│   │   └── chart_result.py       # ChartResult data model
│   │
│   ├── systems/                   # Fortune system implementations
│   │   ├── __init__.py           # System registry
│   │   ├── ziwei/                # Ziwei Doushu system (iztro-py based)
│   │   ├── bazi/                 # BaZi (Four Pillars) system
│   │   └── astrology/            # Western astrology (stub)
│   │
│   ├── transports/                # Communication transports
│   │   ├── stdio_transport.py    # stdio transport (default for MCP)
│   │   └── http_transport.py     # Streamable HTTP transport (stateless JSON mode)
│   │
│   ├── utils/                     # Validators, formatters, rate limiter, etc.
│   └── prompts/                   # Prompt templates (shipped with the package)
│
└── tests/                         # Unit tests