Figranium MCP Server

A Model Context Protocol (MCP) server for Figranium built using @modelcontextprotocol/sdk. This server allows LLM clients (like Claude Desktop, Cursor, and Manus AI) to discover, execute, inspect, schedule, and programmatically create Figranium automation tasks via standard STDIO transport.

Table of Contents

• Quick Start (Docker / OCI)
• Client Integration
  • Claude Desktop
  • Cursor IDE
  • Manus AI / Registry Clients
• Environment Variables
• Server-Wide System Instructions
• Available Resources
• Available Tools
  • Task Operations
  • Execution Operations
  • Schedule Operations
• Rich Input Diagnostics & Self-Correction
• Local Development & Source Build

Quick Start (Docker / OCI)

No Node.js runtime or repository clone is required. The official container image is published on GitHub Container Registry (ghcr.io).

docker pull ghcr.io/figranium/figranium-mcp:latest

Client Integration

Claude Desktop

Add the container configuration to your claude_desktop_config.json:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "figranium": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "ghcr.io/figranium/figranium-mcp:latest"
      ],
      "env": {
        "FIGRANIUM_BASE_URL": "[http://host.docker.internal:11345](http://host.docker.internal:11345)",
        "FIGRANIUM_API_KEY": "your_figranium_api_key_here"
      }
    }
  }
}

Note for Local Hosts: If your Figranium instance runs locally on your host machine, use http://host.docker.internal:11345 so the Docker container can reach your host network.

Cursor IDE

Add via Settings > Features > MCP > Add New MCP Server:

• Name: figranium
• Type: command
• Command: docker run -i --rm -e FIGRANIUM_BASE_URL=http://host.docker.internal:11345 -e FIGRANIUM_API_KEY=your_key ghcr.io/figranium/figranium-mcp:latest

Manus AI / Registry Clients

For environments supporting direct MCP Registry resolution, register using the server's official registry namespace:

io.github.figranium/figranium-mcp

Clients reading from the registry will resolve the ghcr.io OCI identifier automatically.

Environment Variables

Server-Wide System Instructions

The server initializes with embedded guidelines for LLM agents detailing the task lifecycle:

1. Task Creation: Structuring name, starting URL, execution mode (scrape, agent, or headful), and stealth mechanisms.
2. Step Sequence Construction: Ordering action steps (navigate, wait_selector, click, type, javascript) and execution flow.
3. Selector Strategy: Preferring robust ARIA, ID, and semantic class selectors with fallback strategies.
4. Execution & Variables: Injecting and overriding runtime context variables.

Available Resources

figranium://schemas/task-v1.json

• MIME Type: application/json
• Description: Exposes the complete JSON Schema specification of a Figranium task. Allows agents to dynamically inspect valid parameters and payload shapes.

Available Tools

Task Operations

• create_task: Create a complete, fully-configured Figranium automation task including sequential action steps, state variables, anti-bot stealth mechanisms, and optional scheduling.
• task_list: List all task IDs, names, and descriptions registered on the Figranium server.
• task_execute: Run a saved task by taskId with optional variable overrides.

Execution Operations

• execution_list: Retrieve a summary of past task execution logs and statuses.

Schedule Operations

• schedule_list: List all tasks with configured schedules.
• schedule_get_all_status: Retrieve overall scheduler state and metadata.
• schedule_get_status: Get active schedule details and next run time for a specific taskId.
• schedule_set: Create or update a cron or frequency schedule on a task.
• schedule_delete: Disable and remove a task schedule.
• schedule_describe: Validate and preview a schedule configuration without applying it.

Rich Input Diagnostics & Self-Correction

If an invalid parameter payload is supplied to create_task, the server returns structured Zod diagnostic output (isError: true). This allows connected LLMs to analyze schema errors and attempt immediate self-correction.

Example response:

Schema Validation Failed!

Detailed breakdown of validation errors:
 - At Step Index 2 (action step #3), parameter "type" failed validation: Invalid enum value. Expected 'click' | 'type' | 'wait' ..., received 'clikc'

Local Development & Source Build

If you wish to modify the source code or run without Docker:

Prerequisites

• Node.js v18+
• npm v9+

Build & Run

# Clone repository
git clone [https://github.com/figranium/figranium-mcp.git](https://github.com/figranium/figranium-mcp.git)
cd figranium-mcp

# Install dependencies and compile TypeScript
npm install
npm run build

# Watch mode for active development
npm run watch

Testing with MCP Inspector

Inspect server tools and resources using the official MCP debugging suite:

npx @modelcontextprotocol/inspector node dist/index.js