Servidor MCP OPTIMADE

Uma ferramenta de Model Context Protocol (MCP) para consultar bancos de dados de materiais compatíveis com Optimade, totalmente configurável com predefinições de filtro personalizadas e endpoints de provedores.

🎯 Visão Geral

Esta ferramenta permite consultas estruturadas de dados em múltiplos bancos de dados OPTIMADE (ex.: Materials Project, Materials Cloud, COD), via protocolo MCP. As principais capacidades incluem:

Facilmente implantável via uvx, cline
É possível interagir com o cliente em linguagem natural, permitindo que o modelo de linguagem gere o filtro de consulta OPTIMADE.
O JSON retornado pelo OPTIMADE será salvo localmente, e um resumo será gerado durante a interação.

Nota: A consulta requer dois parâmetros. Um é o filtro de consulta optimade, e o outro é o banco de dados a ser consultado.

✨ Recursos

Recursos MCP que o modelo pode ler sob demanda:
- optimade://docs/filters – Gramática de filtros e exemplos (Markdown)
- optimade://spec/queryable_props – Lista de permissões de campos marcados como “Query: MUST be a queryable property …” (JSON)
- optimade://docs/providers – URLs padrão de provedores (JSON, gerado a partir da configuração)
- optimade://docs/filter_presets – Trechos de filtros nomeados (JSON)
- optimade://prompts/ask_for_provider – Prompt de sistema para orientar a seleção de URLs e linting (Texto)
- optimade://results/<uuid> – Dinâmico: JSON completo de consultas anteriores
Ferramentas
- lint_filter(filter) → "ok" / "warn: …" / "syntax error: …"
  (Aviso = não está na lista de permissões, mas permitido; Erro de sintaxe = bloqueado)
- query_optimade(filter, baseUrls?) → pré-visualização (primeiros 5) + link para o recurso JSON completo
- list_providers() → Descobrir endpoints públicos globais OPTIMADE
Fallback de provedor
1. baseUrls fornecido pelo usuário → 2) padrões de configuração → 3) fallback para espelho único (https://optimade.fly.dev)
Pronto para proxy via .env (HTTP_PROXY, HTTPS_PROXY).

🧩 O que o LLM pode ler (Recursos)

URI	Tipo	Finalidade
`optimade://docs/filters`	`text/markdown`	Gramática completa e exemplos
`optimade://spec/queryable_props`	`application/json`	Lista de permissões: campos marcados como “MUST be queryable”
`optimade://docs/providers`	`application/json`	URLs padrão de provedores da configuração
`optimade://docs/filter_presets`	`application/json`	Trechos de filtros nomeados para inspiração
`optimade://prompts/ask_for_provider`	`text/plain`	Prompt de sistema para orientar a escolha de URL e linting
`optimade://results/<uuid>`	`application/json`	Dinâmico: JSON completo de consultas anteriores

Importante: Os recursos não são injetados automaticamente. Seu cliente MCP deve chamar resources/read (ou você configura a inicialização/fluxo de trabalho para lê-los).

⚙️ Instalação e Uso

✅ Recomendado via uv

Instale a ferramenta:

uv pip install optimade-mcp-server

No cline ou em qualquer inicializador compatível com MCP, configure a ferramenta da seguinte forma:

{
  "mcpServers": {
    "optimade_mcp_server": {
      "disabled": false,
      "timeout": 60,
      "type": "stdio",
      "command": "uvx",
      "args": [
        "optimade-mcp-server"
      ]
    }
  }
}

🌐 Suporte a Proxy (Opcional)

Se você precisar usar uma VPN ou proxy, crie um arquivo .env na raiz do projeto:

HTTP_PROXY=http://127.0.0.1:<your-port>
HTTPS_PROXY=http://127.0.0.1:<your-port>

Se você não precisar de proxy, pode comentar ou remover a configuração de proxy no código-fonte.

🪪 Licença

Este projeto está licenciado sob a Licença MIT. Consulte LICENSE para detalhes.

🙋 FAQ

P: Os recursos são injetados automaticamente no contexto do modelo?
R: Não. O cliente deve chamar resources/read (ou configurar uma etapa de inicialização/fluxo de trabalho). O servidor aplica fallback de provedor automaticamente se baseUrls forem omitidos.

P: Posso usar campos que não estão na lista de permissões?
R: Sim. lint_filter retorna warn: band_gap. O modelo deve mostrar um aviso e pedir sua confirmação antes de consultar.

P: Como exporto o resultado completo?
R: O servidor sempre salva um JSON completo em optimade://results/<uuid>.

OPTIMADE MCP Server

Documentação