Metadata-Version: 2.4
Name: dhcckb-ytenx-mcp
Version: 0.1.0
Summary: 韵典网（ytenx.org）音韵查询 MCP Server — 支持查詢廣韻、中原音韻、洪武正韻牋、分韻撮要、上古音系五部韻書的漢字音韻數據
Project-URL: Repository, https://pypi.org/project/dhcckb-ytenx-mcp/
Author: ytenx-mcp contributors
License: MIT
License-File: LICENSE
Keywords: chinese,guangyun,mcp,phonology,rhyme,ytenx,廣韻,音韻,韻典
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Education
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Text Processing :: Linguistic
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

# ytenx-mcp

韵典网（ytenx.org）音韵查询 MCP Server — 支持查询单个汉字的音韵数据，覆盖五部韵书。

## 功能

通过 MCP 协议提供 `query_character_phonology` 工具，查询以下五部韵书：

| 韵书 | dict key | 说明 |
|------|----------|------|
| 廣韻 | `guangyun` | 宋代韵书，记录中古音 |
| 中原音韻 | `zhongyuan` | 元代韵书，记录近古音 |
| 洪武正韻牋 | `hongwu` | 明代韵书 |
| 分韻撮要 | `fenyun` | 清代粤语韵书 |
| 上古音系 | `shanggu` | 郑张尚芳上古音拟音 |

## 安装

### 使用 uvx（推荐，无需手动安装）

```bash
uvx ytenx-mcp
```

### 使用 pip

```bash
pip install ytenx-mcp
python -m ytenx_mcp
```

## MCP Client 配置

### Claude Desktop (claude_desktop_config.json)

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

或使用 pip 安装后：

```json
{
  "mcpServers": {
    "ytenx": {
      "command": "python",
      "args": ["-m", "ytenx_mcp"]
    }
  }
}
```

### Claude Code (mcp.json)

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

## Tool Schema

### query_character_phonology

查询单个汉字的音韵数据。

**参数：**

| 参数 | 类型 | 必填 | 说明 |
|------|------|------|------|
| `character` | string | 是 | 要查询的单个汉字，如 `東`、`魚` |
| `dictionaries` | string[] | 否 | 指定查询的韵书列表，默认全部五部。可选值：`guangyun`、`zhongyuan`、`hongwu`、`fenyun`、`shanggu` |

**返回格式：**

```json
{
  "character": "東",
  "dictionaries": {
    "guangyun": {
      "name": "廣韻",
      "entries": [
        {
          "character": "東",
          "entry_index": 1,
          "fanqie": "德紅切",
          "xiaoyun": "東",
          "yun_she": "通開一平",
          "rhyme_group": "東",
          "initial": "端",
          "baxter": "tuwng",
          "gu_yun": "tung",
          "annotation": "春方也說文曰動也从日在木中...",
          "raw_phonetic_header": "德 紅 切 東 小韻",
          "raw_rhyme_info": "通開一平 東 端 (白一平: tuwng; 古韻: tung)"
        }
      ],
      "not_found": false
    },
    "zhongyuan": {
      "name": "中原音韻",
      "entries": [
        {
          "character": "東",
          "entry_index": 1,
          "initial": "端",
          "rhyme_group": "東鍾",
          "tone": "陰平",
          "xiaoyun": "東",
          "raw_phonetic_info": "端 母 東鍾 韻 陰平 東 小韻"
        }
      ],
      "not_found": false
    },
    "hongwu": {
      "name": "洪武正韻牋",
      "entries": [
        {
          "character": "東",
          "entry_index": 1,
          "fanqie": "德紅切",
          "tone": "平聲",
          "rhyme_group": "一東",
          "xiaoyun": "東",
          "romanization": "tuŋ",
          "annotation": "【正韻】徳紅切春方也..."
        }
      ],
      "not_found": false
    },
    "fenyun": {
      "name": "分韻撮要",
      "entries": [
        {
          "character": "東",
          "entry_index": 1,
          "initial": "端",
          "rhyme_group": "東",
          "tone": "陰平",
          "xiaoyun": "東",
          "annotation": "東西"
        }
      ],
      "not_found": false
    },
    "shanggu": {
      "name": "上古音系",
      "entries": [
        {
          "character": "東",
          "entry_index": 1,
          "phonetic_element": "東",
          "rhyme_group": "東",
          "rhyme_subdivision": 0,
          "reconstruction": "toːŋ",
          "annotation": "種（種籽）初文..."
        }
      ],
      "not_found": false
    }
  }
}
```

当某部韵书查询不到数据时，`entries` 为空数组且 `not_found` 为 `true`，不会抛出错误。

## 依赖

- Python 3.10+
- [httpx](https://www.python-httpx.org/) — 异步 HTTP 客户端
- [beautifulsoup4](https://www.crummy.com/software/BeautifulSoup/) + [lxml](https://lxml.de/) — HTML 解析
- [mcp](https://pypi.org/project/mcp/) — MCP Python SDK

## 许可证

MIT

## 数据来源

所有音韵数据来自 [韻典網](https://ytenx.org/)，版权归原作者 [BYVoid](https://www.byvoid.com/) 所有。
