Metadata-Version: 2.4
Name: judian-poetry-mcp
Version: 1.0.4
Summary: Local Stdio MCP server for Judian poetry OpenAPI.
Requires-Python: >=3.10
Description-Content-Type: text/markdown
Requires-Dist: mcp>=1.0.0
Requires-Dist: httpx[http2]>=0.27.0
Requires-Dist: keyring>=25.0.0

# judian-poetry-mcp

聚典诗文数据库本地 Stdio MCP 服务。它把 Kimi Code CLI、Claude Code 等 MCP 客户端与聚典诗文 OpenAPI 连接起来，所有 HTTPS 请求都从用户本机发出，用于满足聚典授权阶段的 IP 白名单校验要求。

当前版本：`1.0.4`

## 特性

- 本地 Stdio MCP，不走云端中转。
- `clientSecret` 保存到系统钥匙串，不写入 Kimi、Claude 或 MCP 配置文件。
- 支持诗词搜索、诗词详情、诗词译文、标签、诗人搜索、诗人详情 6 个工具。
- 不注册赏析工具，因为聚典赏析接口当前返回加密文本。

## 安装

推荐使用隔离环境，避免影响系统 Python 里的其它包：

```powershell
python -m venv C:\Users\%USERNAME%\.judian-mcp
C:\Users\%USERNAME%\.judian-mcp\Scripts\python.exe -m pip install --upgrade pip
C:\Users\%USERNAME%\.judian-mcp\Scripts\python.exe -m pip install judian-poetry-mcp
```

也可以直接安装到当前 Python：

```powershell
python -m pip install judian-poetry-mcp
```

## 一次性配置

```powershell
C:\Users\%USERNAME%\.judian-mcp\Scripts\python.exe -m judian_mcp_server setup
```

按提示输入：

```text
聚典 clientId:
聚典 clientSecret:
用户标识 userId [local_mcp_user]:
```

## Kimi 注册

隔离环境安装时：

```powershell
kimi mcp add --transport stdio judian-poetry-db -- C:\Users\%USERNAME%\.judian-mcp\Scripts\python.exe -m judian_mcp_server
kimi mcp test judian-poetry-db
```

全局安装时：

```powershell
kimi mcp add --transport stdio judian-poetry-db -- python -m judian_mcp_server
kimi mcp test judian-poetry-db
```

## Claude Code 注册

隔离环境安装时：

```powershell
claude mcp add --transport stdio --scope user judian-poetry-db -- C:\Users\%USERNAME%\.judian-mcp\Scripts\python.exe -m judian_mcp_server
claude mcp get judian-poetry-db
```

全局安装时：

```powershell
claude mcp add --transport stdio --scope user judian-poetry-db -- python -m judian_mcp_server
claude mcp get judian-poetry-db
```

## 可用工具

| 工具 | 说明 |
| --- | --- |
| `search_poetry` | 检索诗文作品，返回 ID、题名、作者、朝代 |
| `get_poetry_details` | 获取作品详情和正文 |
| `get_poetry_translation` | 调用 `/{id}/explain` 获取译文 |
| `get_poetry_tags` | 获取诗词和诗人相关标签 |
| `search_poetry_authors` | 检索诗人 |
| `get_poetry_author_details` | 获取诗人详情 |

## 自检

```powershell
python -m judian_mcp_server doctor
python -m judian_mcp_server config-path
```

## 升级

隔离环境：

```powershell
C:\Users\%USERNAME%\.judian-mcp\Scripts\python.exe -m pip install --upgrade judian-poetry-mcp
```

全局安装：

```powershell
python -m pip install --upgrade judian-poetry-mcp
```

升级后不需要重新运行 `setup`，原有系统钥匙串和用户配置会继续使用。
