zotero-ima-mcp

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

本项目是 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 创建 Client ID / API Key。

安装

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

# 方式一：从 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 凭证（任选其一）：

# 环境变量
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

初始化与检查：

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 后：

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）

{
  "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