# china-context-mcp

把**中文世界的数据源**桥接成 AI 工具。零凭证、免交付、可验证。

## 为什么做这个

给 AI 提供工具/服务/资源，是未来需求的重要方向。但调研发现一个结构性缺口：

- 国际服务（GitHub / Slack / Notion…）的 MCP server 覆盖中位数约 **1554** 个仓库；
- 中国服务（微信 / 支付宝 / 飞书 / 抖音…）的 MCP 覆盖中位数仅 **88** 个——差 **17.7×**。
  （数据：GitHub Search `「<服务> mcp」 in:name,description`，2026-09-25）

缺口只在「广义中国服务→AI」这一层成立。本仓库是这条「桥接层」方向的**最小可验证载体**：
先把**零凭证、公开 API、对中文 AI 真有用、且没被官方垄断**的数据源接进来。

> ⚠️ 支付宝「支付 MCP」已被官方于 2025-04-15 发布，故本项目**不重复造支付类 MCP**，只接官方未覆盖的真空数据源。

## 当前模块（均零凭证）

| 工具 | 数据源 | 用途 |
|---|---|---|
| `random_poem` | jinrishici.com | 随机一句中国古典诗词（作者/出处/分类），用于中文创作、文化问答、国学陪练 |
| `holiday_info(date)` | timor.tech | 查询中国某日期是否为法定节假日、调休补班工作日、工资倍率 |
| `holiday_summary(year?)` | timor.tech | **年度聚合摘要**：连续假期区间与天数、法定 3 倍工资天数、调休补班清单、全年总休假天数。省略 year 用当年 |
| `history_today(date?)` | 60s-api.viki.moe | 历史上的今天：某月某日的历史事件列表（标题/年份/简述）；省略 date 用今天 |

### `holiday_summary` 为什么是差异化的一层

timor 的两个接口都只给**扁平数据**：`holiday_info` 一次一天，`holiday/year` 一次给全年条目。但它们**给不出**下面这些结论——而这些恰恰是最容易算错的：

```
2026 年中国节假日与调休摘要

【假期区间】共 7 个，合计 33 天（不含补班）
  · 元旦  01-01 ~ 01-03   3天（3倍工资 1 天）
  · 春节  02-15 ~ 02-23   9天（3倍工资 4 天）
  · 清明节  04-04 ~ 04-06   3天（3倍工资 1 天）
  · 劳动节  05-01 ~ 05-05   5天（3倍工资 2 天）
  · 端午节  06-19 ~ 06-21   3天（3倍工资 1 天）
  · 中秋节  09-25 ~ 09-27   3天（3倍工资 1 天）
  · 国庆节  10-01 ~ 10-07   7天（3倍工资 3 天）

【调休补班】共 6 天
  · 01-04 元旦后补班（调休上班，非假日）
  · 02-14 春节前补班（调休上班，非假日）
  · 02-28 春节后补班（调休上班，非假日）
  · 05-09 劳动节后补班（调休上班，非假日）
  · 09-20 中秋节前补班（调休上班，非假日）
  · 10-10 国庆节后补班（调休上班，非假日）

【工资倍率】3倍 13 天 / 2倍 20 天
```

**一处必须记住的坑**：合并假期区间要按**日期连续性**，不能按名称。中国法定假常把「春节」拆成 除夕/初一/初二…（且假日条目的 `target` 字段恒为 `-`，无法用于分组），按同名合并会把春节拆成 9 个单日区间，与「春节放 9 天」的用户心智严重不符。

## 安装

```bash
cd prod/china-mcp
pip install -e .
```

依赖：`mcp`、`fastmcp`（Python ≥ 3.10）。

## 接入 AI 客户端（stdio）

在 Claude Desktop / Cursor / 任意支持 MCP 的客户端配置：

```json
{
  "mcpServers": {
    "china-context": {
      "command": "china-context-mcp"
    }
  }
}
```

或指向模块：

```json
{
  "mcpServers": {
    "china-context": {
      "command": "python",
      "args": ["-m", "china_context_mcp"]
    }
  }
}
```

## 本地验证

```bash
python -m china_context_mcp   # 启动 stdio 服务，由 MCP 客户端连接
```

## 路线图（真空待接数据源，按稀缺度）

- [x] 历史上的今天（零凭证，已接 60s-api.viki.moe）
- [ ] 空气质量 / 天气（中国，公开源多需 key，待找零凭证源）
- [ ] 成语词典（零凭证）⏸ **暂缓**：已实测 muxiaoguo/oick/oioweb/aa1/codelife/xxapi/qqsuu 等候选，**均无可达的零凭证源**（404 / 隧道拦截 / 空端点），不建立在未验证源上
- [ ] 中国大学 / 专业库（零凭证）

## 许可

MIT