xzkcz/iztro-mcp-server

iztro MCP Server

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

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

From source

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:

@xzkcz/iztro-mcp-server

Development

To run the server in development mode:

npm run dev

Production

To build and run the server:

npm run build
npm start

Testing

Run the test suite:

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

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:

{
  "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:

{
  "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

npm run build

Testing

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
• Issues: https://github.com/xzkcz/iztro-mcp-server/issues
• npm Package: https://www.npmjs.com/package/@xzkcz/iztro-mcp-server
• iztro Library: https://github.com/SylarLong/iztro
• Model Context Protocol: https://modelcontextprotocol.io/

License

This project is licensed under the MIT License - see the file for details.