Ookcite Mcp

Name: Ookcite Mcp
Author: TurtleTech-ehf

本地服务

ookcite.turtletech.us科研与教育22 周前更新

代码仓库访问官网

关于 Ookcite Mcp

Ookcite Mcp 是面向学术工作流的 MCP 服务，可验证 DOI、解析与格式化引文，并管理参考文献集合。它返回引文元数据，不提供 PDF 或全文。

主要功能

01验证 DOI 与 ISBN
02解析杂乱的引文文本
03批量检查与格式化参考文献
04支持 CSL 引文样式
05导入、导出与管理文献集合

适用场景

01提交论文前核对参考文献
02将粘贴的引文列表转换为 BibTeX
03按指定 CSL 样式生成书目

MCP 相关

向 MCP 客户端提供引文验证、查询、格式化和集合管理工具；也可通过标准输入输出或远程 Streamable HTTP 连接。

#citation #academic

配置

本地服务的配置在各客户端中通用，复制后粘贴到客户端的 MCP 配置文件即可。

mcp.json · 通用配置

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": [
        "-y",
        "@turtletech/ookcite-mcp"
      ],
      "env": {
        "OOKCITE_API_KEY": "<OOKCITE_API_KEY>"
      }
    }
  }
}

启动命令npx -y @turtletech/ookcite-mcp

需要配置的环境变量

OOKCITE_API_KEY密钥Optional. Raises the anonymous rate limit and enables the collection tools. Sign up at https://my.turtletech.us/signup?service=ookcite&source=ookcite_mcp

本地服务需要在你的电脑上安装运行环境（如 Node.js 18+）。各客户端的配置文件位置不同，请参考客户端文档。

安装包

npm@turtletech/ookcite-mcp0.6.5stdio

工具

还没有获取到工具列表

本地服务需要在你的电脑上运行后才能读取工具，维护者暂未提供工具列表。

详细介绍

OokCite MCP Server

让支持 MCP 的工具能够验证 DOI、格式化引文、管理参考文献集，并识别伪造的参考文献。仅返回引文元数据——不提供 PDF 或全文文章。桌面客户端可通过标准输入和输出运行。远程客户端请使用 https://ookcite-api.turtletech.us/mcp。

快速开始

一条命令即可安装和配置：

npx @turtletech/ookcite-mcp setup

此命令会自动检测受支持的 MCP 客户端，并为你写入配置。连接 OokCite 账户，即可提高速率限制并使用参考文献集工具，无需将 API 密钥放入 shell 参数或 MCP 配置中：

npx @turtletech/ookcite-mcp setup --connect

此命令会打开 TurtleTech 控制面板，创建或启用 Free 计划，将签发的密钥存储在平台凭据存储区，并仅向检测到的客户端写入凭据引用。在无头机器上使用 setup --connect --device。

仍支持使用已有 API 密钥：

npx @turtletech/ookcite-mcp setup --key YOUR_API_KEY

基本用法（每天 20 次查询）无需 API 密钥：format_citation 和较小的纯文本 import_bibliography（省略 collection，最多 8 项）。注册以了解更多。

将列表粘贴为 BibTeX

import_bibliography 接受带编号或以空行分隔的引文列表，不仅限于 .bib / .ris。粘贴少量内容时省略 collection：该工具会解析条目并返回 .bib 文本。使用密钥时，传入 collection 即可保存解析后的条目。随后，export_collection 可输出 .bib（format=bib）或 CSL 参考文献文本（format=csl 或 ieee 等样式 ID）。 npx @turtletech/ookcite-mcp setup 仍是安装程序。该服务不会获取 PDF。

更改 MCP 配置后，请重启客户端或重新加载其 MCP 服务。许多客户端不会热重载已运行的 stdio 服务的环境变量更改。

安装（其他方式）

npm（推荐）：

npm install -g @turtletech/ookcite-mcp

cargo-binstall（最快，无需 Node.js）：

cargo binstall ookcite-mcp

cargo install（从源代码安装）：

cargo install ookcite-mcp

预编译二进制文件：从 GitHub Releases 下载适用于 Linux（x86_64、aarch64）、macOS（x86_64、aarch64）和 Windows 的版本。

配置

如果你使用了 setup，就已完成。否则，请将以下内容添加到 MCP 客户端配置中：

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"]
    }
  }
}

使用 API 密钥：

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"],
      "env": {
        "OOKCITE_API_KEY": "your_key_here"
      }
    }
  }
}

如果你进行了全局安装（npm install -g 或 cargo install），可以直接使用 "command": "ookcite-mcp"，而不必使用 npx。

不将密钥放入配置文件

setup --connect 默认使用平台凭据存储。除非明确指定 --replace-credential 或 --replace-config，否则它不会替换现有的平台凭据或命名的 OokCite MCP 配置。

也可以使用通用凭据管理器。存储命令会通过标准输入接收新密钥；它不得要求密钥作为命令行参数传入。MCP 服务启动时，检索命令会通过标准输出打印密钥：

npx @turtletech/ookcite-mcp setup --connect \
  --store-command "credential-cli store ookcite" \
  --retrieve-command "credential-cli read ookcite"

如果要使用仅所有者可访问的文件，而不是凭据管理器：

npx @turtletech/ookcite-mcp setup --connect \
  --credential-file "$HOME/.config/ookcite/api-key"

该文件会以仅所有者可访问的权限创建，且永远不会被覆盖。平台、辅助命令和文件这几种形式会在客户端配置中写入如下引用：

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"],
      "env": {
        "OOKCITE_API_KEY_COMMAND": "credential-cli read ookcite"
      }
    }
  }
}

启动时，来源优先级仍为 OOKCITE_API_KEY、OOKCITE_API_KEY_COMMAND、OOKCITE_API_KEY_FILE，然后是平台凭据引用。如果这些来源均未设置，服务将以匿名模式启动。对于有意将密钥保留在客户端配置中的现有部署，仍可使用 setup --key。

凭据检索遵循两项限制：

检索时标准输入会关闭，因此无法读取 MCP JSON-RPC。
检索过程受 OOKCITE_API_KEY_TIMEOUT 限制，默认值为 10 秒；其输出绝不会复制到诊断信息中。

请查阅客户端的 MCP 文档，了解其配置文件的位置。无法使用自动设置时，请使用上文的 mcpServers.ookcite JSON，然后重启客户端或重新加载其 MCP 服务。

可选环境变量（stdio MCP，所有客户端通用）：

变量	用途
`OOKCITE_API_KEY`	提高速率限制 + 集合工具（基本查询/格式化功能可选）
`OOKCITE_API`	覆盖 API 基础 URL（默认 `https://ookcite-api.turtletech.us`）
`OOKCITE_MCP_READ_ONLY`	`1` 会彻底禁用集合变更（适用于审核 / CI 自动化）
`OOKCITE_MCP_ALLOW_MUTATE`	`0` 会拒绝变更；未设置或设为 `1` 时允许（服务端仍需要 API 密钥）
`OOKCITE_STARTUP_PROBES`	`1` 会在接受 MCP 连接前，通过 stderr 运行身份验证 + npm 更新检查（默认关闭，以加快连接速度）
`OOKCITE_API_KEY_COMMAND`	打印密钥到标准输出的命令；标准输入会关闭
`OOKCITE_API_KEY_FILE`	受所有者权限保护、首行包含密钥的文件
`OOKCITE_API_KEY_TIMEOUT`	凭据检索允许的秒数（默认 10）
`OOKCITE_CREDENTIAL_STORE`	设为 `platform` 以加载平台凭据引用
`OOKCITE_CREDENTIAL_SERVICE`	平台凭据服务名称（默认 `ookcite-mcp`）
`OOKCITE_CREDENTIAL_ACCOUNT`	平台凭据账户名称（默认 `default`）

Marketplace 插件

OokCite 有两种安装方式。

在此仓库中，添加 Marketplace TurtleTech-ehf/ookcite-mcp，然后安装 ookcite@ookcite。这会注册 ookcite Marketplace，并在 plugins/ookcite 中启用插件。该插件连接到 https://ookcite-api.turtletech.us/mcp，并添加三个技能：格式化粘贴的参考文献（/ookcite:format-bibliography）、提交前核验参考文献（/ookcite:verify-references），以及构建并导出文集（/ookcite:build-collection）。按提示登录。在匿名每日限额内，登录前也可以格式化一条引文并检查一份简短的 DOI 列表。保存文集需要使用已登录的账户。

Web、桌面和 cowork 应用使用同一地址作为目录连接器。选择登录。通过该 URL 提交连接器，并提交 plugins/ookcite 文件夹作为插件包。从 Marketplace 安装不会提交任何一项。

远程连接器不必支持动态客户端注册。该插件会发送预先注册的公共客户端 ID ookcite-remote，因此代码客户端不会调用注册端点。该客户端的发现信息会公布 S256 PKCE，且没有 registration_endpoint。受保护资源会将该客户端的 issuer 列在首位，其 resource 字段为 https://ookcite-api.turtletech.us/mcp。客户端会原样接受目录回调，也接受 localhost 和 127.0.0.1 上任意端口的环回重定向。访问令牌必须满足 exp - iat <= 3600，否则资源服务器会拒绝它们。

远程 MCP

无需安装任何内容，即可在聊天产品中使用 OokCite。添加此地址，选择登录，并在提示时批准登录：

https://ookcite-api.turtletech.us/mcp

聊天产品随后会发送一个短期访问令牌：

Authorization: Bearer <access token>

查询会计入该已登录账户。粘贴的 API 密钥会被拒绝。传输方式为无状态 Streamable HTTP：一次 POST，JSON 输入和 JSON 输出。选择 Streamable HTTP 和登录（OAuth）。不要选择旧版 SSE 传输、API 密钥或“无身份验证”。

将 ookcite-api.turtletech.us 列入允许名单后，eduGenAI Chat：

字段	值
名称	OokCite
描述	核验 DOI 和 ISBN、解析格式混乱的引文，并按 CSL 样式格式化参考文献条目。仅返回引文元数据，不提供 PDF 或全文。
URL	`https://ookcite-api.turtletech.us/mcp`
传输方式	Streamable HTTP
身份验证	OAuth

ookcite-mcp serve 会运行你自己的副本。通过子进程启动的桌面客户端仍使用标准输入和输出。

变量	用途
`OOKCITE_API`	OokCite API 基础 URL（默认值为 `https://ookcite-api.turtletech.us`）
`OOKCITE_MCP_HTTP_AUTH`	登录时使用 `oauth`，运行自己的副本时使用 `bearer`，或使用 `none`
`OOKCITE_MCP_OIDC_ISSUER`	登录 issuer。身份验证为 `oauth` 时必填
`OOKCITE_MCP_OIDC_AUDIENCE`	令牌受众。身份验证为 `oauth` 时必填
`OOKCITE_MCP_OIDC_SCOPE`	必需范围（默认值为 `openid`）
`OOKCITE_MCP_PATH`	MCP 路径（默认值为 `/mcp`）
`OOKCITE_MCP_ALLOWED_HOSTS`	额外的 `Host` 名称，以逗号分隔。始终允许环回地址
`OOKCITE_MCP_ALLOWED_ORIGINS`	可调用该端点的浏览器 `Origin` 值。允许缺少 Origin 的请求

MCP 使用提示

优先使用批量工具（verify_references、batch_format、batch_add_to_collection、 import_bibliography），而非多次调用单条引文工具。
修改文集需要已登录账户，或者在你自行运行的副本中使用 OOKCITE_API_KEY。破坏性工具（delete_collection、remove_from_collection、unshare_collection）带有注释，供支持 MCP 工具提示的客户端使用。
在 MCP 路径上，服务器仅将诊断信息写入 stderr；stdout 专用于 JSON-RPC。

工具

查询与验证

工具	用途
`validate_doi`	检查 DOI 是否存在（防止产生幻觉）
`lookup_isbn`	通过 ISBN 查找图书
`reverse_lookup`	根据杂乱的引文文本查找论文；返回原始查询、置信度和标题
`batch_resolve`	在一次请求中解析多条引文字符串（最多 50 条）
`enhanced_search`	按作者、类别和引文属性搜索语料库
`health_check`	检查 API 的可用性和运行状况

格式化

工具	用途
`format_citation`	按 2900 多种 CSL 样式格式化 DOI（单条引文无需 API 密钥）
`verify_references`	批量检查 DOI，以及随附的任何书目信息主张
`batch_format`	一次格式化多条引文
`search_styles`	按名称查找 CSL 样式 ID
`list_styles`	分页浏览完整的 CSL 样式列表
`group_cite`	生成分组的文内标注（例如 [1-3]）

账户

工具	用途
`usage`	当前生效的套餐，以及每日（和每月）剩余查询次数

ORCID

工具	用途
`orcid_search`	按姓名、所属机构或 ORCID ID 查找 ORCID 个人资料
`orcid_profile`	按 ID 获取一个 ORCID 个人资料
`ingest_orcid`	为 ORCID 个人资料中的出版物编制索引，使其可供搜索

集合（需要登录）

集合是登录后才能使用的功能。托管服务使用登录账号。自行运行的副本使用 OOKCITE_API_KEY。例外情况是：较小的纯文本 import_bibliography 不指定 collection 时，会在匿名配额内返回 .bib。

工具	用途
`list_collections`	列出已保存的引文集合
`add_to_collection`	添加引文（通过 DOI 或自由文本）
`batch_add_to_collection`	一次添加多条引文
`import_bibliography`	导入 BibTeX、RIS 或粘贴的纯文本列表
`export_collection`	将集合导出为 BibTeX 或 CSL 文本
`search_collection`	在集合中搜索；每条匹配结果均返回 `entry_id`
`check_duplicates`	检查重复项；匹配结果会返回 `entry_id`
`delete_collection`	删除集合
`update_collection`	更新名称、描述或样式
`remove_from_collection`	按 `entry_id`、裸 DOI 或 `doi:10.x/y` 移除条目
`update_entry_metadata`	更正已保存条目的标题、作者、年份、DOI 等
`merge_entries`	将同一集合中的两个条目合并为一个
`update_tags`	设置集合标签
`reorder_collection`	重新排列条目

典型工作流：

将带编号的引文列表粘贴到 import_bibliography（列表较小时省略 collection），并保留返回的 .bib
或将 references.bib / library.bib 纳入版本控制，再将该文件导入集合
修改时使用 search_collection、check_duplicates 和 export_collection（bib 或 csl）
将集合用作审计和导出辅助，而不要把它当作参考文献的唯一副本

**本地覆盖：**API 尚未存储 update_entry_metadata 发送的所有字段，因此，在自行运行的副本（stdio，或使用 auth=none 的 serve）中，每次编辑也会保存在 $XDG_DATA_HOME/ookcite/overrides/<collection>.json，并在 export_collection 时应用。已登录的 HTTP 服务不会保存本地覆盖。 eid_as=pages 会将文章编号放在 elsarticle-num 输出的位置。请参阅 docs/local-overrides.md。

**移除单个条目：**调用 search_collection（或 check_duplicates）查看每条匹配结果，其格式为 entry_id: …（如果存储的 ID 不透明，还会显示 aliases: doi:…）。将该 entry_id 传给 remove_from_collection，或传入论文的裸 DOI / doi:10.x/y——服务会在调用 API 前在本地解析别名。

共享与集合操作

工具	用途
`share_collection`	创建可分享的链接
`unshare_collection`	撤销共享
`view_shared`	按令牌查看已共享的集合
`merge_collections`	合并多个集合
`batch_move_entries`	在集合之间移动条目

拥有集合的登录账号可以使用共享功能。免费账号可在每日配额内导入和批量添加。合并和批量移动需要 Academic 或 Business 套餐。

实用工具

工具	用途
`generate_citation_keys`	为 DOI 列表生成更优的 Better BibTeX 风格键
`expand_journal`	将期刊缩写展开为全称
`normalize_bibliography`	将 BibTeX 或 RIS 重新渲染为规范的 BibTeX

这三项功能需要 Academic 或 Business 套餐。

计划与定价

套餐	价格	每日查询次数	每月 API 调用次数	集合	每个集合的条目数
匿名	免费	20	--	0	--
免费	免费	60	--	4	200
学术	EUR 4/mo	20,000	10,000	10	1,000
商业	EUR 10/mo	20,000	40,000	20	4,000

如果 API 已有集合元数据，则可以在不消耗配额的情况下重新查询。如果检索时必须重新解析论文，则可能会计入当前套餐的配额。学术套餐的付费结账面向经认可机构的学生、研究人员和教育工作者；已验证的 ORCID 也可以使已登录的账户获得学术套餐的限制。

防止幻觉

将以下内容添加到系统提示词中：

引用任何论文之前，请使用 validate_doi 确认该文献确实存在。如果验证失败，请勿加入该引用。

对于修订工作流，请添加：

将项目参考文献保存在受版本控制的本地 .bib 文件中。使用 OokCite 集合进行验证、去重和导出。

工作原理

MCP 服务连接到公共的 OokCite API，用于查找和格式化引文。它是 OokCite REST API 的轻量级 MCP 封装，不使用本地数据库，也没有繁重的依赖项。

注册免费账户（每天可查询 60 次），或升级到学术套餐（EUR 4/mo）或商业套餐（EUR 10/mo），以获得更高的每月 API 调用限额、更大的集合、付费实用工具、合并和批量移动功能。

源码结构

该 crate 是一个围绕 OokCite 公共 REST API 的轻量 MCP（stdio）封装。本地没有引文数据库；所有状态都存储在 API 上，docs/local-overrides.md 中所述的每个集合的元数据覆盖项除外。

路径	作用
`src/main.rs`	二进制入口：`--version`、`setup`、启动 MCP 服务
`src/cli.rs`	启动探测（通过 `/api/v1/me` 验证 `OOKCITE_API_KEY`、检查更新）
`src/setup.rs`	`ookcite-mcp setup` / `npx add-mcp` 客户端配置安装程序
`src/server.rs`	`Server` + `#[tool_router]` MCP 工具处理程序（底部还包含单元测试）
`src/tool_args.rs`	工具参数结构体（`serde` + `schemars`）
`src/constants.rs`	API 基础 URL、软件包版本、反向查找置信度阈值
`src/http_error.rs`	面向客户端的字符串所用的 `error_detail` 和 HTTP 状态分类
`src/collection_entries.rs`	集合条目 ID、裸 DOI / `doi:` 别名解析、搜索行
`src/plaintext.rs`	粘贴列表拆分和本地 `.bib` 渲染
`src/bib_export.rs`	根据提供方记录、已存储字段和文本清理生成集合 BibTeX
`src/overrides.rs`	导出时应用的本地每集合元数据覆盖项
`src/resolve_helpers.rs`	反向查找和自由文本解析负载辅助函数
`src/endpoints.rs`	端点注册表（`lib` crate 接口）；经过契约测试
`src/lib.rs`	库根模块（仅导出 `endpoints`）
`tests/api_contract.rs`	解密 `contract/openapi.json.age`；断言每个端点都存在
`contract/`	使用 Age 加密的 OpenAPI 快照 + `regen.sh`
`npm/`	`@turtletech/ookcite-mcp` 安装程序/封装（下载发布版二进制文件）
`demo/`	Asciinema 录制脚本
marketplace catalog	列出来自 `./plugins/ookcite` 的 `ookcite`
`plugins/ookcite/`	插件清单、托管 MCP URL、三个技能
`scripts/set-version.sh`	Cocogitto 预升级钩子：软件包、注册表和插件版本

集合 / 条目 ID： search_collection 和 check_duplicates 会输出 entry_id: … 行。remove_from_collection 接受该 ID、裸 DOI 或 doi:10.x/y（在发起 DELETE 调用前于 collection_entries 中进行本地解析）。

发布： 标签 v* 会运行 .github/workflows/release.yml（多架构 GitHub Release 资产、crates.io、npm）。版本升级使用 cocogitto （cog.toml + scripts/set-version.sh）。

为何 server.rs 这么大： rmcp 的 #[tool_router] / #[tool] 宏要求处理程序位于同一个 impl Server 中。若不绕过宏，进一步拆分文件对用户的价值不大；与其费力对付宏，不如先拆出测试，或添加小型辅助函数（resolve_many、共享的 Me 类型）。

贡献 / 本地检查

cargo test --bin ookcite-mcp          # unit tests (no contract key needed)
cargo build --release
./target/release/ookcite-mcp --version

# Contract tests (optional locally; required in CI with secret):
export OOKCITE_CONTRACT_KEY="value-from-your-credential-manager"
cargo test --test api_contract

实时 MCP 冒烟测试（可选；需要 OOKCITE_API_KEY）：在临时集合中使用裸 DOI 添加、搜索和移除条目，然后运行 delete_collection。

文档

许可证

MIT。请参阅 LICENSE。

支持 Markdown

登录后评论

第一次接触 MCP？

从协议是什么，到在客户端里装上第一个服务，这几条回答覆盖了大多数入门问题。

阅读入门指南

一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。