SideButton

Appearance

MCP Tools Reference ​

Complete reference for all 29 MCP tools the SideButton server exposes, generated from the server's own tool registry. Tools marked read-only never change page, input, or workflow state.

Connect a client first — see MCP Setup. Browser tools require the Chrome extension to be connected (check with get_browser_status); the deep-dive on selectors and snapshots lives in Browser Tools.

Workflow & Run Tools ​

Run workflow automations and read their results.

run_workflow ​

Run Workflow

Execute a workflow automation by ID. Returns a run_id for tracking execution status.

ParameterTypeRequiredDescription
workflow_idstringYesUnique identifier of the workflow
paramsobjectNoKey-value parameters required by the workflow

get_workflow ​

Get Workflow · read-only

Get detailed information about a specific workflow.

ParameterTypeRequiredDescription
workflow_idstringYesUnique identifier of the workflow

list_workflows ​

List Workflows · read-only

List all available workflow automations.

ParameterTypeRequiredDescription
sourcestringNoFilter by source Values: all, actions, workflows.

get_run_log ​

Get Run Log · read-only

Retrieve the execution log for a completed workflow run.

ParameterTypeRequiredDescription
run_idstringYesThe run ID returned from run_workflow

list_run_logs ​

List Run Logs · read-only

List recent workflow execution logs.

ParameterTypeRequiredDescription
limitnumberNoMaximum number of logs to return
workflow_idstringNoFilter logs by workflow ID

Artifact Tools ​

Publish files from a running job to the portal.

publish_artifact ​

Publish Artifact

Publish a piece of evidence (a screenshot, a design mockup, an RCA/coverage report) to the portal RIGHT NOW, mid-session, and get back a paste-ready snippet to cite in your ONE resolution comment on the ticket. The file is uploaded, attached to the ticket automatically, and given a tokenized no-login download link — the snippet contains that link plus the Jira inline-attachment reference. Use this the moment you have evidence worth showing, instead of waiting for the end of the session (nothing you save after your comment is written can be cited in it). Only works on a dispatched job (it needs the on-box job context); on a ticketless/chat job it returns a download link only. Files must be ≤ 25 MB and live under your home directory. On any failure the file is left on disk and still uploads at session end, so save deliverables under artifacts/ as a fallback.

ParameterTypeRequiredDescription
pathstringYesPath to the file to publish. A relative path resolves against your workspace (~/workspace); an absolute path is also accepted, as long as it stays within your home directory.
kindstringNoGallery category. Optional — inferred from the file extension when omitted (images → screenshot, .svg/.html → mock, .pdf/.md/.txt/.csv/.json → report). Values: screenshot, mock, report.
captionstringNoOptional short label for the snippet. Shown only in the returned snippet as a hint for your comment; it is NOT stored on the artifact.

Browser Session Tools ​

Connection status, whole-page capture, and HTTP auth for the controlled browser.

get_browser_status ​

Get Browser Status · read-only

Check if the browser extension is connected.

No parameters.

capture_page ​

Capture Page Selectors · read-only

Capture selectors and interactive elements from the current page.

No parameters.

set_basic_auth ​

Set HTTP Basic Auth

Provide HTTP Basic Auth credentials so the browser logs in silently instead of showing the native username/password modal, which would otherwise block the page and hang automation. Applies to the connected tab. Omit "origin" to use the credentials for any site that challenges; pass "origin" (e.g. "https://staging.example.com") to scope them to one site. When a challenge has no matching credentials it is dismissed so the page never hangs.

ParameterTypeRequiredDescription
usernamestringYesBasic Auth username.
passwordstringYesBasic Auth password.
originstringNoOptional origin to scope the credentials to (e.g. "https://staging.example.com"). Omit to apply to any challenged site.

clear_basic_auth ​

Clear HTTP Basic Auth

Remove stored HTTP Basic Auth credentials. Omit "origin" to clear all stored credentials; pass "origin" to clear just that site.

ParameterTypeRequiredDescription
originstringNoOptional origin to clear (e.g. "https://staging.example.com"). Omit to clear all stored credentials.

Move around and read the page without changing it.

Navigate Browser

Navigate the connected browser tab to a URL.

ParameterTypeRequiredDescription
urlstringYesThe URL to navigate to

snapshot ​

Accessibility Snapshot · read-only

Capture accessibility snapshot of the current page. Returns YAML with element refs for use with click/type. Use includeContent=true to also include visible text content as markdown. Note: taking a snapshot may dismiss inline modals or popups — use screenshot instead if you need to verify modal content.

ParameterTypeRequiredDescription
includeContentbooleanNoInclude visible text content in the snapshot as markdown (default: false). Useful for reading articles, documentation, or any page content.

exists ​

Check Element Exists · read-only

Check if an element exists on the page. Returns true/false without throwing. Useful for conditional logic.

ParameterTypeRequiredDescription
selectorstringYesCSS selector to check.
timeoutnumberNoHow long to wait before returning false, in milliseconds (default: 2000).

wait ​

Wait for Element · read-only

Wait for an element to appear on the page. Blocks until the element matching the selector exists in the DOM, or throws after timeout.

ParameterTypeRequiredDescription
selectorstringYesCSS selector to wait for.
timeoutnumberNoMaximum wait time in milliseconds (default: 5000).

extract ​

Extract Element Text · read-only

Extract text content from an element.

ParameterTypeRequiredDescription
selectorstringYesCSS selector for the element.

extract_all ​

Extract All Matching · read-only

Extract text from all elements matching a selector, joined by a separator. Useful for getting lists of items, table columns, or repeated elements.

ParameterTypeRequiredDescription
selectorstringYesCSS selector matching multiple elements.
separatorstringNoString to join results with (default: "\n").
attributestringNoOptional attribute to extract instead of text content (e.g., "href", "src").

extract_map ​

Extract Structured Data · read-only

Extract structured data from repeated elements. For each element matching the outer selector, extracts named fields using sub-selectors. Returns JSON array of objects.

ParameterTypeRequiredDescription
selectorstringYesCSS selector for the repeating container elements (e.g., "table tbody tr", ".card").
fieldsobjectYesMap of field names to extraction rules. Each rule has a "selector" (relative CSS selector) and optional "attribute".

screenshot ​

Take Screenshot

Capture a screenshot of the current page. Prefer cropping to a specific area instead of capturing the full viewport — use ref (from snapshot), selector (CSS), or region (manual rect) to save context tokens. Full viewport is fine for first visit to a new page; after that, crop to the relevant section. Pass path to write the PNG to a file instead of returning image bytes — that is what you want for docs screenshots and QA evidence, since the file can then be published with publish_artifact and never enters your context.

ParameterTypeRequiredDescription
refnumberNoElement reference from snapshot (the number after ref=). Crops screenshot to that element with padding.
selectorstringNoCSS selector for the element. Crops screenshot to that element with padding.
regionobjectNoManual crop region in CSS pixels (viewport coordinates).
pathstringNoWrite the PNG here instead of returning image bytes; returns the path and byte count as text. Accepts ~/... or an absolute path; a relative path resolves against ~/workspace. Must stay inside the home directory. Parent directories are created, and an existing file is overwritten.

Interaction Tools ​

Act on the page: click, type, select, scroll, and scripted batches.

click ​

Click Element

Click an element on the page.

ParameterTypeRequiredDescription
selectorstringNoCSS selector for the element. Supports :has-text("text") pseudo-selector.
refnumberNoElement reference from snapshot (the number after ref=).
elementstringNoHuman-readable element description (for logging).

type ​

Type Text

Type text into an input element.

ParameterTypeRequiredDescription
selectorstringNoCSS selector for the input element.
refnumberNoElement reference from snapshot.
elementstringNoHuman-readable element description.
textstringYesText to type.
submitbooleanNoPress Enter after typing (default: false).

fill ​

Fill Form Field

Fill a form field by setting its value programmatically. Unlike "type" (which simulates keystrokes), "fill" sets the value directly and triggers React/Vue/Angular change events. Use this for framework-controlled inputs where "type" doesn't work.

ParameterTypeRequiredDescription
selectorstringYesCSS selector for the input element.
valuestringYesValue to set on the input.

press_key ​

Press Key

Press a key on the keyboard. Use this for keyboard shortcuts, Tab navigation, Enter, Escape, arrow keys, etc. Supports key combinations like "Ctrl+A" or "Shift+Tab".

ParameterTypeRequiredDescription
keystringYesKey to press. Examples: "Tab", "Enter", "Escape", "ArrowDown", "Backspace", "Shift+Tab", "Ctrl+A". For single characters, use the character directly (e.g., "a").
selectorstringNoOptional CSS selector to focus before pressing the key.
refnumberNoOptional element reference from snapshot to focus before pressing the key.

select_option ​

Select Dropdown Option

Select an option from a native <select> dropdown element. Use this instead of click for <select> elements, as native dropdowns cannot be controlled via click events.

ParameterTypeRequiredDescription
selectorstringNoCSS selector for the <select> element.
refnumberNoElement reference from snapshot (the number after ref=).
elementstringNoHuman-readable element description (for logging).
valuestringNoThe option value to select (matches <option value="...">).
labelstringNoThe visible text of the option to select (matches <option> text content).

hover ​

Hover Element

Hover over an element (positions cursor for scroll targeting).

ParameterTypeRequiredDescription
selectorstringYesCSS selector for the element.

scroll ​

Scroll Page

Scroll the page.

ParameterTypeRequiredDescription
directionstringYesScroll direction. Values: up, down, left, right.
amountnumberNoScroll amount in pixels (default: 300).

scroll_into_view ​

Scroll Element Into View

Scroll a specific element into the viewport. More precise than "scroll" — targets an exact element.

ParameterTypeRequiredDescription
selectorstringYesCSS selector for the element to scroll into view.
blockstringNoVertical alignment in viewport (default: "center"). Values: start, center, end, nearest.

inject_css ​

Inject CSS

Inject a CSS rule into the current page. The main use is pre-capture redaction: blur or hide sensitive elements, then screenshot to a file, so no unredacted image ever exists. Pass an id to make the injection replaceable — injecting the same id again swaps the rule rather than stacking a second one.

ParameterTypeRequiredDescription
cssstringYesCSS to inject, e.g. ".user-email { filter: blur(6px); }"
idstringNoOptional identifier for the injected style element, so it can be replaced or removed later.

evaluate ​

Evaluate JavaScript

Execute JavaScript in the browser page context and return the result. Useful for reading page state, checking values, or performing calculations.

ParameterTypeRequiredDescription
jsstringYesJavaScript code to evaluate in the page context.

browser_batch ​

Batch Browser Actions

Run a SEQUENCE of browser actions in ONE call instead of one round trip per action. Each step is the same shape you would pass to the individual tool, plus a "cmd" field naming which tool to run.

A batch is a DETERMINISTIC run: actions you already know the selectors for, executed top to bottom, halting at the first failure (unless on_error:"continue"). By default it ends by returning a fresh accessibility snapshot of the resulting page, so you can decide the next move in the same turn. The moment you need to SEE something before choosing an action, end the batch and read the returned snapshot.

Guidance:

  • Prefer CSS selectors over refs inside a batch. Refs come from a prior snapshot and go stale the instant a step re-renders the page; selectors survive.
  • After a navigate (or an action that loads new content), add a { "cmd": "wait", "selector": "..." } step before interacting with the new content.
  • Add "optional": true to a step whose failure should not halt the batch.
  • Add "return": "drop" to a side-effect-only step you do not need echoed back (e.g. a screenshot taken only to trigger lazy-load).

Batchable cmds: navigate, wait, exists, click, type, fill, press_key, select_option, scroll, scroll_into_view, hover, extract, extract_all, extract_map, snapshot, screenshot, inject_css, evaluate.

To capture a redacted screenshot in one call: navigate → inject_css (blur the sensitive selectors) → wait → screenshot with a "path". The shot lands on disk already redacted and no image bytes come back.

Example — log in then land on the dashboard in one call: { "steps": [ { "cmd": "navigate", "url": "https://app.example.com/login" }, { "cmd": "wait", "selector": "#user" }, { "cmd": "fill", "selector": "#user", "value": "alice" }, { "cmd": "fill", "selector": "#pw", "value": "secret" }, { "cmd": "click", "selector": "button[type=submit]" }, { "cmd": "wait", "selector": ".dashboard" } ] }

ParameterTypeRequiredDescription
stepsarray of objectsYesOrdered list of actions. Each item is { "cmd": "<tool name>", ...that tool's arguments }. Optional per-step keys: "optional" (boolean — failure never halts the batch) and "return": "drop" (omit this step's output from the response).
on_errorstringNo"stop" (default): halt at the first failed step, marking the rest skipped. "continue": run every step regardless. Values: stop, continue.
snapshot_tailbooleanNoAppend a fresh accessibility snapshot of the final page to the response so you can decide the next action (default: true). Skipped automatically when the last step is already a snapshot or screenshot. Set false to opt out.

Next Steps ​

Released under the Apache-2.0 License.

Copyright 2025-present Max Svistun