# 名人、历史人物与动漫游戏角色生日库 (birthday-mcp)

一个完全本地化、零公网依赖的高性能生日知识库与 FastMCP 服务，专为 Hermes 及各类 Agent 和本地用户设计。

## 核心特性

- **完全本地化**：查询全程运行于本地 SQLite (`data/birthday.db`)，正常查询过程中不访问任何公网服务。
- **全方位覆盖**：
  - 动漫角色、漫画角色、游戏角色、Galgame / VN 角色（CharacterDB / Bangumi / VNDB）
  - 声优、作者、导演等现实创作者人物
  - 中国历史人物（CBDB 中国历代人物传记数据库）
  - 全球知名人物与世界历史人物（Pantheon 2025 / HPI）
  - 中国现代知名人物（院士、学者、作家、演员、歌手、运动员等补充库）
- **高性能架构**：
  - **DuckDB** 用于离线海量数据清洗、多源 Join 与三级去重。
  - **SQLite** 配备专用的 `birthday_index` 覆盖索引，单次查询毫秒级返回。
  - **FastMCP** 规范暴露 4 个轻量易用的语义工具。

## MCP 工具列表

1. `get_birthdays(month, day, limit=50, categories=None, country=None, occupation=None)`：查询指定日期的生日人物列表，按知名度热度值降序。
2. `search_person(name, limit=20)`：根据姓名或别名（支持中文、日文、英文、拼音）模糊或精确搜索人物信息。
3. `get_person(person_id)`：获取人物完整多语言名称、生日历法详情、身份标签与来源记录。
4. `get_upcoming_birthdays(days=7, limit_per_day=20, categories=None)`：获取今天起未来 N 天内的即将生日人物。

## 快速上手

### 1. 安装与初始化

```bash
# 使用 uv 创建虚拟环境并安装依赖
uv venv --python 3.12
uv pip install -e .[dev]
```

### 2. 构建本地数据库

```bash
# 运行 ETL 构建管道 (生成 data/birthday.db)
uv run birthday-etl
```

### 3. 运行 FastMCP 服务

```bash
# 启动标准 stdio MCP 服务
uv run birthday-mcp
```

在 Hermes 或 Claude Desktop 配置中加入：

```json
{
  "mcpServers": {
    "birthday": {
      "command": "d:/dev-code/BirthdayAll/.venv/Scripts/python.exe",
      "args": ["-m", "app.main"]
    }
  }
}
```

### 4. 运行测试套件

```bash
uv run pytest
```