# 中国节假日MCP服务器

一个基于模型上下文协议（MCP）的中国节假日和农历信息服务器，为AI助手提供准确的法定节假日、调休安排、中国传统节日、农历转换、二十四节气和八字计算功能。西方节日都是固定公历日期，不需要查询工具。

## 🌟 功能特性

- **节假日查询**: 查询中国法定节假日、传统节日和调休安排
- **月历查询**: 查询指定月份完整日历，包含节假日和调休安排
- **农历转换**: 公历与农历日期相互转换
- **农历信息**: 获取详细的农历日期描述，包括生肖、干支等
- **二十四节气**: 查询二十四节气信息和季节划分
- **八字计算**: 根据出生日期时间计算四柱八字和五行属性
- **FastMCP架构**: 基于官方推荐的FastMCP框架，提供更好的性能和稳定性

## 🏗️ 技术架构

本项目基于官方推荐的FastMCP框架开发，具有以下特性：

- **简化的工具注册**: 使用 `@mcp.tool()` 装饰器
- **自动类型验证**: 自动处理参数验证和类型转换
- **标准化接口**: 完全符合MCP协议最佳实践

## 📦 安装

### 环境要求

- Python 3.8+
- 支持MCP协议的AI客户端（如Claude Desktop）

### 使用uvx安装（推荐）

```bash
# 直接从PyPI安装并运行
uvx china-festival-mcp
```

### 本地开发安装

```bash
# 克隆项目
git clone https://github.com/your-username/china-festival-mcp.git
cd china-festival-mcp

# 使用uvx运行（会自动安装依赖）
uvx --from . python -m src.server_fastmcp
```

## 🚀 使用方法

```bash
# 从PyPI直接运行
uvx china-festival-mcp

# 或本地开发运行
uvx --from . python -m src.server_fastmcp
```

## ⚙️ MCP客户端配置

### Claude Desktop配置

编辑 `~/Library/Application Support/Claude/claude_desktop_config.json`：

#### 从PyPI安装（推荐）

```json
{
  "mcpServers": {
    "china-festival-mcp": {
      "command": "uvx",
      "args": ["china-festival-mcp"]
    }
  }
}
```

#### 本地开发

```json
{
  "mcpServers": {
    "china-festival-mcp": {
      "command": "uvx",
      "args": ["--from", ".", "python", "-m", "src.server_fastmcp"],
      "cwd": "/path/to/china-festival-mcp"
    }
  }
}
```

### 其他MCP客户端

对于其他支持MCP协议的客户端，使用相同的uvx配置方式：

```json
{
  "mcpServers": {
    "china-festival-mcp": {
      "command": "uvx",
      "args": ["china-festival-mcp"]
    }
  }
}
```

## 📚 API文档

### 节假日工具

#### `holiday_info`
查询指定日期的节假日信息，包含是否为节假日的判断

**返回:**
```json
{
  "date": "2024-01-01",
  "name": "元旦",
  "type": "holiday",
  "is_holiday": true,
  "is_work_day": false,
  "note": "法定节假日",
  "weekday_name_en": "Monday"
}
```

#### `next_holiday`
获取下一个节假日

**返回:**
```json
{
  "name": "春节",
  "date": "2024-02-10",
  "days_until": 40,
  "note": "法定节假日",
  "weekday_name_en": "Saturday"
}
```

#### `current_year_holidays`
获取当前年份所有节假日

**返回:**
```json
{
  "year": 2024,
  "holidays": [
    {
      "date": "2024-01-01",
      "name": "元旦",
      "note": "法定节假日"
    }
  ],
  "total_count": 1
}
```

#### `current_year_work_days`
获取当前年份调休工作日安排

**返回:**
```json
{
  "year": 2024,
  "work_days": [
    {
      "date": "2024-02-04",
      "name": "春节调休",
      "note": "调休工作日"
    }
  ],
  "total_count": 1
}
```

#### `month_calendar`
查询指定月份的完整日历，包含节假日和调休信息。不指定年份时查询当前年份，不指定月份时查询当前月份。

**参数:**
- `month`: 月份，1-12
- `year`: 年份

**返回:**
```json
{
  "year": 2024,
  "month": 6,
  "month_name": "2024年6月",
  "days": [
    {
      "date": "2024-06-10",
      "day": 10,
      "name": "端午节",
      "type": "holiday",
      "is_holiday": true,
      "is_work_day": false,
      "note": "法定节假日",
      "weekday_name_cn": "星期一",
      "weekday_name_en": "Monday"
    }
  ],
  "weeks": [],
  "holidays": [],
  "work_days": [],
  "total_days": 30,
  "holiday_count": 1,
  "work_day_count": 0
}
```

### 农历工具

#### `gregorian_to_lunar`
公历转农历

**返回:**
```json
{
  "gregorian_date": "2024-01-01",
  "lunar_year": 2023,
  "lunar_month": 11,
  "lunar_day": 20,
  "is_leap_month": false,
  "zodiac": "兔"
}
```

#### `lunar_to_gregorian`
农历转公历

**返回:**
```json
{
  "lunar_date": "2023年十一月二十",
  "gregorian_year": 2024,
  "gregorian_month": 1,
  "gregorian_day": 1,
  "gregorian_date": "2024-01-01"
}
```

#### `get_lunar_string`
获取农历日期的详细中文描述

**返回:**
```json
{
  "gregorian_date": "2024-01-01",
  "lunar_year": 2023,
  "lunar_month": 11,
  "lunar_day": 20,
  "is_leap_month": false,
  "zodiac": "兔",
  "year_gan_zhi": "癸卯",
  "tian_gan": "癸",
  "di_zhi": "卯",
  "lunar_month_name": "十一月",
  "lunar_day_name": "二十",
  "lunar_string": "癸卯年 十一月 二十"
}
```

#### `get_24_lunar_feast`
获取二十四节气信息

**返回:**
```json
{
  "year": 2024,
  "month": 1,
  "solar_terms": [
    {
      "name": "小寒",
      "date": "2024-01-06",
      "days_until": 5,
      "season": "冬季"
    },
    {
      "name": "大寒",
      "date": "2024-01-20",
      "days_until": 19,
      "season": "冬季"
    }
  ]
}
```

#### `get_8zi`
计算八字（四柱）

**返回:**
```json
{
  "eight_characters": "甲辰 丙寅 甲子 庚午"
}
```

### 日期工具

#### `get_weekday`
根据公历日期计算星期几

**返回:**
```json
{
  "weekday_number": 1,
  "weekday_name_zh": "星期一",
  "weekday_name_en": "Monday",
  "date": "2024-01-01"
}
```

## 📁 项目结构

```
china-festival-mcp/
├── src/                       # 核心源代码
│   ├── __init__.py
│   ├── server_fastmcp.py      # FastMCP服务器主程序
│   ├── data/                  # 数据模块
│   │   ├── bazi_calculator.py # 八字计算模块
│   │   └── solar_terms.py     # 二十四节气数据
│   ├── tools/                 # 工具模块
│   │   ├── __init__.py
│   │   ├── holiday.py         # 节假日查询工具
│   │   ├── lunar.py           # 农历转换工具
│   │   └── weekday.py         # 星期计算工具
│   └── utils/                 # 工具函数
│       ├── __init__.py
│       ├── date_utils.py      # 日期工具
│       └── logger.py          # 日志管理
├── scripts/                   # 发布脚本
│   └── publish.py             # 自动发布脚本
├── test_solar_terms.py        # 节气测试脚本
├── .gitignore                 # Git忽略文件
├── pyproject.toml             # 项目配置和依赖
├── README.md                  # 项目说明
├── LICENSE                    # 许可证
├── PUBLISH_GUIDE.md           # 发布指南
└── publish.sh                 # 发布脚本
```




## 🙏 致谢

本项目基于 [PyLunar](https://github.com/swordzjj/PyLunar/tree/master) 项目和 [holiday-cn](https://github.com/NateScarlet/holiday-cn)项目开发，感谢原作者的贡献。