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 — 8 tools, 3 prompts, documentation resources | | Skills | 15 guided workflows for Claude Code, Codex, OpenCode, Copilot, Continue, and Cursor | | CLI | npx funifier-mcp@latest init (interactive setup) and npx funifier-mcp search (doc search) |

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
npx funifier-mcp search "<query>"    Search Funifier documentation
funifier-mcp                         Start the MCP server (stdio)
funifier-mcp --version               Print version

funifier-mcp search

Lexical search across all Funifier docs — returns ranked file paths so you only read what's relevant:

npx funifier-mcp search "trigger event groovy before_create"
npx funifier-mcp search "quiz question answer" --skill funifier-create-quiz
npx funifier-mcp search "leaderboard ranking" --top 5 --min-score 0.3

Flags: --top N (max results, default 3), --skill <id> (boosts skill's primary docs), --min-score N (threshold, default 0.5).

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.

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 |

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

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/

Invoke any skill with /funifier-<name> in Claude Code:

/funifier-create-trigger
/funifier-debug
/funifier-help

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

| Skill | Description | |-------|-------------| | funifier-help | Documentation router and guidance | | funifier-debug | Systematic debugging workflow | | funifier-create-trigger | Create server-side event handlers (Groovy) | | funifier-create-scheduler | Create scheduled Groovy jobs | | funifier-create-aggregate | Create MongoDB aggregate pipelines | | funifier-create-custom-page | Create Studio admin pages (AngularJS) | | funifier-create-action | Create trackable player actions | | funifier-create-challenge | Create missions with rewards | | funifier-create-point | Create point categories | | funifier-create-level | Create level progression | | funifier-create-leaderboard | Create rankings | | funifier-create-quiz | Create quizzes | | funifier-create-virtual-good | Create virtual store items | | funifier-implement-frontend | Build frontend consuming Funifier API |

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