학술 연구 플러그인

이 저장소는 비공개/개발자 모드용 학술 연구 플러그인(Academic Research Plugin)의 재사용 가능한 오픈소스 참조 구현체입니다. stdio MCP 서버와 Codex 스킬을 통해 추적 가능한 학술 검색 및 증거 워크플로우를 제공합니다.

이것은 공개 OpenAI 플러그인 디렉토리 배포가 아닙니다. 개발자는 자신만의 OpenAI Platform 터널, 런타임 자격 증명, ChatGPT 개발자 모드 MCP 연결, 로컬 .app.json 배선을 직접 생성해야 합니다. 해당 값들은 의도적으로 이 저장소에 포함되어 있지 않습니다.

V0.1.0 상태

릴리스된 V0.1.0 플러그인 기능은 고정(frozen)되어 있습니다. 구현은 설계 문서의 공급자 계약, 스키마, 검색 및 순위 규칙, 증거 수준, 출처(provenance) 요구 사항, 보안 경계, MCP 프로토콜 동작, 스킬 워크플로우를 보존합니다.

운영자 승인 V0.1.0 수정안은 ScholarRead 직접 비교(head-to-head comparison)를 선택 사항으로 만들고 연기합니다. 릴리스 검증은 비비교(non-comparative) 방식으로 유지되며, 단위 테스트, 공급자 계약, 통합, 보안, 결정적 재생(deterministic replay), MCP 프로토콜, 스킬 활성화/출력 범위와 함께 독립형 정확성, 식별자, 증거, 출처, 성능 저하, 보안 보호 장치를 포함합니다. docs/SPEC_AMENDMENT_V0.1.0.md를 참조하세요.

Related MCP server: Academic Paper MCP HTTP/SSE Server

플러그인의 기능

• 결정적 요청 및 융합 규칙을 사용하여 지원되는 학술 공급자를 검색합니다.

• 식별자를 조작하거나 조용히 퍼지 병합(fuzzy merge)하지 않고 학술 식별자를 보수적으로 정규화하고 해석합니다.

• 제한된 범위의 지원되는 전문(full text)을 검색하고 증거 수준과 사용 불가/미지원 콘텐츠를 명시적으로 보고합니다.

• 출처를 보존하는 결과로 인용 관계를 탐색합니다.

• 빌드된 서버 dist/src/server.js를 통해 고정된 MCP 도구를 노출합니다.

• 감사 가능한 연구 워크플로우를 위한 증거 기반 문헌 검토 스킬을 활성화합니다.

저장소 구성

• ACADEMIC_RESEARCH_PLUGIN_DESIGN.md — 규범적 구현 명세서.

• SOURCE_AUDIT.md — 과거 검증 증거; 대체 설계 권위가 아닙니다.

• src/ — TypeScript MCP 서버, 공급자, 검색, 전문(full-text), 출처, 보안 코드.

• 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에서는 cp 대신 Copy-Item .env.example .env를 사용하세요. .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로 로컬에 저장하세요. 이슈, 채팅, 저장소 파일, .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.