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).

Zero-config npm usage is also supported:

npx -y figranium-mcp

For local development:

git clone https://github.com/figranium/figranium-mcp
dcd figranium-mcp
npm install
npm run build

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

Environment Variables

The server requires the following environment variables to interact with your Figranium instance:

• FIGRANIUM_BASE_URL: The base URL of your Figranium server. Defaults to http://localhost:11345.
• FIGRANIUM_API_KEY: The API key generated from Figranium settings to authorize requests. This variable is required for startup.

If FIGRANIUM_API_KEY is missing, the server prints a clear setup message and exits gracefully.

---

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": "npx",
      "args": ["-y", "figranium-mcp"],
      "env": {
        "FIGRANIUM_BASE_URL": "http://localhost: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://localhost:11345 when running via npx.

---

Cursor Integration

Add the following to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "figranium": {
      "command": "npx",
      "args": ["-y", "figranium-mcp"],
      "env": {
        "FIGRANIUM_BASE_URL": "http://localhost:11345",
        "FIGRANIUM_API_KEY": "YOUR_API_KEY"
      }
    }
  }
}

This lets Claude Desktop and Cursor launch the package directly without requiring a local build or a Docker bridge.

---

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 npx -y figranium-mcp