Agents and MCP
SuiteCut::Client is a C++20 library with a stable C ABI. It controls suitecut's CEF engine,
installed Chrome or Chromium, or Firefox, without Node.js, CEF headers or an automation library. Its
suitecut-native-control executable is also a command-line tool and an MCP server. No
model is embedded; your host brings the agent.
Build and install
You need a C++20 compiler, threads, OpenSSL and ZLIB. Linux and a separately qualified macOS ARM64 build are supported.
cmake -S native/client -B build/native-client -DCMAKE_BUILD_TYPE=Release
cmake --build build/native-client -j 2
ctest --test-dir build/native-client --output-on-failure
cmake --install build/native-client --prefix "$PWD/build/native-client-install"
Add -DBUILD_SHARED_LIBS=ON for a shared library. Downstream CMake projects use
find_package(SuiteCutClient CONFIG REQUIRED) and link SuiteCut::Client. The C ABI is declared in suitecut/client.h.
C++ API
suitecut/browser.hpp provides browser, context, page and locator objects. The default
backend is the CEF engine; its path must be absolute, with its runtime files beside it.
#include <suitecut/browser.hpp>
suitecut::LaunchOptions options;
options.executable = "/absolute/path/to/suitecut-browser";
auto browser = suitecut::Browser::launch(options);
auto context = browser.new_context();
auto page = context.new_page();
page.navigate("https://example.com");
auto observation = page.observe(); // Accessibility nodes and references.
auto title = page.evaluate("document.title").as_string();
browser.close();
Chrome and Firefox
The same facade launches an installed Chrome or Chromium over a private CDP pipe, without the
CEF runtime. C callers use sc_client_launch_chromium.
suitecut::LaunchOptions options;
options.executable = "/usr/bin/chromium";
options.headless = true;
auto browser = suitecut::Browser::launch_chromium(options);
auto page = browser.main_page();
page.navigate("https://example.com");
auto screenshot = page.screenshot();
browser.close();
Firefox uses native WebDriver BiDi through the same page, locator and agent interfaces.
Browser::connect_firefox attaches to a running Firefox instead.
suitecut::LaunchOptions options;
options.executable = "/usr/bin/firefox";
auto browser = suitecut::Browser::launch_firefox(options);
auto page = browser.main_page();
page.navigate("https://example.com");
auto title = page.title();
Simple agent
SimpleAgent gives a model three tools: observe, act and
wait. Each observation returns short element refs and replaces the previous ones,
so stale refs are rejected.
#include <suitecut/simple_agent.hpp>
suitecut::AgentDriver driver(browser);
suitecut::SimpleAgent agent(driver);
auto seen = agent.call("observe", {{"boxes", true}});
auto done = agent.call("act", {
{"action", "fill"}, {"ref", "e1"}, {"value", "Hello"}});
auto ready = agent.call("wait", {{"text", "Saved"}, {"timeoutMs", 2000}});
- Compact observations return up to 100 controls and 8 KiB of text by default, with explicit truncation.
-
act.actionsruns up to 64 known actions in order and stops on the first failure. - Calls share one deadline, 5 seconds by default and capped at 30 seconds.
- Mutations are never retried, and password values are redacted.
-
deliveredrecords that the browser acknowledged an action;effectchecks an optional visible condition. Neither proves the task succeeded.
Command-line sessions
A named session keeps a browser alive between invocations. Only open starts one;
close retires it, and idle sessions close after ten minutes.
suitecut-native-control --session shop --browser /usr/bin/chromium open https://example.com
suitecut-native-control --session shop snapshot
suitecut-native-control --session shop --response none fill e12 'Ada'
suitecut-native-control --session shop click e15
suitecut-native-control --session shop snapshot --scope '#checkout' --delta
suitecut-native-control --session shop screenshot --output /tmp/checkout.png
suitecut-native-control --session shop close
--response none keeps the other refs from the last observation valid. Use
help, tools or profiles to explore without launching a browser.
Files written with --output are created with mode 0600. Named sessions need POSIX.
MCP server
Configure the installed executable as a stdio MCP server.
{
"mcpServers": {
"suitecut": {
"command": "/absolute/install/prefix/bin/suitecut-native-control",
"args": ["--browser", "/usr/bin/chromium", "--mcp"]
}
}
}
Screenshots come back as image content and PDFs as embedded resources. Page content and WebMCP descriptions are untrusted data. Closing stdin retires the session.
Tool groups and backends
The default core group has the three agent tools, profiles and eight navigation,
reading, tab, frame, viewport, upload and history tools. Add network,
state, debug or media, or use all for the full
53-tool driver. Groups limit what's advertised; they aren't a sandbox.
suitecut-native-control --browser /usr/bin/chromium --mcp --tools core,network
suitecut-native-control --backend firefox --browser /usr/bin/firefox --mcp
suitecut-native-control --backend cef --browser /absolute/path/to/suitecut-browser --mcp
suitecut-native-control --connect 9222 --mcp
--connect-header, --tls-ca, --tls-cert and
--tls-key configure remote connections. --profile,
--browser-arg and --headed are also supported.