Skip to main content

MAPLE

Model-Agnostic Platform for Laboratory Experiments

MAPLE adds LLM agent capabilities to any MADSci-powered laboratory (v0.5.x) via MCP. Two agents — an Operator for experiment execution and an Overseer for lab monitoring — connect to your lab through configurable MCP servers.

Architecture

MAPLE Architecture

Quick Start

pip install maple-mcp
cd your-experiment/
cp .env.example .env          # Configure MADSci URLs + model provider
maple serve stub              # Start demo (no LLM needed)
maple chat operator           # Open TUI — type anything
maple down                    # Stop all services

For a real LLM experiment:

maple serve operator          # Start with your configured model
maple chat operator           # Run — auto-sends your experiment brief (see below)
maple chat operator --resume  # Pick up where you left off
maple chat operator --test    # Collaborative session — drive the robot turn-by-turn

maple chat operator auto-sends the experiment: block from your maple.config.yaml as the opening brief, so the agent starts running as soon as the TUI opens (only on a fresh session, and only if an objective is set). Use --test for an interactive session instead: the agent starts one experiment, then waits and executes tasks you type ("home the DOFBOT", "what are its constraints?") until you tell it to stop — useful for connectivity checks and exploring a new robot.

See examples/block_sorting/ for a complete walkthrough.

Installation

pip install maple-mcp

Requires Python 3.10+ and a running MADSci lab (v0.5.x).

CLI

maple serve {all, operator, overseer, stub, mock} [--dev]
maple chat {operator, overseer} [--resume] [--test]
maple down
maple status
maple logs

--test (operator only): collaborative mode — interactive, turn-by-turn control instead of an autonomous run.

Configuration

One maple.config.yaml per experiment:

experiment:
  name: My Experiment
  objective: Sort samples by type
  constraints:
    - "Only handle one sample at a time"

operator:
  vision:
    views:
      workspace:
        backend: "vision:MyVision"
        capture:
          node: MyRobot
          action: capture_camera_image
        covers: [MyRobot]
    default_view: workspace
  custom_tools:
    - "my_tools:prepare_sample"
  post_action_hooks:
    - node: AnalysisNode
      action: verify_placement

Infrastructure goes in .env (IPs, API keys, model provider).

The experiment: block is the brief the Operator runs. maple chat operator serializes it and sends it as the opening message on a fresh session, so the agent begins autonomously when the TUI opens. Leave objective empty to disable auto-send and type the brief yourself. --test ignores this block and sends the built-in collaborative brief instead.

Extending MAPLE

Config keys below are dotted paths into maple.config.yaml — e.g. operator.vision.views is the views: key nested under operator: → vision:.

Extension Point Mechanism Config Key
Vision detection/verification Subclass VisionBackend (pure: frames in, results out) — (referenced by a view's backend)
Vision views (scenes + routing) Declare views mapping cameras/nodes to backends operator.vision.views
MCP tools @mcp.tool decorator operator.custom_tools / overseer.custom_tools
Agent hooks extra_hooks param on factory Programmatic
Post-action hooks YAML (no code) operator.post_action_hooks
System prompts Markdown file operator.prompt / overseer.prompt

Supported Models

Provider Environment Variable
OpenAI MODEL_PROVIDER=openai
Anthropic MODEL_PROVIDER=anthropic
Ollama (local, free) MODEL_PROVIDER=ollama

Multi-User

Each device auto-generates a unique identity token. Multiple users can run experiments simultaneously — sessions are isolated automatically.

Programmatic Usage

from maple.operator.agent import create_operator_agent

agent = create_operator_agent("my-session")
result = agent("Sort the colored blocks by color.")

Testing

pytest -m "not integration"                    # Unit tests (no network)
docker compose -f docker-compose.ci.yaml up -d # Start MADSci
pytest -m integration                          # Integration tests

Compatibility

  • Python 3.10+
  • MADSci >=0.5.0, <0.6.0
  • FastMCP 3.x

License

MIT

Metadata

Release files for maple-mcp 0.1.4

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for maple-mcp 0.1.4
File Size Uploaded Provenance Actions
maple_mcp-0.1.4.tar.gz 127.0 kB With provenance Details for maple_mcp-0.1.4.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for maple-mcp 0.1.4
File Interpreter ABI Platform Actions
maple_mcp-0.1.4-py3-none-any.whl Python 3 none any Details for maple_mcp-0.1.4-py3-none-any.whl

Total release size: 169.4 kB

Release files / maple_mcp-0.1.4.tar.gz

Download URL maple_mcp-0.1.4.tar.gz
Size 127.0 kB
Tags Source
SHA-256 checksum
How to use checksums
40d56683b9cc45dbcb2d70d2a3bb66d9153c8988195403f72b0bfe0e83090aa2
BLAKE2b-256 checksum
How to use checksums
4adc55bb978c5289f3ec75082991bee5c4b1147184e25e96ad2bd413b5a1edff
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Release files / maple_mcp-0.1.4-py3-none-any.whl

Download URL maple_mcp-0.1.4-py3-none-any.whl
Size 42.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
cb22ebb9418d5a4506e478019b0ad6c1ea81b7be8a664676f3f90675485079a3
BLAKE2b-256 checksum
How to use checksums
9d35f4a4b5a703b08c9bc2613c298154c8c70010b7f0f138482f3e7815961f30
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

Security for maple-mcp 0.1.4

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for maple_mcp-0.1.4.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Oct 28, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page