mcp-bazi-project-guide

八字计算MCP服务器项目指南

🎯 项目概述

这是一个基于TypeScript的专业八字计算MCP服务器，使用lunar-javascript库提供八字计算服务。项目已完成现代化API升级，采用最新MCP SDK，可通过npm包@mymcp-fun/[email protected]一行命令使用。

📁 项目结构

核心源代码

• src/server.ts - MCP服务器主入口，使用新版McpServer API和registerTool方法
• src/bazi-service.ts - 八字计算核心服务，包装lunar-javascript库
• src/types.ts - TypeScript类型定义，包含输入输出接口

配置文件

• package.json - npm包配置，依赖管理，构建脚本
• tsconfig.json - TypeScript开发配置
• tsconfig.build.json - TypeScript生产构建配置

测试文件

• tests/final-accuracy-test.js - 最终准确性测试，验证100%兼容性
• tests/test-mcp-server.js - MCP服务器功能测试
• tests/basic-functionality.js - 基础功能测试
• tests/test-lunar-javascript.js - lunar-javascript库API测试

文档

• README.md - 项目说明文档，包含安装使用指南
• LICENSE - MIT开源许可证

🔧 技术栈

核心依赖

• @modelcontextprotocol/sdk: 最新MCP协议SDK，使用McpServer类
• zod: Schema验证库，版本3.25.67+
• lunar-javascript: 权威的中文农历计算库，1600+周下载量
• TypeScript: 类型安全的JavaScript超集，版本5.0+
• Node.js: 运行环境，要求18.0+

现代化API特性

• ✅ McpServer类: 替代旧版Server类，更简洁的API
• ✅ registerTool方法: 自动处理MCP协议细节
• ✅ Zod验证: 内置参数验证和类型安全
• ✅ 简化代码: 从173行减少到89行（48%缩减）

🎯 核心功能

MCP工具: get_bazi_details

计算生辰八字和五行信息的主要工具

输入参数:

interface BaziToolInput {
  year: number;        // 出生年份 (1900-2100)
  month: number;       // 出生月份 (1-12)
  day: number;         // 出生日期 (1-31)
  hour: number;        // 出生时间 (0-23)
  gender?: string;     // 性别 (可选，默认male)
  timezone?: string;   // 时区 (可选，默认Asia/Shanghai)
}

输出结果 (使用中文字段名):

interface BaziResult {
  四柱: {              // 四柱信息
    年柱: string;      // 年柱，如"乙酉"
    月柱: string;      // 月柱，如"己丑"
    日柱: string;      // 日柱，如"丁巳"
    时柱: string;      // 时柱，如"壬子"
  };
  五行: {              // 五行分析（整数计数）
    木: number;        // 木，如1
    火: number;        // 火，如2
    土: number;        // 土，如2
    金: number;        // 金，如1
    水: number;        // 水，如2
  };
  生肖: string;        // 生肖，如"鸡"
  星座: string;        // 星座，如"水瓶"
  农历: {              // 农历日期
    农历年: number;
    农历月: number;
    农历日: number;
    是否闰月: boolean;
    农历月名: string;  // 如"腊月"
  };
  日主: string;        // 日主天干，如"丁"
}