iztro Chart MCP Server

A Model Context Protocol (MCP) server for generating and capturing astrolabe charts from ziwei.pub using FastMCP and Playwright.

Features

• FastMCP Integration: Built with the FastMCP TypeScript framework for easy MCP server development
• Astrolabe Screenshot Capture: Automatically captures screenshots of astrolabe charts from ziwei.pub
• Playwright Automation: Uses Playwright for reliable web scraping and screenshot generation
• TypeScript Support: Full TypeScript support with proper type definitions
• Parameter Validation: Uses Zod for robust parameter validation

Installation

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

Development

npm run dev

Building

npm run build

Running

npm start

Running with npx

npx @xzkcz/iztro-chart-mcp-server

Testing with MCP CLI

You can test the server using the MCP CLI:

# Install MCP CLI if you haven't already
npm install -g @modelcontextprotocol/cli

# Test the server
npx @mcp/cli src/index.ts

Available Tools

1. download_chart

Capture a screenshot of an astrolabe chart from ziwei.pub.

Parameters:

• date (string): Birth date in YYYY-M-D format (e.g., "2000-8-16")
• hour (number): Birth hour in 24-hour format (0-23)
• gender (enum): Gender of the person ("male" or "female")
• path (string, optional): Path to save image (default: "astro-chart.png")

Example:

{
  "name": "download_chart",
  "arguments": {
    "date": "2000-8-16",
    "hour": 6,
    "gender": "male",
    "path": "my-chart.png"
  }
}

Claude Desktop Integration

To use this server with Claude Desktop, add the following to your Claude Desktop configuration:

{
  "mcpServers": {
    "iztro-chart": {
      "command": "npx",
      "args": ["@xzkcz/iztro-chart-mcp-server"],
      "env": {}
    }
  }
}

Project Structure

├── src/
│   ├── index.ts          # Main server implementation
│   ├── astrolabe.ts      # Astrolabe screenshot logic
│   ├── astrolabe.test.ts # Unit tests for astrolabe functionality
│   └── hourToTimeIndex.ts # Hour to Chinese time index conversion
├── dist/                 # Compiled JavaScript output
├── package.json          # Project dependencies and scripts
├── tsconfig.json         # TypeScript configuration
├── vitest.config.ts      # Vitest test configuration
└── README.md            # This file

Dependencies

• @modelcontextprotocol/sdk: Core MCP SDK
• fastmcp: FastMCP framework for TypeScript
• playwright: Web automation and screenshot capture
• zod: Schema validation
• typescript: TypeScript compiler
• tsx: TypeScript execution engine

Development Dependencies

• vitest: Fast unit testing framework
• @vitest/ui: Visual test interface
• jsdom: DOM implementation for testing

License

MIT