Academic Research Plugin

本仓库是一个可复用的开源参考实现，用于私有/开发者模式的学术研究插件（Academic Research Plugin）。它通过 stdio MCP 服务器和 Codex 技能提供可追踪的学术检索与证据工作流。

这不是公开的 OpenAI 插件目录（Plugin Directory）部署。开发者必须自行创建 OpenAI Platform 隧道、运行时凭据、ChatGPT 开发者模式 MCP 连接以及本地 .app.json 配置。这些值有意不包含在本仓库中。

V0.1.0 状态

已发布的 V0.1.0 插件功能已冻结。该实现保留了设计文档中的提供商契约、模式、检索与排序规则、证据等级、溯源要求、安全边界、MCP 协议行为以及技能工作流。

经运营方批准的 V0.1.0 修订将 ScholarRead 头对头比较改为可选并推迟执行。发布验证仍为非比较性，涵盖单元、提供商契约、集成、安全、确定性回放、MCP 协议以及技能激活/输出，同时包含独立的正确性、标识符、证据、溯源、降级和安全保障。参见 docs/SPEC_AMENDMENT_V0.1.0.md。

Related MCP server: Academic Paper MCP HTTP/SSE Server

插件功能

• 使用确定性请求与融合规则搜索受支持的学术提供商。

• 保守地规范化和解析学术标识符，不虚构标识符，也不静默进行模糊合并。

• 检索有界且受支持的全文，并明确报告证据等级以及不可用/不支持的内容。

• 遍历引文关系，并保留溯源结果。

• 通过构建后的服务器 dist/src/server.js 暴露已冻结的 MCP 工具。

• 激活基于证据的文献综述技能，用于可审计的研究工作流。

仓库内容

• ACADEMIC_RESEARCH_PLUGIN_DESIGN.md — 规范性实现规范。

• SOURCE_AUDIT.md — 历史验证证据；它不是替代性的设计权威。

• src/ — TypeScript MCP 服务器、提供商、检索、全文、溯源和安全代码。

• skills/ — 打包的学术文献综述技能。

• .codex-plugin/plugin.json — 已冻结的 V0.1.0 插件清单。

• .app.json.example — 安全的本地配置模板。真正的 .app.json 会被忽略。

• docs/PUBLIC_SETUP.md — 独立复现指南。

• tests/ — 单元、契约、安全、集成和基准测试夹具。

官方 OpenAI tunnel-client 的源代码和二进制文件未随仓库提供。当你需要私有 MCP 连接时，请从当前的 OpenAI Platform 隧道设置或官方 openai/tunnel-client 仓库获取。

前提条件

• Git。

• 按设计固定的 Node.js 24.19.0 和 npm 11.17.0。

• 一个有权访问 ChatGPT 开发者模式并具备相关 Platform 隧道权限（用于私有测试）的 OpenAI 账户。

• 仅为你打算使用的提供商准备凭据。确定性测试使用夹具，不需要真实的提供商密钥。

• 官方 tunnel-client 仅用于私有 ChatGPT/Codex MCP 连接；本地单元或契约测试不需要它。

OpenAI 当前文档指出，Secure MCP Tunnel 可保持 MCP 服务器私有，使用出站连接，并支持开发者模式测试，但不支持公开插件提交。Secure MCP Tunnel

全新克隆安装

从干净的克隆开始：

git clone <your-repository-url>
cd academic-research-plugin
npm ci
cp .env.example .env

在 Windows PowerShell 中，请使用 Copy-Item .env.example .env 而不是 cp。将 .env 保留在本地；它会被 Git 忽略。

环境变量

.env.example 仅包含变量名。只设置你启用的提供商和本地集成所需的值：

该应用不需要通用的公共 HTTP 监听器。MCP 服务器仅支持 stdio，隧道客户端将请求转发到确切的构建产物 dist/src/server.js。

构建与测试

设计固定了运行时和依赖版本。在仓库根目录运行适用的检查：

npm run verify:env
npm run verify:contracts
npm run build
npm run test:unit
npm run test:contract
npm run test:security
npm run test:integration
npm run verify:plugin

设计所需的构建产物是：

dist/src/server.js

npm run benchmark 是发布后的可选评估。当它需要推迟的 ScholarRead 比较时，不得将其视为 V0.1.0 发布门禁；不要合成比较结果。

创建私有 Secure MCP Tunnel

1. 在 OpenAI Platform 隧道设置 中，创建或选择一个隧道，并复制其自身的 tunnel_id。

2. 创建或获取 tunnel-client 所需的运行时 API 密钥。通过官方密钥/环境机制将其作为 CONTROL_PLANE_API_KEY 存储在本地。切勿将其粘贴到 issue、聊天、仓库文件、.env.example、.app.json 或会被记录到历史中的命令中。

3. 构建本仓库并确认 dist/src/server.js 存在。

4. 按照官方 Secure MCP Tunnel 指南下载/构建当前官方 tunnel-client。不要将二进制文件或源代码复制到本仓库中用于发布。

5. 配置官方命名的 stdio 配置文件。下面的命令和目标遵循设计要求的路径；仅将占位符替换为你机器上创建的值：

export CONTROL_PLANE_API_KEY="<set-locally-through-your-secret-mechanism>"

tunnel-client init \
  --sample sample_mcp_stdio_local \
  --profile academic-research-local \
  --tunnel-id "<YOUR_TUNNEL_ID>" \
  --mcp-command "node /ABSOLUTE/PATH/TO/academic-research-plugin/dist/src/server.js"

tunnel-client doctor --profile academic-research-local --explain
tunnel-client run --profile academic-research-local

在 Windows PowerShell 中，使用可执行文件的 PowerShell 命令行语法和相同的参数。在创建或测试 ChatGPT 连接时保持该配置文件运行。官方指南记录了本地健康检查端点 /healthz、/readyz、/metrics 和 /ui；在测试前确认 healthy 和 ready 状态。

对于长期部署，请在适合你主机的服务/监督机制下运行此官方配置文件，并保持相同的仅出站边界。不要用临时的公共监听器替代官方隧道流程。

注册你自己的 ChatGPT 开发者模式连接

OpenAI 开发者模式工作流与 Platform 隧道权限是分开的。当前文档记录的流程是：

1. 在 ChatGPT 中，打开设置 → 安全与登录，如果你的账户/工作区策略允许，请启用开发者模式。

2. 打开 ChatGPT 插件/开发者模式连接界面，然后选择 + 按钮。

3. 输入你自己的面向用户的名称和描述。

4. 在连接下，选择隧道，然后选择你可用的隧道或输入你自己的 tunnel_id。

5. 创建连接并查看发现的工具和元数据。

这是私有/开发者模式连接，不是向公共插件目录提交。官方连接指南记录了相同的开发者模式和隧道步骤：连接并测试你的插件。

设计的打包契约要求连接工作流返回的技术 ID 以 plugin_asdk_app 开头。请复制你自己的连接/打包工作流显示的确切 ID；切勿自行编造。然后创建被忽略的本地配置文件：

cp .app.json.example .app.json

仅将 plugin_asdk_app_REPLACE_WITH_YOUR_REGISTERED_TECHNICAL_ID 替换为你自己注册的技术 ID。在本地验证它，而不要将其暴露在 Git 中：

node scripts/verify-plugin.mjs --expected-app-id "<YOUR_PLUGIN_ASDK_APP_ID>"

公共克隆在没有 .app.json 的情况下以模板模式通过 npm run verify:plugin。提供 --expected-app-id 需要有真实的本地 .app.json。.app.json 文件会被忽略，且必须保留在用户本地。

在私有/开发者模式下使用

在隧道报告 healthy/ready 且 ChatGPT 已发现 MCP 工具后，开始新对话，从工具菜单添加私有连接，并运行具有代表性的学术请求。对照设计检查提供商降级、证据等级、溯源、标识符行为、不支持内容报告以及工具结果。

对于本地 Codex 或其他 stdio MCP 客户端，请使用确切的构建命令：

node /ABSOLUTE/PATH/TO/academic-research-plugin/dist/src/server.js

集成测试覆盖 MCP 初始化和已冻结的工具列表。不要将此 stdio 服务器暴露为可独立访问的公共 HTTP 服务。

公开发布边界

本仓库旨在作为开源 GitHub 参考/模板发布。在 GitHub 上发布它并不会发布 OpenAI 应用、注册公共插件、创建隧道或授予任何其他人访问权限。每位开发者都必须创建并保护自己的 OpenAI 资源，并使用私有/开发者模式。

在发布之前，请运行 docs/PUBLIC_SETUP.md 中描述的仓库密钥和历史检查，审查完整的 diff，并确认没有跟踪任何本地 .app.json、.env、隧道材料、生成的构建输出或特定于机器的文件。

参考

• 规范性仓库规范：ACADEMIC_RESEARCH_PLUGIN_DESIGN.md。

• 历史契约证据：SOURCE_AUDIT.md。

• OpenAI Secure MCP Tunnel：https://developers.openai.com/api/docs/guides/secure-mcp-tunnels。

• OpenAI 插件连接/测试：https://developers.openai.com/plugins/deploy/connect-chatgpt。

• 官方 tunnel-client 源代码：https://github.com/openai/tunnel-client。