actions-robot-bootrapper

---

QUICK START

Start the Sema4.ai action server:

action-server start

Server addresses:

• API root: http://localhost:8080
• MCP (ModelContext Protocol): http://localhost:8080/mcp

OpenAPI docs are available at http://localhost:8080/openapi.json when the server is running.

---

MCP SERVER — PURPOSE & ARCHITECTURE

Short answer: the MCP server exposes the Python actions in src/actions_bootrapper and src/robot_bootrapper as HTTP POST endpoints so LLMs and agent frameworks can drive robot lifecycle and action-package workflows programmatically.

What it does (brief):

• Exposes automation operations (create, run, test, package, update) as HTTP endpoints.
• Manages action packages: bootstrap, update code/deps/devdata, open in editor, start/stop.
• Provides robot lifecycle commands that wrap rcc functionality via Python helpers.
• Serves logs, files, and artifacts to help agents inspect state and debug.
• Accepts secrets when starting action packages so runtime code can access credentials.

Key implementation files:

• src/actions_bootrapper/actions.py — action-package lifecycle actions (bootstrap, start/stop server, update code/devdata, retrieve logs/files).
• src/robot_bootrapper/robot_actions.py — robot lifecycle and rcc wrappers (create, run, dependencies, wrap/unwrap, docs, etc.).

Note: action packages created by the bootstrapper are placed in the user's home directory under ~/actions_bootstrapper/<package-name>.

---

ENDPOINT CATALOG (available under /mcp)

All routes are POST requests to http://localhost:8080/mcp. The action path in the request body maps to the following endpoints. Grouped by purpose for readability.

Action package management

• /api/actions/actions-robot-bootstrapper/bootstrap-action-package/run — Create a new action package scaffold.
• /api/actions/actions-robot-bootstrapper/update-action-package-dependencies/run — Replace package.yaml contents.
• /api/actions/actions-robot-bootstrapper/update-action-package-action-dev-data/run — Write devdata/input_<action>.json for an action.
• /api/actions/actions-robot-bootstrapper/update-action-code/run — Replace actions.py in the package.
• /api/actions/actions-robot-bootstrapper/open-action-code/run — Open package in VSCode (uses code binary).
• /api/actions/actions-robot-bootstrapper/start-action-server/run — Start the packaged action-server (spawns subprocess, writes action_server.log).
• /api/actions/actions-robot-bootstrapper/stop-action-server/run — POSTs /api/shutdown to the running package to stop it.

Robot lifecycle & rcc wrappers

• /api/actions/actions-robot-bootstrapper/create-robot/run — rcc robot initialize wrapper.
• /api/actions/actions-robot-bootstrapper/pull-robot/run — Pull a robot from GitHub.
• /api/actions/actions-robot-bootstrapper/list-templates/run — List available robot templates.
• /api/actions/actions-robot-bootstrapper/create-from-template/run — Create robot from a remote template.
• /api/actions/actions-robot-bootstrapper/run-robot/run — Run the robot (invokes rcc run).
• /api/actions/actions-robot-bootstrapper/run-task/run — Run a named task.
• /api/actions/actions-robot-bootstrapper/list-tasks/run — List tasks for a robot.
• /api/actions/actions-robot-bootstrapper/task-testrun/run — Robot task testrun helper.
• /api/actions/actions-robot-bootstrapper/robot-dependencies/run — Check robot dependencies.
• /api/actions/actions-robot-bootstrapper/robot-diagnostics/run — Run diagnostics.
• /api/actions/actions-robot-bootstrapper/wrap-robot/run and /unwrap-robot/run — Package/unpackage robots.

Utilities, logs and docs

• /api/actions/actions-robot-bootstrapper/get-file-contents/run — Read files inside action packages (default actions.py).
• /api/actions/actions-robot-bootstrapper/get-action-run-logs/run — Fetch a run's artifacts/text logs.
• /api/actions/actions-robot-bootstrapper/get-action-run-logs-latest/run — Fetch the latest run logs.
• /api/actions/actions-robot-bootstrapper/run-shell-command/run — Run arbitrary shell commands (safe usage note below).
• /api/actions/actions-robot-bootstrapper/docs-list/run, /docs-recipes/run, /docs-changelog/run — Expose rcc docs commands.
• /api/actions/actions-robot-bootstrapper/help/run — Wrapper around rcc --help.

Other helpers

• /api/actions/actions-robot-bootstrapper/prebuild-holotree/run — Prebuild holotree for faster runs.
• /api/actions/actions-robot-bootstrapper/export-holotree-environment/run — Export holotree environment to zip.
• /api/actions/actions-robot-bootstrapper/import-holotree-environment/run — Import exported holotree.
• /api/actions/actions-robot-bootstrapper/update-robot-task-code/run — Replace tasks.py in a robot.
• /api/actions/actions-robot-bootstrapper/update-robot-yaml/run — Replace robot.yaml.
• /api/actions/actions-robot-bootstrapper/update-conda-yaml/run — Replace conda.yaml.

Notes:

• The server exposes OpenAPI (OAS 3.1); fetch it at /openapi.json.
• Most endpoints are thin wrappers over Python functions in src/ — read those files to see expected arguments and behaviour.
• Use get-file-contents and the action logs endpoints to inspect the action package state.

---

EXAMPLES

Start a packaged action server (example payload — MCP wrapper expects action path and arguments):

{
	"action": "/api/actions/actions-robot-bootstrapper/start-action-server/run",
	"args": { "action_package_name": "my-package", "secrets": "{}" }
}

Fetch the latest action run logs:

{
	"action": "/api/actions/actions-robot-bootstrapper/get-action-run-logs-latest/run",
	"args": { "action_server_url": "http://localhost:8080" }
}

MCP request format (HTTP)

POST to http://localhost:8080/mcp with JSON body. Minimal body example:

{
	"action": "/api/actions/actions-robot-bootstrapper/get-file-contents/run",
	"args": { "action_package_name": "my-package", "file_name": "actions.py" }
}

Curl examples

Start action server (example):

curl -X POST http://localhost:8080/mcp \
	-H 'Content-Type: application/json' \
	-d '{"action":"/api/actions/actions-robot-bootstrapper/start-action-server/run","args":{"action_package_name":"my-package","secrets":"{}"}}'

Get latest logs:

curl -X POST http://localhost:8080/mcp \
	-H 'Content-Type: application/json' \
	-d '{"action":"/api/actions/actions-robot-bootstrapper/get-action-run-logs-latest/run","args":{"action_server_url":"http://localhost:8080"}}'

---

KEY FILES

• src/actions_bootrapper/actions.py — action-package lifecycle and server start/stop helpers.
• src/robot_bootrapper/robot_actions.py — robot-facing helpers that call rcc via subprocess.
• start_action_server.py — small helper used by the start_action_server action to spawn action-server start in the action package directory.
• package.yaml — package dependencies for action packages created by the bootstrapper.

---

SECURITY & SAFETY

Be cautious when using /run-shell-command/run and other endpoints that execute subprocesses — they run with the same permissions as the action server process. Prefer using specific helper actions that validate inputs.

When starting action packages you can pass secrets (JSON map). These are injected into the environment of the spawned process; validate and restrict secrets handling in production.

---

If you'd like, I can also add example curl requests, a short diagram, or inline examples of expected request/response shapes for a few key endpoints.

---

QUICK REFERENCE (cheat sheet)

Common actions and required args (POST to /mcp with JSON {action, args}):

• Start action server

  • action: /api/actions/actions-robot-bootstrapper/start-action-server/run
  • args: { action_package_name: string, secrets: string (JSON map) }

• Stop action server

  • action: /api/actions/actions-robot-bootstrapper/stop-action-server/run
  • args: { action_server_url: string }

• Get file contents

  • action: /api/actions/actions-robot-bootstrapper/get-file-contents/run
  • args: { action_package_name: string, file_name?: string } (file_name defaults to actions.py)

• Update action code

  • action: /api/actions/actions-robot-bootstrapper/update-action-code/run
  • args: { action_package_name: string, action_code: string }

• Create robot from template

  • action: /api/actions/actions-robot-bootstrapper/create-robot/run
  • args: { template: string, directory: string }

Common response shapes:

• Success: an object with result string (or plain string for some actions).
• Error: an object with error string explaining the failure.

Example minimal success response:

{ "result": "Action Server started at http://localhost:8080" }

Example error response:

{ "error": "File not found: /home/user/actions_bootstrapper/my-package/actions.py" }