Paper Chaser MCP

Estado de la versión: El repositorio, la CLI, los metadatos de la imagen Docker y la identidad pública de MCP están ahora alineados en paper-chaser-mcp. Las imágenes GHCR y los recursos de GitHub Release son los principales canales de distribución pública; PyPI permanece intencionadamente restringido hasta que se complete la recuperación de la cuenta y la configuración del editor de confianza.

Un servidor MCP para investigación académica: busca artículos, rastrea citas, consulta autores, repara referencias rotas, explora expedientes de especies y recupera textos normativos, todo desde un único servidor FastMCP al que los asistentes de IA pueden llamar directamente.

Proveedores: Semantic Scholar · arXiv · OpenAlex · CORE · SerpApi Google Scholar (opt-in, de pago) · Crossref · Unpaywall · ECOS · FederalRegister.gov · GovInfo

Contenido

• ¿Qué puede hacer?

• Perfiles guiado vs experto

• Inicio rápido

• Guía rápida de decisión de herramientas

• Flujos de trabajo principales

• Contrato de respuesta del agente

• Diseño de exportación diferida

• Nota de migración

• Instalación

• Configuración

• Herramientas

• Recursos y avisos

• Recursos de empaquetado de Microsoft

• Pruebas con MCP Inspector

• Desarrollo

• Guías

• Licencia

• Enlaces

Related MCP server: Academic MCP Server

¿Qué puede hacer?

Paper Chaser MCP ahora es guiado-por-defecto: la superficie pública predeterminada está diseñada para ser difícil de usar mal y explícita sobre la confianza.

• Punto de entrada de investigación predeterminado: research gestiona el descubrimiento, la recuperación de elementos conocidos, la reparación de citas y el enrutamiento normativo en una única ruta con clasificación de confianza, con una política propia del servidor que prioriza la calidad para el uso guiado.

• Seguimiento fundamentado: follow_up_research responde basándose en un único searchSessionId guardado; si lo omites, el servidor solo infiere una sesión cuando la elección es única. El seguimiento con sesión guardada puede clasificar conjuntos de fuentes mixtos en evidencia relevante, contexto más débil y pistas fuera de objetivo cuando los metadatos almacenados ya son suficientes.

• Metadatos de decisión: las respuestas guiadas muestran executionProvenance, y los flujos ambiguos de seguimiento o inspección de fuentes devuelven cargas útiles estructuradas sessionResolution / sourceResolution en lugar de errores opacos.

• Recuperación centrada en referencias: resolve_reference gestiona DOI/arXiv/URL, fragmentos de citas y referencias de tipo normativo, y las entradas exactas de DOI/arXiv/ URL de artículo se resuelven como anclas exactas en lugar de caer en la reparación difusa. Las coincidencias ambiguas solo con título o con metadatos conflictivos ahora pueden devolver multiple_candidates o needs_disambiguation; trátalas como anclas candidatas, no como resoluciones listas para citar.

• Respuesta principal compacta: la research guiada comienza con un summary breve que prioriza la recomendación, manteniendo la evidencia estructurada, las pistas y los campos de procedencia disponibles debajo.

• Auditabilidad de fuentes: inspect_source expone un único sourceId con procedencia, estado de confianza, justificación de coincidencia débil y próximos pasos de lectura directa conscientes de la calidad; el searchSessionId omitido solo se acepta cuando existe una sesión guardada compatible.

• Verdad en tiempo de ejecución: get_runtime_status muestra el perfil/transporte activo y advertencias de estado del proveedor sin requerir diagnósticos de bajo nivel. configuredSmartProvider es el paquete inteligente configurado; activeSmartProvider es la ruta de ejecución efectiva más reciente; las instantáneas de arranque en frío emiten una advertencia provisional explícita en lugar de afirmar una alternativa determinista antes de que se resuelva la primera llamada inteligente, y los conjuntos de proveedores de nivel superior ahora dividen disabledProviderSet, suppressedProviderSet, degradedProviderSet y quotaLimitedProviderSet en lugar de combinarlos.

• La profundidad experta sigue disponible: las herramientas sin procesar/inteligentes/específicas de proveedor siguen existiendo para flujos de trabajo de operadores bajo el perfil experto.

Perfiles guiado vs experto

Usa PAPER_CHASER_TOOL_PROFILE para elegir la superficie anunciada:

Valor práctico predeterminado: PAPER_CHASER_TOOL_PROFILE=guided con PAPER_CHASER_HIDE_DISABLED_TOOLS=true.

Inicio rápido

Si quieres la ruta local más rápida, instala desde el código fuente y añade el servidor a tu cliente MCP en modo stdio:

pip install -e .

{
  "mcpServers": {
    "paper-chaser": {
      "command": "python",
      "args": ["-m", "paper_chaser_mcp"],
      "env": {
        "PAPER_CHASER_TOOL_PROFILE": "guided",
        "PAPER_CHASER_HIDE_DISABLED_TOOLS": "true",
        "PAPER_CHASER_ENABLE_SEMANTIC_SCHOLAR": "true",
        "PAPER_CHASER_ENABLE_ARXIV": "true",
        "PAPER_CHASER_ENABLE_CORE": "false"
      }
    }
  }
}

Luego empieza con uno de estos avisos en tu cliente MCP:

• Research retrieval-augmented generation for coding agents and return only trustworthy findings.

• Use my last searchSessionId to answer one grounded follow-up question.

• Resolve this citation fragment: Vaswani et al. 2017 Attention Is All You Need.

• Research the regulatory history of California condor under 50 CFR 17.95.

Si quieres una plantilla de entorno local para ejecuciones de shell o Docker Compose, copia .env.example a .env y rellena solo los proveedores que uses.

Guía rápida de decisión de herramientas

Flujos de trabajo principales

1. Investigación guiada primero

research(query="retrieval-augmented generation for coding agents", limit=5)
→ inspect resultStatus, answerability, summary, evidence, leads, routingSummary
→ if resultStatus=needs_disambiguation with clarification.reason=underspecified_reference_fragment:
  tighten the anchor or pivot to resolve_reference instead of forcing retrieval
→ if resultStatus=abstained and sources are suppressed: inspect suppressedSourceSummaries before rerunning or escalating
→ save searchSessionId for follow-up or source inspection

2. Haz una pregunta de seguimiento fundamentada

follow_up_research(searchSessionId="...", question="What evaluation tradeoffs show up here?")
→ inspect answerStatus
→ if answered: use answer + evidence (compact default: sources are identified by selectedEvidenceIds)
→ if abstained/insufficient_evidence: use nextActions, suppressedSourceSummaries, and inspect_source
→ mixed saved sessions can still answer relevance-triage questions such as which items are on-topic vs off-target
→ uniquely anchored recommendation asks can also return a safe start-here answer plus topRecommendation
→ if you omit searchSessionId and multiple saved sessions exist: provide it explicitly
→ for full source records pass responseMode="standard"; for diagnostics responseMode="debug"
→ for selection asks ("where should I start?", "most recent?"), read topRecommendation

3. Resuelve referencias antes de una búsqueda amplia cuando sea posible

resolve_reference(reference="10.1038/nrn3241")
→ exact DOI/arXiv/paper URL should resolve directly when supported
resolve_reference(reference="Rockstrom et al planetary boundaries 2009 Nature 461 472")
→ inspect status and bestMatch/alternatives
→ only treat bestMatch as citation-ready when status=resolved
→ if status=multiple_candidates or needs_disambiguation: pick a candidate or add a stronger author/year/venue clue before citing it
→ if resolved: run research with the resolved anchor

4. Inspecciona una fuente antes de citarla

inspect_source(searchSessionId="...", evidenceId="...")
→ inspect verificationStatus, topicalRelevance, whyClassifiedAsWeakMatch, confidenceSignals, canonicalUrl, directReadRecommendations
→ if searchSessionId is omitted and inference is ambiguous, rerun with an explicit saved session id

5. Gestiona la abstención y la aclaración explícitamente

• Si research.resultStatus es abstained o needs_disambiguation, no inventes una síntesis. Acota con un ancla concreta: DOI, título exacto, nombre de especie, agencia, año o sede.

• Cuando research devuelve needs_disambiguation con clarification.reason=underspecified_reference_fragment, el servidor se detiene intencionadamente antes de una recuperación especulativa sobre un fragmento de cita/referencia vago. Afina el conjunto de pistas o cambia a resolve_reference.

• Si follow_up_research.answerStatus es abstained o insufficient_evidence, trátalo como una señal de seguridad. Usa inspect_source y vuelve a ejecutar research con un alcance más ajustado.

6. Alternativa experta cuando necesitas control fino

PAPER_CHASER_TOOL_PROFILE=expert
→ search_papers_smart / ask_result_set / map_research_landscape / expand_research_graph
→ search_papers / search_papers_bulk and provider-specific families
→ search_federal_register / get_federal_register_document / get_cfr_text for direct regulatory primary-source control

Para las herramientas inteligentes expertas, deep es el modo predeterminado que prioriza la calidad. Usa balanced solo cuando una menor latencia justifique una pasada más estrecha, y reserva fast para pruebas de humo o depuración.

La research guiada ya no acepta un parámetro público latencyProfile. El servidor posee esa política y actualmente aplica una ruta respaldada por deep que prioriza la calidad con una escalada de revisión acotada cuando la primera pasada es demasiado débil.

Contrato de respuesta del agente

Trata estos como los principales contratos guiados:

Para el descubrimiento amplio de orientación de agencias, el enrutamiento guiado permanece en la ruta de fuentes primarias regulatorias. Los documentos de autoridad fuera de tema pueden seguir apareciendo como leads, pero no deben desplazar la orientación o los documentos de política más relevantes anclados a la consulta de la recomendación de nivel superior.

Para auditorías a nivel de fuente, tratar whyClassifiedAsWeakMatch y confidenceSignals.sourceScopeLabel / confidenceSignals.sourceScopeReason como la explicación principal de por qué un registro de autoridad se conservó como coincidencia débil o pista fuera de tema.

Señales adicionales de confianza y fundamentación llegaron en la ola de la fase 4 de llm-guidance. Las respuestas guiadas pueden exponer confidenceSignals.evidenceQualityProfile, confidenceSignals.synthesisMode, confidenceSignals.evidenceProfileDetail, confidenceSignals.synthesisPath, confidenceSignals.trustRevisionNarrative y un grupo trustSummary.authoritativeButWeak para registros de fuentes primarias que son autoritativos pero no responden al tema. searchStrategy puede mostrar regulatoryIntent, intentFamily, una subjectCard para especies y fundamentación regulatoria, y subjectChainGaps que describen evidencia faltante de la cadena de sujetos. inspect_source empareja cada sugerencia de lectura directa con una entrada directReadRecommendationDetails con la forma {trustLevel, whyRecommended, cautions} para que los agentes puedan priorizar las lecturas directas por calidad. Consulte Paper Chaser Golden Paths y Guided And Smart Robustness Notes para saber cómo leer y actuar sobre estas señales.

Diseño de exportación diferida

La exportación de sesiones se difiere intencionalmente en esta ola. La forma futura planificada es export_search_session(searchSessionId, format) con format en ris, bibtex o csv, usando el esquema de fuente/citación guided-v2 para que la exportación pueda aterrizar sin otra reescritura del contrato público.

Nota de migración

Si anteriormente usó la superficie inteligente/bruta directamente:

1. Comience con research en lugar de search_papers_smart o search_papers.

2. Use follow_up_research en lugar de ask_result_set para la QA fundamentada predeterminada.

3. Use resolve_reference en lugar de resolve_citation/search_papers_match como primer paso de recuperación de elementos conocidos.

4. Mantenga las herramientas expertas para flujos de trabajo explícitos de operadores estableciendo PAPER_CHASER_TOOL_PROFILE=expert.

5. No envíe latencyProfile a research guiado; el servidor ahora es dueño de esa política internamente.

6. Para las herramientas inteligentes expertas, deep es ahora el valor predeterminado. Elija balanced explícitamente cuando quiera el respaldo de menor latencia.

7. Espere que los envoltorios guiados muestren executionProvenance, sessionResolution, sourceResolution y abstentionDetails.

Para la nota detallada de cambios importantes, consulte Guided Reset Migration Note.

Instalación

Opciones de distribución actuales:

• Checkout del código fuente: la ruta local más directa hoy en día, especialmente para desarrollo y clientes de escritorio MCP.

• Imagen de GHCR: el canal principal de distribución de contenedores para clientes MCP basados en Docker.

• Activos de GitHub Release: las etiquetas v* generan artefactos wheel y sdist y los adjuntan a un GitHub Release en borrador para su revisión.

• PyPI: intencionalmente restringido por ahora; usa instalaciones desde el código fuente o los artefactos de GitHub Release hasta que esa vía se vuelva a habilitar.

Para instalaciones locales desde el código fuente:

pip install -e .

Extras opcionales para la capa de IA aditiva:

• Solo el runtime de la capa inteligente compartida, incluido el modo determinista: pip install -e ".[ai]"

• Compatibilidad con el proveedor OpenAI o Azure OpenAI: pip install -e ".[ai,openai]"

• Compatibilidad con el chat-router de Hugging Face: pip install -e ".[ai,huggingface]"

• Compatibilidad con el proveedor NVIDIA: pip install -e ".[ai,nvidia]"

• Compatibilidad con el proveedor Anthropic: pip install -e ".[ai,anthropic]"

• Compatibilidad con el proveedor Google: pip install -e ".[ai,google]"

• Compatibilidad con el proveedor Mistral: pip install -e ".[ai,mistral]"

• Utilidades de publicación de evaluación de Azure AI Foundry: pip install -e ".[eval-foundry]"

• Utilidades de publicación de evaluación de Hugging Face: pip install -e ".[eval-huggingface]"

• Ambas variantes de utilidades de publicación de evaluación: pip install -e ".[eval]"

• Añade ,ai-faiss a cualquiera de los comandos anteriores si quieres el backend opcional de FAISS.

Azure OpenAI usa el mismo extra openai. Hugging Face usa un extra huggingface dedicado que instala el SDK compatible con OpenAI además del adaptador LangChain OpenAI; este repositorio lo documenta como una vía de proveedor inteligente solo para chat con los embeddings deshabilitados. Las utilidades de publicación de evaluación usan extras separados a propósito: eval-foundry es para la compatibilidad con la carga de conjuntos de datos de Azure AI Foundry, y eval-huggingface es para la compatibilidad con la publicación en repositorios de conjuntos de datos o buckets de Hugging Face. Esos extras son independientes del runtime de chat del proveedor inteligente.

Configuración

El contrato completo de variables de entorno locales se encuentra en .env.example. Ese archivo refleja los ajustes locales públicos compatibles con docker-compose.yaml. Los identificadores, secretos y parámetros de Bicep específicos de Azure se documentan intencionalmente por separado en docs/azure-deployment.md.

Clientes de escritorio MCP

Usa el transporte stdio para clientes de escritorio MCP a menos que necesites específicamente HTTP. Consulta el ejemplo JSON de Inicio rápido anterior para la definición del servidor.

• Claude Desktop ruta de configuración:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

  • Windows: %APPDATA%\Claude\claude_desktop_config.json

• Cursor: añade la misma definición de servidor MCP en la configuración de Cursor.

Broker de búsqueda y flags de funcionalidad

El modo guiado comienza desde research. Los controles intermediados y específicos del proveedor que aparecen a continuación son controles de ruta experta.

Valores predeterminados de la capa inteligente

Estos son los valores predeterminados efectivos de planificador/síntesis cuando se habilita PAPER_CHASER_ENABLE_AGENTIC=true y no se sobrescriben intencionalmente las variables de modelo.

PAPER_CHASER_EMBEDDING_MODEL tiene como valor predeterminado text-embedding-3-large, pero los embeddings permanecen desactivados hasta que se establezca PAPER_CHASER_DISABLE_EMBEDDINGS=false. Siguen desactivados por defecto porque los embeddings han sido poco fiables en este código base y mejorarlos está fuera del alcance de la versión actual de política guiada. En la superficie de proveedores actual, los embeddings solo los utilizan los proveedores que los admiten explícitamente, lo que significa que la ruta documentada de Hugging Face sigue siendo solo de chat, aunque use un enrutador compatible con OpenAI.

Línea base recomendada: habilite Semantic Scholar, OpenAlex, Crossref y Unpaywall para flujos de trabajo académicos generales; habilite ScholarAPI cuando desee recuperación explícita de texto completo o PDF; mantenga SerpApi como opcional porque es una ruta de recuperación de recuerdo de pago.

Reglas del broker que más importan:

• El orden de respaldo de búsqueda predeterminado es Semantic Scholar, luego arXiv, luego CORE, luego SerpApi cuando está habilitado.

• preferredProvider, providerOrder y PAPER_CHASER_PROVIDER_ORDER aceptan core, semantic_scholar, arxiv, scholarapi y serpapi o serpapi_google_scholar.

• Los filtros exclusivos de Semantic Scholar, como publicationDateOrYear, fieldsOfStudy, publicationTypes, openAccessPdf y minCitationCount, pueden obligar al broker a omitir proveedores incompatibles.

• Las respuestas del broker exponen brokerMetadata.providerUsed, brokerMetadata.attemptedProviders y brokerMetadata.recommendedPaginationTool para que los agentes puedan seguir el siguiente paso correcto.

Modos de transporte e implementación

Distinciones clave:

• PAPER_CHASER_HTTP_HOST y PAPER_CHASER_HTTP_PORT controlan el shell directo y las implementaciones alojadas. Docker Compose mantiene el enlace del contenedor en 0.0.0.0:8080 y usa PAPER_CHASER_PUBLISHED_HOST / PAPER_CHASER_PUBLISHED_PORT para la asignación del lado del host.

• paper-chaser-mcp deployment-http ejecuta el envoltorio de implementación utilizado por Compose y Azure. Agrega /healthz más autenticación opcional y aplicación de Origen delante del punto final MCP.

Ejemplo de ejecución HTTP local directa:

PAPER_CHASER_TRANSPORT=streamable-http \
PAPER_CHASER_HTTP_HOST=127.0.0.1 \
PAPER_CHASER_HTTP_PORT=8000 \
python -m paper_chaser_mcp

Si necesita la historia completa de implementación de Azure, incluidos los modos de flujo de trabajo bootstrap y full, lea docs/azure-deployment.md, docs/azure-architecture.md y docs/azure-security-model.md.

Paquete MCP de Docker (stdio)

Para clientes MCP locales que lanzan servidores como subprocesos, use la imagen en modo stdio. Para iteración local no publicada, compile y ejecute paper-chaser-mcp:local. Para el paquete público reutilizable, use la etiqueta GHCR publicada:

docker run --rm -i ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest

Para una imagen compilada localmente:

docker run --rm -i paper-chaser-mcp:local

Una entrada de cliente MCP respaldada por Docker normalmente se ve así:

{
  "mcpServers": {
    "paper-chaser": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest"]
    }
  }
}

Este modo es ideal para uso MCP de escritorio local porque el host lanza y posee el ciclo de vida del proceso del servidor.

El repositorio también incluye server.json para que la imagen OCI pública y los metadatos del paquete MCP permanezcan alineados para las herramientas de registro/descubrimiento. El flujo de trabajo del paquete público está impulsado por etiquetas para GHCR: una etiqueta v* publica la imagen de contenedor reutilizable en ghcr.io/joshuasundance-swca/paper-chaser-mcp. La publicación en el Registro MCP está intencionalmente desacoplada en un flujo de trabajo manual separado para que el envío a GHCR no dependa de la disponibilidad del registro.

La publicación del paquete de Python se prepara por separado en .github/workflows/publish-pypi.yml: las solicitudes de extracción compilan y twine check la distribución, y los trabajos de publicación reales permanecen inactivos hasta que la variable del repositorio ENABLE_PYPI_PUBLISHING se establece en true. Después de que se restaure el acceso a PyPI/TestPyPI y se registren los editores de confianza, el envío manual puede publicar en TestPyPI y una etiqueta v* puede publicar en PyPI.

Los activos de la versión de GitHub se manejan por separado en .github/workflows/publish-github-release.yml: una etiqueta v* o un envío manual compila artefactos wheel y sdist, los verifica con twine check, genera SHA256SUMS y los sube a una página de borrador de versión de GitHub para que los artefactos de Python puedan revisarse antes de una promoción pública más amplia.

Docker Compose (modo envoltorio HTTP)

Para pruebas HTTP locales, MCP Inspector o integraciones de tipo puente, este repositorio incluye docker-compose.yaml con valores predeterminados solo de localhost. Compose inicia explícitamente el subcomando deployment-http, por lo que el comportamiento del envoltorio HTTP no depende del transporte predeterminado de la imagen.

Compose mantiene el host de enlace del contenedor y el puerto interno fijos en 0.0.0.0:8080 y anula el transporte predeterminado de la aplicación a streamable-http, para que las herramientas de navegador y los clientes de tipo puente puedan conectarse a través de http://127.0.0.1:8000/mcp sin banderas de shell adicionales. El archivo compose expone los controles visibles para el usuario: transporte, ruta MCP, claves de proveedor, conmutadores de proveedor, autenticación y la asignación de puerto host publicado.

1. Copie .env.example a .env.

2. Complete cualquier clave de proveedor opcional que desee usar.

3. Inicie el servicio:

docker compose -f docker-compose.yaml up --build

El servicio escucha en http://127.0.0.1:8000 por defecto, sirve /healthz para sondas y expone MCP a través de http://127.0.0.1:8000/mcp.

curl http://127.0.0.1:8000/healthz

Si establece PAPER_CHASER_HTTP_AUTH_TOKEN y deja PAPER_CHASER_HTTP_AUTH_HEADER=authorization, el envoltorio de implementación espera Authorization: Bearer <token> en /mcp. El andamiaje de Azure incluido anula el nombre del encabezado a x-backend-auth y hace que API Management inyecte ese encabezado para tráfico solo de backend. El host publicado predeterminado es 127.0.0.1; solo cambie PAPER_CHASER_PUBLISHED_HOST cuando intencionalmente quiera que el contenedor sea accesible más allá de la máquina local.

Si deja los campos de clave de proveedor en blanco, los clientes locales aún funcionan. El servidor recurre a las rutas de proveedor gratuitas/predeterminadas donde se admiten, y SerpApi permanece deshabilitado por defecto.

Sidecar de Inspector de Docker Compose

Para depuración basada en navegador sin instalar Node localmente, use la pila dedicada de Inspector:

docker compose -f compose.inspector.yaml up --build

Esta pila mantiene a Inspector separado de la imagen del servidor MCP y vincula la interfaz de usuario y el proxy solo a localhost:

• Interfaz de usuario de Inspector: http://127.0.0.1:6274

• Proxy de Inspector: http://127.0.0.1:6277

La autenticación del proxy de Inspector permanece habilitada por defecto. Use docker compose -f compose.inspector.yaml logs mcp-inspector para leer el token de sesión que Inspector imprime al inicio.

Dentro de Inspector, conéctese usando Streamable HTTP y establezca:

• URL: http://paper-chaser-mcp:8080/mcp

• Transporte: streamable-http

compose.inspector.yaml acepta anulaciones de IMAGE, por lo que puede probar una etiqueta específica sin editar archivos:

IMAGE=ghcr.io/joshuasundance-swca/paper-chaser-mcp:latest docker compose -f compose.inspector.yaml up

Herramientas

Referencia completa de herramientas. Consulte la Guía rápida de decisión de herramientas anterior para saber por dónde empezar.

Herramientas predeterminadas guiadas

Capa experta de investigación inteligente

Estas herramientas son rutas de perfil experto para una orquestación más profunda y control del proveedor.

Búsqueda de artículos

Búsqueda de elementos conocidos y reparación de citas

Citas, referencias y autores

Recuperación de texto y PDF de ScholarAPI

Entidades de OpenAlex

Expedientes de especies de ECOS

Registro Federal y CFR

Extras de SerpApi (opcional, de pago)

Recuperación y diagnóstico

Recorrido de ECOS

El charrán mínimo de California es un flujo de ECOS de extremo a extremo representativo:

1. Llame a search_species_ecos con query="California least tern" para obtener el id de especie de ECOS 8104.

2. Llame a get_species_profile_ecos con species_id="8104" para inspeccionar el expediente de la especie, los documentos de recuperación agrupados, las opiniones biológicas y los enlaces de planes de conservación.

3. Llame a list_species_documents_ecos con species_id="8104" y, por ejemplo, documentKinds=["recovery_plan","five_year_review","biological_opinion"] para aplanar el inventario de documentos.

4. Llame a get_document_text_ecos en el PDF de revisión de cinco años de 2025 o en el PDF del plan de recuperación revisado para convertir el documento fuente en Markdown para el análisis posterior.

Recursos y prompts

• Recurso: guide://paper-chaser/agent-workflows - guía de incorporación compacta para elegir herramientas y seguir la paginación de forma segura

• Recurso: paper://{paper_id} - markdown compacto + carga útil estructurada para un artículo resuelto

• Recurso: author://{author_id} - markdown compacto + carga útil estructurada para un autor resuelto

• Recurso: search://{searchSessionId} - conjunto de resultados guardado que se muestra a partir de las salidas de las herramientas

• Recurso: trail://paper/{paper_id}?direction=citations|references - recurso compacto de rastro de citas/referencias

• Prompt: plan_paper_chaser_search - prompt de planificación reutilizable con valores predeterminados guiados y respaldo experto explícito

• Prompt: plan_smart_paper_chaser_search - prompt de planificación para flujos de trabajo expertos intencionales en modo inteligente

• Prompt: triage_literature - flujo de trabajo de triaje guiado para el mapeo de temas basado en la confianza y la selección de próximos pasos

• Prompt: plan_citation_chase - prompt de planificación de expansión de citas

• Prompt: refine_query - prompt de refinamiento de consulta acotado para búsquedas amplias o ruidosas

Las respuestas de las herramientas de lectura principales también muestran:

• agentHints - próximas herramientas recomendadas, orientación de reintentos y advertencias

• clarification - respaldo de aclaración acotado cuando el servidor no puede desambiguar de forma segura por sí solo

• resourceUris - recursos de seguimiento que los clientes compatibles pueden abrir directamente

• searchSessionId - identificador de conjunto de resultados reutilizable para flujos de trabajo de seguimiento inteligentes y rastros de búsqueda/expansión en caché

Recursos de empaquetado de Microsoft

Este repositorio mantiene una superficie de servidor MCP universal y distribuye recursos de empaquetado aditivos para clientes orientados a Microsoft:

• mcp-tools.core.json - superficie predeterminada guiada de bajo contexto (research, follow_up_research, resolve_reference, inspect_source, get_runtime_status)

• mcp-tools.full.json - paquete guiado + experto para entornos que se ejecutan intencionalmente con PAPER_CHASER_TOOL_PROFILE=expert

• microsoft-plugin.sample.json - metadatos de muestra de agente declarativo / orientado a complementos

Estos recursos se dirigen a HTTP de flujo continuo y salidas de herramientas compactas. Son orientación de empaquetado, no una compilación de tiempo de ejecución separada.

Pruebas con MCP Inspector

La ruta local recomendada es el flujo de trabajo de sidecar de Docker:

docker compose -f compose.inspector.yaml up --build

Esto mantiene a Inspector fuera de la imagen MCP de producción y vincula los puertos de Inspector solo a localhost.

Si prefiere un Inspector instalado en el host, aún puede ejecutar:

npm install -g @modelcontextprotocol/inspector
mcp-inspector python -m paper_chaser_mcp

Desarrollo

Instale el paquete con los extras de desarrollo:

pip install -e ".[dev]"

Si también desea la capa de IA aditiva más cada integración de proveedor alojado en el mismo entorno:

pip install -e ".[all]"

all se expande a ai,openai,huggingface,nvidia,anthropic,google,mistral,dev, por lo que Azure OpenAI sigue usando el mismo extra openai mientras que Hugging Face sigue siendo una superficie de instalación separada compatible con OpenAI solo para chat.

Si también necesita el backend FAISS opcional localmente:

pip install -e ".[all,ai-faiss]"

Las dependencias del proyecto se declaran en pyproject.toml; no hay un requirements.txt de tiempo de ejecución separado que mantener sincronizado.

Ejecute la suite de pruebas local:

pytest

Instale y ejecute los hooks de pre-commit configurados:

pre-commit install
pre-commit run --all-files

pre-commit install instala tanto los hooks pre-commit rápidos como los más pesados de pre-push configurados en .pre-commit-config.yaml. Los hooks de etapa manual no se invocan automáticamente; ejecute pre-commit run --hook-stage manual --all-files (o los comandos directos anteriores) cuando desee la puerta local completa.

Los extras de desarrollo incluyen pytest, pytest-asyncio, pytest-cov, ruff, mypy, bandit, build, bumpver, pip-audit, shellcheck-py, types-defusedxml y pre-commit. La automatización de dependencias de GitHub está configurada tanto para paquetes de Python como para GitHub Actions mediante Dependabot, con solicitudes de extracción verificadas por el flujo de trabajo de revisión de dependencias.

Para la paridad local con CI en los archivos de flujo de trabajo de GitHub, mantenga shellcheck disponible en PATH antes de ejecutar pre-commit. Instalar shellcheck-py en el venv del repositorio activo satisface esto para muchas configuraciones; verifique con shellcheck --version en lugar de asumir que el bash de flujo de trabajo en línea se está analizando localmente.

Aumentos de versión

Los metadatos de versión se gestionan con bumpver desde pyproject.toml. La versión del paquete registrada permanece en forma PEP 440 simple, como 0.2.0, mientras que la forma de la etiqueta de lanzamiento permanece v0.2.0 para coincidir con el activador del flujo de trabajo de publicación existente.

Para una revisión segura de ramas de PR, pruebe un aumento de parche en seco sin tocar el estado de git:

bumpver update --patch --dry --no-fetch --no-commit --no-tag-commit --no-push

Para una rama real de preparación de lanzamiento, actualice el contrato de versión registrado pero aún deje la confirmación, la etiqueta y el envío bajo control explícito del mantenedor:

bumpver update --patch --no-commit --no-tag-commit --no-push

Validación local completa

La puerta local equivalente a CI del repositorio es más amplia que pytest solo. Para una pasada local exhaustiva, ejecute:

python -m pip check
pre-commit run --all-files
python -m pytest --cov=paper_chaser_mcp --cov-report=term-missing --cov-fail-under=87
python -m mypy --config-file pyproject.toml
python -m ruff check .
python -m bandit -c pyproject.toml -r paper_chaser_mcp
python -m build
python -m pip_audit . --progress-spinner off

Si prefiere invocar las comprobaciones más pesadas gestionadas por hooks a través de pre-commit, pre-commit run --hook-stage manual --all-files ejecuta los hooks de etapa manual pip check, cobertura, compilación y pip-audit definidos en .pre-commit-config.yaml.

Cuando toque IaC de Azure, documentación de implementación, el Dockerfile, la política de APIM o el flujo de trabajo de implementación de Azure, también ejecute:

python scripts/validate_psrule_azure.py
python scripts/validate_deployment.py --skip-docker

Para la paridad con la ruta de validación de implementación completa del flujo de trabajo Deploy Azure, ejecute:

python scripts/validate_deployment.py --require-az --require-docker --image-tag paper-chaser-mcp:ci-validate

Prueba de humo del flujo de trabajo agéntico de GitHub

El repositorio incluye un flujo de trabajo de regresión agéntico en .github/workflows/test-paper-chaser.md (fuente) y .github/workflows/test-paper-chaser.lock.yml (archivo de bloqueo compilado). Ejecuta el agente contra el servidor MCP local dentro de GitHub Actions, ejercita los caminos dorados primarios, evalúa la calidad de la experiencia del agente y puede registrar problemas accionables para el trabajo de seguimiento.

Después de editar el flujo de trabajo de Markdown, vuelva a compilar y validar:

gh aw compile test-paper-chaser --dir .github/workflows
pre-commit run --all-files

Confirme tanto la fuente .md como la salida .lock.yml juntas, luego ejecute Test Paper Chaser MCP desde la interfaz de GitHub Actions.

Entradas del flujo de trabajo: mode (smoke, comprehensive o feature_probe), tool_profile (guided por defecto, expert cuando intencionalmente desea cobertura sin procesar/específica del proveedor) y un focus_prompt opcional. Selecciónelos mediante entradas de workflow_dispatch.

Secretos requeridos: COPILOT_GITHUB_TOKEN es obligatorio. GH_AW_MODEL_AGENT_COPILOT (variable de Actions, opcional) controla el modelo del agente. CORE_API_KEY y SEMANTIC_SCHOLAR_API_KEY son opcionales.

El repositorio también incluye .github/workflows/agentic-assign.yml, que asigna automáticamente GitHub Copilot a los issues etiquetados como agentic y needs-copilot (a menos que también estén etiquetados como needs-human, blocked o no-agent). El flujo de trabajo Validate recompila test-paper-chaser.md en CI y falla si el archivo de bloqueo está obsoleto, por lo que las pull requests no pueden desincronizarse silenciosamente. El flujo de trabajo se "despliega" cuando GitHub Actions ve el .lock.yml confirmado en la rama donde debe ejecutarse.

Consulta SECURITY.md para conocer la postura de seguridad del repositorio público y la vía de notificación privada recomendada para vulnerabilidades.

Para la orientación de los mantenedores tras la división de módulos, comienza con docs/agent-handoff.md. La superficie pública de MCP permanece en paper_chaser_mcp/server.py, mientras que la implementación vive en paper_chaser_mcp/dispatch.py, paper_chaser_mcp/search.py, paper_chaser_mcp/tools.py, paper_chaser_mcp/runtime.py, paper_chaser_mcp/models/ y los subpaquetes de proveedores bajo paper_chaser_mcp/clients/.

Guías

• Instrucciones de GitHub Copilot: orientación específica del repositorio para GitHub Copilot y el agente de codificación en la nube de GitHub, incluidos los valores predeterminados del flujo de trabajo y las expectativas de planificación duradera.

• Transferencia de agente: estado actual del repositorio, comandos de validación y próximo trabajo recomendado para agentes de seguimiento.

• Guía de selección de LLM: responsabilidades del planificador frente a las de síntesis, valores predeterminados actuales del modelo de capa inteligente, el embudo de arranque de evaluación en torno a generate_eval_topics.py y run_eval_autopilot.py, y criterios para elegir LLM en este repositorio.

• Plan del programa de evaluación de LLM: estrategia de evaluación basada en roles, plan de generación de conjuntos de datos, pila de evaluadores y despliegue por fases para la medición rigurosa del rendimiento de LLM en este repositorio.

• Esquema del conjunto de datos de evaluación de LLM: esquema JSONL, reglas de campos, convenciones de gobernanza y disposición de almacenamiento para conjuntos semilla de evaluación basados en roles y la futura expansión de benchmarks.

• Estrategia de plataforma de evaluación de LLM: cómo combinar evaluaciones locales del repositorio con Azure AI Foundry, Hugging Face y bucles de aprendizaje activo con trazas en vivo sin perder portabilidad.

• Promoción de trazas de evaluación de LLM: flujo de trabajo y formato auxiliar para promover trazas en vivo revisadas a filas de evaluación duraderas.

La captura opcional de candidatos de evaluación en vivo se puede habilitar con PAPER_CHASER_ENABLE_EVAL_TRACE_CAPTURE=true y PAPER_CHASER_EVAL_TRACE_PATH=..., y luego convertirla en una cola de revisión con scripts/build_eval_review_queue.py antes de la promoción.

Las exportaciones portables para sistemas posteriores de evaluación y entrenamiento están disponibles a través de scripts/export_eval_assets.py, incluidos JSONL de evaluación compatibles con Foundry, JSONL de conjuntos de datos de Hugging Face y JSONL de entrenamiento estilo chat a partir de trazas aprobadas en revisión.

Los asistentes de publicación específicos por servicio están disponibles a través de scripts/upload_foundry_eval_dataset.py y scripts/upload_hf_eval_assets.py para enviar exportaciones revisadas a un conjunto de datos de proyecto de Foundry, un repositorio de conjuntos de datos de Hugging Face o un bucket de Hugging Face.

Las ejecuciones de curación por lotes expertas ahora pueden emitir batch-summary.json y batch-ledger.csv junto con el informe bruto, los eventos capturados y la cola de revisión, de modo que las comprobaciones de deriva y rendimiento sin conexión no dependan de reproducir los artefactos JSONL completos.

Para el arranque de evaluación local del repositorio, el flujo de trabajo de nivel superior actual es:

• scripts/generate_eval_topics.py para la generación de temas dirigida por el planificador, asignación de taxonomía, clasificación, poda, equilibrio y emisión de escenarios

• scripts/run_eval_autopilot.py para la generación basada en perfiles, paquetes de ejecución inmutables, comprobaciones de reserva y traspaso de flujo de trabajo protegido

• scripts/run_eval_workflow.py para la captura de lotes expertos, revisión o promoción, división de conjuntos de datos y evaluación en vivo de la matriz de proveedores

Los perfiles de muestra del autopiloto incluidos ahora incluyen valores predeterminados de ciencia equilibrada además de perfiles de ejecución limitada como single-seed-exploratory-review, single-seed-exploratory-safe y single-seed-diagnostic-force. Esos perfiles de ejecución limitada pueden habilitar la diversificación de una sola semilla para que las ejecuciones de una sola semilla pidan al planificador variantes adicionales de revisión, regulatorias y orientadas a métodos, en lugar de depender solo de umbrales de flujo de trabajo más flexibles.

Consulta docs/llm-evaluation-integrations.md para conocer la postura actual de integración con Foundry y Hugging Face, incluido cuándo hf-mount es una buena opción para un sumidero de captura compartido.

• Plan de lanzamiento y publicación: la guía de lanzamiento actual para GHCR, recursos de GitHub Release, publicación manual en el Registro MCP y PyPI inactivo.

• Nota de migración de restablecimiento guiado: cambio disruptivo en la superficie predeterminada, división entre guiado y experto, y lista de verificación de migración de clientes.

• Rutas doradas de Paper Chaser: personas principales, valores predeterminados del flujo de trabajo, señales de éxito y trabajo de seguimiento futuro orientado al flujo de trabajo.

• Implementación de Azure: modos de implementación, secretos y variables requeridos, y rutas de validación para el despliegue privado de Azure.

• Arquitectura de Azure: límites de confianza, topología de ejecución y separación de credenciales para el andamiaje de Azure.

• Modelo de seguridad de Azure: clases de credenciales, uso de Key Vault y separación de autenticación de backend en el despliegue de Azure.

• Programa de actualización de proveedores: roles de proveedor, perfiles de latencia, diagnósticos, corpus de referencia y puertas de aceptación para la actualización de proveedores priorizando la fiabilidad.

• Guía de proveedor de OpenRouter: orientación centrada en la implementación para añadir y operar OpenRouter como proveedor de capa inteligente solo de chat, incluido el plan actual de puesta en marcha de Trinity.

• Guía de integración de ScholarAPI: guía de planificación para añadir ScholarAPI como proveedor explícito de descubrimiento, monitoreo, texto completo y PDF sin debilitar los contratos de proveedor actuales orientados a grafos.

• Guía de API de OpenAlex: orientación centrada en la implementación para la superficie MCP explícita de OpenAlex del repositorio, incluidos autenticación, límites basados en créditos, paginación, semántica de /works y advertencias de normalización.

• Guía de API de Semantic Scholar: orientación práctica para un uso respetuoso y eficaz de la API de Semantic Scholar con limitación de velocidad asíncrona, reintentos y desarrollo local basado en .env.

• Guía de Google Scholar de SerpApi: notas de investigación exhaustiva sobre las capacidades de SerpApi, compensaciones y consideraciones de coste y cumplimiento; el repositorio incluye los flujos explícitos de citado por, versiones, autor, cuenta y formato de citación documentados allí.

• Plan de migración de FastMCP: justificación histórica de la arquitectura para la migración a FastMCP y la superficie de compatibilidad.

Licencia

MIT

Enlaces

Protocolo y ejecución

• Model Context Protocol

• FastMCP

• Precios de SerpApi

Proveedores académicos

• API de Semantic Scholar

• Manual del usuario de la API de arXiv

• Documentación de CORE API v3

• Documentación de OpenAlex API

• Documentación de ScholarAPI

• API de Google Scholar de SerpApi

• API REST de Crossref

• API de Unpaywall

Fuentes regulatorias y de especies

• ECOS

• API de FederalRegister.gov

• API de GovInfo