Complemento de investigación académica

Este repositorio es una implementación de referencia reutilizable y de código abierto para un complemento de investigación académica en modo privado/desarrollador. Proporciona un flujo de trabajo de recuperación académica y evidencia trazable a través de un servidor MCP stdio y una habilidad de Codex.

Esta no es una implementación pública del Directorio de Complementos de OpenAI. Un desarrollador debe crear su propio túnel de la Plataforma OpenAI, credencial de tiempo de ejecución, conexión MCP en modo desarrollador de ChatGPT y cableado local .app.json. Esos valores están intencionalmente ausentes de este repositorio.

Estado de V0.1.0

La funcionalidad del complemento V0.1.0 publicada está congelada. La implementación conserva los contratos de proveedores, esquemas, reglas de recuperación y clasificación, niveles de evidencia, requisitos de procedencia, límites de seguridad, comportamiento del protocolo MCP y flujo de trabajo de la habilidad del documento de diseño.

La enmienda V0.1.0 aprobada por el operador hace que la comparación directa de ScholarRead sea opcional y diferida. La validación de la versión sigue siendo no comparativa e incluye cobertura de pruebas unitarias, de contrato de proveedores, de integración, de seguridad, de reproducción determinista, de protocolo MCP y de activación/salida de la habilidad, junto con las salvaguardas independientes de corrección, identificadores, evidencia, procedencia, degradación y seguridad. Consulte docs/SPEC_AMENDMENT_V0.1.0.md.

Related MCP server: Academic Paper MCP HTTP/SSE Server

Qué hace el complemento

• Busca en proveedores académicos compatibles mediante reglas deterministas de solicitud y fusión.

• Canoniza y resuelve identificadores académicos de forma conservadora sin inventar identificadores ni fusionar difusamente en silencio.

• Recupera texto completo acotado y compatible e informa explícitamente del nivel de evidencia y del contenido no disponible/no compatible.

• Recorre las relaciones de citas con resultados que preservan la procedencia.

• Expone las herramientas MCP congeladas a través del servidor integrado en dist/src/server.js.

• Activa la habilidad de revisión de literatura fundamentada en evidencia para flujos de trabajo de investigación auditables.

Contenido del repositorio

• ACADEMIC_RESEARCH_PLUGIN_DESIGN.md — especificación de implementación normativa.

• SOURCE_AUDIT.md — evidencia de verificación histórica; no es una autoridad de diseño alternativa.

• src/ — servidor MCP TypeScript, proveedores, recuperación, texto completo, procedencia y código de seguridad.

• skills/ — la habilidad empaquetada de revisión de literatura académica.

• .codex-plugin/plugin.json — manifiesto de complemento V0.1.0 congelado.

• .app.json.example — plantilla segura de cableado local. El .app.json real se ignora.

• docs/PUBLIC_SETUP.md — recorrido de replicación independiente.

• tests/ — fixtures de pruebas unitarias, de contrato, de seguridad, de integración y de referencia.

El código fuente y el binario oficiales de tunnel-client de OpenAI no se incluyen. Obténgalos de la configuración actual del túnel de la Plataforma OpenAI o del repositorio oficial openai/tunnel-client cuando necesite una conexión MCP privada.

Requisitos previos

• Git.

• Node.js 24.19.0 y npm 11.17.0, según lo fijado por el diseño.

• Una cuenta de OpenAI con acceso al modo desarrollador de ChatGPT y los permisos relevantes del túnel de la Plataforma para pruebas privadas.

• Credenciales de proveedor solo para los proveedores que tenga intención de usar. Las pruebas deterministas usan fixtures y no requieren claves de proveedor en vivo.

• El tunnel-client oficial solo para la conectividad MCP privada de ChatGPT/Codex; no es necesario para las pruebas unitarias o de contrato locales.

La documentación actual de OpenAI indica que el Túnel MCP Seguro mantiene el servidor MCP privado, usa una conexión saliente y admite pruebas en modo desarrollador, pero no el envío público de complementos. Túnel MCP seguro

Instalación desde un clon nuevo

Desde un clon limpio:

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

En Windows PowerShell, use Copy-Item .env.example .env en lugar de cp. Mantenga .env local; Git lo ignora.

Variables de entorno

.env.example contiene solo nombres. Establezca solo los valores necesarios para los proveedores e integraciones locales que habilite:

La aplicación no requiere un listener HTTP público genérico. El servidor MCP es solo stdio, y el cliente del túnel reenvía las solicitudes al artefacto integrado exacto dist/src/server.js.

Compilación y pruebas

El diseño fija las versiones de tiempo de ejecución y de dependencias. Ejecute las comprobaciones aplicables desde la raíz del repositorio:

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

El artefacto de compilación requerido por el diseño es:

dist/src/server.js

npm run benchmark es una evaluación opcional posterior a la publicación. No debe tratarse como una puerta de publicación de V0.1.0 cuando requiera la comparación de ScholarRead diferida; no sintetice resultados de comparación.

Cree un túnel MCP seguro privado

1. En la configuración del túnel de la Plataforma OpenAI, cree o seleccione un túnel y copie su propio tunnel_id.

2. Cree u obtenga la clave de API de tiempo de ejecución requerida por tunnel-client. Almacénela localmente mediante el mecanismo oficial de secretos/entorno como CONTROL_PLANE_API_KEY. Nunca la pegue en un problema, chat, archivo del repositorio, .env.example, .app.json o un comando que se registre en el historial.

3. Compile este repositorio y verifique que dist/src/server.js exista.

4. Descargue/compile el tunnel-client oficial actual siguiendo la guía oficial del túnel MCP seguro. No copie el binario ni el código fuente en este repositorio para su publicación.

5. Configure el perfil stdio oficial con nombre. El comando y el destino a continuación siguen la ruta requerida por el diseño; reemplace solo los marcadores de posición con los valores creados en su máquina:

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

En Windows PowerShell, use la sintaxis de línea de comandos del ejecutable y los mismos argumentos. Mantenga el perfil en ejecución mientras crea o prueba la conexión de ChatGPT. La guía oficial documenta las superficies de salud locales /healthz, /readyz, /metrics y /ui; confirme el estado saludable y listo antes de probar.

Para una implementación de larga duración, ejecute este perfil oficial bajo el mecanismo de servicio/supervisor apropiado para su host y conserve el mismo límite de solo salida. No reemplace el flujo oficial del túnel con un listener público ad hoc.

Registre su propia conexión de modo desarrollador de ChatGPT

El flujo de trabajo de modo desarrollador de OpenAI es independiente del permiso del túnel de la Plataforma. El flujo documentado actual es:

1. En ChatGPT, abra Configuración → Seguridad e inicio de sesión y habilite Modo desarrollador si la política de su cuenta/espacio de trabajo lo permite.

2. Abra la superficie de conexión de complementos/modo desarrollador de ChatGPT y seleccione el botón +.

3. Ingrese su propio nombre y descripción visibles para el usuario.

4. En Conexión, elija Túnel y luego seleccione su propio túnel disponible o ingrese su propio tunnel_id.

5. Cree la conexión y revise las herramientas y metadatos descubiertos.

Esta es una conexión privada/de modo desarrollador, no un envío al Directorio público de complementos. La guía oficial de conexión documenta los mismos pasos de modo desarrollador y Túnel: Conecte y pruebe su complemento.

El contrato de empaquetado del diseño requiere que el ID técnico devuelto por el flujo de trabajo de conexión comience con plugin_asdk_app. Copie el ID exacto que muestre su propio flujo de trabajo de conexión/empaquetado; nunca invente uno. Luego cree el archivo de cableado local ignorado:

cp .app.json.example .app.json

Reemplace solo plugin_asdk_app_REPLACE_WITH_YOUR_REGISTERED_TECHNICAL_ID con su propio ID técnico registrado. Valídelo localmente sin exponerlo en Git:

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

El clon público pasa npm run verify:plugin en modo plantilla sin .app.json. Proporcionar --expected-app-id intencionalmente requiere el .app.json local real. El archivo .app.json se ignora y debe permanecer local para el usuario.

Uso en modo privado/desarrollador

Después de que el túnel informe saludable/listo y ChatGPT haya descubierto las herramientas MCP, inicie una nueva conversación, agregue la conexión privada desde el menú de herramientas y ejecute solicitudes académicas representativas. Verifique la degradación del proveedor, los niveles de evidencia, la procedencia, el comportamiento de los identificadores, los informes de contenido no compatible y los resultados de las herramientas según el diseño.

Para Codex local u otro cliente MCP stdio, use el comando integrado exacto:

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

La prueba de integración ejercita la inicialización de MCP y la lista de herramientas congeladas. No exponga este servidor stdio como un servicio HTTP público accesible de forma independiente.

Límite de publicación pública

Este repositorio está destinado a publicarse como una referencia/plantilla de GitHub de código abierto. Publicarlo en GitHub no publica una aplicación de OpenAI, no registra un complemento público, no crea un túnel ni otorga acceso a nadie más. Cada desarrollador debe crear y proteger sus propios recursos de OpenAI y usar el modo privado/desarrollador.

Antes de publicar, ejecute las comprobaciones de secretos e historial del repositorio descritas en docs/PUBLIC_SETUP.md, revise el diff completo y confirme que no se rastreen .app.json, .env, material de túnel, salida de compilación generada ni archivos específicos de la máquina.

Referencias

• Especificación normativa del repositorio: ACADEMIC_RESEARCH_PLUGIN_DESIGN.md.

• Evidencia histórica de contrato: SOURCE_AUDIT.md.

• Túnel MCP seguro de OpenAI: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels.

• Conexión/prueba de complementos de OpenAI: https://developers.openai.com/plugins/deploy/connect-chatgpt.

• Código fuente oficial de tunnel-client: https://github.com/openai/tunnel-client.