@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 six main tools:

1. **get_astrolabe** - Generate an astrolabe using solar calendar date
2. **get_horoscope_decades** - Get all decadal data for whole life
3. **get_horoscope_ages** - Get all age data for whole life
4. **get_horoscope_years** - Get all yearly data for whole life
5. **get_horoscope_months** - Get monthly data for one year
6. **get_mutaged_places** - Get the 4 palaces affected by the four transformations (禄权科忌) from a specific palace
7. **gen_astrolabe** - Generate an astrolabe, decades, years, ages, months in separate JSON files in a specific path

## 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 run test            # Run tests once
npm run test:watch      # Run tests in watch mode
npm run test:coverage   # Run tests with coverage report
npm run test:ui         # Run tests with UI
```

## MCP Tools

### get_astrolabe

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")
- `fixLeap` (boolean, optional): Whether to fix the leap month (default: true)
- `locale` (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

### get_horoscope_decades

Get all decadal data for whole life.

**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")
- `fixLeap` (boolean, optional): Whether to fix the leap month (default: true)
- `locale` (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

### get_horoscope_ages

Get all age data for whole life.

**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")
- `fixLeap` (boolean, optional): Whether to fix the leap month (default: true)
- `locale` (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

### get_horoscope_years

Get all yearly data for whole life.

**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")
- `fixLeap` (boolean, optional): Whether to fix the leap month (default: true)
- `locale` (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

### get_horoscope_months

Get monthly data for one year.

**Parameters:**
- `year` (number, required): Year to get monthly data for (e.g., 2024)
- `fixLeap` (boolean, optional): Whether to fix the leap month (default: true)
- `locale` (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

### get_mutaged_places

Get the 4 palaces that are affected by the four transformations (禄权科忌) from a specific palace.

**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")
- `palaceName` (number | string, required): Palace to analyze. Can be either:
  - A number (0-11): Palace index (0=命宫, 1=兄弟, 2=夫妻, 3=子女, 4=财帛, 5=疾厄, 6=迁移, 7=奴仆, 8=官禄, 9=田宅, 10=福德, 11=父母)
  - A Chinese string: Palace name (e.g., "命宫", "财帛", "官禄", "夫妻", "子女", "疾厄", "迁移", "奴仆", "田宅", "福德", "父母", "兄弟")
  - An English string: Palace name (e.g., "soul", "wealth", "career", "spouse", "children", "health", "surface", "friends", "property", "spirit", "parents", "siblings")
- `fixLeap` (boolean, optional): Whether to fix the leap month (default: true)
- `locale` (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

**Returns:**
A structured response containing:
- `sourcePalace`: Information about the source palace
- `mutagedPlaces`: Array of 4 elements corresponding to the four transformations [禄, 权, 科, 忌]
- `metadata`: Birth information and generation timestamp

### gen_astrolabe

Generate an astrolabe, decades, years, ages, months in separate JSON files in a specific path.

**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")
- `path` (string, required): Absolute path to the directory where the JSON files will be saved
- `fixLeap` (boolean, optional): Whether to fix the leap month (default: true)
- `locale` (enum, optional): Locale for the output ("zh-CN" or "en-US", default: "zh-CN")

**Returns:**
- `success`: Boolean indicating success
- `files`: Array of strings containing the paths of the generated files (`astrolabe.json`, `decades.json`, `ages.json`, `years.json`, `months.json`)

## Example Usage

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

```json
{
  "tool": "get_astrolabe",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "male",
    "fixLeap": true,
    "locale": "zh-CN"
  }
}
```

```json
{
  "tool": "get_mutaged_places",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "female",
    "palaceName": "命宫",
    "fixLeap": true,
    "locale": "zh-CN"
  }
}
```

```json
{
  "tool": "get_mutaged_places",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "male",
    "palaceName": 0,
    "fixLeap": true,
    "locale": "zh-CN"
  }
}
```

```json
{
  "tool": "get_mutaged_places",
  "parameters": {
    "date": "2000-8-16",
    "hour": 2,
    "gender": "female",
    "palaceName": "soul",
    "fixLeap": true,
    "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
├── getAstroMonth.ts      # Utility for astrology month calculations
├── getAstroYear.ts       # Utility for astrology year calculations
├── hourToTimeIndex.ts    # Utility for time index conversion
└── tests/
    ├── bySolar.test.ts       # Tests for solar calendar functions
    ├── getAstroMonth.test.ts # Tests for astrology month utilities
    ├── getAstroYear.test.ts  # Tests for astrology year utilities
    ├── hourToTimeIndex.test.ts # Tests for time index utilities
    ├── integration.test.ts   # Integration tests
    ├── iztro.test.ts         # Tests for iztro library integration
    └── tools.test.ts         # Tests for MCP tools
```

### 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.