infinitebacklog-mcp

Servidor MCP Infinite Backlog

Este é um servidor Model Context Protocol para o Infinite Backlog, o rastreador de coleções gratuito. O Infinite Backlog não possui uma API pública de escrita, então as ferramentas controlam uma janela Playwright Chromium. Depois que você fizer login, os extras aninhados ainda podem ser verificados com um GET /api/user_collections somente leitura.

Se você é um assistente chamando as ferramentas, leia AGENTS.md.

Fazer login

Você faz login uma vez. Depois disso, a mesma janela lembra de você. Seus cookies do Brave, Chrome ou Edge não são usados.

• Na janela. Deixe o nome de usuário e a senha vazios. Uma janela do navegador abre. Faça login lá você mesmo.
• Em um arquivo. Copie .env.example para .env nesta pasta. Coloque seu nome de usuário ou e-mail em IB_USERNAME, e sua senha em IB_PASSWORD.

O que você pode fazer

• Pesquisar no catálogo de jogos
• Atualizar sua coleção
• Definir avaliações e escrever resenhas
• Manter registros de jogo
• Adicionar DLC, pacotes e outros extras a um jogo que você já possui

Ferramentas

Determinísticas (sempre disponíveis)

Nome	Descrição	Entradas principais
open_site	Abre um caminho do Infinite Backlog na janela Playwright deste servidor. headless=false mostra a janela para que você possa fazer login uma vez.	path, wait_ms, headless
search_games	Pesquisa no catálogo de jogos.	query, wait_ms
get_page_text	Extrai o texto visível da página.	max_chars
get_page_html	Lê o HTML de um seletor (padrão body).	selector, max_chars
get_links	Lista links na página atual.	max_links
click	Clica por seletor CSS ou text=... em uma página do Infinite Backlog. Bloqueado para DELETE GAME, DELETE DRAFT, YES/NO e UNLOCK CUSTOM TAGS.	selector, wait_ms
fill	Preenche um campo de entrada. Recusa seletores de senha e credenciais.	selector, value
evaluate_js	JavaScript de página apenas para depuração. Desabilitado a menos que IB_ALLOW_EVAL_JS=true.	expression
screenshot	Salva um PNG no diretório infinitebacklog-mcp temporário do SO (o caminho é restrito).	path, full_page
login	Digita IB_USERNAME e IB_PASSWORD no formulário de login. Se algum estiver ausente, nada é digitado.	headless
current_url	Retorna a URL e o título atuais.	nenhuma
close_browser	Fecha a janela do Playwright. Brave, Chrome e Edge permanecem abertos.	nenhuma
list_related_content	Lista DLC relacionados, pacotes, edições e extras em uma página de jogo.	game_slug, wait_ms
list_collection_content_menus	Lê Adicionar DLC, DLC possuídos, caixas de complementos e o texto GAME EDITION em um formulário de edição (requer login).	edit_path, wait_ms
add_game_content	Anexa extras aninhados no formulário de edição do item pai. Marca os inputs addon-*, não o rótulo.	parent_slug, names, collection_id
list_collection_game_options	Lê cópias, controle de plataformas extras, progresso, aquisição, avaliações, resenhas e Registros de Jogo (sem salvar).	slug, collection_id
set_game_rating	Define ou limpa a nota geral de 1 a 10, além de Visual / Jogabilidade / História / Áudio / Jogabilidade.	slug, score, sub-avaliações, clear
add_game_review	Rascunha ou publica em /games/{slug}/add-review. Publicar exige 800+ caracteres.	slug, body, publish, title
delete_game_review	Exclui uma resenha rascunho. Resenhas publicadas estão fora do escopo, a menos que sejam nomeadas.	slug, confirm, published
add_game_platform_copy	Adiciona outra cópia de GAME INFORMATION via button.extra-platform.	slug, platform, digital, submit
set_game_progress	Define o status por cópia, conclusão, barra de 0 a 100 e notas.	slug, collection_id, status, completion, progress, notes, clear_fields
set_game_acquisition	Define ou limpa ACQUISITION INFO (tipo, fonte, data, valor, custos, notas, Digital Service).	slug, collection_id, campos de aquisição, clear_fields
delete_game_copy	Exclui uma cópia salva. Clica no único botão DELETE GAME FOR {platform} e depois em YES.	collection_id (obrigatório), confirm=true (obrigatório)
list_play_records	Lê as categorias de Registros de Jogo em /edit/stats.	slug, collection_id
set_play_record_category	Adiciona uma categoria (keyValue / checkbox / progress / table).	slug, name, type, layout
set_play_record	Adiciona ou atualiza uma linha dentro de uma categoria.	slug, category, action, name, value
remove_play_record	Remove uma linha, ou uma categoria inteira com confirm=true.	slug, category, row_index, confirm

Autônomas (requer browser-use e uma chave de LLM)

Nome	Descrição	Entradas principais
run_browser_use_task	Objetivo de alto nível apenas em infinitebacklog.net. O agente planeja e executa com visão e DOM. Melhor para fluxos de várias etapas ou frágeis.	task, max_steps, model, headless

Requisitos

• Python 3.11 ou mais recente
• Playwright Chromium
• Um cliente MCP (Cursor, Claude Desktop, VS Code e outros)
• Uma chave de API de LLM apenas ao usar run_browser_use_task

Instalação

cd infinitebacklog-mcp
python -m venv .venv
# Windows: .venv\Scripts\activate
# Unix: source .venv/bin/activate
pip install -e .
python -m playwright install chromium

Agente autônomo opcional:

pip install -e ".[agent]"

Copie .env.example para .env e preencha o que precisar. Não faça commit de .env.

Início rápido

Após a instalação:

infinitebacklog-mcp

Ou como módulo:

python -m infinitebacklog_mcp.server

Desenvolvimento sem instalar o script de console ainda funciona:

python server.py

O nome do servidor MCP é infinitebacklog. O registro vai apenas para stderr, que é o que o transporte stdio exige.

Configuração do cliente MCP

Use o caminho absoluto para este projeto. Trate chaves de API e IB_PASSWORD como segredos. O processo carrega .env do diretório do projeto e não substituirá variáveis que você já definiu.

Comando instalado (estilo Cursor / Claude Desktop):

{
  "mcpServers": {
    "infinitebacklog": {
      "command": "infinitebacklog-mcp",
      "env": {
        "OPENAI_API_KEY": "sk-..."
      }
    }
  }
}

Caminho do módulo (desenvolvimento):

{
  "mcpServers": {
    "infinitebacklog": {
      "command": "python",
      "args": ["-m", "infinitebacklog_mcp.server"],
      "cwd": "/absolute/path/to/infinitebacklog-mcp",
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "IB_USERNAME": "",
        "IB_PASSWORD": ""
      }
    }
  }
}

Inicialização por arquivo legado (ainda suportada):

{
  "mcpServers": {
    "infinitebacklog": {
      "command": "python",
      "args": ["/absolute/path/to/infinitebacklog-mcp/server.py"],
      "env": {
        "OPENAI_API_KEY": "sk-...",
        "IB_USERNAME": "",
        "IB_PASSWORD": ""
      }
    }
  }
}

Páginas públicas funcionam sem sessão. As ferramentas de coleção precisam de um dos dois caminhos de login acima.

Variáveis de ambiente

Variável	Obrigatória	Descrição
OPENAI_API_KEY	Para a ferramenta autônoma (uma das quatro)	Chave OpenAI para run_browser_use_task
ANTHROPIC_API_KEY	Alternativa	Chave Anthropic
GOOGLE_API_KEY	Alternativa	Chave Google
BROWSER_USE_API_KEY	Alternativa	Chave browser-use Cloud
IB_USERNAME	Para login no .env	Nome de usuário ou e-mail para o formulário de login do Infinite Backlog. Deixe em branco para entrar via Playwright.
IB_PASSWORD	Para login no .env	Senha para esse formulário. Deixe em branco para entrar via Playwright. Trate como um segredo.
IB_HEADLESS	Opcional	Modo headless padrão quando uma ferramenta não passa headless (true / false)
IB_VIEWPORT_WIDTH	Opcional	Largura do viewport do Playwright (padrão 1280, limitada)
IB_VIEWPORT_HEIGHT	Opcional	Altura do viewport do Playwright (padrão 800, limitada)
IB_ALLOW_EVAL_JS	Opcional	Ativa a ferramenta de depuração evaluate_js (true / false, padrão false)
IB_CHROMIUM_NO_SANDBOX	Opcional	Passa --no-sandbox para o Chromium (padrão false; apenas containers)

Segurança

• Projeto não oficial. Não afiliado ao Infinite Backlog.
• Navegação, buscas de API na página e run_browser_use_task permanecem em https://infinitebacklog.net. Outras origens são rejeitadas.
• evaluate_js está desativado por padrão. Capturas de tela só podem ser gravadas no diretório infinitebacklog-mcp temporário do SO. O --no-sandbox do Chromium é opcional via IB_CHROMIUM_NO_SANDBOX.
• O fill genérico recusa campos de senha. Apenas login digita IB_PASSWORD, e somente no formulário de login do Infinite Backlog.
• Trate chaves de API e IB_PASSWORD como segredos. Não faça commit de .env.
• Assistentes que usam essas ferramentas devem seguir AGENTS.md.

Desenvolvimento

Estrutura do projeto:

infinitebacklog-mcp/
├── AGENTS.md              # operating brief for MCP client agents
├── src/infinitebacklog_mcp/
│   ├── server.py          # MCPServer, instructions, main()
│   ├── browser.py         # Playwright lifecycle
│   ├── login.py           # Keycloak username/password form
│   ├── config.py          # constants, .env loading
│   ├── security.py        # origin, cookie, path, and identifier allowlists
│   ├── matching.py        # name / kind matching
│   ├── tools/             # deterministic + agent tools
│   └── ...
├── tests/
├── docs/assets/           # README logos
└── server.py              # compatibility shim

Licença

MIT. Veja LICENSE.