funifier-mcp

Funifier AI toolkit — API client, MCP server, and AI assistant skills for the Funifier gamification platform.

What's included

| Component | Description | |-----------|-------------| | API Client | Pure Node.js client for the Funifier REST API (80+ methods, 18 resource types) | | MCP Server | Model Context Protocol server — 14 tools, 3 prompts, documentation resources | | Skills | 32 guided workflows for Claude Code, Codex, OpenCode, Copilot, Continue, and Cursor | | CLI | npx funifier-mcp@latest init — interactive setup for AI platforms |

Quick Start

npx funifier-mcp@latest init

One command — no install required. init is interactive: it asks which AI platforms you use (Claude Code, Codex CLI, OpenCode, Cursor, Copilot, Google Antigravity), prompts for your Funifier credentials, and writes all config files automatically (skills, MCP config, funifier.json).

CLI Reference

npx funifier-mcp@latest init         Interactive setup for AI platforms
funifier-mcp                         Start the MCP server (stdio)
funifier-mcp --version               Print version

Documentation access

Once the MCP server is connected, agents discover and read docs through MCP tools — the docs ship inside the package, so nothing is copied into your project:

• funifier_search_docs "<query>" — ranked, relevant doc paths for a query
• funifier_read_doc path=<path> — full markdown of a doc (e.g. path=modules/trigger)

MCP Server Setup

The MCP server exposes Funifier as tools in any MCP-compatible AI client. npx funifier-mcp@latest init configures it automatically. For manual setup, install the package first (npm install funifier-mcp) then configure your client:

Claude Code / Cursor / Antigravity (.mcp.json)

{
  "mcpServers": {
    "funifier": {
      "command": "node",
      "args": ["/absolute/path/to/node_modules/funifier-mcp/dist/mcp/bundle.js"],
      "env": {
        "FUNIFIER_API_KEY": "your-api-key",
        "FUNIFIER_SECRET_KEY": "your-secret-key",
        "FUNIFIER_SERVER_URL": "https://your-instance.funifier.com"
      }
    }
  }
}

Codex CLI (.codex/config.toml)

[mcp_servers.funifier]
command = "node"
args = ["/absolute/path/to/node_modules/funifier-mcp/dist/mcp/bundle.js"]
enabled = true

[mcp_servers.funifier.env]
FUNIFIER_API_KEY = "your-api-key"
FUNIFIER_SECRET_KEY = "your-secret-key"
FUNIFIER_SERVER_URL = "https://your-instance.funifier.com"

OpenCode (opencode.json)

{
  "mcp": {
    "funifier": {
      "type": "local",
      "command": ["node", "/absolute/path/to/node_modules/funifier-mcp/dist/mcp/bundle.js"],
      "environment": {
        "FUNIFIER_API_KEY": "your-api-key",
        "FUNIFIER_SECRET_KEY": "your-secret-key",
        "FUNIFIER_SERVER_URL": "https://your-instance.funifier.com"
      }
    }
  }
}

Runtime connection

If no config is provided at startup, use the funifier_connect tool to connect:

funifier_connect({ apiKey: "...", secretKey: "...", serverUrl: "https://..." })

Credentials via funifier.json

Place in your project root for automatic connection at startup:

{
  "apiKey": "your-api-key",
  "secretKey": "your-secret-key",
  "serverUrl": "https://your-instance.funifier.com"
}

Add funifier.json to .gitignore — it contains secrets. Also ignore .funifier/backups/ — permission snapshots may contain app_secret values and full scope lists.

MCP Tools

| Tool | Description | |------|-------------| | funifier_connect | Connect to a Funifier instance (or switch between instances) | | funifier_list | List resources by type with optional search filtering | | funifier_get | Get a specific resource with full details (including code) | | funifier_save | Create or update a resource | | funifier_delete | Delete a resource by type and ID | | funifier_execute | Execute a scheduler, aggregate, or public endpoint | | funifier_logs | Get execution logs for triggers and schedulers | | funifier_database | Query, aggregate, insert, update, delete on any collection | | funifier_permissions | Manage API scopes/security roles and Studio roles/assignments; every mutation auto-backups prior state to .funifier/backups/ — use list_backups and restore_backup to roll back |

Resource types: trigger, scheduler, aggregate, websocket, widget, custom-page, public-endpoint, challenge-aggregate, auth-module, ai-knowledge, action, challenge, point, level, leaderboard, quiz, virtual-good-catalog, virtual-good-item

Permissions backup and rollback

Every mutating funifier_permissions action writes a full pre-image snapshot under .funifier/backups/ before the remote write. Snapshots may contain secrets — keep .funifier/backups/ in .gitignore (npx funifier-mcp init adds it automatically).

funifier_permissions({ action: "list_backups" })
funifier_permissions({ action: "restore_backup", backup_path: "<path from list_backups>" })

Restore refuses cross-server application when the snapshot's serverUrl differs from the current connection. Optional env vars: FUNIFIER_PROJECT_ROOT (project directory, set in generated MCP configs) and FUNIFIER_BACKUP_ROOT (override backup directory). Snapshots are not auto-pruned — delete old files manually when needed.

Skills and Instructions

npx funifier-mcp@latest init copies the right files for each platform automatically. For manual setup, install first (npm install funifier-mcp) then copy:

Claude Code

npm install funifier-mcp
cp -r node_modules/funifier-mcp/skills/* .claude/skills/

Start with /funifier in Claude Code — the router skill routes to the right workflow:

/funifier

Codex CLI / OpenCode

npm install funifier-mcp
cp node_modules/funifier-mcp/AGENTS.md .

The AGENTS.md is the entry point for Codex, OpenCode, and any agent that reads AGENTS.md.

GitHub Copilot / Continue

npm install funifier-mcp
mkdir -p .github
cp node_modules/funifier-mcp/.github/copilot-instructions.md .github/

Copilot and Continue automatically apply .github/copilot-instructions.md.

Cursor IDE

npm install funifier-mcp
mkdir -p .cursor/rules
cp node_modules/funifier-mcp/.cursor/rules/funifier.mdc .cursor/rules/

Cursor discovers and applies .mdc files in .cursor/rules/ automatically.

Available Workflows

All workflows are accessible through a single /funifier skill. The skill router loads in every conversation (one description) and loads the specific workflow file on demand.

| Workflow | Reference file | |----------|----------------| | Help and routing | references/help.md | | Debug any resource | references/debug.md | | Create trigger | references/create-trigger.md | | Create scheduler | references/create-scheduler.md | | Create aggregate | references/create-aggregate.md | | Create custom page | references/create-custom-page.md | | Create action | references/create-action.md | | Create challenge | references/create-challenge.md | | Create point category | references/create-point.md | | Create level progression | references/create-level.md | | Create leaderboard | references/create-leaderboard.md | | Create quiz | references/create-quiz.md | | Create virtual good | references/create-virtual-good.md | | Implement frontend | references/implement-frontend.md | | Manage player | references/manage-player.md | | Manage team | references/manage-team.md | | Create competition | references/create-competition.md | | Create folder | references/create-folder.md | | Create lottery | references/create-lottery.md | | Create mystery box | references/create-mystery.md | | Create story | references/create-story.md | | Create crossword | references/create-crossword.md | | Create notification | references/create-notification.md | | Create last mile | references/create-lastmile.md | | Create webhook | references/create-webhook.md | | Create websocket | references/create-websocket.md | | Create widget | references/create-widget.md | | Create swap | references/create-swap.md | | Create custom object | references/create-custom-object.md | | Configure security | references/configure-security.md | | Import CSV | references/import-csv.md | | Upload file | references/upload-file.md |

API Client

npm install funifier-mcp

import { createAPIClient } from "funifier-mcp";

const api = createAPIClient({
  apiKey: "your-api-key",
  secretKey: "your-secret-key",
  serverUrl: "https://your-instance.funifier.com",
});

// List resources
const triggers = await api.listTriggers();

// Execute an aggregate
const result = await api.executeAggregate("my-aggregate-id", {});

// Query any collection
const players = await api.queryCollection("player", { active: true }, { limit: 10 });

Configuration

Environment variables

| Variable | Description | |----------|-------------| | FUNIFIER_API_KEY | API key for authentication | | FUNIFIER_SECRET_KEY | Secret key for authentication | | FUNIFIER_SERVER_URL | Base URL of your Funifier instance | | FUNIFIER_DOCS_PATH | Path to documentation files (optional override) |

Config resolution order

funifier.json in cwd → environment variables.

Documentation

• docs/PLATFORM_SETUP.md — Detailed setup for all platforms
• docs/QUICK_REFERENCE.md — Copy-paste setup commands
• docs/INSTALL_EXAMPLES.md — Real-world scenarios
• docs/MCP_SETUP.md — MCP configuration and troubleshooting

License

MIT