sino-calendar-mcp

v1.6.2

Published

3 months ago

中国农历节日转换MCP服务 - 提供公历日期到中国农历、节日、24节气的智能转换功能

0High
0Medium
0Low

tairraos

mcp chinese-calendar lunar-calendar festivals solar-terms

中国农历节日转换MCP服务

一个基于Model Context Protocol (MCP) 的中国农历节日转换服务，提供公历与农历转换、传统节日识别、24节气计算、工作日判断等功能。

开发日期: 2025年10月29日
开发者: Tairraos

🌟 功能特性

农历转换：公历日期转换为农历格式（天干地支年份）
节日识别：识别传统节日（春节、中秋节、端午节等）和现代节日
24节气：准确计算24节气日期
工作日判断：支持法定节假日和调休规律
日期范围查询：批量获取日期范围内的信息
输入验证：完善的日期格式验证和错误处理

📦 安装与配置

环境要求

Node.js >= 18.0.0
npm 或 pnpm

安装依赖

# 使用npm
npm install

# 或使用pnpm
pnpm install

编译项目

npm run build

🚀 使用方法

1. 直接启动服务

# 方式1：使用npx（推荐，无需安装）
npx sino-calendar-mcp

# 方式2：使用启动脚本
node start.js

# 方式3：使用npm脚本
npm start

# 方式4：直接运行编译后的文件
node dist/index.js

2. 作为MCP服务器

方式1：使用npx（推荐）

{
  "mcpServers": {
    "sino-calendar": {
      "command": "npx",
      "args": ["-y", "sino-calendar-mcp"],
      "env": {}
    }
  }
}

方式2：本地安装

在MCP客户端配置文件中添加：

{
  "mcpServers": {
    "sino-calendar": {
      "command": "node",
      "args": ["/path/to/sino-calendar-mcp/start.js"],
      "env": {}
    }
  }
}

3. 运行测试

# 运行所有测试
npm test

# 运行单元测试
npm run test:unit

# 运行集成测试
npm run test:integration

# 运行测试并生成覆盖率报告
npm run test:coverage

# 运行编译检查
npm run check

🛠️ API 接口

基础查询接口

get_date_info

获取指定日期的完整信息。

参数：

date (string): 日期，格式为 YYYY-MM-DD

示例：

{
  "name": "get_date_info",
  "arguments": {
    "date": "2025-01-29"
  }
}

返回：

{
  "date": "2025年1月29日",
  "week": "星期三",
  "dayType": "休息日",
  "lunarDate": "乙巳年正月初一",
  "adjusted": "调休",
  "festival": "春节"
}

get_date_range_info

获取日期范围内所有日期的信息。

参数：

startDate (string): 开始日期，格式为 YYYY-MM-DD
endDate (string): 结束日期，格式为 YYYY-MM-DD

限制：

日期范围不能超过366天

示例：

{
  "name": "get_date_range_info",
  "arguments": {
    "startDate": "2025-01-28",
    "endDate": "2025-02-03"
  }
}

返回：

{
  "dates": [
    {
      "date": "2025年1月28日",
      "week": "星期二",
      "dayType": "休息日",
      "lunarDate": "乙巳年腊月廿九",
      "adjusted": "调休",
      "festival": "除夕"
    }
    // ... 更多日期信息
  ]
}

反向查询接口

reverse_query_by_name

通过农历日期、节日名称、节气名称反向查询公历日期。

参数：

query (string): 查询内容，支持多种格式：
- 农历日期：农历2025年正月初一、正月初一、闰六月十五
- 节日名称：春节、中秋、端午节（支持部分匹配）
- 节气名称：立春、冬至、春分
type (string): 查询类型：
- lunar: 农历日期查询
- festival: 节日查询
- solar_term: 节气查询
year (number, 可选): 指定查询年份，不指定则查询前后5年

农历日期查询示例：

{
  "name": "reverse_query_by_name",
  "arguments": {
    "query": "正月初一",
    "type": "lunar",
    "year": 2025
  }
}

节日查询示例：

{
  "name": "reverse_query_by_name",
  "arguments": {
    "query": "中秋",
    "type": "festival"
  }
}

节气查询示例：

{
  "name": "reverse_query_by_name",
  "arguments": {
    "query": "立春",
    "type": "solar_term",
    "year": 2025
  }
}

返回格式：

{
  "dates": [
    {
      "date": "2025年1月29日",
      "week": "星期三",
      "dayType": "休息日",
      "lunarDate": "乙巳年正月初一",
      "festival": "春节"
    }
  ]
}

query_by_date_range

在指定日期范围内查询特定类型的日期。

参数：

startDate (string): 开始日期，格式为 YYYY-MM-DD
endDate (string): 结束日期，格式为 YYYY-MM-DD
type (string): 查询类型：
- rest_days: 休息日（周末和节假日）
- work_days: 工作日
- festivals: 有节日的日期
- solar_terms: 有节气的日期

示例：

{
  "name": "query_by_date_range",
  "arguments": {
    "startDate": "2025-01-01",
    "endDate": "2025-01-31",
    "type": "festivals"
  }
}

返回：

{
  "results": [
    {
      "date": "2025年1月1日",
      "week": "星期三",
      "dayType": "休息日",
      "lunarDate": "乙巳年腊月初二",
      "festival": "元旦"
    },
    {
      "date": "2025年1月29日",
      "week": "星期三",
      "dayType": "休息日",
      "lunarDate": "乙巳年正月初一",
      "festival": "春节"
    }
  ]
}

📊 数据字段说明

基础字段

date: 中文格式的公历日期
week: 中文格式的星期
dayType: 日期类型（"工作日" | "休息日"）
lunarDate: 农历日期（天干地支年份 + 月份 + 日期）

可选字段

adjusted: 调休信息（"调休" | "补班"）
festival: 节日名称
solarTerm: 24节气名称

日期类型说明

工作日: 正常工作日
休息日: 周末或法定节假日
调休: 因节假日调整的休息日
补班: 因节假日调整的工作日

🎯 支持的节日

传统节日

春节、元宵节、清明节、端午节、七夕节、中秋节、重阳节、腊八节、除夕

现代节日

元旦、妇女节、劳动节、青年节、儿童节、建党节、建军节、教师节、国庆节

24节气

立春、雨水、惊蛰、春分、清明、谷雨
立夏、小满、芒种、夏至、小暑、大暑
立秋、处暑、白露、秋分、寒露、霜降
立冬、小雪、大雪、冬至、小寒、大寒

🔧 开发指南

🧪 测试

测试覆盖率

本项目实现了100%的测试覆盖率，确保代码质量和功能稳定性：

语句覆盖率: 100%
分支覆盖率: 100%
函数覆盖率: 100%
行覆盖率: 100%

测试统计

测试套件: 8个
测试用例: 198个
测试类型: 单元测试 + 集成测试

测试覆盖的功能模块

核心引擎测试

DateInfoEngine: 日期信息获取、日期范围查询、周围日期信息
LunarEngine: 农历转换、天干地支计算、闰月处理
FestivalEngine: 传统节日识别、现代节日识别、节日日期计算
SolarTermEngine: 24节气计算、节气查询、边界条件处理
WorkdayEngine: 工作日判断、法定节假日识别、调休规则

工具类测试

DateUtils: 日期格式化、日期验证、日期计算
Validator: 输入验证、错误处理、边界值检查
ErrorHandler: 错误日志记录、操作追踪

边界条件测试

极端日期: 测试年份1到9999的边界情况
无效输入: 测试各种无效日期格式和参数
默认参数: 测试所有可选参数的默认值分支
空值处理: 测试null、undefined等特殊值
月份边界: 测试跨月、跨年的日期计算

运行测试

# 运行所有测试并查看覆盖率
npm run test:coverage

# 运行特定类型的测试
npm run test:unit        # 单元测试
npm run test:integration # 集成测试

# 运行特定文件的测试
npm test -- --testPathPattern="dateInfoEngine"
npm test -- --testPathPattern="lunarEngine"

# 以详细模式运行测试
npm test -- --verbose

# 监听模式（开发时使用）
npm test -- --watch

测试文件结构

tests/
├── unit/                  # 单元测试
│   ├── engines/          # 引擎单元测试
│   │   ├── dateInfoEngine.test.ts
│   │   ├── lunarEngine.test.ts
│   │   ├── festivalEngine.test.ts
│   │   ├── solarTermEngine.test.ts
│   │   └── workdayEngine.test.ts
│   └── utils/            # 工具类单元测试
│       ├── dateUtils.test.ts
│       ├── validator.test.ts
│       └── errorHandler.test.ts
├── integration/          # 集成测试
│   └── dateInfoEngine.integration.test.ts
└── setup.ts             # 测试配置

📁 项目结构

sino-calendar-mcp/
├── src/                    # 源代码
│   ├── engines/           # 业务引擎
│   │   ├── dateInfoEngine.ts    # 日期信息引擎
│   │   ├── lunarEngine.ts       # 农历转换引擎
│   │   ├── festivalEngine.ts    # 节日识别引擎
│   │   ├── solarTermEngine.ts   # 24节气引擎
│   │   └── workdayEngine.ts     # 工作日判断引擎
│   ├── data/              # 数据文件
│   │   ├── festivals.ts         # 节日数据
│   │   ├── solarTerms.ts        # 24节气数据
│   │   └── workdayRules.ts      # 工作日规则
│   ├── utils/             # 工具类
│   │   ├── dateUtils.ts         # 日期工具
│   │   ├── validator.ts         # 输入验证
│   │   └── errorHandler.ts      # 错误处理
│   ├── types/             # 类型定义
│   │   ├── index.ts             # 主要类型
│   │   └── lunar-javascript.d.ts # 第三方库类型
│   └── index.ts           # 主入口文件
├── dist/                  # 编译输出
├── test.js               # 测试脚本
├── start.js              # 启动脚本
└── README.md             # 使用说明

添加新节日

在 src/data/festivals.ts 中添加节日定义
更新 FestivalEngine 的识别逻辑
运行测试确保功能正常

添加新的工作日规则

在 src/data/workdayRules.ts 中添加规则
更新 WorkdayEngine 的判断逻辑
运行测试验证准确性

🐛 故障排除

常见问题

编译错误
```
npm run build
```

依赖问题

rm -rf node_modules package-lock.json
npm install

Node.js版本过低
- 确保使用 Node.js 18.0.0 或更高版本
日期解析错误
- 确保日期格式为 YYYY-MM-DD
- 检查日期是否有效（如2月30日无效）

调试模式

设置环境变量启用详细日志：

DEBUG=sino-calendar:* node start.js

📄 许可证

MIT License

🤝 贡献

欢迎提交 Issue 和 Pull Request！

👨‍💻 开发者

Tairraos - 项目创建者和维护者
开发时间：2025年10月29日

📞 支持

如有问题，请通过以下方式联系：

提交 GitHub Issue
查看项目文档
运行测试脚本进行自检

注意: 本服务基于 lunar-javascript 库进行农历计算，节日和工作日数据基于中国大陆的法定规定。

Published

Vulnerabilities

Links

Maintainers

Keywords

Readme

中国农历节日转换MCP服务

🌟 功能特性

📦 安装与配置

环境要求

安装依赖

编译项目

🚀 使用方法

1. 直接启动服务

2. 作为MCP服务器

方式1：使用npx（推荐）

方式2：本地安装

3. 运行测试

🛠️ API 接口

基础查询接口

get_date_info

get_date_range_info

反向查询接口

reverse_query_by_name

query_by_date_range

📊 数据字段说明

基础字段

可选字段

日期类型说明

🎯 支持的节日

传统节日

现代节日

24节气

🔧 开发指南

🧪 测试

测试覆盖率

测试统计

测试覆盖的功能模块

核心引擎测试

工具类测试

边界条件测试

运行测试

测试文件结构

📁 项目结构

添加新节日

添加新的工作日规则

🐛 故障排除

常见问题

调试模式

📄 许可证

🤝 贡献

👨‍💻 开发者

📞 支持