Academic Research Plugin

This repository is a reusable, open-source reference implementation for a private/developer-mode Academic Research Plugin. It provides a traceable scholarly retrieval and evidence workflow through a stdio MCP server and a Codex skill.

This is not a public OpenAI Plugin Directory deployment. A developer must create their own OpenAI Platform tunnel, runtime credential, ChatGPT developer-mode MCP connection, and local .app.json wiring. Those values are intentionally absent from this repository.

V0.1.0 status

The released V0.1.0 plugin functionality is frozen. The implementation preserves the design document's provider contracts, schemas, retrieval and ranking rules, evidence levels, provenance requirements, security boundaries, MCP protocol behavior, and skill workflow.

The operator-approved V0.1.0 amendment makes the ScholarRead head-to-head comparison optional and deferred. Release validation remains non-comparative and includes unit, provider-contract, integration, security, deterministic replay, MCP protocol, and skill activation/output coverage, together with the standalone correctness, identifier, evidence, provenance, degradation, and security safeguards. See docs/SPEC_AMENDMENT_V0.1.0.md.

What the plugin does

• Searches supported scholarly providers using deterministic request and fusion rules.
• Conservatively canonicalizes and resolves scholarly identifiers without fabricating identifiers or silently making fuzzy merges.
• Retrieves bounded, supported full text and reports evidence level and unavailable/unsupported content explicitly.
• Traverses citation relationships with provenance-preserving results.
• Exposes the frozen MCP tools through the built server at dist/src/server.js.
• Activates the evidence-grounded literature-review skill for auditable research workflows.

Repository contents

• ACADEMIC_RESEARCH_PLUGIN_DESIGN.md — normative implementation specification.
• SOURCE_AUDIT.md — historical verification evidence; it is not an alternate design authority.
• src/ — TypeScript MCP server, providers, retrieval, full-text, provenance, and security code.
• skills/ — the packaged academic literature-review skill.
• .codex-plugin/plugin.json — frozen V0.1.0 plugin manifest.
• .app.json.example — safe local wiring template. The real .app.json is ignored.
• docs/PUBLIC_SETUP.md — independent replication walkthrough.
• tests/ — unit, contract, security, integration, and benchmark fixtures.

The official OpenAI tunnel-client source and binary are not vendored. Obtain them from the current OpenAI Platform tunnel settings or the official openai/tunnel-client repository when you need a private MCP connection.

Prerequisites

• Git.
• Node.js 24.19.0 and npm 11.17.0, as pinned by the design.
• An OpenAI account with access to ChatGPT developer mode and the relevant Platform tunnel permissions for private testing.
• Provider credentials only for the providers you intend to use. The deterministic tests use fixtures and do not require live provider keys.
• The official tunnel-client only for private ChatGPT/Codex MCP connectivity; it is not needed for local unit or contract tests.

OpenAI's current documentation states that Secure MCP Tunnel keeps the MCP server private, uses an outbound connection, and supports developer-mode testing but not public plugin submission. Secure MCP Tunnel

Fresh-clone installation

From a clean clone:

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

On Windows PowerShell, use Copy-Item .env.example .env instead of cp. Keep .env local; it is ignored by Git.

Environment variables

.env.example contains names only. Set only the values needed for the providers and local integrations you enable:

Variable	Purpose
OPENALEX_API_KEY	Optional OpenAlex credential.
SEMANTIC_SCHOLAR_API_KEY	Optional Semantic Scholar credential.
CROSSREF_MAILTO	Optional contact address for Crossref requests.
ZOTERO_ENABLED	Set to true only when the design-prescribed local Zotero API is available; default is false.
OPENALEX_MAX_CONTENT_REQUESTS_PER_DAY	The bounded OpenAlex content-request limit.
CONTROL_PLANE_API_KEY	Secure MCP Tunnel runtime credential. Keep it in the official local secret/environment mechanism used by tunnel-client; do not add it to .env, tracked files, shell history, or chat.

The application does not require a generic public HTTP listener. The MCP server is stdio-only, and the tunnel client forwards requests to the exact built artifact dist/src/server.js.

Build and test

The design pins the runtime and dependency versions. Run the applicable checks from the repository root:

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

The build artifact required by the design is:

dist/src/server.js

npm run benchmark is optional post-release evaluation. It must not be treated as a V0.1.0 release gate when it requires the deferred ScholarRead comparison; do not synthesize comparison results.

Create a private Secure MCP Tunnel

1. In OpenAI Platform tunnel settings, create or select a tunnel and copy its own tunnel_id.
2. Create or obtain the runtime API key required by tunnel-client. Store it locally through the official secret/environment mechanism as CONTROL_PLANE_API_KEY. Never paste it into an issue, chat, repository file, .env.example, .app.json, or a command that will be recorded in history.
3. Build this repository and verify that dist/src/server.js exists.
4. Download/build the current official tunnel-client following the official Secure MCP Tunnel guide. Do not copy the binary or source into this repository for publication.
5. Configure the official named stdio profile. The command and target below follow the design's required path; replace only the placeholders with values created on your machine:

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

On Windows PowerShell, use the executable's PowerShell command-line syntax and the same arguments. Keep the profile running while creating or testing the ChatGPT connection. The official guide documents the local health surfaces /healthz, /readyz, /metrics, and /ui; confirm healthy and ready status before testing.

For a long-lived deployment, run this official profile under the service/supervisor mechanism appropriate to your host and preserve the same outbound-only boundary. Do not replace the official tunnel flow with an ad-hoc public listener.

Register your own ChatGPT developer-mode connection

The OpenAI developer-mode workflow is separate from the Platform tunnel permission. The current documented flow is:

1. In ChatGPT, open Settings → Security and login and enable Developer mode if your account/workspace policy allows it.
2. Open the ChatGPT Plugins/developer-mode connection surface and select the + button.
3. Enter your own user-facing name and description.
4. Under Connection, choose Tunnel, then select your own available tunnel or enter your own tunnel_id.
5. Create the connection and review the discovered tools and metadata.

This is a private/developer-mode connection, not a submission to the public Plugin Directory. The official connection guide documents the same developer-mode and Tunnel steps: Connect and test your plugin.

The design's packaging contract requires the technical ID returned by the connection workflow to begin with plugin_asdk_app. Copy the exact ID shown by your own connection/packaging workflow; never invent one. Then create the ignored local wiring file:

cp .app.json.example .app.json

Replace only plugin_asdk_app_REPLACE_WITH_YOUR_REGISTERED_TECHNICAL_ID with your own registered technical ID. Validate it locally without exposing it in Git:

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

The public clone passes npm run verify:plugin in template mode without .app.json. Supplying --expected-app-id intentionally requires the real local .app.json. The .app.json file is ignored and must remain user-local.

Use in private/developer mode

After the tunnel reports healthy/ready and ChatGPT has discovered the MCP tools, start a new conversation, add the private connection from the tools menu, and run representative scholarly requests. Check provider degradation, evidence levels, provenance, identifier behavior, unsupported-content reporting, and tool results against the design.

For local Codex or another stdio MCP client, use the exact built command:

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

The integration test exercises MCP initialization and the frozen tool listing. Do not expose this stdio server as an independently reachable public HTTP service.

Public-release boundary

This repository is intended to be published as an open-source GitHub reference/template. Publishing it on GitHub does not publish an OpenAI app, register a public plugin, create a tunnel, or grant access to anyone else. Each developer must create and protect their own OpenAI resources and use private/developer mode.

Before publishing, run the repository's secret and history checks described in docs/PUBLIC_SETUP.md, review the complete diff, and confirm that no local .app.json, .env, tunnel material, generated build output, or machine-specific files are tracked.

References

• Normative repository specification: ACADEMIC_RESEARCH_PLUGIN_DESIGN.md.
• Historical contract evidence: SOURCE_AUDIT.md.
• OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels.
• OpenAI plugin connection/testing: https://developers.openai.com/plugins/deploy/connect-chatgpt.
• Official tunnel-client source: https://github.com/openai/tunnel-client.