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.5

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.5
File Size Uploaded Provenance Actions
maple_mcp-0.1.5.tar.gz 128.3 kB With provenance Details for maple_mcp-0.1.5.tar.gz

Built distribution (wheel)

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

Total release size: 171.7 kB

Release files / maple_mcp-0.1.5.tar.gz

Download URL maple_mcp-0.1.5.tar.gz
Size 128.3 kB
Tags Source
SHA-256 checksum
How to use checksums
e868c5492aa7a99e0945a82cb10b4b8baf9555714c615b2f90b5deeaac4b65fd
BLAKE2b-256 checksum
How to use checksums
7de936e9d2d028ca4195a4e598d06936f2ab9e635091f55b6888ecf07ea99191
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 30, 2026.

Transparency log

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

Download URL maple_mcp-0.1.5-py3-none-any.whl
Size 43.4 kB
Tags Python 3
SHA-256 checksum
How to use checksums
4a31404db01941f6cfd792dd6533348b2f01c08fe5cdca1fdeacc14f8cee1ceb
BLAKE2b-256 checksum
How to use checksums
e0d459800bd002057cceb321035fc8911af42a6a97184ad20123b65856a0cc83
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 30, 2026.

Transparency log

Security for maple-mcp 0.1.5

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.5.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 30, 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