@xzkcz/iztro-mcp-server/README.md

MCP server exposing iztro astrology methods for Zi Wei Dou Shu astrolabe generation and horoscope analysis

# iztro MCP Server

[![npm version](https://badge.fury.io/js/@xzkcz%2Fiztro-mcp-server.svg)](https://badge.fury.io/js/@xzkcz%2Fiztro-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)

A Model Context Protocol (MCP) server that exposes the `iztro` library methods for Zi Wei Dou Shu astrology calculations.

## About

This MCP server provides a bridge between the powerful [iztro](https://github.com/SylarLong/iztro) astrology library and MCP-compatible clients, enabling seamless integration of Chinese astrology calculations into AI applications and workflows.

## Features

This MCP server provides three main tools:

1. **generate_astrolabe_by_solar** - Generate an astrolabe using solar calendar date
2. **get_horoscope_analysis** - Get horoscope analysis for a specific date
3. **get_palace_info** - Get detailed information about all palaces in an astrolabe

## Installation

### From npm

```bash
npm install -g @xzkcz/iztro-mcp-server
```

### From source

```bash
git clone https://github.com/xzkcz/iztro-mcp-server.git
cd iztro-mcp-server
npm install
npm run build
```

## Usage

### As a Global Package

After installing globally, you can run the server directly:

```bash
@xzkcz/iztro-mcp-server
```

### Development

To run the server in development mode:

```bash
npm run dev
```

### Production

To build and run the server:

```bash
npm run build
npm start
```

### Testing

Run the test suite:

```bash
npm test                # Run tests in watch mode
npm run test:run        # Run tests once
npm run test:coverage   # Run tests with coverage report
npm run test:ui         # Run tests with UI
```

## Hour to TimeIndex Conversion

The server automatically converts 24-hour format (0-23) to Chinese `timeIndex` (0-12) based on traditional Chinese time periods (十二时辰). Users should provide hours in standard 24-hour format, and the server will handle the conversion internally.

### Time Period Mapping

| Hour Range | timeIndex | Chinese Period | Name | Description |
|------------|-----------|----------------|------|-------------|
| 00:00-01:00 | 0 | 早子时 (Early Zi) | 夜半 | Early Night/Midnight |
| 01:00-03:00 | 1 | 丑时 (Chou) | 鸡鸣 | Rooster Crow |
| 03:00-05:00 | 2 | 寅时 (Yin) | 平旦 | Dawn |
| 05:00-07:00 | 3 | 卯时 (Mao) | 日出 | Sunrise |
| 07:00-09:00 | 4 | 辰时 (Chen) | 食时 | Breakfast Time |
| 09:00-11:00 | 5 | 巳时 (Si) | 隅中 | Mid-morning |
| 11:00-13:00 | 6 | 午时 (Wu) | 日中 | Noon |
| 13:00-15:00 | 7 | 未时 (Wei) | 日昳 | Afternoon |
| 15:00-17:00 | 8 | 申时 (Shen) | 晡时 | Late Afternoon |
| 17:00-19:00 | 9 | 酉时 (You) | 日入 | Sunset |
| 19:00-21:00 | 10 | 戌时 (Xu) | 黄昏 | Dusk |
| 21:00-23:00 | 11 | 亥时 (Hai) | 人定 | Night Rest |
| 23:00-00:00 | 12 | 晚子时 (Late Zi) | 夜半 | Late Night/Midnight |

**Note**: The mapping follows traditional Chinese time periods (十二时辰) where 子时 is uniquely divided into 早子时 (Early Zi, 00:00-01:00) and 晚子时 (Late Zi, 23:00-00:00), reflecting the ancient practice of distinguishing the two parts of the Zi period that span across midnight.

## MCP Tools

### generate_astrolabe_by_solar

Generate an astrolabe using solar calendar date for Zi Wei Dou Shu astrology analysis.

**Parameters:**
- `date` (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
- `hour` (number, required): Birth hour in 24-hour format (0-23)
- `gender` (enum, required): Gender of the person ("male" or "female")
- `isDST` (boolean, optional): Whether daylight saving time was in effect (default: false)
- `locale` (string, optional): Locale for the output (default: "en-US")

### get_horoscope_analysis

Get horoscope analysis for a specific date using an existing astrolabe.

**Parameters:**
- `date` (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
- `hour` (number, required): Birth hour in 24-hour format (0-23)
- `gender` (enum, required): Gender of the person ("male" or "female")
- `isDST` (boolean, optional): Whether daylight saving time was in effect (default: false)
- `locale` (string, optional): Locale for the output (default: "en-US")
- `targetDate` (string, optional): Target date for horoscope analysis (defaults to current date)

### get_palace_info

Get detailed information about all palaces in an astrolabe.

**Parameters:**
- `date` (string, required): Birth date in YYYY-M-D format (e.g., "2000-8-16")
- `hour` (number, required): Birth hour in 24-hour format (0-23)
- `gender` (enum, required): Gender of the person ("male" or "female")
- `isDST` (boolean, optional): Whether daylight saving time was in effect (default: false)
- `locale` (string, optional): Locale for the output (default: "en-US")

## Example Usage

When connected to an MCP client, you can use these tools like:

```json
{
  "tool": "generate_astrolabe_by_solar",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "male",
    "isDST": false,
    "locale": "en-US"
  }
}
```

## MCP Client Configuration

To use this server with an MCP client, add it to your client configuration:

```json
{
  "mcpServers": {
    "iztro-astrology": {
      "command": "@xzkcz/iztro-mcp-server",
      "args": []
    }
  }
}
```

## Requirements

- Node.js >= 18.0.0
- npm or yarn

## Dependencies

- **fastmcp**: TypeScript framework for building MCP servers
- **iztro**: Lightweight JavaScript library for Zi Wei Dou Shu astrolabe generation
- **zod**: Schema validation library

## Development

### Project Structure

```
src/
├── index.ts              # Main MCP server implementation
├── iztro.test.ts         # Tests for iztro library integration
├── mcp-tools.test.ts     # Tests for MCP tools
└── integration.test.ts   # Integration tests
```

### Building

```bash
npm run build
```

### Testing

```bash
npm run test:run          # Run all tests
npm run test:coverage     # Run tests with coverage
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for your changes
5. Run the test suite
6. Submit a pull request

## Links

- **Repository**: [https://github.com/xzkcz/iztro-mcp-server](https://github.com/xzkcz/iztro-mcp-server)
- **Issues**: [https://github.com/xzkcz/iztro-mcp-server/issues](https://github.com/xzkcz/iztro-mcp-server/issues)
- **npm Package**: [https://www.npmjs.com/package/@xzkcz/iztro-mcp-server](https://www.npmjs.com/package/@xzkcz/iztro-mcp-server)
- **iztro Library**: [https://github.com/SylarLong/iztro](https://github.com/SylarLong/iztro)
- **Model Context Protocol**: [https://modelcontextprotocol.io/](https://modelcontextprotocol.io/)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.