Offline MCP tools¶
This optional package exposes six read tools through the maintained MCP SDK’s stdio transport. It uses the published host RC1 package and installed contracts 0.21.1/harness 0.22.3 CLIs. The assistant integration guide relates these tools to configuration, campaigns, execution and archive assessment.
describe_contract: describe a schema ID from the operator’s catalog.validate_documents: validate registered immutable document IDs.explain_bundle: explain a registered scenario/runtime bundle and its optional model, dataset, permit or verification documents.summarize_otlp: summarize one registered OTLP JSON-lines artifact.explain_result: explain one registered canonical result.inspect_offline_readiness: inspect the installed offline environment.
These operations do not start observations or run evaluators. Trusted bootstrap may supply domain extension schemas as registered immutable artifact IDs. Bundle-specific evaluator receipts and live readiness remain outside this interface.
Supported document versions come from the selected installed workers and the
operator’s schema catalog. The locked published workers support canonical role
defaults and explicit native v2 documents. The adapter forwards both versions
as exact files without adding ROS fields.
A native incomplete verdict remains incomplete through explain_result.
Install the published bundle¶
Download the MCPB, worker lock and checksums from the immutable 0.1.0-rc.1 release. This Linux profile uses an operator-selected Node 24.21.0 executable and an operator-prepared bootstrap file. The Python workers are installed separately:
set -eu
mkdir robotics-mcp
cd robotics-mcp
release=https://github.com/mmkolpakov/robotics-runtime/releases/download/mcp-v0.1.0-rc.1
curl -fLO "$release/robotics-runtime-mcp-0.1.0-rc.1.mcpb"
curl -fLO "$release/public-cli.lock"
curl -fLO "$release/SHA256SUMS"
gh release verify-asset mcp-v0.1.0-rc.1 robotics-runtime-mcp-0.1.0-rc.1.mcpb \
--repo mmkolpakov/robotics-runtime
gh release verify-asset mcp-v0.1.0-rc.1 public-cli.lock \
--repo mmkolpakov/robotics-runtime
sha256sum --check --ignore-missing SHA256SUMS
python3 -m zipfile -e robotics-runtime-mcp-0.1.0-rc.1.mcpb bundle
uv venv --python 3.12 .public-workers
uv pip install --python .public-workers/bin/python --require-hashes --no-deps \
--only-binary :all: --requirement public-cli.lock
The GitHub CLI verifies each downloaded file against the immutable release.
Checksums also check the downloaded bytes. Treat the bundle as executable code.
For a qualification package, prepare bootstrap.json with the helper below.
A compatible MCPB client substitutes the approved node_executable and
bootstrap_file into the bundle’s manifest. A generic stdio client can launch:
/approved/node-24.21.0/bin/node "$PWD/bundle/bin/server.mjs" \
--config "$PWD/bootstrap.json"
The bundle contains the server, bootstrap helper, license and locked production Node dependencies. It does not install the Python workers or prepare the operator’s corpus at startup. The MCPB manifest declares the Linux profile and its two required file selections.
Install and configure from source¶
Use Node 24.21.0/npm 11.19.0. Install the locked workspace dependencies at the repository root, build the host, and install the published Python workers in a separate environment:
npm ci --ignore-scripts --engine-strict
npm run build --workspace @robotics-runtime/host
cd mcp
uv venv --python 3.12 .public-workers
uv pip install --python .public-workers/bin/python --require-hashes --no-deps \
--only-binary :all: --requirement public-cli.lock
The trusted operator selects CLI executables and an approved corpus of local regular files. Files must be read-only and have exact SHA-256/size identities. Artifact and scratch roots must be canonical directories with no group/other write access. Request arguments contain IDs; they cannot supply paths, URLs, executables, environments or arbitrary flags.
For example, prepare read-only evidence/scenario.json and
evidence/runtime.json, then generate a bootstrap using public byte references:
mkdir -p -m 700 mcp-scratch
chmod 444 evidence/scenario.json evidence/runtime.json
CONTRACTS_CLI="$PWD/.public-workers/bin/robotics-contracts" \
HARNESS_CLI="$PWD/.public-workers/bin/robotics-acceptance" \
node --input-type=module > bootstrap.json <<'JS'
import { referenceFile } from '@robotics-runtime/host';
import { resolve, join } from 'node:path';
const root = resolve('evidence');
const artifacts = [];
for (const id of ['scenario', 'runtime']) {
const path = id + '.json';
const ref = await referenceFile(join(root, path));
artifacts.push({ id, path, sha256: ref.sha256, size_bytes: ref.size_bytes });
}
console.log(JSON.stringify({
artifactRoot: root, scratchRoot: resolve('mcp-scratch'),
contractsCli: process.env.CONTRACTS_CLI, harnessCli: process.env.HARNESS_CLI,
artifacts, schemas: [{ id: 'scenario', schema: 'acceptance-scenario.v1' }],
bundles: [{ id: 'example', scenario: 'scenario', runtime: 'runtime' }]
}, null, 2));
JS
Configure an MCP client to launch node bin/server.mjs --config bootstrap.json
from this directory. Use the equivalent absolute executable/config paths when
the client launches from another directory. The client owns the stdio process;
the SDK handles discovery and tool calls for MCP 2026-07-28 and negotiated
legacy clients. Current-protocol clients use server/discover and per-request
capabilities; legacy clients use their negotiated initialization path.
The protocol specification
defines that distinction; client setup does not add domain operations.
Prepare a qualification package¶
For an externally verified qualification package, prepare the existing bootstrap
from its writer-produced qualification-arguments.txt. Select a stable read-only
operator corpus and a private scratch directory, then run the helper with the
same installed contracts Python used by the workers. From the published bundle:
mkdir -p -m 700 mcp-scratch
.public-workers/bin/python bundle/tools/prepare-bootstrap.py \
--package-root /absolute/verified-package --domain primary \
--scratch-root "$PWD/mcp-scratch" \
--contracts-cli "$PWD/.public-workers/bin/robotics-contracts" \
--harness-cli "$PWD/.public-workers/bin/robotics-acceptance" > bootstrap.json
For a source checkout, use tools/prepare-bootstrap.py instead of the bundle
path. Repeat --domain for each selected qualification domain. The helper prints the
artifact/bundle ID mapping to stderr and the existing bootstrap JSON to stdout.
Success exits 0; a refused input exits 2 without emitting a bootstrap.
IDs derive from logical subject names and remain stable when the corpus moves.
Built-in schema IDs use the installed public catalog, replacing dots with
underscores. No document bytes or signed subject names are rewritten.
The imported file contains literal arguments on separate lines, not a shell
command. Only artifact/extension bindings and the public qualification profile
pair are accepted: v1 without a comparison rule, or v2 with
exact_assertion_outcome. These profile fields are data, never forwarded to a
worker. The public contracts loader validates selected contract documents and
provides their exact SHA-256/size. Contract documents, metrics and declared
extension schemas enter the existing catalog; recordings, packages and other raw
payloads stay outside this read corpus. A bundle needs one scenario and the
selected runtime-manifests/<domain>.json; optional roles must be unambiguous.
Preparation refuses links, nonregular/outside inputs, changed selected files, unknown arguments and existing MCP size/count violations. It assumes a stable operator-owned corpus: its path/stat checks do not establish raceproof admission against malicious concurrent directory replacement. It neither verifies signatures nor qualifies the package. Each later MCP call still verifies the registered identities through the existing private snapshot mechanism. Executables, roots and trust remain explicit operator choices.
Resource-aware clients can discover the registered choices by listing resources
and reading robotics-runtime://catalog. This bounded, fixed bootstrap view
contains schema IDs/names, relative artifact paths with SHA/size and bundle
roles. Reading it launches no worker. Tool calls still capture and verify the
selected bytes; catalog metadata is neither a fresh file check nor qualification.
For a stock mcporter 0.16.1 configuration
whose robotics_runtime entry selects the approved Node/entrypoint/config argv,
list and read the catalog, then use its IDs in the six existing tools:
mcporter --config /absolute/operator/mcporter.json resource robotics_runtime --output json
mcporter --config /absolute/operator/mcporter.json resource robotics_runtime robotics-runtime://catalog --output json
Results and limits¶
Each tool returns a JSON text envelope with the public Jobs result:
ok, exitCode, signal, timedOut, canceled, stdout, stderr,
diagnostic, code, durationMs, and captured input IDs/digests/sizes.
Bootstrap may include extensionSchemas: [{ uri, artifact_id }]. Schema bytes
pass the same identity/snapshot checks and count toward the combined input limit.
Only validate_documents and explain_bundle receive the public CLI extension
registry; requests cannot choose a URI or path. describe_contract describes
registered built-in schemas. Explain validates document relationships and metadata;
it does not fetch model/dataset/permit asset URIs or verify those asset bytes.
Each stdout/stderr value is a UTF-8-decoded string; Execa applies final-newline
stripping after capture. The adapter leaves worker JSON as text, so large integer
tokens never become JavaScript Numbers. MCP encodes these strings inside its own JSON envelope.
These text results do not preserve arbitrary original worker-stream bytes.
isError describes an invocation or admission failure. A successful explanation
of a failed result preserves that result’s failure; it does not make the run pass.
An offline dependency report is not native readiness or qualification.
Default limits are 30 seconds per worker, 1,048,576 UTF-16 code units per decoded
output stream and 16 MiB combined regular-file input. Bootstrap overrides are
capped at 120 seconds, 4,194,304 code units per output stream and 64 MiB input.
limits.maxOutputBytes measures JavaScript string .length before final-newline
removal. It is not an encoded MCP JSON envelope byte limit.
Four calls may execute concurrently. Inputs are captured into
private verified read-only copies, removed after the worker settles. Symlinks,
changed bytes, outside paths and unknown IDs refuse before worker startup.
Byte bounds apply to regular-file capture. Worker deadlines do not interrupt
blocked filesystem calls; the client must separately bound ownership of the
stdio server process, including startup and filesystem operations.
Stdio trusts the local operator’s bootstrap and installed worker code. Tool annotations are hints, not authorization or an OS sandbox. This package exposes no HTTP/OAuth listener, native run catalog, start/cancel command or cleanup API. Execution integrations use actual admitted consumer/controller operations and the existing capture/drain/export/cleanup lifecycle. The server integration contract keeps read, execute, cancel and recovery permissions distinct. An optional Tasks projection reports an existing operation handle; it adds no execution owner. Dagu’s own MCP endpoint belongs to the selected local campaign workbench and has broader operator powers. It does not replace this document adapter.
Test¶
From the source checkout after installing the dependencies above:
MCP_TEST_CONTRACTS_CLI="$PWD/.public-workers/bin/robotics-contracts" \
MCP_TEST_HARNESS_CLI="$PWD/.public-workers/bin/robotics-acceptance" \
npm test
Tests use the official MCP client and the installed public CLIs. The installed consumer check installs only the host and mcp workspaces from the single root lockfile and runs the existing tool tests with a read-only filesystem, no network and no source checkout. Native execution and desktop client qualification have separate gates. Controlled worker probes separately exercise raw 64-bit output, timeout, output overflow and request cancellation. These probes are subprocess-boundary checks.
With the locked published workers, run the native v2 document integration check:
MCP_TEST_CONTRACTS_CLI="$PWD/.public-workers/bin/robotics-contracts" \
MCP_TEST_HARNESS_CLI="$PWD/.public-workers/bin/robotics-acceptance" \
npm run test:native
This check prepares the public native archive example before starting MCP. It then exercises all six read operations, original source hashes, missing observation diagnostics and large integer preservation through real CLI validation. It does not execute a native workload through MCP.
See result and recording inspection for the CLI/JUnit path and compatible upstream viewers.