Metadata-Version: 2.5
Name: chinese-corpus-mcp
Version: 0.1.1
Summary: 中华版本语料库平台官方 MCP Server（Python 版）— chunk_search / deep_research / book_search（默认一把 API Key，数据集在平台后台切换）
Project-URL: Homepage, https://chinese-corpus.cn
Author: chinese-corpus
License-Expression: MIT
License-File: LICENSE
Keywords: chinese-corpus,knowledge-service,mcp,model-context-protocol
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering :: Artificial Intelligence
Requires-Python: >=3.11
Requires-Dist: httpx2<3,>=2.12
Requires-Dist: mcp<3,>=2.1.1
Description-Content-Type: text/markdown

# chinese-corpus-mcp

中文语料平台的官方 MCP（Model Context Protocol）服务器（Python 版）。接入后，你的 AI 助手（Claude、Cursor、其他 MCP 客户端）可以直接检索平台授权语料、发起深度研究、查询全平台图书元数据。

与 npm 版 [`@chinese-corpus/mcp-server`](https://www.npmjs.com/package/@chinese-corpus/mcp-server) 是同一产品的两种语言实现，功能完全对等：**二选一安装即可**——机器上有 Python 用本包（uvx 直跑，无需安装 Node.js），有 Node.js 用 npm 版。

## 五个工具

| 工具 | 作用 | 计费 |
| --- | --- | --- |
| `chunk_search` | 在当前数据集内做语义+关键词混合检索，返回带引用四要素（书名/作者/出版社/章节）的图书片段 | 每次调用扣积分（数据集单价） |
| `deep_research` | 提交深度研究任务并阻塞等待结构化报告（子问题/结论/证据/引用） | 每次任务扣积分 |
| `deep_research_status` | 按 taskId 查询任务状态/进度/报告（超时后的取回通道） | 不扣积分（状态查询） |
| `book_search` | 检索全平台图书元数据（CIP 在版编目），与 Key 绑定的数据集无关 | 免费 |
| `get_service_context` | 只读自查：当前 Key 绑定了哪个数据集 | 不扣积分 |

**数据集范围由你的 API Key 在平台侧决定**：工具参数、环境变量、配置文件里都没有（也不允许有）"选数据集"的开关。要换数据集，去平台网站「用户中心 → API Key 管理」切换当前绑定即可，下一次调用立即生效，MCP 服务器无需重启、无需改配置。

## 安装（推荐：一句话让 AI 助手帮你装）

需要 Python 3.11+ 与 [uv](https://docs.astral.sh/uv/)（`curl -LsSf https://astral.sh/uv/install.sh | sh`）。把下面这段话原样发给你的 AI 助手（Claude / Cursor 等），它会帮你完成安装和配置：

> 请帮我安装中文语料平台的 MCP 服务器：在终端运行 `uvx chinese-corpus-mcp --help` 确认可用（需要 Python 3.11+ 与 uv），然后把它注册为 MCP 服务器（命令 `uvx`，参数 `chinese-corpus-mcp`，环境变量 `CHINESE_CORPUS_API_KEY`，值我会单独提供）。全部工具（chunk_search / deep_research / deep_research_status / book_search / get_service_context）都启用，不需要任何启动参数。

不想用 AI 助手？也可以先安装再配置：`pipx install chinese-corpus-mcp`（或 `pip install chinese-corpus-mcp`），然后命令填 `chinese-corpus-mcp`。uvx 形态免安装、卸载即删配置，对系统侵入最小。

## 手动配置

### Claude Desktop / 标准 MCP 客户端（单服务器）

在 MCP 配置文件（如 `claude_desktop_config.json`）中加入：

```json
{
  "mcpServers": {
    "chinese-corpus": {
      "command": "uvx",
      "args": ["chinese-corpus-mcp"],
      "env": {
        "CHINESE_CORPUS_API_KEY": "ck_你的APIKey"
      }
    }
  }
}
```

### 环境变量

| 变量 | 必填 | 说明 |
| --- | --- | --- |
| `CHINESE_CORPUS_API_KEY` | 是 | 平台 API Key（形如 `ck_...`），在平台「用户中心 → API Key 管理」创建；只在创建时完整展示一次 |
| `CHINESE_CORPUS_API_BASE_URL` | 否 | 平台 API 地址，默认 `http://10.25.2.15`（平台内网入口，通常无需修改）；仅当平台方另行提供新地址时覆盖 |
| `CHINESE_CORPUS_PROFILE_NAME` | 否 | 仅本地显示用的标签（如 `公司内网`），不会发送到平台；一台机器跑多个服务器条目时用于区分 |

没有 dataset / datasetId 环境变量——数据集选择永远在平台后台完成（见上文）。本服务器默认不读取 `HTTP_PROXY` 等代理环境变量（默认地址是内网入口，走代理反而连不上）；需要代理的自定义部署请联系平台方。

### Cursor / 其他客户端

任何支持"命令 + 环境变量"形态 MCP 服务器的客户端都适用：命令 `uvx` + 参数 `chinese-corpus-mcp`，环境变量同上表。

## 进阶：一台机器多个服务器条目

默认一把 Key 对应一个服务器条目已够用（换数据集在后台切换，见上）。仅当你需要**同时**保持两个不同数据集在线时，才注册多个条目，并用 `CHINESE_CORPUS_PROFILE_NAME` 区分：

```json
{
  "mcpServers": {
    "chinese-corpus-全库": {
      "command": "uvx",
      "args": ["chinese-corpus-mcp"],
      "env": { "CHINESE_CORPUS_API_KEY": "ck_key_a", "CHINESE_CORPUS_PROFILE_NAME": "全库" }
    },
    "chinese-corpus-古籍库": {
      "command": "uvx",
      "args": ["chinese-corpus-mcp"],
      "env": { "CHINESE_CORPUS_API_KEY": "ck_key_b", "CHINESE_CORPUS_PROFILE_NAME": "古籍库" }
    }
  }
}
```

> 提示：本包与 npm 版是同一产品身份，命令名相同（`chinese-corpus-mcp`）。uvx / npx 直跑形态互不安装、互不冲突；只有当你把两个包都"全局安装"到同一台机器时，才需要留意 PATH 中谁在前——一般用不到这种组合。

## 常见问题

- **返回「API Key 无效或已过期」**：检查 `CHINESE_CORPUS_API_KEY` 是否配置、Key 是否仍为 ACTIVE 且未过期、是否被吊销。
- **返回「积分不足」**：到平台网站充值后重试；余额与消费记录在个人中心查询（工具不返回余额）。
- **返回「无权访问此 Key 绑定的数据集」**：数据集已下架或归属变更；到用户中心切换绑定数据集。
- **想换检索的图书范围**：不是改 MCP 配置——去平台「用户中心 → API Key 管理」切换 Key 的当前绑定数据集，下一次调用生效，无需重启。
- **`deep_research` 超时**：任务不会被取消，稍后用 `deep_research_status`（带返回的 taskId）取回报告。
- **book_search 翻页**：返回的 `count` 是本页条数，不是命中总数；按 page/pageSize 翻页（最多第 10 页）。

## 日志与排障

MCP 服务器按协议要求只把 JSON-RPC 帧写到 stdout；运行日志全部走 stderr（不会干扰客户端解析）。排障时看客户端的 MCP 日志面板即可，报错文本带「请求编号」，反馈给平台时可一并附上。

## 许可证

MIT（见 [LICENSE](./LICENSE)）。
