Ookcite MCP

Valide DOIs em um banco de dados real de citações, formate referências em mais de 2900 estilos CSL (APA, IEEE, Chicago, Nature, etc.) e identifique referências acadêmicas alucinadas antes que cheguem ao seu artigo, documentação ou apresentação. Gerencie coleções de citações, importe/exporte BibTeX e processe referências em lote. 29 ferramentas.

GitHub

Documentação

Servidor MCP OokCite

Dê a ferramentas compatíveis com MCP a capacidade de validar DOIs, formatar citações, gerenciar coleções bibliográficas e detectar referências fabricadas. Retorna apenas metadados de citação — não PDFs ou artigos em texto completo. Clientes desktop podem executá-lo via entrada e saída padrão. Clientes remotos usam https://ookcite-api.turtletech.us/mcp.

Início Rápido

Um comando para instalar e configurar:

npx @turtletech/ookcite-mcp setup

Isso detecta automaticamente clientes MCP compatíveis e escreve a configuração para você. Conecte uma conta OokCite para limites de taxa mais altos e ferramentas de coleção sem colocar uma chave de API em argumentos de shell ou configuração MCP:

npx @turtletech/ookcite-mcp setup --connect

O comando abre o painel TurtleTech, cria ou ativa o plano Free, armazena a chave emitida no armazenamento de credenciais da plataforma e escreve apenas uma referência de credencial para os clientes detectados. Use setup --connect --device em uma máquina sem cabeça.

Uma chave de API existente continua suportada:

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

Nenhuma chave de API é necessária para uso básico (20 consultas/dia): format_citation e um pequeno import_bibliography em texto simples (omitindo collection, até 8 itens). Inscreva-se para mais.

Cole uma lista em BibTeX

import_bibliography aceita uma lista de citações numerada ou separada por linhas em branco, não apenas .bib / .ris. Omita collection para uma pequena colagem: a ferramenta resolve os itens e retorna texto .bib. Com uma chave, passe collection para salvar as entradas resolvidas. export_collection pode então emitir .bib (format=bib) ou texto de bibliografia CSL (format=csl ou um id de estilo como ieee). npx @turtletech/ookcite-mcp setup continua sendo o instalador. O servidor nunca busca PDFs.

Após alterar a configuração MCP, reinicie o cliente ou recarregue seus servidores MCP. Muitos clientes não recarregam a quente mudanças de variáveis de ambiente para servidores stdio já em execução.

Instalação (Métodos Alternativos)

npm (recomendado):

npm install -g @turtletech/ookcite-mcp

cargo-binstall (mais rápido, sem Node.js):

cargo binstall ookcite-mcp

cargo install (a partir do código-fonte):

cargo install ookcite-mcp

Binários pré-compilados: Baixe de GitHub Releases para Linux (x86_64, aarch64), macOS (x86_64, aarch64) e Windows.

Configuração

Se você usou setup, está pronto. Caso contrário, adicione à configuração do seu cliente MCP:

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

Com uma chave de API:

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

Se você instalou globalmente (npm install -g ou cargo install), pode usar "command": "ookcite-mcp" diretamente em vez de npx.

Mantendo a chave fora do arquivo de configuração

setup --connect usa o armazenamento de credenciais da plataforma por padrão. Ele se recusa a substituir uma credencial de plataforma existente ou uma configuração nomeada do OokCite MCP a menos que --replace-credential ou --replace-config seja fornecido explicitamente.

Um gerenciador de credenciais genérico pode ser usado em vez disso. O comando de armazenamento recebe a nova chave na entrada padrão; ele não deve esperar a chave em um argumento de linha de comando. O comando de recuperação imprime a chave na saída padrão quando o servidor MCP inicia:

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

Para um arquivo explícito somente do proprietário em vez de um gerenciador de credenciais:

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

O arquivo é criado com permissões somente do proprietário e nunca é sobrescrito. As formas de plataforma, comando auxiliar e arquivo colocam referências como estas na configuração do cliente:

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

Na inicialização, a precedência da fonte permanece OOKCITE_API_KEY, OOKCITE_API_KEY_COMMAND, OOKCITE_API_KEY_FILE, e então a referência de credencial da plataforma. Com nenhuma delas, o servidor inicia anônimo. setup --key permanece disponível para implantações existentes que intencionalmente mantêm a chave na configuração do cliente.

A recuperação de credenciais obedece a duas restrições:

A recuperação recebe entrada padrão fechada, então não pode consumir MCP JSON-RPC.
A recuperação é limitada por OOKCITE_API_KEY_TIMEOUT, que tem como padrão 10 segundos, e sua saída nunca é copiada para diagnósticos.

Consulte a documentação MCP do seu cliente para a localização do arquivo de configuração. Use o JSON mcpServers.ookcite acima quando a configuração automática não estiver disponível, então reinicie o cliente ou recarregue seus servidores MCP.

Env opcional (stdio MCP, todos os clientes):

Variável	Finalidade
`OOKCITE_API_KEY`	Limites de taxa mais altos + ferramentas de coleção (opcional para consulta/formatação básica)
`OOKCITE_API`	Substituir URL base da API (padrão `https://ookcite-api.turtletech.us`)
`OOKCITE_MCP_READ_ONLY`	`1` desativa permanentemente mutações de coleção (revisão / automação de CI)
`OOKCITE_MCP_ALLOW_MUTATE`	`0` nega mutações; não definido ou `1` permite (chave de API ainda necessária no servidor)
`OOKCITE_STARTUP_PROBES`	`1` executa verificações de autenticação + atualização npm no stderr antes de aceitar conexões MCP (padrão desligado para conexão mais rápida)
`OOKCITE_API_KEY_COMMAND`	Comando que imprime a chave no stdout; stdin está fechado
`OOKCITE_API_KEY_FILE`	Arquivo protegido do proprietário cuja primeira linha é a chave
`OOKCITE_API_KEY_TIMEOUT`	Segundos permitidos para recuperação de credenciais (padrão 10)
`OOKCITE_CREDENTIAL_STORE`	`platform` para carregar uma referência de credencial de plataforma
`OOKCITE_CREDENTIAL_SERVICE`	Nome do serviço de credencial de plataforma (padrão `ookcite-mcp`)
`OOKCITE_CREDENTIAL_ACCOUNT`	Nome da conta de credencial de plataforma (padrão `default`)

Plugin de marketplace

OokCite instala de duas maneiras.

A partir deste repositório, adicione o marketplace TurtleTech-ehf/ookcite-mcp e instale ookcite@ookcite. Isso registra o marketplace ookcite e habilita o plugin em plugins/ookcite. O plugin conecta-se a https://ookcite-api.turtletech.us/mcp e adiciona três habilidades: formatar uma bibliografia colada (/ookcite:format-bibliography), verificar referências antes da submissão (/ookcite:verify-references) e construir e exportar uma coleção (/ookcite:build-collection). Entre quando solicitado. Formatar uma citação e verificar uma lista curta de DOIs também funciona antes do login, dentro do limite diário anônimo. Salvar uma coleção requer a conta conectada.

Os aplicativos web, desktop e cowork usam o mesmo endereço como um conector de diretório. Escolha entrar. Submeta o conector por essa URL e submeta a pasta plugins/ookcite como o pacote do plugin. Instalar a partir do marketplace não submete nenhuma das listagens.

Um conector remoto não precisa suportar registro dinâmico de cliente. O plugin envia o id de cliente público pré-registrado ookcite-remote, então o cliente de código não chama um endpoint de registro. A descoberta para esse cliente publica S256 PKCE e nenhum registration_endpoint. O recurso protegido lista o emissor desse cliente primeiro, e seu campo resource é https://ookcite-api.turtletech.us/mcp. O cliente aceita o callback de diretório exatamente, e redirecionamentos de loopback em localhost e 127.0.0.1 em qualquer porta. Tokens de acesso devem satisfazer exp - iat <= 3600 ou o servidor de recursos os rejeita.

MCP Remoto

Use OokCite de um produto de chat sem instalar nada. Adicione este endereço, escolha entrar e aprove o login quando solicitado:

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

O chat então envia um token de acesso de curta duração:

Authorization: Bearer <access token>

As consultas contam contra essa conta conectada. Uma chave de API colada é rejeitada. O transporte é Streamable HTTP sem estado: um POST, JSON na entrada e JSON na saída. Selecione Streamable HTTP e entrar (OAuth). Não selecione o transporte SSE legado, uma chave de API ou "Sem autenticação".

eduGenAI Chat, após ookcite-api.turtletech.us ser colocado na lista de permissões:

Campo	Valor
Nome	OokCite
Descrição	Verifique DOIs e ISBNs, resolva citações confusas e formate entradas de bibliografia em estilos CSL. Retorna apenas metadados de citação, não PDFs ou texto completo.
URL	`https://ookcite-api.turtletech.us/mcp`
Transporte	Streamable HTTP
Autenticação	OAuth

ookcite-mcp serve executa sua própria cópia. Clientes desktop que iniciam um subprocesso ainda usam entrada e saída padrão.

Variável	Finalidade
`OOKCITE_API`	URL base da API OokCite (padrão `https://ookcite-api.turtletech.us`)
`OOKCITE_MCP_HTTP_AUTH`	`oauth` para entrar, `bearer` para sua própria cópia, ou `none`
`OOKCITE_MCP_OIDC_ISSUER`	Emissor de entrada. Necessário quando a autenticação é `oauth`
`OOKCITE_MCP_OIDC_AUDIENCE`	Público do token. Necessário quando a autenticação é `oauth`
`OOKCITE_MCP_OIDC_SCOPE`	Escopo necessário (padrão `openid`)
`OOKCITE_MCP_PATH`	Caminho MCP (padrão `/mcp`)
`OOKCITE_MCP_ALLOWED_HOSTS`	Nomes extras de `Host`, separados por vírgula. Loopback é sempre permitido
`OOKCITE_MCP_ALLOWED_ORIGINS`	Valores de `Origin` do navegador que podem chamar o endpoint. Uma Origin ausente é permitida

Dicas de uso do MCP

Prefira ferramentas em lote (verify_references, batch_format, batch_add_to_collection, import_bibliography) em vez de muitas chamadas de citação única.
Mutações de coleção exigem a conta conectada, ou OOKCITE_API_KEY em uma cópia que você mesmo executa. Ferramentas destrutivas (delete_collection, remove_from_collection, unshare_collection) são anotadas para clientes que honram dicas de ferramentas MCP.
O servidor escreve diagnósticos no stderr apenas no caminho MCP; stdout é reservado para JSON-RPC.

Ferramentas

Consulta e Validação

Ferramenta	Finalidade
`validate_doi`	Verificar se um DOI existe (anti-alucinação)
`lookup_isbn`	Consultar um livro por ISBN
`reverse_lookup`	Encontrar um artigo a partir de texto de citação confuso; retorna consulta original, confiança e título
`batch_resolve`	Resolver muitas strings de citação em uma única solicitação (máx. 50)
`enhanced_search`	Busca no corpus com facetas de autor / categoria / citação
`health_check`	Verificar disponibilidade e saúde da API

Formatação

Ferramenta	Finalidade
`format_citation`	Formatar um DOI em qualquer um dos 2900+ estilos CSL (sem chave de API para uma única citação)
`verify_references`	Verificação em lote de DOIs e qualquer alegação bibliográfica passada com eles
`batch_format`	Formatar múltiplas citações de uma vez
`search_styles`	Encontrar ids de estilo CSL por nome
`list_styles`	Navegar pela lista completa de estilos CSL
`group_cite`	Gerar marcadores no texto agrupados (ex.: [1-3])

Conta

Ferramenta	Finalidade
`usage`	Plano em vigor mais consultas diárias (e mensais) restantes

ORCID

Ferramenta	Finalidade
`orcid_search`	Encontrar perfis ORCID por nome, afiliação ou id ORCID
`orcid_profile`	Buscar um perfil ORCID por id
`ingest_orcid`	Indexar as publicações do perfil ORCID de um perfil para que sejam pesquisáveis

Coleções (requer login)

Coleções são um recurso para contas conectadas. O servidor hospedado usa a conta do login. Uma cópia que você mesmo executa usa OOKCITE_API_KEY. Um pequeno import_bibliography em texto simples sem collection é a exceção: retorna .bib sob o limite anônimo.

Ferramenta	Finalidade
`list_collections`	Listar coleções de citações salvas
`add_to_collection`	Adicionar uma citação (por DOI ou texto livre)
`batch_add_to_collection`	Adicionar várias citações de uma vez
`import_bibliography`	Importar BibTeX, RIS ou uma lista de texto puro colada
`export_collection`	Exportar coleção como texto BibTeX ou CSL
`search_collection`	Pesquisar dentro de uma coleção; retorna `entry_id` por correspondência
`check_duplicates`	Verificar duplicatas; retorna `entry_id` para correspondências
`delete_collection`	Excluir uma coleção
`update_collection`	Atualizar nome, descrição ou estilo
`remove_from_collection`	Remover uma entrada por `entry_id`, DOI simples ou `doi:10.x/y`
`update_entry_metadata`	Corrigir título, autores, ano, DOI, … de uma entrada salva
`merge_entries`	Mesclar duas entradas de uma coleção em uma
`update_tags`	Definir tags em uma coleção
`reorder_collection`	Reordenar entradas

Fluxo de trabalho típico:

Cole uma lista numerada de citações em import_bibliography (omitir collection para uma lista pequena) e guarde o .bib retornado
Ou mantenha references.bib / library.bib sob controle de versão e importe esse arquivo para uma coleção
Use search_collection, check_duplicates e export_collection (bib ou csl) durante a revisão
Trate a coleção como um companheiro de auditoria/exportação, não como a única cópia da sua bibliografia

Substituições locais: a API ainda não armazena todos os campos que update_entry_metadata envia, então uma cópia executada na sua própria máquina (stdio, ou serve com auth=none) também mantém cada edição em $XDG_DATA_HOME/ookcite/overrides/<collection>.json e a aplica em export_collection. Um servidor HTTP com login não mantém substituições locais. eid_as=pages coloca números de artigo onde elsarticle-num os imprime. Veja docs/local-overrides.md.

Removendo uma única entrada: chame search_collection (ou check_duplicates) para ver cada resultado como entry_id: … (e opcionalmente aliases: doi:… quando o id armazenado for opaco). Passe esse entry_id para remove_from_collection, ou passe o DOI simples do artigo / doi:10.x/y — o servidor resolve aliases localmente antes da chamada à API.

Compartilhamento e Operações de Coleção

Ferramenta	Finalidade
`share_collection`	Criar um link compartilhável
`unshare_collection`	Revogar compartilhamento
`view_shared`	Visualizar uma coleção compartilhada por token
`merge_collections`	Mesclar várias coleções
`batch_move_entries`	Mover entradas entre coleções

O compartilhamento está disponível para contas com login que possuem coleções. Contas gratuitas podem importar e adicionar em lote dentro da cota diária. Mesclar e mover em lote exigem um plano Acadêmico ou Empresarial.

Utilitários

Ferramenta	Finalidade
`generate_citation_keys`	Chaves estilo Better BibTeX para uma lista de DOIs
`expand_journal`	Expandir uma abreviação de periódico para o nome completo
`normalize_bibliography`	Re-renderizar BibTeX ou RIS como BibTeX canônico

Esses três exigem um plano Acadêmico ou Empresarial.

Planos e Preços

Nível	Preço	Consultas/dia	Chamadas de API/mês	Coleções	Entradas/coleção
Anônimo	Grátis	20	--	0	--
Grátis	Grátis	60	--	4	200
Acadêmico	EUR 4/mês	20.000	10.000	10	1.000
Empresarial	EUR 10/mês	20.000	40.000	20	4.000

Reconsultas podem ser atendidas sem uso de cota quando os metadados da coleção já estão disponíveis para a API. Uma recuperação que precise resolver o artigo novamente pode contar contra a cota do plano atual. A compra do plano Acadêmico pago é destinada a estudantes, pesquisadores e educadores em instituições credenciadas; um ORCID verificado também pode qualificar uma conta com login para os limites Acadêmicos.

Anti-Alucinação

Adicione isto ao seu prompt de sistema:

Antes de citar qualquer artigo, use validate_doi para confirmar que a referência existe. Se a validação falhar, não inclua a citação.

Para fluxos de revisão, adicione:

Mantenha a bibliografia do projeto em um arquivo local .bib sob controle de versão. Use coleções OokCite para verificação, deduplicação e exportação.

Como Funciona

O servidor MCP conecta-se à API pública OokCite para pesquisar e formatar citações. É um wrapper MCP leve em torno da API REST OokCite, sem banco de dados local e sem dependências pesadas.

Cadastre-se para uma conta gratuita (60 consultas/dia), ou atualize para Acadêmico (EUR 4/mês) ou Empresarial (EUR 10/mês) para limites mensais de API mais altos, coleções maiores, utilitários pagos, mesclagem e movimentação em lote.

Estrutura do código-fonte

O crate é um wrapper MCP fino (stdio) em torno da API REST pública OokCite. Não há banco de dados local de citações; todo o estado vive na API, exceto as substituições de metadados por coleção descritas em docs/local-overrides.md.

Caminho	Função
`src/main.rs`	Entrada binária: `--version`, `setup`, iniciar servidor MCP
`src/cli.rs`	Sondagens de inicialização (validar `OOKCITE_API_KEY` via `/api/v1/me`, verificação de atualização)
`src/setup.rs`	Instalador de configuração do cliente `ookcite-mcp setup` / `npx add-mcp`
`src/server.rs`	Manipuladores de ferramentas MCP `Server` + `#[tool_router]` (mais testes unitários no final)
`src/tool_args.rs`	Estruturas de argumentos de ferramentas (`serde` + `schemars`)
`src/constants.rs`	URL base da API, versão do pacote, limite de confiança para pesquisa reversa
`src/http_error.rs`	`error_detail` e classificação de status HTTP para mensagens voltadas ao cliente
`src/collection_entries.rs`	IDs de entradas de coleção, resolução de alias DOI simples / `doi:`, linhas de pesquisa
`src/plaintext.rs`	Divisão de lista colada e renderização local de `.bib`
`src/bib_export.rs`	BibTeX de coleção a partir de registros do provedor, campos armazenados e limpeza de texto
`src/overrides.rs`	Substituições locais de metadados por coleção aplicadas na exportação
`src/resolve_helpers.rs`	Auxiliares de payload para pesquisa reversa e resolução de texto livre
`src/endpoints.rs`	Registro de endpoints (superfície do crate `lib`); testado por contrato
`src/lib.rs`	Raiz da biblioteca (exporta apenas `endpoints`)
`tests/api_contract.rs`	Descriptografa `contract/openapi.json.age`; verifica se todos os endpoints existem
`contract/`	Snapshot OpenAPI criptografado com Age + `regen.sh`
`npm/`	Instalador/empacotador `@turtletech/ookcite-mcp` (baixa binário de release)
`demo/`	Scripts de gravação Asciinema
catálogo do marketplace	Lista `ookcite` de `./plugins/ookcite`
`plugins/ookcite/`	Manifesto do plugin, URL MCP hospedada, três habilidades
`scripts/set-version.sh`	Gancho pré-bump Cocogitto: versões do pacote, registro e plugin

Coleções / IDs de entradas: search_collection e check_duplicates emitem linhas entry_id: …. remove_from_collection aceita esse id, um DOI simples ou doi:10.x/y (resolvido localmente em collection_entries antes da chamada DELETE).

Release: a tag v* executa .github/workflows/release.yml (assets de Release multi-arquitetura no GitHub, crates.io, npm). Os incrementos de versão usam cocogitto (cog.toml + scripts/set-version.sh).

Por que server.rs é grande: as macros #[tool_router] / #[tool] de rmcp mantêm os manipuladores em um único impl Server. Mais divisões de arquivos sem soluções alternativas de macro agregam pouco valor ao usuário; remova testes ou adicione pequenos auxiliares (resolve_many, tipo Me compartilhado) antes de lutar contra a macro.

Contribuindo / verificações locais

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

Teste MCP ao vivo (opcional; requer OOKCITE_API_KEY): adicionar/pesquisar/remover com um DOI simples em uma coleção descartável e depois delete_collection.

Documentação

Licença

MIT. veja LICENSE.