Integration API

The read-only API for site tools and MCP clients, and the site-group server that uses it.

Site tools on the enterprise network (messaging, the CMMS, an MES) and AI assistants through MCP can read BooleX's prepared answers, sequences of events and workflow results; a site-group server can poll a site summary. The edge PC pushes nothing out. The API is off by default: it is mounted only when the site has made an integration account.

Accounts

docker compose -f deploy/compose.yaml run --rm assistant python -m edge.api.integration add NAME --scope workflows --file /config/integration.json

The command prints the account's token once and keeps only its SHA-256 hash in config/integration.json. Scopes: answers, events, workflows (the default) and site-summary; repeat --scope to give an account more than one. Every request needs Authorization: Bearer <token> from an account with the endpoint's scope. Every endpoint is GET only; any other method is refused (405). Each read is audited with the account and what it read.

Endpoints

Answers are read, never asked for: the API serves only the answers BooleX already prepared on a stop, each statement with its source IDs and the AI-advice label, so no question reaches the model through it. The sequence of events is the deterministic timeline (no model); trend values stay on the edge PC.

A workflow result carries the run's identity, trigger, outcome, cited statements, review state and reviews (action, time, note) and the AI-advice label. Tool calls and the values they read stay on the edge PC, and reviewers are not named. The site summary holds only stops, confirmed root causes, alarm statistics and open items.

The API runs on the same HTTPS listener as the Web UI (flow F10).

Site-group server

A multi-site operator runs the site-group server on its own network. It shows the site-group overview.

1. On each site, make an account with the site-summary scope and give its token to the group: python -m edge.api.integration add GROUP --scope site-summary.
2. Write the group configuration (below).
3. Start it: python -m edge.site_group group.yaml (port 8090, or BOOLE_GROUP_PORT). Its users are named accounts in its own users.json.

sites:
  - {id: dublin, title: Dublin dairy, url: "https://edge-dublin:8080", token_file: tokens/dublin}
  - {id: cork, title: Cork bottling, url: "https://edge-cork:8080", token_file: tokens/cork}
interval_s: 900        # how often each summary is fetched
period_hours: 24       # the period each summary covers
ca_file: sites-ca.pem  # the sites' TLS certificates

The group server's client can only send GET to the one summary path, so nothing reaches back to a plant.

MCP clients

An MCP client (an AI assistant on the enterprise network) reaches the same endpoints through the MCP bridge, a small stdio MCP server that runs beside the client, not on the edge PC:

python -m edge.mcp_bridge --url https://boolex.plant.local --token-file integration.token [--ca edge-ca.pem]

Its tools are list_answers, get_answer, get_sequence_of_events, list_workflow_results and get_site_summary, each one GET on the integration API with the account's token, so the scopes, the audit and the refusal of any write apply unchanged. Every tool is marked read-only; none sends anything to the plant or changes the platform. The edge PC opens nothing new: the bridge uses flow F10.