Adding support for a new AiiDA plugin

aiida-mcp exposes calcjob-specific tools through modules discovered via the aiida_mcp.plugins entry point group. Any installed package can declare one — it does not need to live in this repo. This page walks through adding support for a new one, and the shared helpers in aiida_mcp.plugins that do most of the work for you regardless of where the module lives.

aiida-mcp itself still bundles a module for aiida-mlip under aiida_mcp.plugins, registered through this same entry point mechanism via the entry point declared in aiida-mcp’s own pyproject.toml. aiida-dlpoly and aiida-chemshell instead declare their own modules (aiida_dlpoly.mcp and aiida_chemshell.mcp) directly in their own pyproject.toml files — the real, working examples of the genuinely third-party case. See Registering the module below for both cases.

The plugin contract

A plugin module is any module referenced by an aiida_mcp.plugins entry point that provides two functions:

is_available() -> bool

Return whether the underlying AiiDA plugin package is installed, so the server can decide whether to register its tools. In practice this is almost always a one-liner delegating to aiida_mcp.plugins.calcjob.calcjob_available(), checking one representative entry point.

register(mcp: MCPServer) -> None

Define and register the plugin’s @mcp.tool()-decorated functions on the given server.

aiida_mcp.plugins.register_all() enumerates every aiida_mcp.plugins entry point, loads the module it points at, and calls register(mcp) only if is_available() returns True:

def register_all(mcp: MCPServer) -> list[str]:
    registered = []
    for ep in entry_points(group=ENTRY_POINT_GROUP):
        module = ep.load()
        if module.is_available():
            module.register(mcp)
            registered.append(ep.name)
    return registered

Because is_available() is checked before anything else, a plugin module must be safe to import even when the AiiDA plugin package it wraps is not installed — never import the third-party package at module level. aiida_mcp.plugins.mlip demonstrates this: it imports aiida_mlip only inside the bodies of the functions that need it, so the module (and the rest of the server) still loads cleanly when aiida-mlip is absent.

Shared helpers

A few existing modules do most of the work for you; use them rather than re-implementing their logic.

aiida_mcp.plugins.calcjob
  • calcjob_available() — check an entry point is installed.

  • describe_calcjob() — generically describe a calcjob’s plugin-specific inputs, outputs, exit codes and changed metadata option defaults, straight from its spec(). Every describe_*_calcjob tool in the codebase is a one-line call to this.

  • submit_calcjob() — validate a dict of inputs against the calcjob spec, store any unstored Data inputs, and submit to the daemon. Nothing is stored if validation fails.

  • load_code() — load a code by label or PK, raising a ToolError with a clear message if it does not exist or is ambiguous.

aiida_mcp.plugins.workflow

The WorkChain equivalent of calcjob, for plugins whose user-facing process is a workflow rather than a bare calcjob (e.g. aiida-cif2j’s WannierTB2JWorkChain).

  • workflow_available() — check an aiida.workflows entry point is installed.

  • describe_workflow() — describe a workflow’s plugin-specific outputs and exit codes. Deliberately does not describe inputs: WorkChains commonly build their input namespace via spec.expose_inputs(...) from other processes, producing deeply nested PortNamespace inputs that a flat, generic listing would misrepresent. The workflow’s own submit_* tool and its hand-written docstring are the authoritative description of what it accepts.

  • submit_workflow() — the WorkChain equivalent of submit_calcjob: validate a dict of inputs against the workflow spec, store any unstored Data inputs (including ones nested inside a namespace dict, e.g. from spec.expose_inputs(OtherProcess, namespace="other")), and submit. Use this when the WorkChain’s inputs are plain/namespaced data, the same shape you’d pass directly to submit/run — as aiida-chemshell’s GeometryOptimisationWorkChain is.

Not every WorkChain fits that shape: if its real entry point is a bespoke get_builder_from_protocol-style classmethod that does its own input assembly and validation (as aiida-cif2j’s WannierTB2JWorkChain does), wrap that directly instead — build a ProcessBuilder and submit it — rather than forcing it through submit_workflow.

aiida_mcp.plugins.inputs
  • FileInput — a pydantic model for “give exactly one of path (on the machine running the server), text, or pk (of an existing node)”. ControlInput extends it with a parameters field for building a Dict node inline.

  • build_node() — turn a FileInput/ControlInput into an unstored node (from path/text/parameters) or load an existing one (from pk), checking it is one of the accepted types.

  • load_existing_node() — load a stored node by PK, checking its type, for inputs that can only ever reference an existing node (e.g. a FolderData retrieved by some other calculation) rather than be built fresh from a path or text. build_node’s own pk branch is implemented in terms of this.

Use FileInput/build_node for any input that naturally comes from a file, text, or an existing node. If the underlying AiiDA plugin already ships its own loading helpers with equivalent behaviour (as aiida-mlip does — see When the plugin has its own loaders below), prefer those instead, so you don’t duplicate logic the plugin’s own maintainers keep in sync with their calcjob.

Worked example: a single calcjob

aiida_dlpoly.mcp (in the aiida-dlpoly repository) is the simplest real example: one calcjob, three file-like inputs, two resource options. The shape to follow is:

"""<Plugin name> calcjob tools."""

from typing import Any

from aiida.engine.daemon.client import get_daemon_client
from aiida.manage.configuration import get_profile
from mcp.server.mcpserver import MCPServer
from mcp.server.mcpserver.exceptions import ToolError

from aiida_mcp import connection
from aiida_mcp.plugins.calcjob import (
    calcjob_available,
    describe_calcjob,
    load_code,
    submit_calcjob,
)
from aiida_mcp.plugins.inputs import FileInput, build_node

ENTRY_POINT = "my_plugin"


def is_available() -> bool:
    """Return whether the <plugin> calcjob plugin is installed.

    Returns
    -------
    bool
        True if the ``my_plugin`` entry point is installed.
    """
    return calcjob_available(ENTRY_POINT)


def submit_job(code, some_file: FileInput, num_machines: int = 1, ...) -> dict[str, Any]:
    """Build the inputs for a <plugin> calcjob and submit it to the daemon.

    Parameters
    ----------
    ...

    Returns
    -------
    dict[str, Any]
        The process PK, uuid, label, description, code, input node PKs, and daemon state.
    """
    connection.ensure_profile()

    # validate resources, build the metadata dict (resources/label/description) ...
    inputs = {
        "code": load_code(code),
        "some_file": build_node(some_file, "some_file", "default.txt", (orm.SinglefileData,)),
        "metadata": metadata,
    }

    node = submit_calcjob(ENTRY_POINT, inputs)

    daemon_running = get_daemon_client(get_profile().name).is_daemon_running
    result = {
        "pk": node.pk,
        "uuid": node.uuid,
        "label": node.label,
        "description": node.description,
        "code": inputs["code"].full_label,
        "inputs": {"some_file": inputs["some_file"].pk},
        "daemon_running": daemon_running,
    }
    if not daemon_running:
        result["note"] = "The daemon is not running; the job will wait until it starts."
    return result


def register(mcp: MCPServer) -> None:
    """Register the <plugin> tools on the given MCP server."""

    @mcp.tool()
    def describe_my_plugin_calcjob() -> dict[str, Any]:
        """Describe the <plugin> calcjob: inputs, outputs, exit codes and defaults."""
        return describe_calcjob(ENTRY_POINT)

    @mcp.tool()
    def submit_my_plugin_job(code, some_file: FileInput, num_machines: int = 1, ...) -> dict[str, Any]:
        """Submit a <plugin> calculation to the daemon; creates nodes and starts a job.

        ... (full numpydoc Parameters/Returns — this docstring is sent to MCP clients verbatim)
        """
        return submit_job(code=code, some_file=some_file, num_machines=num_machines, ...)

Note the split between a plain submit_job function and the @mcp.tool()-wrapped submit_my_plugin_job inside register(): the plain function is what tests call directly (so they don’t need a running MCP server or a decorated-function’s quirks), and the tool wrapper is a thin, separately-documented pass-through. Every tool in the codebase follows this split.

Several optional inputs

aiida_chemshell.mcp (in the aiida-chemshell repository) shows the next level up: several optional FileInput/ControlInput and plain scalar inputs. Rather than a long chain of if value is not None: inputs[...] = ... statements inline in submit_job (which quickly trips Ruff’s cyclomatic-complexity check, C901), factor that assembly into a small private helper:

def _optional_inputs(structure_index, structure2, force_field_file, parameters) -> dict[str, Any]:
    inputs: dict[str, Any] = {}
    if structure_index is not None:
        inputs["structure_index"] = orm.Int(structure_index)
    if structure2 is not None:
        inputs["structure2"] = build_node(structure2, "structure2", "structure2.xyz", STRUCTURE_TYPES)
    ...
    for name, value in parameters.items():
        if value is not None:
            inputs[name] = build_node(value, name, f"{name}.json", (orm.Dict,))
    return inputs

submit_job then just does inputs.update(_optional_inputs(...)). The same pattern — a _set_scalar(inputs, name, value, wrapper) one-liner called repeatedly rather than inlined — is used in aiida_mcp.plugins.mlip for its many optional boolean/float/int/str inputs.

Several calcjobs from one module

Some AiiDA plugins expose more than one calcjob entry point from a shared base class (aiida-mlip has four: single point, geometry optimisation, MD and phonons). aiida_mcp.plugins.mlip handles this with one module registering several tools:

  • An ENTRY_POINTS dict mapping short names to entry point strings.

  • A _common_inputs() helper building the inputs every job type shares (code, structure, model, device, resources, metadata), called by every submit_*_job function.

  • A _submit() helper wrapping the shared “call submit_calcjob, build the result dict” logic.

  • One submit_*_job function per entry point, each calling _common_inputs() then adding its own extra inputs.

  • register() registering one describe_*_calcjob and one submit_*_job tool per entry point — eight tools total, from this one module.

When the plugin has its own loaders

Not every input fits FileInput/build_node well. aiida-mlip’s structure and model inputs accept a path, a URL (for model), or the PK of an existing node, but as a single string/int value rather than a {"path": ...}-style object — and aiida_mlip.helpers.help_load already provides load_structure/load_model functions implementing exactly that logic (including caching and deduplicating downloaded models). aiida_mcp.plugins.mlip calls those directly instead of reinventing them:

def _load_structure(structure: str | int) -> orm.StructureData:
    from aiida_mlip.helpers.help_load import load_structure

    try:
        return load_structure(structure)
    except Exception as exc:
        raise ToolError(f"structure: {exc}") from exc

The import is kept inside the function (not at module level) for the same reason as is_available() above: the module must still import cleanly when aiida-mlip is not installed. When a plugin provides loaders or validation of its own, prefer wrapping those over duplicating the logic yourself — you get the same behaviour the plugin’s own CLI/workflows use, and it stays correct if the upstream plugin changes its loading rules.

Registering the module

Once the module exists, declare an aiida_mcp.plugins entry point pointing at it. Where that declaration lives depends on whether the module ships in its own package or is bundled in this repo:

A genuinely third-party AiiDA plugin package (the expected case — e.g. a new aiida-my-plugin package with its own my_package.mcp module) declares the entry point in its own pyproject.toml:

[project.entry-points."aiida_mcp.plugins"]
my_plugin = "my_package.mcp"

No change to aiida-mcp itself is needed — the package just needs to be installed (or reinstalled, so its entry point metadata is regenerated) alongside aiida-mcp. aiida-dlpoly and aiida-chemshell both follow exactly this pattern for real: see their respective pyproject.toml and aiida_dlpoly/mcp.py/aiida_chemshell/mcp.py.

A module bundled in this repo (as mlip.py currently is) instead needs the entry point declared in this project’s pyproject.toml:

  1. Add its entry point to [project.entry-points."aiida_mcp.plugins"]:

    [project.entry-points."aiida_mcp.plugins"]
    mlip = "aiida_mcp.plugins.mlip"
    my_plugin = "aiida_mcp.plugins.my_plugin"
    
  2. Add the AiiDA plugin package as an optional dependency in pyproject.toml:

    [project.optional-dependencies]
    my_plugin = ["aiida-my-plugin"]
    
  3. Reinstall aiida-mcp (e.g. pip install -e .) so the new entry point is picked up — editable installs do not regenerate entry point metadata automatically when pyproject.toml changes.

  4. Update test_all_tools_are_registered in tests/test_server.py with the new tool names — but only in an environment where the new plugin package is actually installed; see Testing below.

  5. Update Tools and the README with the new tools and their arguments.

Docstring convention

Project docstrings follow numpydoc style (enforced for the general shape by Ruff’s D rules with convention = "numpy" in pyproject.toml, though Ruff does not check that every parameter is documented under that convention — that’s on you). For any @mcp.tool()-decorated function, the docstring is sent to MCP clients verbatim as the tool’s description (mcp.server.mcpserver.tools.base does func_doc = description or fn.__doc__ or "" — there is no structured per-parameter parsing), so a complete Parameters/Returns/Raises docstring directly improves what an AI client understands about the tool, not just what a human reading the source sees.

Testing

Tests for a plugin typically mock the final aiida.engine.submit call (or, if the AiiDA plugin package is not installed in the environment running the tests, the submit_calcjob helper itself — see below) so that no real job is submitted, then assert on the inputs that would have been submitted:

@pytest.fixture
def fake_submit():
    node = orm.CalcJobNode()
    node.set_process_type("aiida.calculations:my_plugin")
    with mock.patch.object(calcjob, "submit", return_value=node) as patched:
        node.store_all = lambda: None
        yield patched

If the real AiiDA plugin package is installed in the test environment (as aiida-dlpoly and aiida-chemshell are in their own repositories’ development environments, for aiida_dlpoly.mcp and aiida_chemshell.mcp respectively — see those repositories’ own test suites), mocking only the final aiida.engine.submit call still exercises the real calcjob’s input validation — so tests can assert on genuine ToolError messages raised by the plugin’s own validate_inputs, not just this project’s glue code.

If the real package is not installed (as was the case developing aiida_mcp.plugins.mlip), the real entry point is not registered with AiiDA at all, so calcjob.CalculationFactory(entry_point) — called inside submit_calcjob() before the mocked submit is ever reached — fails. In that situation, mock the plugin module’s own submit_calcjob name instead (bypassing real spec validation entirely), and, if the plugin module imports helper functions from the third-party package lazily (as described in When the plugin has its own loaders), inject minimal fake modules via sys.modules that mimic the handful of functions/classes actually used:

@pytest.fixture
def fake_aiida_mlip(monkeypatch):
    help_load = types.ModuleType("aiida_mlip.helpers.help_load")
    help_load.load_structure = lambda value: orm.StructureData()
    help_load.load_model = lambda value, architecture, cache_dir=None: orm.SinglefileData(...)
    modules = {
        "aiida_mlip": types.ModuleType("aiida_mlip"),
        "aiida_mlip.helpers": types.ModuleType("aiida_mlip.helpers"),
        "aiida_mlip.helpers.help_load": help_load,
        ...
    }
    for name, module in modules.items():
        monkeypatch.setitem(sys.modules, name, module)

Tests built this way verify the plugin module’s own glue logic (input assembly, error handling, resource validation) correctly, but not the real third-party package’s actual behaviour — treat them as a stopgap, and prefer installing the real package in the test environment once that’s possible, matching how aiida-dlpoly and aiida-chemshell test their own mcp modules in their own repositories.