# zotero-ima-mcp

面向科研文献工作流的本地 MCP 服务：以 **Zotero** 管理来源，以 **MinerU** 提取全文，以 **腾讯 ima 知识库** 沉淀文献、Wiki 与结构化 Analysis，并通过 **Skills** 让 AI Agent 按可追溯流程工作。

本项目是 [`zotero-obsidian-mcp`](https://pypi.org/project/zotero-obsidian-mcp/) 的 ima 移植版：保留 Zotero + MinerU 的成熟适配器，把 Obsidian 本地 Vault 替换为腾讯 ima 云端笔记，用本地 JSON 注册表维护「稳定身份 → ima note_id」映射。

## 架构

```
用户自然语言任务
        ↓
7 个科研 Skills：识别意图、规划步骤、约束证据与输出
        ↓
34 个 MCP Tools：版本契约、查询、导入、解析、检索、校验与事务写入
        ↓
Zotero Desktop ── PDF ── MinerU ── 腾讯 ima 知识库
                                     ├─ 文献主笔记 ([zim] <zoteroKey>)
                                     ├─ 全文笔记  ([zim] fulltext <zoteroKey>)
                                     ├─ 文献索引  ([zim] 文献索引)
                                     ├─ Wiki      ([zim] wiki <topic>)
                                     └─ 五类 Analysis / 分析总览
```

项目不绑定大模型供应商。MCP Tools 负责确定性的本地/云端数据操作，Skills 负责把工具编排成可复用的科研工作流。

## 核心功能

- **稳定文献身份**：以 Zotero 父条目 `zoteroKey` 作为主键。
- **Zotero 导入与同步**：支持单篇、Collection、notes、annotations、BibTeX、存储附件和链接附件。
- **MinerU 全文解析**：将 PDF 规范化为 Markdown，发布为 ima 全文笔记。
- **腾讯 ima 文献库**：自动维护文献索引、主笔记、全文笔记、Wiki 与 Analysis。
- **本地注册表**：`<stateDir>/registry.json` 记录每个身份对应的 ima `note_id`，作为幂等与恢复依据。
- **结构化研究层**：支持 `full_read`、`literature_review`、`passage_qa`、`figure_qa`、`concept` 五类 Analysis。
- **科研 Skills**：内置 `paper-qa`、`full-read`、`passage-qa`、`figure-qa`、`compare-papers`、`literature-review`、`concept-learning`。
- **安全写入**：支持 dry-run、事务预览；全部写入先经 `transactionId` 登记。
- **多客户端接入**：支持 Codex、Claude Code、OpenCode、Pi、Hermes 和 WorkBuddy（stdio / SSE / streamable-http）。

## ima OpenAPI 端点

| 操作 | 端点 |
|------|------|
| 创建笔记 | `openapi/note/v1/import_doc` |
| 追加笔记 | `openapi/note/v1/append_doc` |
| 搜索笔记 | `openapi/note/v1/search_note` |
| 获取笔记内容 | `openapi/note/v1/get_doc_content` |
| 可写知识库列表 | `openapi/wiki/v1/get_addable_knowledge_base_list` |
| 知识库详情 | `openapi/wiki/v1/get_knowledge_base` |
| 知识库条目列表 | `openapi/wiki/v1/get_knowledge_list` |

凭证获取：登录 [https://ima.qq.com/agent-interface](https://ima.qq.com/agent-interface) 创建 Client ID / API Key。

## 安装

要求 Python 3.10+。推荐使用 uv 或 pipx：

```bash
# 方式一：从 GitHub 直接安装（推荐）
uv tool install "git+https://github.com/shuishousong/zotero-ima-mcp@main"
# 或
pipx install "git+https://github.com/shuishousong/zotero-ima-mcp@main"

# 方式二：从源码安装（先克隆仓库）
git clone https://github.com/shuishousong/zotero-ima-mcp.git
cd zotero-ima-mcp
python -m pip install -e .

# 方式三：无需持久安装
uvx --from "git+https://github.com/shuishousong/zotero-ima-mcp@main" zotero-ima-mcp doctor
```

## 首次配置

设置 ima 凭证（任选其一）：

```bash
# 环境变量
export IMA_CLIENT_ID="your-client-id"
export IMA_API_KEY="your-api-key"

# 或惯例凭证文件（与 ima-upload skill 兼容）
mkdir -p ~/.config/ima
echo -n "your-client-id" > ~/.config/ima/client_id
echo -n "your-api-key"   > ~/.config/ima/api_key
```

初始化与检查：

```bash
export ZIM_STATE_DIR="~/.zotero-ima-mcp"
zotero-ima-mcp config init --state-dir "$ZIM_STATE_DIR"
zotero-ima-mcp config get   --state-dir "$ZIM_STATE_DIR"
zotero-ima-mcp doctor       --state-dir "$ZIM_STATE_DIR"
zotero-ima-mcp call ima_ping --json '{}'
```

启动 Zotero Desktop 并启用本地 API 后：

```bash
zotero-ima-mcp call zotero_search_items --json '{"query":"photocatalysis"}'
zotero-ima-mcp import item ABCD1234 --state-dir "$ZIM_STATE_DIR" --dry-run
zotero-ima-mcp import item ABCD1234 --state-dir "$ZIM_STATE_DIR"
zotero-ima-mcp mineru parse ABCD1234 --state-dir "$ZIM_STATE_DIR" --dry-run
zotero-ima-mcp mineru parse ABCD1234 --state-dir "$ZIM_STATE_DIR"
```

## MCP 配置（OpenCode / Claude Code）

```json
{
  "mcpServers": {
    "zotero-ima-literature": {
      "command": "zotero-ima-mcp",
      "args": ["serve", "--transport", "stdio"],
      "env": {
        "ZIM_STATE_DIR": "~/.zotero-ima-mcp",
        "IMA_CLIENT_ID": "your-client-id",
        "IMA_API_KEY": "your-api-key"
      }
    }
  }
}
```

## 工具面（34 个）

- **版本 / 系统 / 配置（4）**：`literature_version`、`literature_doctor`、`literature_config_get/validate/initialize`
- **Zotero（6）**：`zotero_ping`、`zotero_search_items`、`zotero_list_collections`、`zotero_get_item`、`zotero_get_children`、`zotero_get_bibtex`
- **ima（4）**：`ima_ping`、`ima_list_knowledge_bases`、`ima_search_notes`、`ima_get_note`
- **导入与同步（4）**：`literature_import_item/collection`、`literature_sync_item/collection`
- **MinerU（3）**：`literature_parse_mineru`、`literature_parse_mineru_batch`、`literature_remove_mineru_output`
- **索引与校验（3）**：`literature_rebuild_index`、`literature_rebuild_analysis_base`、`literature_verify`
- **阅读与检索（2）**：`literature_paper_read`、`literature_retrieve`
- **Analysis（3）**：`literature_analysis_get/write`、`literature_rebuild_analysis_base`
- **Wiki（3）**：`literature_wiki_context/write/list`
- **事务（2）**：`literature_preview_transaction`、`literature_rollback_transaction`

## Skills

| Skill | 工作流 |
|-------|--------|
| `paper-qa` | 单篇快速问答，默认不写入 ima |
| `full-read` | 单篇完整精读并保存 `full_read` |
| `passage-qa` | 定位具体段落、方法、数据或结论 |
| `figure-qa` | 解读图、表、Scheme 和方程 |
| `compare-papers` | 对用户选定论文建立可比性矩阵 |
| `literature-review` | 对文献池进行主题化综述 |
| `concept-learning` | 跨文献建立概念模型 |

## 与 Obsidian 版的差异（ima 边界）

腾讯 ima OpenAPI 当前只提供 **create / append / search / read**，没有 update/delete 端点。因此：

- **更新语义**：已存在的笔记通过 `append_doc` 追加带 `<!-- zim:append:start -->` 标记的修订块；全文重解析生成新版本标题（`[zim] fulltext <key> ·vN`），注册表始终指向最新。
- **回滚语义**：`literature_rollback_transaction` 回滚本地注册表并输出云端清理计划；ima 笔记无法程序化删除，需手动清理。
- **PDF 存储**：PDF 缓存在本地 `<pdfDir>`（默认 `~/.zotero-ima-mcp/pdf`），ima 中沉淀的是 MinerU 全文笔记而非二进制 PDF。
- **身份恢复**：本地注册表损坏时，可依据 ima 笔记标题前缀（`[zim]`）用 `ima_search_notes` 重新索引。

## 安全边界

- 所有写操作先 dry-run，再提交并保存 `transactionId`。
- 不要提交 ima 凭证、Zotero 数据目录、MinerU token 或其他凭据到仓库。
- MinerU 可能把 PDF 发送到外部服务，使用前确认授权和组织政策。
- 推荐本地 `stdio`；SSE/HTTP 必须放在可信认证边界之后。
- 事务日志不替代独立的 ima 备份。

## 许可证

MIT