iztro MCP 服务器

基于 iztro 的模型上下文协议 (MCP) 服务器 - 生成紫微斗数星盘支持地理编码和真太阳时转换

演示视频

演示视频 - 8月15日

功能特性

• 星盘生成: 根据出生信息生成详细的紫微斗数星盘
• 地理编码服务: 使用高德地图API将地点名称转换为精确坐标
• 真太阳时转换: 采用天文算法计算高精度真太阳时
• MCP集成: 与MCP兼容客户端无缝集成
• 安全配置: 支持环境变量和配置文件

快速开始

安装

全局安装推荐

npm install -g ziwei_iztro-mcpserver

本地安装

npm i ziwei_iztro-mcpserver

配置

** 重要提示使用前请配置您自己的API密钥**

方式一环境变量推荐

# 复制示例环境文件
cp .env.example .env

# 编辑 .env 文件并添加您的高德地图API密钥
echo "AMAP_API_KEY=your_actual_api_key_here" > .env

方式二配置文件

# 复制示例配置文件
cp iztro-mcp-config.example.json iztro-mcp-config.json

# 编辑配置文件并添加您的API密钥

获取高德地图API密钥

1. 访问 高德开放平台
2. 注册账号并登录
3. 创建应用选择"Web服务"类型
4. 获取您的API密钥

自动化设置推荐

# 运行交互式设置脚本
npm run setup

这将引导您完成配置过程并创建必要的文件

使用方法

作为独立服务器

# 启动MCP服务器
ziwei_iztro-mcpserver
# 或者
npm start

与MCP客户端集成

添加到您的MCP客户端配置中

{
  "mcpServers": {
    "iztro": {
      "command": "npx",
      "args": ["ziwei_iztro-mcpserver"]
    }
  }
}

或者本地安装

{
  "mcpServers": {
    "iztro": {
      "command": "node",
      "args": ["/path/to/ziwei_iztro-mcpserver/dist/index.js"]
    }
  }
}

可用工具

1. geocode_location

将地点名称转换为精确坐标

参数

• location (string, 必需): 地点名称例如"安徽省合肥市庐江县金牛镇"

返回

{
  "location": "安徽省合肥市庐江县金牛镇",
  "longitude": 117.123456,
  "latitude": 31.654321,
  "formatted_address": "安徽省合肥市庐江县金牛镇"
}

2. convert_to_apparent_solar_time

根据地理位置将北京时间转换为真太阳时

参数

• beijingTime (string, 必需): 北京时间格式为 YYYY-MM-DD HH:mm:ss
• longitude (number, 必需): 经度东经为正西经为负
• latitude (number, 可选): 纬度北纬为正南纬为负

返回

{
  "beijing_time": "2024-01-01 12:00:00",
  "longitude": 117.123456,
  "latitude": 31.654321,
  "apparent_solar_time": "2024-01-01 12:08:30"
}

3. generate_astrolabe

生成紫微斗数星盘支持基于地点的真太阳时转换

参数

• birthday (string, 必需): 出生日期格式为 YYYY-MM-DD
• birthTime (number, 必需): 出生时辰 (0-11)其中 0=子时1=丑时以此类推
• gender (string, 必需): 性别'男' 或 '女'
• calendarType (string, 可选): 日历类型'solar' 或 'lunar'默认为 'solar'
• isLeapMonth (boolean, 可选): 是否为闰月仅农历有效
• language (string, 可选): 输出语言支持 'zh-CN', 'zh-TW', 'en-US', 'ja-JP', 'ko-KR', 'vi-VN'
• location (string, 可选): 出生地点用于真太阳时转换

返回
完整的星盘数据如果提供了地点参数还包含地点处理信息

开发

前置要求

• Node.js >= 16.0.0
• npm 或 yarn
• TypeScript 5.0+

本地开发

# 克隆仓库
git clone https://github.com/smogievogie/ziwei_iztro-mcpserver.git
cd ziwei_iztro-mcpserver

# 安装依赖
npm install

# 构建项目
npm run build

# 运行设置脚本
npm run setup

# 启动开发服务器
npm run dev

测试

# 使用 MCP Inspector 测试
npx @modelcontextprotocol/inspector node dist/index.js

技术细节

真太阳时计算

• 基于 Jean Meeus天文算法
• 考虑地球轨道椭圆性和轴倾斜
• 与天文年历相比精度在3秒内
• 支持早子时和晚子时区分

地理编码服务

• 由高德地图API提供支持
• 高精度坐标转换
• 支持中国境内详细地址解析
• 地理编码失败时自动回退到原始时间

贡献

欢迎贡献请随时提交Pull Request

开发指南

1. Fork 本仓库
2. 创建 功能分支git checkout -b feature/amazing-feature
3. 提交 您的更改git commit -m 'Add amazing feature'
4. 推送 到分支git push origin feature/amazing-feature
5. 提交 Pull Request

代码规范

• 使用TypeScript确保类型安全
• 遵循ESLint配置
• 添加适当的单元测试
• 根据需要更新文档

许可证

本项目采用MIT许可证 - 详见 LICENSE 文件

致谢

• iztro - 紫微斗数核心库
• MCP SDK - 模型上下文协议TypeScript SDK
• 高德地图API - 地理编码服务提供商

支持

• 问题反馈: GitHub Issues
• 讨论: GitHub Discussions
• 文档: 项目Wiki

---

为紫微斗数爱好者用制作