Skip to main content
Glama
Sign In
Scholar Library

Scholar Library

by SAKURAfan1023
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

Scholar Library · 文献研究插件

面向高校学生与研究员的本地文献库，通过标准MCP接入AI宿主。宿主负责理解与写作；插件负责收集、版本、原件、TextIn任务、证据检索、引用完整性检查、关系、导出和恢复。

状态：0.1.0 开发版，持续更新、完善与迭代中。 能力及验收边界见验收记录。历史开发记录报告 TextIn 直连 API 完成30篇中英文论文、374页解析，以及字段/表格抽取实测；原始材料、响应与本机诊断库不公开，不能仅凭该摘要独立复核；广泛材料质量、人工语义指标及第二种图形AI宿主验收尚未完成，不能视为计划全部验收通过。

环境与兼容性

  • Python 3.12+、uv、Git，以及支持本地 stdio MCP 的 AI 客户端。MCP 是客户端调用本地工具的协议，不是另一个聊天模型。

  • macOS 已有本机运行证据；Linux 使用相同 POSIX 文件锁接口，但尚需独立实机验收。

  • Windows 原生 Python 暂不支持。可在 WSL2/Linux 内安装并让客户端启动 WSL 中的服务；这一组合尚未实机验收，不提供 Windows 原生安装包。

  • 首次安装会下载 Python/依赖，需要网络。API 服务的额度、价格和产品权限由各服务商控制，开源代码不包含免费额度或凭据。

Related MCP server: ResearchBrain MCP Server

安装与运行

git clone https://github.com/SAKURAfan1023/scholar-library.git
cd scholar-library
uv sync --locked --python 3.12
uv run python scripts/configure_local.py
uv run python scripts/smoke_mcp.py

最后一步在临时合成库中验证 MCP，不上传论文、不调用 OCR。将生成的 .mcp.json 内容导入客户端的 MCP 配置；直接作为 Codex 本地插件使用时，仓库中的 manifest 和 Skill 也一并保留。宿主各自的插件注册界面可能不同，配置导入后必须实际调用 workspace_status 确认连接。

手工启动服务用于排障：

uv run scholar-library

以上命令启动stdio MCP服务，等待客户端请求；不会自动上传。.mcp.example.json 提供无密钥格式示例，configure_local.py 生成的 .mcp.json 是本机专用文件，不进入 Git；移动源码后重新生成。正式安装使用python3 scripts/build_release.py构建独立安装包，解压后运行python3 install_release.py --target <新的安装目录>，将生成的mcp.json交给支持本地stdio MCP的客户端。安装会下载锁定依赖，不是全离线安装包。

默认库为~/.local/share/scholar-library，可用环境变量SCHOLAR_DATA_DIR指定。运行环境、源码与文献库相互独立；真实材料不进入Git或插件安装包。

TextIn凭据通过系统钥匙串配置：

uv run scholar-configure TEXTIN_APP_ID
uv run scholar-configure TEXTIN_SECRET_CODE

同名环境变量可覆盖钥匙串，适合受控部署；不要把值写入MCP配置或分享给AI。OpenAlex可配置OPENALEX_API_KEY，可选语义索引配置EMBEDDING_API_KEY。服务商是否开通产品仍须真实验证。

第一次使用

  1. 创建专用材料目录，将要研究的PDF/DOCX/图片/文本放入其中。

  2. 向AI说明研究问题、输入目录、哪些服务允许联网、可用页数和请求预算。

  3. AI调用workspace_status、create_project，建立授权项目，再检索或导入指定材料。

  4. 阅读、追问、对比后将带引用主张保存为research记录，按需要导出。

示例提示：

使用文献插件研究“检索增强生成如何降低文献问答中的错误引用”。先检查工作区，建立研究项目。优先检索Crossref和arXiv，列出候选与来源状态。只下载我选中的开放PDF。全文解析前核对项目上传授权和页数预算。回答必须带原文片段和PDF页序，区分作者结论、推断和证据不足。

已有授权在项目内持续有效，无需每次调用重复确认。host_text控制向宿主返回正文，但无法控制宿主接收后的保存策略。TextIn页范围限制处理页，上传的仍是整个文件。

能力

  • Crossref/OpenAlex/arXiv/PubMed检索及逐来源状态；DOI/PMID/arXiv解析；公开PDF下载。

  • BibTeX/RIS/CSL-JSON与Zotero交换题录，付费数据库通过授权本地全文导入。

  • 独立文献版本、来源快照、阅读和筛选理由，重复与冲突候选。

  • 免费离线PDF文字层解析、原页图核对；TextIn xParse任务续接、分批论文解析、原始缓存、页图读取；单独字段/表格抽取。

  • 中英文关键词检索、可选OpenAI兼容embedding混合检索；向量本地保存。

  • 带精确摘录的回答/卡片/综述，跨论文关系，方法评价；生成产物不污染原文检索。

  • Markdown、JSON、CSV、BibTeX、RIS、CSL-JSON、HTML、PDF、DOCX，GB/T 7714与APA参考文献。

  • 带哈希的备份/恢复、删除影响预览、版本冲突控制。

边界

  • 单人本地库，允许多个新服务进程连接；不放网络盘。备份需关闭其他连接；Windows尚未支持POSIX文件锁。

  • 单文件100MiB、PDF最多2000页、每次TextIn处理1–100页；这是本地保护值，不代表服务商必然支持。服务商拒绝时保留任务及失败状态。

  • request_budget累计计入网络检索、下载、解析提交、查询和向量请求，page_budget计入解析/抽取预留页数。未知提交不释放预留量，避免超支；不报告无法核实的货币费用。

  • 本地MD/TXT/DOCX解析不做OCR。DOCX使用段落/表格位置而不是稳定页码，文本框和复杂布局可能未提取。PDF可用parse_local_pdf离线提取文字层进入索引；扫描页/图片需TextIn。文字层完整不代表视觉内容完整，表格、公式、双栏顺序须看原页复核。

  • OpenAlex标志与Crossref撤稿通知都是来源信息，不是论文质量保证；元数据源不全、错误或过期均可能影响结论。

  • 下载和embedding拒绝内网地址并固定实际连接IP；遇到本机代理的198.18/15合成DNS地址时，会通过Cloudflare HTTPS DNS核实公开域名（仅发送域名，另计一次请求预算），不会关闭内网保护。

  • 表格CSV保存表格文本；复杂单元格结构在解析JSON中保留。HTML使用离线KaTeX；PDF/DOCX保留TeX源码，暂不转换为原生数学对象。

  • 删除清理题录、证据和索引并标记相关产物过期；输入文件、旧导出、备份、原始对象文件及服务商副本保留，不能称为彻底擦除。

  • 不提供后台调研/通知、团队服务、付费墙绕过或自动安装模型；宿主不调用工具时不会自主运行研究。

开发验证

uv run pytest -q
uv run ruff check src tests scripts
uv run python scripts/smoke_mcp.py
uv run python scripts/benchmark.py
uv run python scripts/probe_metadata.py

前四项使用独立合成测试库，不调用付费接口。最后一项只联网查询公开题录并保存来源状态，不上传本机论文。可用scripts/evaluate.py对人工标注证据问题计算Recall@10；人工语义支持率不能用合成测试替代。标注格式及指标边界见评估说明。

参考设计与调研、验收记录。

题录交换保留常用出版字段，原始导入文件和未映射字段可追溯；两条ACL官方题录的三格式往返已实测。复杂定制字段与不同管理器兼容性仍需针对样本验证。

直接调用TextIn API

uv run python scripts/textin_acceptance.py submit VERSION_ID --start 1 --end 2提交现有版本；poll JOB_ID只查询已有任务；extract VERSION_ID --key '全部作者（按原文顺序）'抽取字段，--table-header可重复指定表头。这些命令使用HTTP API，不通过MCP，凭据读取系统钥匙串。每次请求先落盘记录，已知任务不重复上传。

独立安装目录同时提供textin_acceptance.py，可用该目录的runtime/bin/python -I执行。用户明确授权无限预算时page_budget/request_budget支持null；未授权时默认0。

配置与数据链路

配置

用途

默认/要求

SCHOLAR_DATA_DIR

SQLite、原件、证据与导出所在的本地库

~/.local/share/scholar-library

TEXTIN_APP_ID / TEXTIN_SECRET_CODE

TextIn 解析与抽取

按需配置；本地文字层解析不需要

OPENALEX_API_KEY

OpenAlex 检索

按服务商当前要求配置

EMBEDDING_API_KEY

可选语义向量服务

非必需；使用前确认正文传输授权

项目 input_root

可读取的材料目录

建项目时显式指定

项目 policy / budgets

联网、上传、正文返回与请求/页数预算

默认拒绝未授权动作，不把旧测试授权带入新项目

flowchart LR
  User[用户授权与研究问题] --> Host[AI 宿主]
  Host --> MCP[本地 MCP 工具]
  MCP --> Store[独立 SQLite 库与原件]
  MCP --> Evidence[证据片段与引用校验]
  MCP -->|按项目授权和预算| Provider[题录检索 / TextIn / 可选向量服务]
  Evidence --> Export[研究记录与多格式导出]

AI 推理在宿主侧进行；本插件负责存储、工具执行和证据约束，不要求另外填一个通用聊天模型 Key。host_text 开启后宿主会接收正文，仍须考虑宿主自身的数据政策。

常见问题与更新

  • 服务启动后没有聊天窗口：stdio 服务在等待 MCP 客户端连接；先用 smoke_mcp.py 核对，再在宿主调用 workspace_status。

  • 找不到凭据：钥匙串和客户端所用系统账户应一致；Linux 需要可用的 keyring 后端，也可从受控启动环境注入同名变量。

  • 检索/上传被拒绝：先核对当前项目授权与预算。不要通过关闭安全检查或自动重试来绕过失败。

  • 找不到之前的记录：核对 SCHOLAR_DATA_DIR 和当前运行版本；更新源码不等于已重启宿主中的旧服务。

  • 解析成功但理解错误：先回看原页和具体摘录，按 评估说明 保存待人工核对状态。

源码方式升级：先保存本地改动，再 git pull --ff-only、uv sync --locked、重新生成 .mcp.json 并在客户端重载服务。独立安装包应安装到新目录，验证后切换配置。数据始终与源码/运行环境分开保存，重要库先备份。

目录与验证证据

src/ 是核心实现，skills/ 是 Agent 工作流，tests/ 是自动回归，scripts/ 含构建、自检和显式联网实验，docs/ 保存设计与验证边界。output/、数据目录、凭据和本机安装清单不公开。

当前公开版本复现结果见 发布验证；历史验收摘要 和 完成度审计 是带日期的开发记录，不代表读者设备、实时外部接口或全部语义质量通过。

维护、贡献与使用声明

持续更新、完善与迭代中。禁止恶意转载与滥用。 转载须保留版权和许可声明，请注明原仓库及修改内容；不得冒充作者或官方、夹带恶意代码、盗取凭据、泄露个人资料或伪造研究/学习证据。

代码按 MIT License 开源。上述反滥用声明不额外撤销 MIT 授予的合法使用、修改、转载或商用权利；第三方材料和服务不随代码一并授权。完整说明见 USE_POLICY.md、第三方声明。

欢迎通过仓库 Issues 反馈 Bug 或建议。请包含版本、系统、脱敏复现步骤、预期与实际结果；不要上传密钥或真实私密材料。提交代码前阅读 贡献指南，安全问题见 SECURITY.md。

Available Tools

38 tools
add_workA

保存题录（title必填；doi/pmid/arxiv、authors、year、journal、url等）。一致标识和标题才自动复用；冲突保留独立记录。

Inputs: metadata (required), project_id (required).

backup_libraryA

备份整个本地文献库和原件；要求其他连接已关闭，备份可能包含多个项目，不含凭据。

Inputs: no named parameters.

build_evidence_packB

构建有界证据包和关联阅读线索。默认本地关键词；semantic=true会将问题发送至项目配置的embedding服务，需要授权与已建索引。

Inputs: query (required), project_id (required), limit, semantic, +1 more.

connect_papersA

保存文献联系；支持/反对关系必须提供两端原文证据和具体条件说明。similar仅是线索。

Inputs: relation (required), version_id (required).

convert_documentB

将已有解析导出为Markdown、结构JSON和表格文本CSV；不重新上传，不承诺Word版式还原。

Inputs: version_id (required).

create_projectA

建立单人研究项目；input_root是用户明确指定的输入目录。policy须反映用户授权，默认全部关闭；预算是累计页数和请求上限。

Inputs: name (required), policy (required), question (required), input_root (required).

delete_workA
Destructive

仅在用户明确要求删除并查看最新预览后调用，使用预览digest防止影响范围变化。

Inputs: work_id (required), inventory_digest (required).

download_fulltextA

从用户选定的公开HTTPS地址下载PDF，最多100MiB；检查每次重定向，不处理账号、付费墙或登录页。

Inputs: url (required), work_id (required).

export_researchB

导出MD/JSON/CSV/BibTeX/RIS/CSL-JSON/HTML/PDF/DOCX及证据清单；拒绝过期产物。style=gb7714或apa；原全文不打包。

Inputs: project_id (required), artifact_ids (required), style.

extract_fieldsB

调用TextIn字段/表格抽取，会上传整个PDF或图片并预留全部页数；结果需复核，不成为原始证据索引。相同请求复用任务。

Inputs: keys (required), version_id (required), table_headers (required).

find_duplicate_candidatesA
Read-only

查找同标识冲突或标题相似的候选，不自动合并不同版本或附件。最多比较最近1000条，候选上限100。

Inputs: project_id (required).

get_parse_jobB

默认只读本地任务；poll=true查询已有远端任务，至少间隔3秒。结果保存并合并各批页面，不重新上传。

Inputs: job_id (required), poll.

import_documentB

本地导入PDF/DOCX/PNG/JPG/MD/TXT，保留不可变原件；不上传。每个新文件版本单独保存。

Inputs: path (required), work_id (required), label.

import_referencesA

导入授权目录内的BibTeX、RIS或CSL-JSON题录；附件须另行导入，不爬取付费数据库。

Inputs: path (required), project_id (required).

index_semantic_searchB

将最多32个原文片段发送到已配置的embedding服务并本地保存向量；重调续接，模型改变后使用新索引。

Inputs: project_id (required).

list_input_filesA
Read-only

仅列输入目录第一层的普通文件名和大小，不读内容、不递归、不上传。

Inputs: project_id (required), limit, offset.

list_recordsB
Read-only

分页找回文献、版本、任务、笔记、关系、检索和核验记录。job列表不重提；内容记录要求host_text授权。

Inputs: kind (required), project_id (required), limit, offset.

parse_documentA

按项目授权向TextIn上传原件并解析指定页范围；每批最多100页。页范围只限制处理，上传的是整个文件。相同版本和范围复用原任务，包括失败/未知提交。

Inputs: version_id (required), end_page, start_page.

parse_local_pdfA

免费离线解析PDF文字层，无上传；扫描页需TextIn OCR。公式、表格、阅读顺序须看原页复核。切换解析器会使旧引用过期。

Inputs: version_id (required).

preview_deletionA
Read-only

预览删除文献及关联索引的影响；混合研究产物标记过期，输入原件、旧导出、备份和服务商数据保留。

Inputs: work_id (required).

read_documentB
Read-only

按原文顺序分页读取当前解析片段、页序和质量信息，不调用OCR。无页码的DOCX/文本用段落定位。

Inputs: version_id (required), limit, offset.

read_evidenceA
Read-only

读取准确引用片段及版本、页序、原始坐标和识别疑点。单片段不证明完整上下文。

Inputs: evidence_id (required).

read_extractionB
Read-only

有界读取已缓存的TextIn原始抽取JSON文本；保留上游位置字段，无可靠定位的字段不得作为核验通过的证据。

Inputs: job_id (required), limit, offset.

read_pageA
Read-only

返回原始PDF页或图片的真实MCP图像，用于核对公式、图表、双栏及OCR误差。page为从1开始的PDF页序，不是印刷页码。

Inputs: page (required), version_id (required).

read_parse_resultA
Read-only

有界读取已缓存的完整xParse原始JSON，包含上游返回的表格结构、字符细节和页元数据；不上传或重提。按next_offset续接。

Inputs: job_id (required), limit, offset.

read_recordA
Read-only

分页读取已保存研究、方法评价、来源、关系或检索记录的完整JSON。先list_records找ID；按next_offset续接。

Inputs: record_id (required), limit, offset.

resolve_identifierA

解析DOI、pmid:或arxiv:标识符并保存题录；不获取全文。

Inputs: identifier (required), project_id (required).

restore_libraryA

从用户指定可信备份恢复至全新目录，校验哈希和数据库；不覆盖现有库，恢复后云服务和正文输出权限全部关闭。

Inputs: archive_path (required), new_directory (required).

resume_parse_observationB

用户解决限流后恢复已知任务的查询；不会上传或重提，下一次get_parse_job(poll=true)才联网。

Inputs: job_id (required), user_note (required), expected_revision (required).

retry_parseA

仅按用户明确重试决定调用。失败/提交未知可能已计费；本次另预留页数，不能保证上游只计费一次。先get_parse_job读取revision。

Inputs: job_id (required), user_note (required), expected_revision (required).

save_method_reviewB

保存宿主的方法评价及局限，必须关联该文献原文；这是AI评价而非已确认的来源身份或客观质量分数。

Inputs: work_id (required), rationale (required), limitations (required), evidence_ids (required), +1 more.

save_researchA

保存宿主生成的阅读卡片/回答/综述。author主张必须引原文；引用须同项目、当前解析、精确摘录。此工具仅校验引用完整性，语义支持需宿主/用户检查。产物不进入原文索引。

Inputs: title (required), claims (required), project_id (required), notes.

search_libraryB
Read-only

本地中英文关键词检索，限定可选版本和字符预算；仅召回当前原文证据，摘要和笔记不作为原始证据。

Inputs: query (required), project_id (required), limit, char_budget, +1 more.

search_literatureA

在crossref/openalex/arxiv/pubmed检索，分别报告失败及成功。保存检索式与结果，不自动纳入或下载；会消耗项目请求预算。

Inputs: query (required), sources (required), project_id (required), limit.

update_project_policyA

按用户授权修改项目服务与预算；先读取当前revision。预算不能低于已预留用量。

Inputs: policy (required), project_id (required), expected_revision (required).

update_workB

修订题录和阅读/纳入状态，保留历史；excluded必须提供理由。selection:unread/reading/included/excluded/read。

Inputs: reason (required), work_id (required), metadata (required), selection (required), +1 more.

verify_workA

联网核对DOI与标题及Crossref更新通知，保留证据和查询时间；未查到撤稿不等于可靠。

Inputs: work_id (required).

workspace_statusA
Read-only

检查安装版本、本地库、已配置凭据（不返回秘密）、项目；不发起联网请求。

Inputs: no named parameters.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Deploy Server
    One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

    TDQS

    B3.4/5.0

    Scored across 38 tools

    Disambiguation4/5

    Tools are mostly well separated by resource and action (e.g., search_literature vs search_library, parse_local_pdf vs parse_document). Some adjacent read/extract/parse-job tools (read_extraction vs read_parse_result, get_parse_job vs retry_parse vs resume_parse_observation) require careful reading, but descriptions clarify boundaries.

    Naming Consistency4/5

    All names use snake_case and nearly all follow a verb_noun or action_object pattern. workspace_status is a minor noun-only exception, but the overall naming convention is predictable and readable.

    Tool Count2/5

    38 tools is above the typical 3-15 band and exceeds the 25+ heavy threshold. The parsing, extraction, and job-management pipeline contains many granular tools that could be consolidated for easier agent selection.

    Completeness4/5

    The surface covers project setup, import, parsing, search, evidence building, export, deletion, backup/restore, and more. Minor lifecycle gaps exist (e.g., no explicit project-level delete/list beyond workspace_status), but major research workflows are well covered.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Resources

    Related MCP Connectors

    Related MCP Servers

    • surveyHelper

      rich7420
      A
      license
      Not graded
      quality
      C
      maintenance
      A local-first MCP server that analyzes research papers, maps citation graphs, and surfaces insights with verbatim-verified contradictions, all while keeping data private on your machine.
      1
      MIT

    • OpenPapers

      arjhinety
      A
      license
      B
      quality
      B
      maintenance
      Enables provenance-first scholarly retrieval, paper ingestion, and reproducible research workflows by searching academic and developer sources, extracting source-located facts and claims, and preserving evidence and provider uncertainty for MCP clients.
      37
      1
      Apache 2.0

    • academic-mcp

      longisland-icetea
      A
      license
      Not graded
      quality
      B
      maintenance
      Enables a local academic research workflow via any MCP client: literature search across Scopus and OpenAlex, citation chains, per-project research memory, paper download, and PDF-to-Markdown conversion through MinerU.
      GPL 3.0