mcp-atomictoolkit

Um servidor compatível com MCP que fornece capacidades de simulação atomística através de ASE, pymatgen, etc.

GitHub
12
Experimente este MCPPatrocinado

Documentação

⚛️ MCP Atomic Toolkit

Python 3.11+ License: MIT MCP tests

[!NOTE] Este projeto está em desenvolvimento ativo. Interfaces e comportamentos podem evoluir.

Um servidor FastMCP para fluxos de trabalho de modelagem atomística alimentado por ASE, pymatgen e potenciais interatômicos modernos de ML.

Ele oferece aos clientes MCP um kit de ferramentas prático para:

  • construir estruturas,
  • executar otimização de geometria + dinâmica molecular,
  • analisar estruturas/trajetórias,
  • e baixar artefatos gerados (dados + gráficos).

✨ Por que este repositório

Se você precisa de fluxos de trabalho atomísticos expostos como ferramentas MCP (em vez de escrever scripts manualmente), este projeto oferece:

  • ferramentas MCP prontas para uso para tarefas comuns de simulação,
  • saídas baseadas em arquivos fáceis de inspecionar/reutilizar,
  • URLs de download de artefatos para que os clientes não precisem de blobs binários no contexto do chat,
  • aplicativo HTTP pronto para implantação com endpoints de saúde e cartão de servidor.

🚀 Recursos

  • Fluxos de trabalho nativos MCP via ferramentas FastMCP
  • Geração de estruturas: bulk, superfície, molécula, supercélula, amorfo, líquido, bicristal, policristal
  • Fluxos de otimização com MLIPs (kim padrão, nequix/orb suportados)
  • Fluxos de dinâmica molecular (Velocity Verlet, Langevin, NVT Berendsen)
  • Saídas de análise:
    • RDF + estatísticas de coordenação
    • MSD + tendências termodinâmicas
    • VACF + difusão (Green-Kubo)
  • Artefatos para download (xyz, extxyz, cif, traj, png, svg, csv, dat, ...)
  • Endpoints compatíveis com registro (/healthz, cartão de servidor, raiz HTTP Streamable)

⚡ Início Rápido

1) Requisitos

  • Python 3.11+

2) Instalação

A instalação principal não requer a API C++ do OpenKIM:

pip install -r requirements.txt

ou:

pip install -e .

OpenKIM (kimpy) é opcional. Ele compila contra a API KIM do sistema, então uma instalação padrão costumava falhar em máquinas sem libkim-api.

Para habilitar a calculadora KIM:

# Debian/Ubuntu
sudo apt-get install -y libkim-api-dev pkg-config

pip install -e ".[kim]"

macOS (Homebrew): brew install openkim-models kim-api e depois pip install -e ".[kim]".

Sem o extra, use calculator_name='auto', 'orb' ou 'nequix'. O código em tempo de execução já faz fallback quando o KIM está ausente.

3) Executar localmente

uvicorn mcp_atomictoolkit.http_app:app --host 0.0.0.0 --port 10000

Alternativa:

python main.py

Modo STDIO (para clientes MCP de desktop):

python -m mcp_atomictoolkit.mcp_server

[!IMPORTANT] Transportes STDIO devem manter o stdout limpo para JSON-RPC. Evite print() ou registro em stdout ao executar o servidor em modo STDIO.

4) Verificação rápida

curl -s http://localhost:10000/healthz

Resposta esperada:

{"status":"ok"}

🧰 Visão Geral das Ferramentas

Principais ferramentas MCP expostas pelo servidor:

  • build_structure_workflow
  • analyze_structure_workflow
  • write_structure_workflow
  • optimize_structure_workflow
  • single_point_workflow
  • run_md_workflow
  • analyze_trajectory_workflow
  • autocorrelation_workflow

Aliases legados também são incluídos para compatibilidade retroativa.

🌐 Endpoints

  • POST / — endpoint principal MCP Streamable HTTP
  • GET /healthz — verificação de saúde
  • GET /docs — documentação leve (README)
  • GET /.well-known/mcp/server-card.json — metadados do cartão do servidor MCP
  • GET /artifacts/{artifact_id}/{filename} — rota de download de artefatos
  • /sse/ — caminho de alias de compatibilidade montado no aplicativo MCP

📦 Implantação

Render

render.yaml está incluído e pronto para uso.

Comando de início padrão:

uvicorn mcp_atomictoolkit.http_app:app --host 0.0.0.0 --port $PORT

Docker

A imagem instala libkim-api-dev e o extra opcional [kim].

docker build -t mcp-atomictoolkit .
docker run --rm -p 7860:7860 mcp-atomictoolkit

🗂️ Estrutura do Projeto

src/mcp_atomictoolkit/
  mcp_server.py          # FastMCP tool definitions
  http_app.py            # Starlette app + routing/endpoints
  workflows/core.py      # High-level workflow orchestration
  analysis/              # Structure/trajectory/VACF analysis logic
  structure_operations.py
  optimizers.py
  md_runner.py
  artifact_store.py      # Download artifact registration + URLs

🧪 Notas de Fluxo de Trabalho (para clientes MCP)

Cobertura de construção de estruturas

build_structure_workflow suporta:

  • bulk (ASE bulk)
  • superfície (ASE surface)
  • molécula (ASE molecule)
  • supercélula (multiplicação de uma estrutura base)
  • amorfo/líquido (estruturas empacotadas aleatoriamente)
  • bicristal e policristal (empilhamento/rotação de grãos)

Para interfaces, estruturas dopadas, adsorvatos ou slabs personalizados, prefira:

  1. Gerar a estrutura com ASE/pymatgen (ou um construtor externo) e depois
  2. Usar write_structure_workflow para persistir a geometria final para etapas subsequentes.

Isso garante que chamadores MCP ainda possam lidar com estruturas avançadas mesmo quando um construtor especializado for necessário.

Folha de referência de kwargs do construtor

builder_kwargs comuns para build_structure_workflow:

  • superfície: indices, layers, vacuum
  • supercélula: size, base_structure_type, base_crystal_system, base_lattice_constant, base_kwargs
  • amorfo/líquido: num_atoms, box_length, relax, relax_steps, relax_fmax
  • bicristal: grain_size, interface_axis, rotation_angle, rotation_axis, interface_gap
  • policristal: num_grains, grain_size, rotation_angle

Opções de otimização

optimize_structure_workflow expõe:

  • max_steps, fmax (convergência)
  • maxstep, alpha (controles de passo/amortecimento BFGS)
  • constraints (fixed_atoms, fixed_bonds, fixed_cell)

Cálculos de ponto único

single_point_workflow calcula energia, forças e tensão (se periódico) sem modificar a estrutura, tornando-o adequado para avaliações rápidas.

Integradores / ensembles de DM

run_md_workflow suporta:

  • velocityverlet / nve (NVE)
  • langevin / nvt-langevin (NVT)
  • nvt / nvt-berendsen (NVT)

Ajuste temperature_K, friction e taut para controlar o comportamento do termostato.

📈 GitHub Pulse

Histórico de estrelas

Star History Chart

🤝 Contribuindo

  • Mantenha as saídas baseadas em arquivos e amigáveis a artefatos.
  • Ao adicionar ferramentas, geralmente atualize ambos:
    • workflows/core.py
    • mcp_server.py
  • Preserve o comportamento de compatibilidade http_app.py a menos que altere intencionalmente os contratos de implantação.

📄 Licença

MIT — veja LICENSE.