@xzkcz/iztro-chart-mcp-server 1.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 iztro-mcp-server
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,127 @@
+# 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
+
+```bash
+npm install @xzkcz/iztro-chart-mcp-server
+```
+
+## Development
+
+```bash
+npm run dev
+```
+
+## Building
+
+```bash
+npm run build
+```
+
+## Running
+
+```bash
+npm start
+```
+
+## Running with npx
+
+```bash
+npx @xzkcz/iztro-chart-mcp-server
+```
+
+## Testing with MCP CLI
+
+You can test the server using the MCP CLI:
+
+```bash
+# 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:**
+```json
+{
+  "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:
+
+```json
+{
+  "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

package/dist/astrolabe.d.ts

@@ -0,0 +1,7 @@
+export interface AstrolabeParams {
+    date: string;
+    hour: number;
+    gender: 'male' | 'female';
+    path: string;
+}
+export declare function downloadChart(params: AstrolabeParams): Promise<string>;

package/dist/astrolabe.js

@@ -0,0 +1,48 @@
+import { chromium } from "playwright";
+import * as path from "path";
+import * as fs from "fs";
+import { hourToTimeIndex } from "./hourToTimeIndex.js";
+export async function downloadChart(params) {
+    const { date, hour, gender, path: savePath } = params;
+    // Convert hour to timeIndex for iztro library
+    const timeIndex = hourToTimeIndex(hour);
+    // Construct the URL
+    const url = `https://ziwei.pub/astrolabe/?d=${date}&t=${timeIndex}&leap=false&g=${gender}&type=solar&n=`;
+    let browser;
+    try {
+        // Launch browser
+        browser = await chromium.launch({ headless: true });
+        const context = await browser.newContext({
+            viewport: { width: 1500, height: 800 }
+        });
+        const page = await context.newPage();
+        // Navigate to the astrolabe page
+        await page.goto(url);
+        // Wait for the astrolabe element to be visible
+        await page.waitForSelector('.iztro-astrolabe', { timeout: 3000 });
+        // Take screenshot of the specific element
+        const targetSelector = ".iztro-astrolabe";
+        const element = await page.locator(targetSelector);
+        // Ensure the element is found
+        if (!element) {
+            throw new Error(`Element ${targetSelector} not found`);
+        }
+        // Ensure the directory exists
+        const fullPath = path.resolve(savePath);
+        const dir = path.dirname(fullPath);
+        if (!fs.existsSync(dir)) {
+            fs.mkdirSync(dir, { recursive: true });
+        }
+        // Take the screenshot
+        await element.screenshot({ path: fullPath });
+        await browser.close();
+        return `Astrolabe chart downloaded successfully to ${fullPath}. URL: ${url}. Parameters: date=${date}, hour=${hour}, gender=${gender}`;
+    }
+    catch (error) {
+        if (browser) {
+            await browser.close();
+        }
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        return `Failed to download astrolabe chart: ${errorMessage}. URL: ${url}. Parameters: date=${date}, hour=${hour}, gender=${gender}`;
+    }
+}

package/dist/astrolabe.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/astrolabe.test.js

@@ -0,0 +1,228 @@
+import { describe, it, expect, vi, beforeEach, afterEach } from 'vitest';
+import { downloadChart } from './astrolabe.js';
+import { chromium } from 'playwright';
+import * as fs from 'fs';
+import * as path from 'path';
+// Mock Playwright
+vi.mock('playwright', () => ({
+    chromium: {
+        launch: vi.fn()
+    }
+}));
+// Mock fs
+vi.mock('fs', () => ({
+    existsSync: vi.fn(),
+    mkdirSync: vi.fn()
+}));
+// Mock path
+vi.mock('path', () => ({
+    resolve: vi.fn(),
+    dirname: vi.fn()
+}));
+describe('downloadChart', () => {
+    const mockBrowser = {
+        newContext: vi.fn(),
+        close: vi.fn()
+    };
+    const mockContext = {
+        newPage: vi.fn()
+    };
+    const mockPage = {
+        goto: vi.fn(),
+        waitForSelector: vi.fn(),
+        locator: vi.fn()
+    };
+    const mockElement = {
+        screenshot: vi.fn()
+    };
+    beforeEach(() => {
+        vi.clearAllMocks();
+        // Setup default mock implementations
+        vi.mocked(chromium.launch).mockResolvedValue(mockBrowser);
+        mockBrowser.newContext.mockResolvedValue(mockContext);
+        mockContext.newPage.mockResolvedValue(mockPage);
+        mockPage.locator.mockReturnValue(mockElement);
+        vi.mocked(fs.existsSync).mockReturnValue(true);
+        vi.mocked(path.resolve).mockImplementation((p) => `/resolved/${p}`);
+        vi.mocked(path.dirname).mockImplementation((p) => `/dirname/${p}`);
+    });
+    afterEach(() => {
+        vi.restoreAllMocks();
+    });
+    describe('successful chart download', () => {
+        it('should successfully download chart with valid parameters', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'male',
+                path: 'test-chart.png'
+            };
+            mockElement.screenshot.mockResolvedValue(undefined);
+            const result = await downloadChart(params);
+            expect(chromium.launch).toHaveBeenCalledWith({ headless: true });
+            expect(mockBrowser.newContext).toHaveBeenCalledWith({
+                viewport: { width: 1500, height: 800 }
+            });
+            expect(mockPage.goto).toHaveBeenCalledWith('https://ziwei.pub/astrolabe/?d=2000-8-16&t=3&leap=false&g=male&type=solar&n=');
+            expect(mockPage.waitForSelector).toHaveBeenCalledWith('.iztro-astrolabe', { timeout: 3000 });
+            expect(mockPage.locator).toHaveBeenCalledWith('.iztro-astrolabe');
+            expect(mockElement.screenshot).toHaveBeenCalledWith({ path: '/resolved/test-chart.png' });
+            expect(mockBrowser.close).toHaveBeenCalled();
+            expect(result).toContain('Astrolabe chart downloaded successfully');
+            expect(result).toContain('/resolved/test-chart.png');
+        });
+        it('should create directory if it does not exist', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'female',
+                path: 'charts/test-chart.png'
+            };
+            vi.mocked(fs.existsSync).mockReturnValue(false);
+            mockElement.screenshot.mockResolvedValue(undefined);
+            await downloadChart(params);
+            expect(fs.mkdirSync).toHaveBeenCalledWith('/dirname//resolved/charts/test-chart.png', { recursive: true });
+        });
+        it('should handle female gender parameter correctly', async () => {
+            const params = {
+                date: '1995-12-25',
+                hour: 0,
+                gender: 'female',
+                path: 'female-chart.png'
+            };
+            mockElement.screenshot.mockResolvedValue(undefined);
+            const result = await downloadChart(params);
+            expect(mockPage.goto).toHaveBeenCalledWith('https://ziwei.pub/astrolabe/?d=1995-12-25&t=0&leap=false&g=female&type=solar&n=');
+            expect(result).toContain('gender=female');
+        });
+        it('should handle edge case hour values', async () => {
+            const params = {
+                date: '2023-1-1',
+                hour: 12,
+                gender: 'male',
+                path: 'edge-chart.png'
+            };
+            mockElement.screenshot.mockResolvedValue(undefined);
+            const result = await downloadChart(params);
+            expect(mockPage.goto).toHaveBeenCalledWith('https://ziwei.pub/astrolabe/?d=2023-1-1&t=6&leap=false&g=male&type=solar&n=');
+            expect(result).toContain('hour=12');
+        });
+    });
+    describe('error handling', () => {
+        it('should handle browser launch failure', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'male',
+                path: 'test-chart.png'
+            };
+            const error = new Error('Failed to launch browser');
+            vi.mocked(chromium.launch).mockRejectedValue(error);
+            const result = await downloadChart(params);
+            expect(result).toContain('Failed to download astrolabe chart: Failed to launch browser');
+            expect(result).toContain('date=2000-8-16');
+            expect(result).toContain('hour=6');
+            expect(result).toContain('gender=male');
+        });
+        it('should handle page navigation failure', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'male',
+                path: 'test-chart.png'
+            };
+            const error = new Error('Navigation timeout');
+            mockPage.goto.mockRejectedValue(error);
+            const result = await downloadChart(params);
+            expect(mockBrowser.close).toHaveBeenCalled();
+            expect(result).toContain('Failed to download astrolabe chart: Navigation timeout');
+        });
+        it('should handle selector timeout', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'male',
+                path: 'test-chart.png'
+            };
+            const error = new Error('Timeout waiting for selector');
+            mockPage.waitForSelector.mockRejectedValue(error);
+            const result = await downloadChart(params);
+            expect(mockBrowser.close).toHaveBeenCalled();
+            expect(result).toContain('Failed to download astrolabe chart: Timeout waiting for selector');
+        });
+        it('should handle screenshot failure', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'male',
+                path: 'test-chart.png'
+            };
+            const error = new Error('Screenshot failed');
+            mockElement.screenshot.mockRejectedValue(error);
+            const result = await downloadChart(params);
+            expect(mockBrowser.close).toHaveBeenCalled();
+            expect(result).toContain('Failed to download astrolabe chart: Screenshot failed');
+        });
+        it('should handle non-Error exceptions', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'male',
+                path: 'test-chart.png'
+            };
+            vi.mocked(chromium.launch).mockRejectedValue('String error');
+            const result = await downloadChart(params);
+            expect(result).toContain('Failed to download astrolabe chart: String error');
+        });
+    });
+    describe('URL construction', () => {
+        it('should construct correct URL with all parameters', async () => {
+            const params = {
+                date: '1990-5-20',
+                hour: 8,
+                gender: 'female',
+                path: 'url-test.png'
+            };
+            mockElement.screenshot.mockResolvedValue(undefined);
+            await downloadChart(params);
+            expect(mockPage.goto).toHaveBeenCalledWith('https://ziwei.pub/astrolabe/?d=1990-5-20&t=4&leap=false&g=female&type=solar&n=');
+        });
+        it('should handle special characters in date', async () => {
+            const params = {
+                date: '2000-12-31',
+                hour: 11,
+                gender: 'male',
+                path: 'special-date.png'
+            };
+            mockElement.screenshot.mockResolvedValue(undefined);
+            await downloadChart(params);
+            expect(mockPage.goto).toHaveBeenCalledWith('https://ziwei.pub/astrolabe/?d=2000-12-31&t=6&leap=false&g=male&type=solar&n=');
+        });
+    });
+    describe('file system operations', () => {
+        it('should resolve path correctly', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'male',
+                path: 'relative/path/chart.png'
+            };
+            mockElement.screenshot.mockResolvedValue(undefined);
+            await downloadChart(params);
+            expect(path.resolve).toHaveBeenCalledWith('relative/path/chart.png');
+            expect(mockElement.screenshot).toHaveBeenCalledWith({ path: '/resolved/relative/path/chart.png' });
+        });
+        it('should check directory existence', async () => {
+            const params = {
+                date: '2000-8-16',
+                hour: 6,
+                gender: 'male',
+                path: 'test/chart.png'
+            };
+            mockElement.screenshot.mockResolvedValue(undefined);
+            await downloadChart(params);
+            expect(path.dirname).toHaveBeenCalledWith('/resolved/test/chart.png');
+            expect(fs.existsSync).toHaveBeenCalledWith('/dirname//resolved/test/chart.png');
+        });
+    });
+});

package/dist/hourToTimeIndex.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Convert 24-hour format to Chinese timeIndex (0-12)
+ * Based on traditional Chinese time periods (十二时辰)
+ * @param hour - Hour in 24-hour format (0-23)
+ * @returns timeIndex - Chinese hour index (0-12)
+ */
+export declare function hourToTimeIndex(hour: number): number;

package/dist/hourToTimeIndex.js

@@ -0,0 +1,64 @@
+/**
+ * Convert 24-hour format to Chinese timeIndex (0-12)
+ * Based on traditional Chinese time periods (十二时辰)
+ * @param hour - Hour in 24-hour format (0-23)
+ * @returns timeIndex - Chinese hour index (0-12)
+ */
+export function hourToTimeIndex(hour) {
+    if (hour < 0 || hour > 23 || !Number.isInteger(hour)) {
+        throw new Error('Hour must be an integer between 0 and 23');
+    }
+    // Chinese time periods mapping (十二时辰) with early/late Zi distinction:
+    // 早子时 (Early Zi): 00:00-01:00 -> timeIndex 0
+    // 丑时 (Chou): 01:00-03:00 -> timeIndex 1  
+    // 寅时 (Yin): 03:00-05:00 -> timeIndex 2
+    // 卯时 (Mao): 05:00-07:00 -> timeIndex 3
+    // 辰时 (Chen): 07:00-09:00 -> timeIndex 4
+    // 巳时 (Si): 09:00-11:00 -> timeIndex 5
+    // 午时 (Wu): 11:00-13:00 -> timeIndex 6
+    // 未时 (Wei): 13:00-15:00 -> timeIndex 7
+    // 申时 (Shen): 15:00-17:00 -> timeIndex 8
+    // 酉时 (You): 17:00-19:00 -> timeIndex 9
+    // 戌时 (Xu): 19:00-21:00 -> timeIndex 10
+    // 亥时 (Hai): 21:00-23:00 -> timeIndex 11
+    // 晚子时 (Late Zi): 23:00-00:00 -> timeIndex 12
+    if (hour >= 0 && hour < 1) {
+        return 0; // 早子时 (Early Zi) - 00:00-01:00
+    }
+    else if (hour >= 1 && hour < 3) {
+        return 1; // 丑时 (Chou) - 01:00-03:00
+    }
+    else if (hour >= 3 && hour < 5) {
+        return 2; // 寅时 (Yin) - 03:00-05:00
+    }
+    else if (hour >= 5 && hour < 7) {
+        return 3; // 卯时 (Mao) - 05:00-07:00
+    }
+    else if (hour >= 7 && hour < 9) {
+        return 4; // 辰时 (Chen) - 07:00-09:00
+    }
+    else if (hour >= 9 && hour < 11) {
+        return 5; // 巳时 (Si) - 09:00-11:00
+    }
+    else if (hour >= 11 && hour < 13) {
+        return 6; // 午时 (Wu) - 11:00-13:00
+    }
+    else if (hour >= 13 && hour < 15) {
+        return 7; // 未时 (Wei) - 13:00-15:00
+    }
+    else if (hour >= 15 && hour < 17) {
+        return 8; // 申时 (Shen) - 15:00-17:00
+    }
+    else if (hour >= 17 && hour < 19) {
+        return 9; // 酉时 (You) - 17:00-19:00
+    }
+    else if (hour >= 19 && hour < 21) {
+        return 10; // 戌时 (Xu) - 19:00-21:00
+    }
+    else if (hour >= 21 && hour < 23) {
+        return 11; // 亥时 (Hai) - 21:00-23:00
+    }
+    else { // hour == 23
+        return 12; // 晚子时 (Late Zi) - 23:00-00:00
+    }
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,51 @@
+#!/usr/bin/env node
+import { FastMCP } from "fastmcp";
+import { z } from "zod";
+import { downloadChart } from "./astrolabe.js";
+import versionJson from './version.json' with { type: 'json' };
+const VERSION = versionJson.version;
+// Create a new FastMCP server instance
+const server = new FastMCP({
+    name: "@xzkcz/iztro-chart-mcp-server",
+    version: VERSION
+});
+// Add astrolabe chart download tool
+server.addTool({
+    name: "download_chart",
+    description: "Download a screenshot of an astrolabe chart from ziwei.pub",
+    parameters: z.object({
+        date: z.string().describe('Birth date in YYYY-M-D format (e.g., "2000-8-16")'),
+        hour: z.number().min(0).max(23).describe('Birth hour in 24-hour format (0-23)'),
+        gender: z.enum(['male', 'female']).describe('Gender of the person'),
+        path: z.string().optional().default('chart.png').describe('Path to save image')
+    }),
+    execute: async (args) => {
+        return await downloadChart(args);
+    },
+});
+// Start the server
+async function main() {
+    try {
+        server.start({
+            transportType: "stdio",
+        });
+        console.error(`🌟iztro-chart-mcp-server@${VERSION} started successfully!`);
+        console.error('Available tools:');
+        console.error('  - download_chart: Download a screenshot of an astrolabe chart from ziwei.pub');
+    }
+    catch (error) {
+        console.error("Server error:", error);
+        process.exit(1);
+    }
+}
+// Handle graceful shutdown
+process.on('SIGINT', () => {
+    console.log('\nShutting down server...');
+    process.exit(0);
+});
+process.on('SIGTERM', () => {
+    console.log('\nShutting down server...');
+    process.exit(0);
+});
+// Start the server
+main().catch(console.error);

package/dist/version.json

@@ -0,0 +1,3 @@
+{
+    "version": "1.0.1"
+}

package/package.json

@@ -0,0 +1,64 @@
+{
+  "name": "@xzkcz/iztro-chart-mcp-server",
+  "version": "1.0.1",
+  "description": "An MCP server for iZtro astrology chart generation",
+  "main": "dist/index.js",
+  "type": "module",
+  "bin": {
+    "iztro-chart-mcp-server": "dist/index.js"
+  },
+  "files": [
+    "dist/**/*",
+    "README.md",
+    "LICENSE"
+  ],  
+  "scripts": {
+    "prebuild": "node scripts/generate-version.js",
+    "build": "npm run prebuild && tsc",
+    "dev": "tsx src/index.ts",
+    "start": "node dist/index.js",
+    "test": "vitest",
+    "test:run": "vitest run",
+    "test:ui": "vitest --ui",
+    "test:coverage": "vitest run --coverage",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "prepack": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "astrology",
+    "iztro",
+    "chart",
+    "server"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.19.1",
+    "fastmcp": "^3.19.0",
+    "playwright": "^1.55.1"
+  },
+  "devDependencies": {
+    "@types/node": "^24.6.2",
+    "@vitest/ui": "^3.2.4",
+    "jsdom": "^27.0.0",
+    "tsx": "^4.20.6",
+    "typescript": "^5.9.3",
+    "vitest": "^3.2.4"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xzkcz/iztro-chart-mcp-server.git"
+  },
+  "homepage": "https://github.com/xzkcz/iztro-chart-mcp-server#readme",
+  "bugs": {
+    "url": "https://github.com/xzkcz/iztro-chart-mcp-server/issues"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }  
+}