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

Prueba este MCPPatrocinado

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. Funciona con clientes que admiten servidores MCP a través de entrada y salida estándar.

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 argumentos de shell o 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). Regístrate para obtener más.

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 de MCP de OokCite nombrada a menos que se proporcione --replace-credential o --replace-config explícitamente.

Se puede usar un administrador 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 se inicia el servidor MCP:

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 administrador 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. Con 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 JSON-RPC de MCP.
La recuperación está limitada por OOKCITE_API_KEY_TIMEOUT, que por defecto es de 10 segundos, y su salida nunca se copia en 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 de 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 definir 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 cuenta de credenciales de plataforma (por defecto `default`)

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 citas individuales.
Las mutaciones de colección requieren OOKCITE_API_KEY. 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
`batch_resolve`	Resuelve muchas cadenas de citas en una solicitud (máx. 50)
`enhanced_search`	Búsqueda en 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
`verify_references`	Comprueba por lotes una lista de DOIs
`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 de usuarios con sesión iniciada. Establece OOKCITE_API_KEY para usar estas herramientas.

Herramienta	Propósito
`list_collections`	Lista las colecciones de citas guardadas
`add_to_collection`	Añade una cita (por DOI o texto libre)
`batch_add_to_collection`	Añade múltiples citas a la vez
`import_bibliography`	Importa archivos BibTeX/RIS a una colección
`export_collection`	Exporta la colección como BibTeX
`search_collection`	Busca dentro de una colección; devuelve `entry_id` por coincidencia
`check_duplicates`	Comprueba duplicados; devuelve `entry_id` para coincidencias
`delete_collection`	Elimina una colección
`update_collection`	Actualiza nombre, descripción o estilo
`remove_from_collection`	Elimina una entrada por `entry_id`, DOI simple o `doi:10.x/y`
`update_entry_metadata`	Corrige el título, autores, año, DOI, … de una entrada guardada
`merge_entries`	Fusiona dos entradas de una colección en una
`update_tags`	Establece etiquetas en una colección
`reorder_collection`	Reordena entradas

Flujo de trabajo típico:

Mantén references.bib o library.bib bajo control de versiones en tu proyecto
Importa ese archivo a una colección de OokCite con import_bibliography
Usa search_collection, check_duplicates y export_collection mientras revisas
Trata la colección como un complemento de auditoría/exportación, no como la única copia de tu bibliografía

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

Operaciones de uso compartido y colección

Herramienta	Propósito
`share_collection`	Crea un enlace compartible
`unshare_collection`	Revoca el uso compartido
`view_shared`	Ve una colección compartida por token
`merge_collections`	Fusiona múltiples colecciones
`batch_move_entries`	Mueve 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 por lotes dentro de su cuota diaria. La fusión y el movimiento por lotes 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`	Expande una abreviatura de revista a su nombre completo
`normalize_bibliography`	Vuelve a renderizar BibTeX o RIS como BibTeX canónico

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

Planes y precios

Nivel	Precio	Consultas/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 reconsultas pueden servirse sin usar la 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 nuevamente 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 a una cuenta con sesión iniciada para los límites Académicos.

Anti-alucinación

Añade esto a tu indicación del sistema:

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

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

Mantén la bibliografía del proyecto en un archivo local .bib bajo control de versiones. Usa 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ístrate para una cuenta gratuita (60 consultas/día), o actualiza a Académico (EUR 4/mes) o Negocio (EUR 10/mes) para límites mensuales de API más altos, colecciones más grandes, utilidades de pago, fusión y movimiento por lotes.

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.

Ruta	Rol
`src/main.rs`	Entrada binaria: `--version`, `setup`, iniciar servidor MCP
`src/cli.rs`	Sondas de inicio (validar `OOKCITE_API_KEY` mediante `/api/v1/me`, verificació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 de `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 API, versión del paquete, umbral de confianza para búsqueda inversa
`src/http_error.rs`	Clasificación de `error_detail` y estado HTTP para cadenas dirigidas 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/resolve_helpers.rs`	Asistentes 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 de OpenAPI cifrada con age + `regen.sh`
`npm/`	Instalador/envoltorio de `@turtletech/ookcite-mcp` (descarga binario de versión)
`demo/`	Scripts de grabación de Asciinema
`scripts/set-version.sh`	Gancho previo a bump de Cocogitto: versión de `Cargo.toml` + `npm/package.json`

Colecciones / IDs de entradas: search_collection y check_duplicates emiten líneas de 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).

Versión: la etiqueta v* ejecuta .github/workflows/release.yml (activos de GitHub Release multi-arquitectura, crates.io, npm). Los incrementos 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. Dividir más archivos sin soluciones de macros añade poco valor al usuario; separa pruebas o añade pequeños ayudantes (resolve_many, tipo compartido Me) antes de luchar contra la macro.

Contribuciones / 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; requiere OOKCITE_API_KEY): añadir/buscar/eliminar con un DOI simple en una colección desechable, luego delete_collection.

Documentación

Licencia

MIT. ver LICENSE.