maple-mcp 0.1.0__tar.gz

maple_mcp-0.1.0/.env.example

@@ -0,0 +1,16 @@
+# MADSci Service URLs
+WORKCELL_SERVER_URL=http://localhost:8005/
+DATA_SERVER_URL=http://localhost:8004/
+EVENT_SERVER_URL=http://localhost:8001/
+EXPERIMENT_SERVER_URL=http://localhost:8002/
+
+# LLM Backend (pick one)
+MODEL_PROVIDER=openai
+OPENAI_API_KEY=sk-...
+# MODEL_PROVIDER=anthropic
+# ANTHROPIC_API_KEY=sk-ant-...
+# MODEL_PROVIDER=ollama
+# OLLAMA_HOST=http://localhost:11434
+
+# Agent model (override per-agent if needed)
+EXECUTOR_AGENT_MODEL=gpt-4o

maple_mcp-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,22 @@
+name: Publish to PyPI
+
+on:
+  release:
+    types: [published]
+
+jobs:
+  publish:
+    runs-on: ubuntu-latest
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install build tools
+        run: pip install build
+      - name: Build package
+        run: python -m build
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

maple_mcp-0.1.0/.github/workflows/test.yml

@@ -0,0 +1,68 @@
+name: Tests
+
+on:
+  push:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'figures/**'
+      - 'LICENSE'
+  pull_request:
+    branches: [main]
+    paths-ignore:
+      - '**.md'
+      - 'figures/**'
+      - 'LICENSE'
+
+jobs:
+  unit:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.10", "3.11", "3.12"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+      - name: Run unit tests
+        run: pytest -m "not integration" --tb=short
+
+  integration:
+    runs-on: ubuntu-latest
+    needs: unit
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Start MADSci services
+        run: |
+          docker compose -f docker-compose.ci.yaml up -d
+          echo "Waiting for services to be ready..."
+          sleep 20
+
+      - name: Verify services are up
+        run: |
+          curl -sf http://localhost:8001/health || (echo "Event Manager not ready" && exit 1)
+          curl -sf http://localhost:8005/health || (echo "Workcell Manager not ready" && exit 1)
+          echo "✓ MADSci services ready"
+
+      - name: Create .env for integration tests
+        run: |
+          printf 'WORKCELL_SERVER_URL=http://localhost:8005/\nEXPERIMENT_SERVER_URL=http://localhost:8002/\nEVENT_SERVER_URL=http://localhost:8001/\nDATA_SERVER_URL=http://localhost:8004/\nRESOURCE_SERVER_URL=http://localhost:8003/\nLOCATION_SERVER_URL=http://localhost:8006/\nMCP_OPERATOR_URL=http://localhost:8102/mcp\n' > examples/block_sorting/.env
+          cp examples/block_sorting/.env .env
+
+      - name: Run integration tests
+        run: pytest -m integration --tb=short
+
+      - name: Tear down
+        if: always()
+        run: |
+          maple down
+          docker compose -f docker-compose.ci.yaml down -v

maple_mcp-0.1.0/.gitignore

@@ -0,0 +1,37 @@
+# Specs (internal planning docs)
+specs/
+
+# Python
+__pycache__/
+*.py[cod]
+*$py.class
+*.egg-info/
+dist/
+build/
+.eggs/
+
+# Virtual environment
+.venv/
+venv/
+env/
+
+# IDE
+.idea/
+.vscode/
+*.swp
+*.swo
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Environment
+.env
+
+# Sessions
+sessions/
+
+# Test artifacts
+.pytest_cache/
+.coverage
+htmlcov/

maple_mcp-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Gabriel Ferrer
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

maple_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,162 @@
+Metadata-Version: 2.5
+Name: maple-mcp
+Version: 0.1.0
+Summary: Model-Agnostic Platform for Laboratory Experiments — LLM agents for autonomous MADSci experiments via MCP
+Project-URL: Homepage, https://github.com/gabrielferrer/maple-mcp
+Project-URL: Repository, https://github.com/gabrielferrer/maple-mcp
+Project-URL: Issues, https://github.com/gabrielferrer/maple-mcp/issues
+Author: Gabriel Ferrer
+License: MIT
+License-File: LICENSE
+Keywords: agents,autonomous-lab,llm,madsci,mcp,robotics
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: fastapi>=0.100.0
+Requires-Dist: fastmcp>=2.0.0
+Requires-Dist: httpx>=0.24.0
+Requires-Dist: madsci-client<0.6.0,>=0.5.0
+Requires-Dist: madsci-common<0.6.0,>=0.5.0
+Requires-Dist: madsci-experiment-application<0.6.0,>=0.5.0
+Requires-Dist: madsci-node-module<0.6.0,>=0.5.0
+Requires-Dist: numpy>=1.24.0
+Requires-Dist: openai>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: pyyaml>=6.0
+Requires-Dist: rich>=13.0.0
+Requires-Dist: strands-agents[anthropic,ollama]>=1.0.0
+Requires-Dist: textual>=4.0.0
+Requires-Dist: typer>=0.9.0
+Requires-Dist: uvicorn>=0.20.0
+Requires-Dist: watchfiles>=0.20.0
+Provides-Extra: dev
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-mock>=3.10.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# MAPLE
+
+**Model-Agnostic Platform for Laboratory Experiments**
+
+MAPLE adds LLM agent capabilities to any [MADSci](https://github.com/AD-SDL/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](figures/architecture-1.png)
+
+## Quick Start
+
+```bash
+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:
+```bash
+maple serve operator          # Start with your configured model
+maple chat operator           # Run an experiment
+maple chat operator --resume  # Pick up where you left off
+```
+
+See [`examples/block_sorting/`](examples/block_sorting/) for a complete walkthrough.
+
+## Installation
+
+```bash
+pip install maple-mcp
+```
+
+Requires Python 3.10+ and a running [MADSci](https://github.com/AD-SDL/MADSci) lab (v0.5.x).
+
+## CLI
+
+```
+maple serve {all, operator, overseer, stub, mock} [--dev]
+maple chat {operator, overseer} [--resume]
+maple down
+maple status
+maple logs
+```
+
+## Configuration
+
+One `maple.config.yaml` per experiment:
+
+```yaml
+experiment:
+  name: My Experiment
+  objective: Sort samples by type
+  constraints:
+    - "Only handle one sample at a time"
+
+operator:
+  vision_backend: "vision:MyVision"
+  custom_tools:
+    - "my_tools:prepare_sample"
+  post_action_hooks:
+    - node: AnalysisNode
+      action: verify_placement
+```
+
+Infrastructure goes in `.env` (IPs, API keys, model provider).
+
+## Extending MAPLE
+
+| Extension Point | Mechanism | Config Key |
+|---|---|---|
+| Vision detection | Subclass `VisionBackend` | `operator.vision_backend` |
+| 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
+
+```python
+from maple.operator.agent import create_operator_agent
+
+agent = create_operator_agent("my-session")
+result = agent("Sort the colored blocks by color.")
+```
+
+## Testing
+
+```bash
+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](LICENSE)

maple_mcp-0.1.0/README.md

@@ -0,0 +1,118 @@
+# MAPLE
+
+**Model-Agnostic Platform for Laboratory Experiments**
+
+MAPLE adds LLM agent capabilities to any [MADSci](https://github.com/AD-SDL/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](figures/architecture-1.png)
+
+## Quick Start
+
+```bash
+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:
+```bash
+maple serve operator          # Start with your configured model
+maple chat operator           # Run an experiment
+maple chat operator --resume  # Pick up where you left off
+```
+
+See [`examples/block_sorting/`](examples/block_sorting/) for a complete walkthrough.
+
+## Installation
+
+```bash
+pip install maple-mcp
+```
+
+Requires Python 3.10+ and a running [MADSci](https://github.com/AD-SDL/MADSci) lab (v0.5.x).
+
+## CLI
+
+```
+maple serve {all, operator, overseer, stub, mock} [--dev]
+maple chat {operator, overseer} [--resume]
+maple down
+maple status
+maple logs
+```
+
+## Configuration
+
+One `maple.config.yaml` per experiment:
+
+```yaml
+experiment:
+  name: My Experiment
+  objective: Sort samples by type
+  constraints:
+    - "Only handle one sample at a time"
+
+operator:
+  vision_backend: "vision:MyVision"
+  custom_tools:
+    - "my_tools:prepare_sample"
+  post_action_hooks:
+    - node: AnalysisNode
+      action: verify_placement
+```
+
+Infrastructure goes in `.env` (IPs, API keys, model provider).
+
+## Extending MAPLE
+
+| Extension Point | Mechanism | Config Key |
+|---|---|---|
+| Vision detection | Subclass `VisionBackend` | `operator.vision_backend` |
+| 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
+
+```python
+from maple.operator.agent import create_operator_agent
+
+agent = create_operator_agent("my-session")
+result = agent("Sort the colored blocks by color.")
+```
+
+## Testing
+
+```bash
+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](LICENSE)

maple_mcp-0.1.0/docker-compose.ci.yaml

@@ -0,0 +1,100 @@
+name: maple_ci
+
+# Minimal MADSci stack for MAPLE integration tests.
+# No lab dashboard, no minio — just the managers needed for E2E testing.
+
+x-madsci-service: &madsci-service
+  image: ghcr.io/ad-sdl/madsci:v0.5.0
+  network_mode: host
+  extra_hosts:
+    - "host.docker.internal:host-gateway"
+  environment:
+    - USER_ID=1000
+    - GROUP_ID=1000
+  restart: "no"
+
+services:
+  # === DATABASES ===
+
+  mongodb:
+    container_name: mongodb
+    image: mongo:8.0
+    network_mode: host
+    volumes:
+      - mongodb_data:/data/db
+
+  redis:
+    container_name: redis
+    image: redis:7.4
+    network_mode: host
+    command: redis-server --appendonly yes
+
+  postgres:
+    container_name: postgres
+    image: postgres:17
+    network_mode: host
+    environment:
+      - POSTGRES_USER=madsci
+      - POSTGRES_PASSWORD=madsci
+      - POSTGRES_DB=resources
+
+  # === MANAGERS ===
+
+  event_manager:
+    <<: *madsci-service
+    container_name: event_manager
+    command: python -m madsci.event_manager.event_server --host 0.0.0.0 --port 8001
+    depends_on:
+      - mongodb
+
+  resource_manager:
+    <<: *madsci-service
+    container_name: resource_manager
+    command: python -m madsci.resource_manager.resource_server --host 0.0.0.0 --port 8003
+    depends_on:
+      - postgres
+      - event_manager
+
+  data_manager:
+    <<: *madsci-service
+    container_name: data_manager
+    command: python -m madsci.data_manager.data_server --host 0.0.0.0 --port 8004
+    depends_on:
+      - mongodb
+      - event_manager
+
+  experiment_manager:
+    <<: *madsci-service
+    container_name: experiment_manager
+    command: python -m madsci.experiment_manager.experiment_server --host 0.0.0.0 --port 8002
+    depends_on:
+      - mongodb
+      - event_manager
+
+  workcell_manager:
+    <<: *madsci-service
+    container_name: workcell_manager
+    command: python -m madsci.workcell_manager.workcell_server --host 0.0.0.0 --port 8005
+    environment:
+      - USER_ID=1000
+      - GROUP_ID=1000
+      - LOCATION_SERVER_URL=http://localhost:8006/
+      - RESOURCE_SERVER_URL=http://localhost:8003/
+      - EVENT_SERVER_URL=http://localhost:8001/
+      - DATA_SERVER_URL=http://localhost:8004/
+    depends_on:
+      - redis
+      - mongodb
+      - resource_manager
+      - event_manager
+      - postgres
+
+  location_manager:
+    <<: *madsci-service
+    container_name: location_manager
+    command: python -m madsci.location_manager.location_server --host 0.0.0.0 --port 8006
+    depends_on:
+      - redis
+
+volumes:
+  mongodb_data:

maple_mcp-0.1.0/examples/block_sorting/.env.example

@@ -0,0 +1,18 @@
+# Environment variables for the block sorting demo.
+# Copy to .env and adjust as needed.
+
+# MADSci service URLs
+WORKCELL_SERVER_URL=http://localhost:8005/
+EXPERIMENT_SERVER_URL=http://localhost:8002/
+EVENT_SERVER_URL=http://localhost:8001/
+DATA_SERVER_URL=http://localhost:8004/
+RESOURCE_SERVER_URL=http://localhost:8003/
+LOCATION_SERVER_URL=http://localhost:8006/
+
+# MCP server URL (Operator)
+MCP_OPERATOR_URL=http://localhost:8102/mcp
+
+# Model provider (not needed for mock agent demo)
+# MODEL_PROVIDER=ollama
+# OLLAMA_HOST=http://localhost:11434
+# OPERATOR_MODEL=qwen3:8b

maple_mcp-0.1.0/examples/block_sorting/README.md

@@ -0,0 +1,99 @@
+# Block Sorting Demo
+
+A self-contained example demonstrating the full MAPLE pipeline. Uses a stub robot node, mock agent (no LLM needed), and an example VisionBackend.
+
+## What's Included
+
+| File | Purpose |
+|------|---------|
+| `vision.py` | `ExampleVision` — hardcoded VisionBackend (3 blocks, always sorted) |
+| `stub_node.py` | Minimal MADSci node with `pick_and_place` action |
+| `mock_agent.py` | Scripted agent — walks through full experiment without an LLM |
+| `maple.config.yaml` | MAPLE config pointing to `vision:ExampleVision` |
+| `.env.example` | Template for service URLs |
+
+## Prerequisites
+
+- Python 3.10+
+- `pip install maple-mcp`
+- A running MADSci lab (real or example lab via `docker compose`)
+
+## Setup
+
+### 1. Configure environment
+
+```bash
+cd examples/block_sorting
+cp .env.example .env
+```
+
+Edit `.env` with your MADSci service URLs. Set `NODE_URL` to the address the Workcell Manager can reach your stub node at.
+
+### 2. Start the stub node
+
+```bash
+python stub_node.py
+```
+
+You should see:
+```
+✓ Registered StubBot at <NODE_URL> with Workcell Manager
+INFO:     Uvicorn running on http://0.0.0.0:2000
+```
+
+### 3. Start the mock agent
+
+```bash
+python mock_agent.py
+```
+
+### 4. Launch the TUI
+
+In a separate terminal:
+
+```bash
+maple chat --agent operator
+```
+
+Type anything (e.g., "sort the blocks") and press Enter. The mock agent streams a scripted experiment:
+
+1. Registers the experiment
+2. Detects 3 blocks (2 red, 1 blue)
+3. Sorts each block with `pick_and_place`
+4. Verifies all blocks sorted
+5. Ends the experiment
+
+Press Enter again to exit.
+
+## Cleanup
+
+The stub node registers as non-permanent. To remove it, restart the Workcell Manager:
+
+```bash
+docker restart workcell_manager
+```
+
+## Going Live
+
+To use a real LLM instead of the mock agent:
+
+1. Install Ollama: `curl -fsSL https://ollama.com/install.sh | sh`
+2. Pull a model: `ollama pull qwen3:8b`
+3. Add to `.env`:
+   ```
+   MODEL_PROVIDER=ollama
+   OLLAMA_HOST=http://localhost:11434
+   OPERATOR_MODEL=qwen3:8b
+   ```
+4. Skip the mock agent — use `maple serve --agent operator --config maple.config.yaml` instead
+5. Run `maple chat --agent operator` and tell it: "Sort the blocks by color"
+
+To use real hardware, replace `ExampleVision` with your own `VisionBackend` subclass and update `vision_backend` in `maple.config.yaml`.
+
+## Troubleshooting
+
+| Problem | Solution |
+|---------|----------|
+| StubBot shows `ready=False` | Check the Workcell Manager can reach NODE_URL |
+| Workflow stuck in "Queued" | Node isn't ready. Verify with `get_nodes()` |
+| Node name already exists | Restart Workcell Manager to clear non-permanent nodes |