ghollyer/amadeus

AMADEUS, short for Addressable Microscope And Detector Experiment Unified Scripting, is a Python project for driving an electron microscope from an AI agent or other MCP client. It exposes microscope automation as a set of MCP tools, so a language model that speaks the Model Context Protocol can move the stage, take images, run spectrum imaging experiments, and analyse the results, instead of a human clicking around in the vendor software. The code is split into two runtime components. The client side runs on the operator's control computer and is the actual MCP server that the AI agent talks to. It holds the experiment state, an image store, a map of points of interest, an experimental plan, operational preferences, and analysis routines such as FFT, lattice spacing extraction, and segmentation. The dm_server side runs inside the microscope vendor's own Python environment, on the computer wired to the instrument. It is intentionally stateless: it receives one command, calls the matching helper for the microscope, stage, camera, STEM detector, spectrum imaging unit, EDS detector, or local file system, and returns either JSON metadata or a raw NumPy image. The two sides communicate over ZMQ on TCP port 9876 using JSON messages, with image producing commands sending metadata plus a multipart binary payload. Installation uses uv pip install with the dev extra. The client is launched with amadeus-server, pointing at a ZMQ address such as tcp://localhost:9876 for local development or the IP of the microscope VM in production, along with a data directory for the image store. The microscope side is started by opening the vendor's Python console and running exec on dm_server/server.py. A separate dm_gui.py script gives a manual control GUI for the microscope side when an agent is not in the loop. The MCP tool list is grouped by area: focus and magnification, beam and stigmation, stage moves and saved locations, STEM and camera imaging, spectrum imaging start and stop, EDS point and map acquisition with elemental quantification, remote file listing and fetching, FFT and segmentation, a map of objects, an experimental plan, sample metadata, and a shutdown command. The test suite runs offline with pytest and pytest-asyncio against mocks, so contributors can work on it without a live microscope. The README notes the project is not affiliated with Gatan Inc., the maker of DigitalMicrograph.