连接 AI 助手与 Zotero 研究库的 Model Context Protocol 服务器。

开发者规范与仓库协作约定见 AGENTS.md。

• MCP 入口：src/zotero_mcp/server.py
• CLI 入口：src/zotero_mcp/cli_app/main.py
• 解析与分发：src/zotero_mcp/cli_app/registry.py

• src/zotero_mcp/handlers/tools.py
• src/zotero_mcp/handlers/prompts.py

• src/zotero_mcp/services/data_access.py（统一数据访问门面）
• src/zotero_mcp/services/scanner.py（批量扫描与分析）
• src/zotero_mcp/services/zotero/metadata_update_service.py（元数据补全）
• src/zotero_mcp/services/zotero/duplicate_service.py（去重）
• src/zotero_mcp/services/zotero/semantic_search.py（语义搜索）

• src/zotero_mcp/clients/zotero/
• src/zotero_mcp/clients/database/
• src/zotero_mcp/clients/metadata/
• src/zotero_mcp/clients/llm/

• 入口: GlobalScanner.scan_and_process()
• 目标: 扫描需要 AI 分析的条目并触发分析
• 逻辑阶段:

1. 扫描 source_collection（默认 00_INBOXS）
2. 候选不足时按集合顺序继续扫描
3. 过滤规则: 必须有 PDF 且未带 AI/条目分析 标签
4. 执行分析并可移动到 target_collection

• 入口: MetadataUpdateService.update_all_items()
• 目标: 使用 Crossref/OpenAlex 增强条目元数据
• 逻辑要点:

1. 先按 DOI 查，DOI 路径不再降级 title/url
2. 清洗 HTML 标题后再做 title 查询
3. 将扩展信息安全写入 extra

• 入口: DuplicateDetectionService.find_and_remove_duplicates()
• 目标: 检测并删除重复条目（永久删除，不移动回收站）
• 分组优先级: DOI > title > URL
• 保留策略: 按完整度评分保留主条目

• 入口: WorkflowService.prepare_analysis() / WorkflowService.batch_analyze()
• 目标: 批量 PDF 分析、生成结构化笔记、支持检查点恢复

• 入口: ZoteroSemanticSearch.search() / update_database()
• 目标: ChromaDB 向量检索与索引更新
• 当前行为:

1. limit <= 0 直接返回空结果
2. 兼容空嵌套列表结果结构
3. 连接拒绝抛出 RuntimeError

跨服务的批处理入口统一由显式参数模型约束:

• src/zotero_mcp/models/operations.py
  • ScannerRunParams
  • MetadataUpdateBatchParams
  • DuplicateScanParams

这三个模型统一了:

• 默认值
• 数值边界（如 scan_limit >= 1）
• 禁止隐式额外字段（extra="forbid"）

批处理服务统一返回 envelope（并保留兼容字段）:

• src/zotero_mcp/services/common/operation_result.py
  • operation_success(...)
  • operation_error(...)

统一字段:

• success
• operation
• status
• metrics
• message / error / details

重复的 offset + limit 循环已统一:

• src/zotero_mcp/services/common/pagination.py
  • iter_offset_batches(...)

已接入:

• scanner.py
• metadata_update_service.py
• duplicate_service.py

zotero-mcp <command> <subcommand> [parameters]

• zotero-mcp system serve
• zotero-mcp system setup
• zotero-mcp system setup-info
• zotero-mcp system version
• zotero-mcp system update [--check-only --force --method pip|uv|conda|pipx]

• zotero-mcp workflow item-analysis
• zotero-mcp workflow metadata-update
• zotero-mcp workflow deduplicate

• zotero-mcp semantic db-update
• zotero-mcp semantic db-status
• zotero-mcp semantic db-inspect

# 扫描并分析
zotero-mcp workflow item-analysis --target-collection 01_SHORTTERMS --output json

# 更新元数据
zotero-mcp workflow metadata-update --scan-limit 200 --treated-limit 100

# 查看语义数据库状态
zotero-mcp semantic db-status --output json

# 获取条目详情
zotero-mcp items get --item-key ABCD1234 --output json

# 创建笔记
zotero-mcp notes create --item-key ABCD1234 --content "My note"

# 上传 PDF 附件
zotero-mcp pdfs add --item-key ABCD1234 --file ./paper.pdf

• zotero_semantic_search - 语义搜索
• zotero_search - 关键词搜索
• zotero_advanced_search - 高级搜索
• zotero_search_by_tag - 标签搜索
• zotero_get_recent - 最近条目

• zotero_get_metadata - 条目元数据
• zotero_get_fulltext - 全文内容
• zotero_get_bundle - 完整条目数据
• zotero_get_children - 附件和笔记
• zotero_upload_pdf - 上传本地 PDF 到条目

• zotero_get_collections - 列出集合
• zotero_find_collection - 按名称查找（模糊匹配）
• zotero_get_tags - 列出所有标签

• zotero_get_annotations - PDF 注释
• zotero_get_notes - 获取笔记
• zotero_search_notes - 搜索笔记/注释
• zotero_create_note - 创建笔记

• zotero_prepare_analysis - 收集 PDF 内容
• zotero_batch_analyze_pdfs - 批量 AI 分析
• zotero_resume_workflow - 恢复中断的工作流
• zotero_list_workflows - 查看工作流状态