Metadata-Version: 2.5
Name: zijian-mcp
Version: 0.1.0
Summary: 字鉴书法识字 MCP Server：上传单字图片，识别楷行草隶篆及甲骨文、金文、战国文字等字形，返回候选汉字、繁体、拼音、置信度与释义
Author: LIU Jin-zhu
License-Expression: MIT
License-File: LICENSE
Keywords: ancient-scripts,calligraphy-recognition,chinese-character,digital-humanities,mcp,model-context-protocol,zijian
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Science/Research
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: annotated-types==0.7.0
Requires-Dist: anyio==4.13.0
Requires-Dist: attrs==26.1.0
Requires-Dist: certifi==2026.4.22
Requires-Dist: charset-normalizer==3.4.7
Requires-Dist: click==8.4.1
Requires-Dist: colorama==0.4.6; platform_system == 'Windows'
Requires-Dist: h11==0.16.0
Requires-Dist: httpcore2==2.16.2
Requires-Dist: httpx2==2.16.2
Requires-Dist: idna==3.20
Requires-Dist: jsonschema-specifications==2025.9.1
Requires-Dist: jsonschema==4.26.0
Requires-Dist: mcp-types==2.3.0
Requires-Dist: mcp==2.3.0
Requires-Dist: opentelemetry-api==1.45.2
Requires-Dist: pillow==12.2.0
Requires-Dist: pydantic-core==2.46.4
Requires-Dist: pydantic==2.13.4
Requires-Dist: pyjwt==2.15.1
Requires-Dist: python-multipart==0.0.34
Requires-Dist: pywin32==312; sys_platform == 'win32'
Requires-Dist: referencing==0.37.0
Requires-Dist: requests==2.34.2
Requires-Dist: rpds-py==2026.9.1
Requires-Dist: sse-starlette==3.7.0
Requires-Dist: starlette==1.10.0
Requires-Dist: truststore==0.10.5
Requires-Dist: typing-extensions==4.15.0
Requires-Dist: typing-inspection==0.4.2
Requires-Dist: urllib3==2.7.0
Requires-Dist: uvicorn==0.54.0
Description-Content-Type: text/markdown

# 字鉴书法识字 MCP Server（zijian-mcp）

上传单字图片，调用「字鉴·书法识别」（shufashibie.com，济南诗书传家教育科技有限公司）智能识别接口，识别古籍、碑帖、书法作品与古文字材料中难以辨认的单个汉字，返回候选字头、繁体字形、拼音、置信度与释义全文。

## 项目背景

「字鉴·书法识别」是教育部、国家语委甲骨文等古文字研究与应用专项重大项目，将人工智能技术引入非标准字体的识读，识读范围覆盖甲骨文、金文、战国文字等古文字及楷、行、草、隶、篆等书法字形，旨在推动古文字研究与人工智能的结合。本工具为该识别能力的非官方 MCP 封装。

## 解决什么问题

传统 OCR 面向规整印刷文本，对碑帖、手迹、篆隶行草及异体字、生僻字常常束手无策。「字鉴」基于"书法字典"字库做字形图像匹配，恰好补上这一环：看到拓片中一个不认识的字，拍照框选，即可得到候选字与释义。本工具将该能力封装为 MCP，供古籍整理、数字人文研究中的智能体直接调用。

## 工具

### `recognize_character`

| 参数 | 类型 | 说明 |
|---|---|---|
| `image_path` | string（可选） | 本地图片文件路径，与 `image_base64` 二选一 |
| `image_base64` | string（可选） | base64 编码图片（可含 `data:` 前缀），与 `image_path` 二选一 |
| `crop_left` / `crop_top` / `crop_right` / `crop_bottom` | integer（可选，四项须同时提供） | 裁剪框像素坐标，用于从整页图/整幅照片中框出单个汉字 |
| `top_n` | integer（可选，默认 5） | 返回候选数量上限 |

返回 JSON：`candidates[]`（含 `char`、`traditional`、`pinyin`、`score`、`definition`，按置信度降序）、`result_image_url`（上传后的单字图）、必要时附 `warning`（Top1 置信度低于 10% 时提示人工复核）。

## 能力边界（重要）

- 识别基于"书法字典"字库的图像匹配：**规整楷书、印刷体、碑刻形态可靠性较高**；
- 变形较大的行草字形、字库未收录的超生僻字**可能无法命中**，此时各候选置信度普遍低于 3%，返回体中会带 `warning` 提示人工复核；
- 每次只识别**一个**汉字，多字图片请用裁剪框参数框出目标字。

## 安装（公共 PyPI）

```bash
uvx zijian-mcp
```

MCP 客户端配置（stdio）：

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

## 说明

- 本项目为非官方封装，数据源为字鉴网页版公开免费接口（无需 API 密钥），仅作学术查字辅助；识别结果数据依据"书法字典"字库，仅供核对参考。
- 已在数字人文智慧平台（dh.cckb.cn）登记分发。

## 许可

MIT
