mcp-atomictoolkit

Un servidor compatible con MCP que proporciona capacidades de simulación atomística a través de ASE, pymatgen, etc.

GitHub
12
Prueba este MCPPatrocinado

Documentación

⚛️ MCP Atomic Toolkit

Python 3.11+ License: MIT MCP tests

[!NOTE] Este proyecto está en desarrollo activo. Las interfaces y el comportamiento pueden evolucionar.

Un servidor FastMCP para flujos de trabajo de modelado atomístico impulsado por ASE, pymatgen y potenciales interatómicos modernos de ML.

Proporciona a los clientes MCP un kit de herramientas práctico para:

  • construir estructuras,
  • ejecutar optimización de geometría + dinámica molecular,
  • analizar estructuras/trayectorias,
  • y descargar artefactos generados (datos + gráficos).

✨ Por qué este repositorio

Si necesitas flujos de trabajo atomísticos expuestos como herramientas MCP (en lugar de escribir scripts manualmente), este proyecto te ofrece:

  • herramientas MCP listas para usar para tareas de simulación comunes,
  • salidas basadas en archivos que son fáciles de inspeccionar/reutilizar,
  • URLs de descarga de artefactos para que los clientes no necesiten blobs binarios en el contexto del chat,
  • aplicación HTTP lista para implementar con endpoints de salud y tarjeta de servidor.

🚀 Características

  • Flujos de trabajo nativos de MCP mediante herramientas FastMCP
  • Generación de estructuras: bulk, superficie, molécula, supercelda, amorfo, líquido, bicristal, policristal
  • Flujos de optimización con MLIPs (kim por defecto, nequix/orb compatibles)
  • Flujos de dinámica molecular (Velocity Verlet, Langevin, NVT Berendsen)
  • Salidas de análisis:
    • RDF + estadísticas de coordinación
    • MSD + tendencias termodinámicas
    • VACF + difusión (Green-Kubo)
  • Artefactos descargables (xyz, extxyz, cif, traj, png, svg, csv, dat, ...)
  • Endpoints compatibles con registros (/healthz, tarjeta de servidor, raíz HTTP Streamable)

⚡ Inicio rápido

1) Requisitos

  • Python 3.11+

2) Instalación

La instalación principal no requiere la API C++ de OpenKIM:

pip install -r requirements.txt

o:

pip install -e .

OpenKIM (kimpy) es opcional. Se compila contra la API KIM del sistema, por lo que una instalación predeterminada solía fallar en máquinas sin libkim-api.

Para habilitar la 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 y luego pip install -e ".[kim]".

Sin el extra, usa calculator_name='auto', 'orb' o 'nequix'. El código en tiempo de ejecución ya recurre a alternativas cuando KIM no está disponible.

3) Ejecutar localmente

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

Alternativa:

python main.py

Modo STDIO (para clientes MCP de escritorio):

python -m mcp_atomictoolkit.mcp_server

[!IMPORTANT] Los transportes STDIO deben mantener stdout limpio para JSON-RPC. Evita print() o registrar en stdout al ejecutar el servidor en modo STDIO.

4) Verificación rápida

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

Respuesta esperada:

{"status":"ok"}

🧰 Resumen de herramientas

Principales herramientas MCP expuestas por el servidor:

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

También se incluyen alias heredados para compatibilidad hacia atrás.

🌐 Endpoints

  • POST / — endpoint principal MCP Streamable HTTP
  • GET /healthz — verificación de salud
  • GET /docs — documentación ligera (README)
  • GET /.well-known/mcp/server-card.json — metadatos de tarjeta de servidor MCP
  • GET /artifacts/{artifact_id}/{filename} — ruta de descarga de artefactos
  • /sse/ — ruta de alias de compatibilidad montada en la aplicación MCP

📦 Implementación

Render

render.yaml está incluido y listo para usar.

Comando de inicio predeterminado:

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

Docker

La imagen instala libkim-api-dev y el extra opcional [kim].

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

🗂️ Estructura del proyecto

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 flujo de trabajo (para clientes MCP)

Cobertura de construcción de estructuras

build_structure_workflow admite:

  • bulk (ASE bulk)
  • superficie (ASE surface)
  • molécula (ASE molecule)
  • supercelda (multiplicación de una estructura base)
  • amorfo/líquido (estructuras empaquetadas aleatoriamente)
  • bicristal y policristal (apilamiento/rotación de granos)

Para interfaces, estructuras dopadas, adsorbatos o láminas personalizadas, prefiere:

  1. Generar la estructura con ASE/pymatgen (o un constructor externo), luego
  2. Usar write_structure_workflow para persistir la geometría final para pasos posteriores.

Esto garantiza que los llamadores MCP puedan manejar estructuras avanzadas incluso cuando se requiere un constructor especializado.

Hoja de referencia de kwargs del constructor

builder_kwargs comunes para build_structure_workflow:

  • superficie: indices, layers, vacuum
  • supercelda: 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

Opciones de optimización

optimize_structure_workflow expone:

  • max_steps, fmax (convergencia)
  • maxstep, alpha (controles de paso/amortiguación BFGS)
  • constraints (fixed_atoms, fixed_bonds, fixed_cell)

Cálculos de punto único

single_point_workflow calcula energía, fuerzas y tensión (si es periódico) sin modificar la estructura, lo que lo hace adecuado para evaluaciones rápidas.

Integradores / conjuntos MD

run_md_workflow admite:

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

Ajusta temperature_K, friction y taut para controlar el comportamiento del termostato.

📈 GitHub Pulse

Historial de estrellas

Star History Chart

🤝 Contribuciones

  • Mantén las salidas basadas en archivos y amigables con artefactos.
  • Al agregar herramientas, generalmente actualiza ambos:
    • workflows/core.py
    • mcp_server.py
  • Preserva el comportamiento de compatibilidad de http_app.py a menos que cambies intencionalmente los contratos de implementación.

📄 Licencia

MIT — consulta LICENSE.