Metadata-Version: 2.4
Name: dhcckb-cbdb-mcp
Version: 1.0.0
Summary: MCP Server for querying CBDB historical biographical database - search person by name and retrieve comprehensive structured data across 10 dimensions.
Author: CBDB MCP Team
License: MIT
Keywords: biographical-database,cbdb,chinese-history,digital-humanities,mcp
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Database
Classifier: Topic :: Sociology :: History
Requires-Python: >=3.10
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.0.0
Requires-Dist: mcp>=1.0.0
Description-Content-Type: text/markdown

# CBDB MCP Server

CBDB 试录入系统人物信息检索 MCP Server — 输入历史人物姓名，从 CBDB（Chinese Biographical Database）试录入系统中检索并返回人物的全部主要信息，涵盖基本資料、地址、别名、著述、官名、入仕、社會區分、親屬、社會關係、社交機構十个维度，以结构化 JSON 格式呈现。

## 功能

- **`search_person_by_name`** — 根据姓名检索人物
  - 输入中文姓名，自动搜索 CBDB 数据库
  - 多个同名人物时返回候选列表
  - 唯一匹配时返回十类完整信息的聚合结果
  - 无结果时返回明确的空结果提示

## 安装

### 方式一：使用 uvx（推荐，无需安装）

```bash
uvx cbdb-mcp
```

### 方式二：使用 pip 安装

```bash
pip install cbdb-mcp
```

安装后执行：

```bash
cbdb-mcp
```

## MCP 客户端配置

### Claude Desktop

在 `claude_desktop_config.json` 中添加：

```json
{
  "mcpServers": {
    "cbdb": {
      "type": "stdio",
      "command": "uvx",
      "args": ["cbdb-mcp"]
    }
  }
}
```

### Cursor / VS Code

在 MCP 配置中添加：

```json
{
  "mcpServers": {
    "cbdb": {
      "type": "stdio",
      "command": "uvx",
      "args": ["cbdb-mcp"],
      "env": {}
    }
  }
}
```

### 使用 pip 安装后的配置

```json
{
  "mcpServers": {
    "cbdb": {
      "type": "stdio",
      "command": "cbdb-mcp"
    }
  }
}
```

## 使用示例

在 MCP 客户端中，通过 LLM 发起查询：

> 帮我查一下苏轼的CBDB信息

Server 将返回包含以下维度的结构化数据：

```json
{
  "success": true,
  "query": "蘇軾",
  "result_count": 1,
  "基本資料": {
    "姓名(中)": "蘇軾",
    "姓名(拼音)": "Su Shi",
    "朝代": "宋",
    "生年": "1037",
    "卒年": "1101",
    ...
  },
  "别名": [
    {"序號": "1", "別名拼音": "Zizhan", "別名漢字": "子瞻", "別名類型": "字"},
    {"序號": "2", "別名拼音": "Dongpo Jushi", "別名漢字": "東坡居士", "別名類型": "號"}
  ],
  "地址": [...],
  "著述": [...],
  "官名": [...],
  "入仕": [...],
  "社會區分": [...],
  "親屬": [...],
  "社會關係": [...],
  "社交機構": [...]
}
```

## 数据维度说明

| 维度 | 说明 | 数据来源 |
|------|------|----------|
| 基本資料 | 姓名、拼音、朝代、生卒年、性别、享年等 | `/basicinformation/{id}` |
| 地址 | 人物相关地址（类别、地名、始年终年） | `/basicinformation/{id}/addresses` |
| 别名 | 字、号等别名（拼音、汉字、类型） | `/basicinformation/{id}/altnames` |
| 著述 | 著作列表（书名、著述角色） | `/basicinformation/{id}/texts` |
| 官名 | 任官记录（官名、地名、始年终年） | `/basicinformation/{id}/offices` |
| 入仕 | 入仕途径（科举、学校等） | `/basicinformation/{id}/entries` |
| 社會區分 | 社会身份分类（中英文、始年终年） | `/basicinformation/{id}/statuses` |
| 親屬 | 亲属关系（关系类别、亲属姓名） | `/basicinformation/{id}/kinship` |
| 社會關係 | 社会关系（关系类别、关系人、作品） | `/basicinformation/{id}/assoc` |
| 社交機構 | 所属社交机构（机构名、角色、始年终年） | `/basicinformation/{id}/socialinst` |

## 系统要求

- Python 3.10+
- 网络连接（需能访问 `http://16.163.176.37:8013`）

## 技术栈

- [FastMCP](https://github.com/jlowin/fastmcp) — MCP Server 框架
- [httpx](https://www.python-httpx.org/) — 异步 HTTP 客户端
- [BeautifulSoup4](https://www.crummy.com/software/BeautifulSoup/) + lxml — HTML 解析

## 开发

```bash
# 克隆源码
git clone <repo-url>
cd cbdb-mcp

# 安装依赖
uv sync

# 运行测试
uv run pytest

# 启动 MCP Server
uv run cbdb-mcp
```

## 数据来源

数据来自 [CBDB（Chinese Biographical Database Project）](https://cbdb.hsites.harvard.edu/) 试录入系统。CBDB 由哈佛大学费正清中国研究中心维护，内容采用 [CC BY-NC-SA 4.0 International](https://creativecommons.org/licenses/by-nc-sa/4.0/) 许可。

## 许可证

MIT License
