Ookcite MCP

Valida DOIs contra una base de datos real de citas, formatea referencias en más de 2900 estilos CSL (APA, IEEE, Chicago, Nature, etc.), y detecta referencias académicas alucinadas antes de que lleguen a tu artículo, documentación o presentación. Gestiona colecciones de citas, importa/exporta BibTeX y procesa referencias por lotes. 29 herramientas.

GitHub

Documentación

Servidor MCP de OokCite

Proporciona a las herramientas compatibles con MCP la capacidad de validar DOIs, formatear citas, gestionar colecciones bibliográficas y detectar referencias fabricadas. Devuelve únicamente metadatos de citas, no PDFs ni artículos de texto completo. Los clientes de escritorio pueden ejecutarlo a través de la entrada y salida estándar. Los clientes remotos usan https://ookcite-api.turtletech.us/mcp.

Inicio rápido

Un comando para instalar y configurar:

npx @turtletech/ookcite-mcp setup

Esto detecta automáticamente los clientes MCP compatibles y escribe la configuración por ti. Conecta una cuenta de OokCite para obtener límites de velocidad más altos y herramientas de colección sin poner una clave de API en los argumentos del shell o en la configuración de MCP:

npx @turtletech/ookcite-mcp setup --connect

El comando abre el panel de TurtleTech, crea o activa el plan gratuito, almacena la clave emitida en el almacén de credenciales de la plataforma y escribe solo una referencia de credencial en los clientes detectados. Usa setup --connect --device en una máquina sin interfaz gráfica.

Una clave de API existente sigue siendo compatible:

npx @turtletech/ookcite-mcp setup --key YOUR_API_KEY

No se requiere clave de API para uso básico (20 consultas/día): format_citation y un pequeño import_bibliography en texto plano (omite collection, hasta 8 elementos). Regístrate para obtener más.

Pega una lista a BibTeX

import_bibliography acepta una lista de citas numerada o separada por líneas en blanco, no solo .bib / .ris. Omite collection para una pequeña pegada: la herramienta resuelve los elementos y devuelve texto .bib. Con una clave, pasa collection para guardar las entradas resueltas. export_collection puede entonces emitir .bib (format=bib) o texto de bibliografía CSL (format=csl o un ID de estilo como ieee). npx @turtletech/ookcite-mcp setup sigue siendo el instalador. El servidor nunca obtiene PDFs.

Después de cambiar la configuración de MCP, reinicia el cliente o recarga sus servidores MCP. Muchos clientes no recargan en caliente los cambios de variables de entorno para servidores stdio ya en ejecución.

Instalación (métodos alternativos)

npm (recomendado):

npm install -g @turtletech/ookcite-mcp

cargo-binstall (el más rápido, sin Node.js):

cargo binstall ookcite-mcp

cargo install (desde el código fuente):

cargo install ookcite-mcp

Binarios precompilados: Descarga desde GitHub Releases para Linux (x86_64, aarch64), macOS (x86_64, aarch64) y Windows.

Configuración

Si usaste setup, ya está listo. De lo contrario, añade a la configuración de tu cliente MCP:

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"]
    }
  }
}

Con una clave de API:

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"],
      "env": {
        "OOKCITE_API_KEY": "your_key_here"
      }
    }
  }
}

Si instalaste globalmente (npm install -g o cargo install), puedes usar "command": "ookcite-mcp" directamente en lugar de npx.

Mantener la clave fuera del archivo de configuración

setup --connect usa el almacén de credenciales de la plataforma por defecto. Se niega a reemplazar una credencial de plataforma existente o una configuración nombrada de OokCite MCP a menos que se proporcione explícitamente --replace-credential o --replace-config.

Se puede usar un gestor de credenciales genérico en su lugar. El comando de almacenamiento recibe la nueva clave en la entrada estándar; no debe esperar la clave en un argumento de línea de comandos. El comando de recuperación imprime la clave en la salida estándar cuando el servidor MCP se inicia:

npx @turtletech/ookcite-mcp setup --connect \
  --store-command "credential-cli store ookcite" \
  --retrieve-command "credential-cli read ookcite"

Para un archivo explícito de solo propietario en lugar de un gestor de credenciales:

npx @turtletech/ookcite-mcp setup --connect \
  --credential-file "$HOME/.config/ookcite/api-key"

El archivo se crea con permisos de solo propietario y nunca se sobrescribe. Las formas de plataforma, comando auxiliar y archivo colocan referencias como estas en la configuración del cliente:

{
  "mcpServers": {
    "ookcite": {
      "command": "npx",
      "args": ["-y", "@turtletech/ookcite-mcp"],
      "env": {
        "OOKCITE_API_KEY_COMMAND": "credential-cli read ookcite"
      }
    }
  }
}

Al inicio, la precedencia de fuentes sigue siendo OOKCITE_API_KEY, OOKCITE_API_KEY_COMMAND, OOKCITE_API_KEY_FILE y luego la referencia de credencial de plataforma. Sin ninguna de ellas, el servidor se inicia de forma anónima. setup --key sigue disponible para implementaciones existentes que mantienen intencionalmente la clave en la configuración del cliente.

La recuperación de credenciales obedece dos restricciones:

La recuperación recibe entrada estándar cerrada, por lo que no puede consumir MCP JSON-RPC.
La recuperación está limitada por OOKCITE_API_KEY_TIMEOUT, que por defecto es de 10 segundos, y su salida nunca se copia en los diagnósticos.

Consulta la documentación de MCP de tu cliente para conocer la ubicación de su archivo de configuración. Usa el JSON mcpServers.ookcite anterior cuando la configuración automática no esté disponible, luego reinicia el cliente o recarga sus servidores MCP.

Env opcional (stdio MCP, todos los clientes):

Variable	Propósito
`OOKCITE_API_KEY`	Límites de velocidad más altos + herramientas de colección (opcional para consulta/formato básico)
`OOKCITE_API`	Anula la URL base de la API (por defecto `https://ookcite-api.turtletech.us`)
`OOKCITE_MCP_READ_ONLY`	`1` desactiva por completo las mutaciones de colección (revisión / automatización de CI)
`OOKCITE_MCP_ALLOW_MUTATE`	`0` deniega mutaciones; sin establecer o `1` permite (la clave de API sigue siendo necesaria en el servidor)
`OOKCITE_STARTUP_PROBES`	`1` ejecuta comprobaciones de autenticación y actualización de npm en stderr antes de aceptar conexiones MCP (desactivado por defecto para una conexión más rápida)
`OOKCITE_API_KEY_COMMAND`	Comando que imprime la clave en stdout; stdin está cerrado
`OOKCITE_API_KEY_FILE`	Archivo protegido por propietario cuya primera línea es la clave
`OOKCITE_API_KEY_TIMEOUT`	Segundos permitidos para la recuperación de credenciales (por defecto 10)
`OOKCITE_CREDENTIAL_STORE`	`platform` para cargar una referencia de credencial de plataforma
`OOKCITE_CREDENTIAL_SERVICE`	Nombre del servicio de credenciales de plataforma (por defecto `ookcite-mcp`)
`OOKCITE_CREDENTIAL_ACCOUNT`	Nombre de la cuenta de credenciales de plataforma (por defecto `default`)

Plugin de marketplace

OokCite se instala de dos maneras.

Desde este repositorio, añade el marketplace TurtleTech-ehf/ookcite-mcp e instala ookcite@ookcite. Eso registra el marketplace ookcite y habilita el plugin en plugins/ookcite. El plugin se conecta a https://ookcite-api.turtletech.us/mcp y añade tres habilidades: formatear una bibliografía pegada (/ookcite:format-bibliography), verificar referencias antes del envío (/ookcite:verify-references) y construir y exportar una colección (/ookcite:build-collection). Inicia sesión cuando se te pida. Formatear una cita y comprobar una lista corta de DOIs también funciona antes de iniciar sesión, dentro del límite diario anónimo. Guardar una colección requiere la cuenta con sesión iniciada.

Las aplicaciones web, de escritorio y de cowork usan la misma dirección como conector de directorio. Elige iniciar sesión. Envía el conector por esa URL y envía la carpeta plugins/ookcite como paquete de plugin. Instalar desde el marketplace no envía ninguna de las dos listas.

Un conector remoto no tiene que soportar el registro dinámico de clientes. El plugin envía el ID de cliente público pre-registrado ookcite-remote, por lo que el cliente de código no llama a un endpoint de registro. El descubrimiento para ese cliente publica S256 PKCE y sin registration_endpoint. El recurso protegido lista el emisor de ese cliente primero, y su campo resource es https://ookcite-api.turtletech.us/mcp. El cliente acepta la devolución de llamada del directorio exactamente, y redirecciones de bucle local en localhost y 127.0.0.1 en cualquier puerto. Los tokens de acceso deben satisfacer exp - iat <= 3600 o el servidor de recursos los rechaza.

MCP remoto

Usa OokCite desde un producto de chat sin instalar nada. Añade esta dirección, elige iniciar sesión y aprueba el inicio de sesión cuando se te pida:

https://ookcite-api.turtletech.us/mcp

El chat envía entonces un token de acceso de corta duración:

Authorization: Bearer <access token>

Las consultas cuentan contra esa cuenta con sesión iniciada. Una clave de API pegada es rechazada. El transporte es Streamable HTTP sin estado: un POST, JSON de entrada y JSON de salida. Selecciona Streamable HTTP e inicio de sesión (OAuth). No selecciones el transporte SSE heredado, una clave de API o "Sin autenticación".

eduGenAI Chat, después de que ookcite-api.turtletech.us esté en la lista blanca:

Campo	Valor
Nombre	OokCite
Descripción	Verifica DOIs e ISBNs, resuelve citas desordenadas y formatea entradas de bibliografía en estilos CSL. Devuelve únicamente metadatos de citas, no PDFs ni texto completo.
URL	`https://ookcite-api.turtletech.us/mcp`
Transporte	Streamable HTTP
Autenticación	OAuth

ookcite-mcp serve ejecuta tu propia copia. Los clientes de escritorio que generan un subproceso siguen usando la entrada y salida estándar.

Variable	Propósito
`OOKCITE_API`	URL base de la API de OokCite (por defecto `https://ookcite-api.turtletech.us`)
`OOKCITE_MCP_HTTP_AUTH`	`oauth` para iniciar sesión, `bearer` para tu propia copia, o `none`
`OOKCITE_MCP_OIDC_ISSUER`	Emisor de inicio de sesión. Requerido cuando la autenticación es `oauth`
`OOKCITE_MCP_OIDC_AUDIENCE`	Audiencia del token. Requerido cuando la autenticación es `oauth`
`OOKCITE_MCP_OIDC_SCOPE`	Alcance requerido (por defecto `openid`)
`OOKCITE_MCP_PATH`	Ruta de MCP (por defecto `/mcp`)
`OOKCITE_MCP_ALLOWED_HOSTS`	Nombres adicionales de `Host`, separados por comas. El bucle local siempre está permitido
`OOKCITE_MCP_ALLOWED_ORIGINS`	Valores de `Origin` del navegador que pueden llamar al endpoint. Un Origin faltante está permitido

Consejos de uso de MCP

Prefiere herramientas por lotes (verify_references, batch_format, batch_add_to_collection, import_bibliography) en lugar de muchas llamadas de cita individual.
Las mutaciones de colección requieren la cuenta con sesión iniciada, o OOKCITE_API_KEY en una copia que ejecutes tú mismo. Las herramientas destructivas (delete_collection, remove_from_collection, unshare_collection) están anotadas para clientes que respetan las sugerencias de herramientas de MCP.
El servidor escribe diagnósticos en stderr solo en la ruta de MCP; stdout está reservado para JSON-RPC.

Herramientas

Consulta y validación

Herramienta	Propósito
`validate_doi`	Comprueba si existe un DOI (anti-alucinación)
`lookup_isbn`	Busca un libro por ISBN
`reverse_lookup`	Encuentra un artículo a partir de texto de cita desordenado; devuelve la consulta original, la confianza y el título
`batch_resolve`	Resuelve muchas cadenas de citas en una sola solicitud (máx. 50)
`enhanced_search`	Búsqueda en el corpus con facetas de autor / categoría / cita
`health_check`	Comprueba la disponibilidad y el estado de la API

Formato

Herramienta	Propósito
`format_citation`	Formatea un DOI en cualquiera de los más de 2900 estilos CSL (sin clave de API para una sola cita)
`verify_references`	Comprueba por lotes DOIs y cualquier afirmación bibliográfica que se pase con ellos
`batch_format`	Formatea múltiples citas a la vez
`search_styles`	Encuentra IDs de estilos CSL por nombre
`list_styles`	Recorre la lista completa de estilos CSL
`group_cite`	Genera marcadores en texto agrupados (p. ej. [1-3])

Cuenta

Herramienta	Propósito
`usage`	Plan en vigor más consultas diarias (y mensuales) restantes

ORCID

Herramienta	Propósito
`orcid_search`	Encuentra perfiles de ORCID por nombre, afiliación o ID de ORCID
`orcid_profile`	Obtiene un perfil de ORCID por ID
`ingest_orcid`	Indexa las publicaciones del perfil de un ORCID para que sean buscables

Colecciones (requiere iniciar sesión)

Las colecciones son una función con sesión iniciada. El servidor alojado usa la cuenta del inicio de sesión. Una copia que ejecutes tú mismo usa OOKCITE_API_KEY. Un pequeño import_bibliography en texto plano sin collection es la excepción: devuelve .bib bajo el límite anónimo.

Herramienta	Propósito
`list_collections`	Listar colecciones de citas guardadas
`add_to_collection`	Añadir una cita (por DOI o texto libre)
`batch_add_to_collection`	Añadir varias citas a la vez
`import_bibliography`	Importar BibTeX, RIS o una lista de texto plano pegada
`export_collection`	Exportar la colección como texto BibTeX o CSL
`search_collection`	Buscar dentro de una colección; devuelve `entry_id` por coincidencia
`check_duplicates`	Comprobar duplicados; devuelve `entry_id` para coincidencias
`delete_collection`	Eliminar una colección
`update_collection`	Actualizar nombre, descripción o estilo
`remove_from_collection`	Eliminar una entrada por `entry_id`, DOI simple o `doi:10.x/y`
`update_entry_metadata`	Corregir el título, autores, año, DOI, … de una entrada guardada
`merge_entries`	Fusionar dos entradas de una colección en una
`update_tags`	Establecer etiquetas en una colección
`reorder_collection`	Reordenar entradas

Flujo de trabajo típico:

Pegue una lista numerada de citas en import_bibliography (omita collection para una lista pequeña) y conserve el .bib devuelto
O mantenga references.bib / library.bib bajo control de versiones e importe ese archivo a una colección
Use search_collection, check_duplicates y export_collection (bib o csl) mientras revisa
Trate la colección como un compañero de auditoría/exportación, no como la única copia de su bibliografía

Anulaciones locales: la API aún no almacena todos los campos que update_entry_metadata envía, por lo que una copia que se ejecute en su propia máquina (stdio, o serve con auth=none) también guarda cada edición en $XDG_DATA_HOME/ookcite/overrides/<collection>.json y la aplica en export_collection. Un servidor HTTP con sesión iniciada no mantiene anulaciones locales. eid_as=pages coloca los números de artículo donde elsarticle-num los imprime. Consulte docs/local-overrides.md.

Eliminar una sola entrada: llame a search_collection (o check_duplicates) para ver cada coincidencia como entry_id: … (y opcionalmente aliases: doi:… cuando el id almacenado sea opaco). Pase ese entry_id a remove_from_collection, o pase el DOI simple del artículo / doi:10.x/y — el servidor resuelve alias localmente antes de la llamada a la API.

Compartir y operaciones de colección

Herramienta	Propósito
`share_collection`	Crear un enlace compartible
`unshare_collection`	Revocar el uso compartido
`view_shared`	Ver una colección compartida por token
`merge_collections`	Fusionar varias colecciones
`batch_move_entries`	Mover entradas entre colecciones

El uso compartido está disponible para cuentas con sesión iniciada que tengan colecciones. Las cuentas gratuitas pueden importar y añadir en lote dentro de su cuota diaria. Fusionar y mover en lote requieren un plan Académico o de Negocio.

Utilidades

Herramienta	Propósito
`generate_citation_keys`	Claves estilo Better BibTeX para una lista de DOIs
`expand_journal`	Expandir una abreviatura de revista a su nombre completo
`normalize_bibliography`	Re-renderizar BibTeX o RIS como BibTeX canónico

Estas tres requieren un plan Académico o de Negocio.

Planes y precios

Nivel	Precio	Búsquedas/día	Llamadas API/mes	Colecciones	Entradas/colección
Anónimo	Gratis	20	--	0	--
Gratis	Gratis	60	--	4	200
Académico	EUR 4/mes	20,000	10,000	10	1,000
Negocio	EUR 10/mes	20,000	40,000	20	4,000

Las re-búsquedas pueden servirse sin usar cuota cuando los metadatos de la colección ya están disponibles para la API. Una recuperación que tenga que resolver el artículo de nuevo puede contar contra la cuota del plan actual. El pago académico está destinado a estudiantes, investigadores y educadores en instituciones acreditadas; un ORCID verificado también puede calificar una cuenta con sesión iniciada para límites académicos.

Anti-alucinación

Añada esto a su prompt de sistema:

Antes de citar cualquier artículo, use validate_doi para confirmar que la referencia existe. Si la validación falla, no incluya la cita.

Para flujos de trabajo de revisión, añada:

Mantenga la bibliografía del proyecto en un archivo local .bib bajo control de versiones. Use colecciones de OokCite para verificación, deduplicación y exportación.

Cómo funciona

El servidor MCP se conecta a la API pública de OokCite para buscar y formatear citas. Es un envoltorio MCP ligero alrededor de la API REST de OokCite sin base de datos local y sin dependencias pesadas.

Regístrese para una cuenta gratuita (60 búsquedas/día), o actualice a Académico (EUR 4/mes) o Negocio (EUR 10/mes) para mayores límites mensuales de API, colecciones más grandes, utilidades de pago, fusión y movimiento en lote.

Estructura del código fuente

El crate es un envoltorio MCP (stdio) ligero alrededor de la API REST pública de OokCite. No hay base de datos de citas local; todo el estado vive en la API, excepto las anulaciones de metadatos por colección descritas en docs/local-overrides.md.

Ruta	Rol
`src/main.rs`	Entrada binaria: `--version`, `setup`, iniciar servidor MCP
`src/cli.rs`	Sondeos de inicio (validar `OOKCITE_API_KEY` vía `/api/v1/me`, comprobación de actualizaciones)
`src/setup.rs`	Instalador de configuración de cliente `ookcite-mcp setup` / `npx add-mcp`
`src/server.rs`	Manejadores de herramientas MCP `Server` + `#[tool_router]` (más pruebas unitarias al final)
`src/tool_args.rs`	Estructuras de argumentos de herramientas (`serde` + `schemars`)
`src/constants.rs`	URL base de la API, versión del paquete, umbral de confianza de búsqueda inversa
`src/http_error.rs`	`error_detail` y clasificación de estado HTTP para cadenas orientadas al cliente
`src/collection_entries.rs`	IDs de entradas de colección, resolución de alias DOI simple / `doi:`, líneas de búsqueda
`src/plaintext.rs`	División de listas pegadas y renderizado local de `.bib`
`src/bib_export.rs`	BibTeX de colección a partir de registros del proveedor, campos almacenados y limpieza de texto
`src/overrides.rs`	Anulaciones locales de metadatos por colección aplicadas en la exportación
`src/resolve_helpers.rs`	Ayudantes de carga útil para búsqueda inversa y resolución de texto libre
`src/endpoints.rs`	Registro de endpoints (superficie del crate `lib`); probado por contrato
`src/lib.rs`	Raíz de la biblioteca (exporta solo `endpoints`)
`tests/api_contract.rs`	Descifra `contract/openapi.json.age`; verifica que cada endpoint exista
`contract/`	Instantánea OpenAPI cifrada con Age + `regen.sh`
`npm/`	Instalador/envoltorio de `@turtletech/ookcite-mcp` (descarga el binario de la versión)
`demo/`	Scripts de grabación de Asciinema
catálogo de marketplace	Lista `ookcite` de `./plugins/ookcite`
`plugins/ookcite/`	Manifiesto del plugin, URL MCP alojada, tres habilidades
`scripts/set-version.sh`	Gancho previo a bump de Cocogitto: versiones de paquete, registro y plugin

Colecciones / IDs de entradas: search_collection y check_duplicates emiten líneas entry_id: …. remove_from_collection acepta ese id, un DOI simple o doi:10.x/y (resuelto localmente en collection_entries antes de la llamada DELETE).

Lanzamiento: la etiqueta v* ejecuta .github/workflows/release.yml (activos de Release multi-arquitectura de GitHub, crates.io, npm). Los cambios de versión usan cocogitto (cog.toml + scripts/set-version.sh).

Por qué server.rs es grande: las macros #[tool_router] / #[tool] de rmcp mantienen los manejadores en un solo impl Server. Más divisiones de archivos sin soluciones de macros añaden poco valor al usuario; separe pruebas o añada pequeños ayudantes (resolve_many, tipo compartido Me) antes de luchar contra la macro.

Contribuir / comprobaciones locales

cargo test --bin ookcite-mcp          # unit tests (no contract key needed)
cargo build --release
./target/release/ookcite-mcp --version

# Contract tests (optional locally; required in CI with secret):
export OOKCITE_CONTRACT_KEY="value-from-your-credential-manager"
cargo test --test api_contract

Prueba de humo MCP en vivo (opcional; necesita OOKCITE_API_KEY): añadir/buscar/eliminar con un DOI simple en una colección desechable, luego delete_collection.

Documentación

Licencia

MIT. consulte LICENSE.