Figranium MCP Server

Create a new Cabinet (durable download queue) on the Figranium server.

Create a complete, fully-configured Figranium automation task including sequential action steps, state variables, anti-bot stealth mechanisms, and optional scheduling.

!!! IMPORTANT GUIDELINES FOR LLM AGENTS !!!

1. VARIABLE TEMPLATING SYNTAX: You MUST use {$variable_name} (with a single curly brace and dollar sign, e.g. {$myVar}) for variable references/templating inside action values, URLs, headers, or body fields. NEVER use double curly braces like {{variable_name}} or JavaScript-style templates like ${variable_name}, as these syntaxes are unsupported and will cause execution failures.

2. TASK VALIDATION: Newly created or updated tasks are ordinarily intended to be validated against a real execution result so configuration, selectors, and extracted output can be checked.

3. MODE SELECTION: Use agent mode by default, including for scraping tasks. scrape mode does not support action blocks and should be used only when extremely fast, action-free scraping is required. Use headful for visible interactive debugging.

4. WORKFLOW BOUNDARIES: Timed Wait and Navigate To cannot be the first action. A fixed initial delay belongs in task-level wait, and the initial destination belongs in task-level url. Get Content cannot be the final action because its value needs a consuming action; use extractionScript for final structured output.

1. Purpose

Use this tool when you need to automate any recurring or complex web-based workflows, including data extraction (scraping), automated form-filling, dashboard testing, or dynamic visual monitoring. Tasks are stored permanently in Figranium and can be executed ad-hoc, triggered via API, or scheduled.

2. Execution Model

Figranium tasks run as a linear sequence of steps defined in the 'actions' array. Actions are processed in order from top to bottom. Control flow steps (such as 'if', 'while', 'repeat') allow loops and branching, while 'on_error' steps define fallback behaviors. Variables represent the state and can be updated dynamically during execution. Ensure all opened block structures (such as 'if', 'while', 'repeat', 'foreach') are closed with an 'end' action step.

3. Comprehensive Step Types

• 'navigate': Redirect browser to a new URL specified in the 'value' field.

• 'wait': Pause execution for N seconds specified in the 'value' field.

• 'wait_selector': Pause until the DOM element matching 'selector' is rendered.

• 'click': Simulate a single, double, or right click on the element matching 'selector'; set 'clickType' to 'double' or 'right' when needed.

• 'check' / 'uncheck': Idempotently set the checked state of a checkbox or radio control matching 'selector'.

• 'drag_and_drop': Drag from 'selector' to the required 'targetSelector'.

• 'reload': Reload the current page and wait for DOM content to load.

• 'select': Choose an option from a native select using 'selector' and its option 'value'.

• 'type': Type the 'value' into the 'selector' input element. Use 'typeMode' to clear/replace or append.

• 'hover': Move mouse pointer to the element matching 'selector'.

• 'press': Press a specific keyboard key (e.g., 'Enter') specified in the 'key' field.

• 'scroll': Scroll the page or target element to a specific coordinate or direction.

• 'javascript': Execute custom JavaScript on the page. Stored in 'value', outputs can be saved to 'varName'.

• 'screenshot': Capture and save a screenshot.

• 'http_request': Perform direct API requests.

• 'if', 'else', 'end': Conditional blocks based on variables.

• 'while', 'repeat', 'foreach': Looping blocks.

• 'stop': Halt task execution.

• 'set': Set or update a task variable.

• 'solve_captcha': Attempt to automatically solve a detected CAPTCHA challenge.

• 'wait_captcha': Pause until a CAPTCHA challenge is initialized/ready without solving it.

• 'upload': Attach the newest unuploaded file, ZIP, or folder from a Cabinet (see 'cabinetId') to a file input, chooser, or drop target matching 'selector'.

• 'finalize_uploads': Mark all Cabinet items attached during the execution as uploaded.

4. Selector Strategy & Fallbacks

When targeting elements, follow this hierarchy of selectors:

1. Unique IDs (e.g., '#submit-button')

2. ARIA roles and labels (e.g., '[aria-label="Search"]')

3. Reliable CSS classes or data attributes (e.g., '.btn-primary', '[data-testid="login"]')

4. Text matchers or XPath as a final resort. Fallback: If an element might be missing or slow to load, wrap the interaction inside an 'if' block evaluating a variable or use 'on_error' to catch failure.

5. Edge Cases & Retry Logic

• Timeouts: Wait-selectors have a default timeout. Ensure critical steps use 'wait_selector' first to avoid clicking non-existent elements.

• Stealth: Turning on options like 'naturalTyping', 'cursorGlide', and 'allowTypos' simulates authentic human speed and rhythm to prevent anti-bot blocking on protected sites.

• Statelessness: Enable 'statelessExecution' to ensure execution is completely fresh without persistent browser storage/cookies.

6. Complex Real-World Multi-Step JSON Example:

{
  "name": "HackerNews Custom Scraper",
  "url": "https://news.ycombinator.com",
  "mode": "agent",
  "wait": 3,
  "rotateUserAgents": true,
  "stealth": {
    "allowTypos": true,
    "cursorGlide": true,
    "naturalTyping": true
  },
  "actions": [
    {
      "type": "wait_selector",
      "selector": ".hnname"
    },
    {
      "type": "click",
      "selector": "a.hnmore"
    },
    {
      "type": "wait",
      "value": "2"
    },
    {
      "type": "javascript",
      "value": "return Array.from(document.querySelectorAll('.athing')).map(tr => ({ id: tr.id, title: tr.querySelector('.titleline > a')?.innerText, href: tr.querySelector('.titleline > a')?.href }));",
      "varName": "hn_stories"
    },
    {
      "type": "navigate",
      "value": "https://httpbin.org/post"
    },
    {
      "type": "wait_selector",
      "selector": "pre"
    },
    {
      "type": "javascript",
      "value": "console.log('Finished scraping and navigated successfully.');"
    }
  ],
  "variables": {},
  "extractionFormat": "json"
}

List a summary of all past execution records.

List all Cabinets (durable download queues) configured on the Figranium server, including their IDs, names, and item counts. Use this to find a Cabinet ID to reference in a Task's 'downloadCabinetId' field or an 'upload' action.

Disable and remove the schedule configuration from a specific task.

Validate and preview/describe a schedule configuration without saving it.

Get overall scheduler status and metadata for all schedules.

Get the detailed schedule status, cron configuration, and next run time for a specific task.

List all tasks that have schedules configured (enabled or not).

Create or update a schedule for a specific task.

Permanently delete a Figranium task by taskId.

Execute a saved automation task by ID and return its real run result. This is also useful for validating newly created or updated tasks against actual browser behavior and output.

List all task IDs, names, and descriptions from Figranium.

Update one or more fields on an existing, saved Figranium browser-automation task.

When to use

Use this after task_list identifies the task to modify—for example, to correct its name or URL, replace its action sequence, change input variables, adjust stealth settings, or revise its extraction script or schedule. The task remains stored under the same taskId and is not executed by this operation.

Required request shape

• taskId is required and must be the ID of an existing task.

• Include at least one additional field. An ID-only request is rejected because it would make no change.

• Every other field is optional: omitted fields are left unchanged.

• Repeating the same request is safe and produces the same stored configuration.

Important update behavior

• For compound fields—actions, variables, stealth, translation, and schedule—send the complete value you want stored for that field, rather than only a nested fragment.

• actions are an ordered replacement sequence. Use agent or headful mode for actions; scrape mode does not support them. Close every if, while, repeat, or foreach block with an end action.

• A replacement sequence cannot start with Timed Wait or Navigate To: use task-level wait or url to establish the starting state. It also cannot end with Get Content: feed that value into a later action, or use extractionScript for final output.

• Use {$variable_name} for task-variable references in URLs, headers, bodies, and action values. Do not use {{variable_name}} or ${variable_name}.

• This tool changes saved configuration but does not run or delete a task. Use task_execute to validate an updated workflow and task_delete only when permanent removal is intended.

Examples

Rename a task: { "taskId": "task_101", "name": "Daily lead extractor" }.

Replace its workflow and output extraction: { "taskId": "task_101", "actions": [{ "type": "wait_selector", "selector": "[data-testid='results']" }], "extractionScript": "return document.title" }.

Retrieve the full template workflow and README by UUID.

Search the Figranium v0.20 template catalog with pagination.