Fuul MCP Server

Fuul MCP Server

Manages affiliate programs, analytics, incentives, and payouts through MCP-compatible clients.

Category
访问服务器

README

@fuul/mcp-server

Fuul Model Context Protocol server for managing affiliate programs, analytics, incentives, and payouts through MCP-compatible clients (Claude Code, Cursor, Claude Desktop).

npm version Node.js

Table of Contents

Quick Start

# 1. Install (choose one method below)
# 2. Authenticate once:
npx -y --package=@fuul/mcp-server@latest fuul-mcp login

# 3. Verify:
npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Installation Methods

1. Claude Code Plugin (Recommended)

The easiest way to use Fuul MCP with Claude Code. Adds the MCP server plus a skill that documents how to use Fuul tools.

Step 1: Install the plugin

/plugin marketplace add kuyen-labs/mcp_server
/plugin install fuul-mcp@fuul-mcp

Step 2: Verify the .mcp.json format

Check the plugin's .mcp.json at:

~/.claude/plugins/cache/fuul-mcp/fuul-mcp/<version>/.mcp.json

It must use the --package= format in args:

{
  "mcpServers": {
    "fuul": {
      "command": "npx",
      "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"],
      "env": {
        "FUUL_API_BASE_URL": "${user_config.FUUL_API_BASE_URL}"
      }
    }
  }
}

If args shows ["-y", "@fuul/mcp-server@latest", "fuul-mcp-server"] (without --package=), update it to match the format above.

Step 3: Reload the plugin

/reload-plugins

Step 4: Authenticate (one-time)

Open a terminal and run:

npx -y --package=@fuul/mcp-server@latest fuul-mcp login

This opens your browser for OAuth. Tokens are saved to ~/.fuul/tokens.json.

Step 5: Verify

npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Optional: Use staging environment

Set FUUL_API_BASE_URL in the plugin's user settings:

Environment URL
Production (default) https://api.fuul.xyz
Staging https://api.stg.fuul.xyz

2. Cursor IDE

Option A: Using npx (no clone required)

  1. Authenticate first:

    npx -y --package=@fuul/mcp-server@latest fuul-mcp login
npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

  2. Configure MCP in Cursor:

    Go to Settings → MCP or edit your mcp.json:

    {
  "mcpServers": {
    "fuul": {
      "command": "npx",
      "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"],
      "env": {
        "FUUL_API_BASE_URL": "https://api.fuul.xyz"
      }
    }
  }
}

Option B: Using local clone

  1. Clone and build:

    git clone https://github.com/kuyen-labs/mcp_server.git
cd mcp_server
npm ci
npm run build

  2. Authenticate:

    npm run cli -- login
npm run cli -- whoami

  3. Configure MCP in Cursor:

    {
  "mcpServers": {
    "fuul": {
      "command": "node",
      "args": ["C:\\path\\to\\mcp_server\\dist\\index.js"],
      "cwd": "C:\\path\\to\\mcp_server"
    }
  }
}

    On macOS/Linux:

    {
  "mcpServers": {
    "fuul": {
      "command": "node",
      "args": ["/path/to/mcp_server/dist/index.js"],
      "cwd": "/path/to/mcp_server"
    }
  }
}

3. npx (Any MCP Client)

Use the published npm package without cloning:

Command Purpose
npx -y --package=@fuul/mcp-server@latest fuul-mcp login Browser OAuth; writes ~/.fuul/tokens.json
npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami Verify session (GET /api/v1/auth/user)
npx -y --package=@fuul/mcp-server@latest fuul-mcp logout Clear tokens
npx -y --package=@fuul/mcp-server@latest fuul-mcp-server Start stdio MCP server

For MCP client configs (JSON), use the --package= format:

{
  "command": "npx",
  "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"]
}

4. Local Development (Clone)

git clone https://github.com/kuyen-labs/mcp_server.git
cd mcp_server
npm ci
cp .env.example .env   # Optional: edit for staging/custom settings
npm run build

Run CLI commands:

npm run cli -- login
npm run cli -- whoami
npm run cli -- logout

Run MCP server:

npm start              # Production (uses dist/)
npm run dev            # Development (uses tsx, watches src/)

Debug with MCP Inspector:

npm run build
npx @modelcontextprotocol/inspector node dist/index.js

Authentication

Authentication uses OAuth with the Fuul dashboard. Tokens are stored locally and shared by the CLI and MCP server.

Token location

OS Path
macOS/Linux ~/.fuul/tokens.json
Windows %USERPROFILE%\.fuul\tokens.json

Login flow

npx -y --package=@fuul/mcp-server@latest fuul-mcp login

This opens your default browser to the Fuul OAuth page. After authorizing, tokens are saved automatically.

Verify session

npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Clear tokens

npx -y --package=@fuul/mcp-server@latest fuul-mcp logout

Configuration

Environment variables are read from process.env and, when present, a .env file in the current working directory.

Variable Default Description
FUUL_API_BASE_URL https://api.fuul.xyz API origin (no trailing slash). Use https://api.stg.fuul.xyz for staging.
FUUL_OAUTH_CLIENT_ID fuul-agent OAuth client ID
FUUL_OAUTH_REDIRECT_URI http://127.0.0.1:8765/callback OAuth callback URL
FUUL_MCP_TOOL_TIMEOUT_MS 90000 Per-tool timeout in milliseconds
FUUL_MCP_PROJECT_API_KEY (unset) Project API key (Bearer) for public API tools: managed affiliates and Events
FUUL_MCP_DEBUG false Set to 1 or true for debug logging

Example .env file

FUUL_API_BASE_URL=https://api.stg.fuul.xyz
FUUL_MCP_DEBUG=1

Note: The .env file is for local development only and is not included in the npm package. Tokens are stored in ~/.fuul/tokens.json, not in .env.

MCP Tool Reference

Tool Categories

Category Tools
Health ping, whoami
Metadata (cached) list_chains, list_trigger_types, list_payout_schemas
Projects list_projects, get_project
Incentives list_incentives, get_incentive, get_trigger
Affiliate Analytics get_affiliate_portal_stats, get_project_affiliate_total_stats, get_project_affiliates_breakdown
Managed Affiliates (project API key) get_project_affiliate_public, create_project_affiliate_public, update_project_affiliate_public
Events (project API key) send_event, send_batch_events, check_event_status
Referrer / referral codes (service_role project API key) get_user_referrer, update_user_referrer, use_referral_code, remove_user_from_referral_code, swap_user_referral_code
Payouts (Read) list_payouts_pending_approval, list_rewards_payouts
Payouts (Write) approve_payouts, reject_payouts
Tiers update_project_tier
Audiences update_audience
Triggers update_trigger
Payout Terms update_payout_term

Tool Examples

All tools receive JSON arguments. Use real UUIDs from your tenant.

Health checks

// ping (no auth required)
{}

// whoami (requires login)
{}

Metadata queries

// list_chains, list_trigger_types, list_payout_schemas
{}

Project operations

// list_projects
{ "page": 1, "query": "acme" }

// get_project
{ "project_id": "550e8400-e29b-41d4-a716-446655440000" }

Incentives

// list_incentives
{ "project_id": "<uuid>" }

// get_incentive
{ "project_id": "<uuid>", "conversion_id": "<uuid>" }

// get_trigger
{ "project_id": "<uuid>", "trigger_id": "<uuid>" }

Agents (Claude Code): draft vs published trigger IDs — see plugin skill plugins/fuul-mcp/skills/fuul/SKILL.md § Draft vs published.

Affiliate analytics

// get_affiliate_portal_stats (single affiliate)
{
  "project_id": "<uuid>",
  "user_identifier": "evm:0x1234..."
}

// get_project_affiliate_total_stats (project totals)
{
  "project_id": "<uuid>",
  "dateRange": "30d"
}

// get_project_affiliates_breakdown (grouped breakdown)
{
  "project_id": "<uuid>",
  "groupBy": "region",
  "dateRange": "30d"
}

groupBy options: audience, tier, region, status

dateRange options: 7d, 30d, 90d, MTD, QTD, custom, all

Events (project API key)

Requires FUUL_MCP_PROJECT_API_KEY or project_api_key on each call. Writes use dry_run then confirmed.

// check_event_status (ingestion only)
{
  "user_identifier": "0x80Fe27F878d2d42BD8b387F3cA4b96CBDEc05326",
  "user_identifier_type": "evm_address",
  "event_name": "trade"
}

// check_event_status (full pipeline after send_event)
{
  "verbose": true,
  "dedup_id": "4bdabf2c-271a-4d66-afd0-a9f24119810a",
  "event_name": "trade"
}

// send_event (dry_run preview)
{
  "name": "trade",
  "user_identifier": "0x80Fe27F878d2d42BD8b387F3cA4b96CBDEc05326",
  "user_identifier_type": "evm_address",
  "dedup_id": "4bdabf2c-271a-4d66-afd0-a9f24119810a",
  "args": { "volume": 1000 },
  "dry_run": true
}

// send_batch_events (confirmed)
{
  "events": [
    {
      "name": "trade",
      "user_identifier": "0x80Fe27F878d2d42BD8b387F3cA4b96CBDEc05326",
      "user_identifier_type": "evm_address",
      "dedup_id": "batch-id-1"
    }
  ],
  "confirmed": true
}

Payout operations

// list_payouts_pending_approval
{ "project_id": "<uuid>", "page": 1, "page_size": 50 }

// list_rewards_payouts
{ "project_id": "<uuid>", "page": 1 }

Write Operations (Two-Step Flow)

All mutation tools require a two-step process:

  1. Preview: Call with dry_run: true — validates and returns a preview without making changes
  2. Confirm: Call with confirmed: true — executes the mutation

Example: Approve payouts

// Step 1: Preview
{
  "project_id": "<uuid>",
  "payout_ids": ["<uuid1>", "<uuid2>"],
  "dry_run": true
}

// Step 2: Confirm (after user approval)
{
  "project_id": "<uuid>",
  "payout_ids": ["<uuid1>", "<uuid2>"],
  "confirmed": true
}

Write tools: approve_payouts, reject_payouts, update_project_tier, update_audience, update_trigger, update_payout_term

Troubleshooting

MCP server fails to start

Symptom: Error like Cannot find package '@fuul/mcp-server' or binary not found.

Solution: Ensure you use the --package= format in args:

{
  "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"]
}

Wrong:

{
  "args": ["-y", "@fuul/mcp-server@latest", "fuul-mcp-server"]
}

401 Unauthorized errors

Symptom: API tools return 401 or whoami fails.

Solution:

  1. Run login again:

    npx -y --package=@fuul/mcp-server@latest fuul-mcp login

  2. Verify tokens exist:

    • macOS/Linux: ~/.fuul/tokens.json
    • Windows: %USERPROFILE%\.fuul\tokens.json

  3. Verify session:

    npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami

Rate limiting (HTTP 429)

Symptom: Tools return 429 errors.

Solution: Wait for the Retry-After header duration, then retry. The MCP server handles this automatically in most cases.

Environment not loading

Symptom: Staging URL not being used despite .env file.

Solution:

  1. Ensure cwd in your MCP config points to the directory containing .env
  2. Or pass environment directly in the config:
    {
  "env": {
    "FUUL_API_BASE_URL": "https://api.stg.fuul.xyz"
  }
}

Windows path issues

Symptom: Paths not resolving correctly on Windows.

Solution: Use double backslashes or forward slashes:

{
  "args": ["C:\\Users\\me\\mcp_server\\dist\\index.js"]
}

Or:

{
  "args": ["C:/Users/me/mcp_server/dist/index.js"]
}

Repository Layout

mcp_server/
├── .claude-plugin/           # Claude Code marketplace manifest
│   └── marketplace.json
├── .github/
│   ├── workflows/            # CI and release workflows
│   │   ├── ci.yml
│   │   └── release.yml
│   └── pull_request_template.md
├── docs/                     # Documentation
│   ├── README.md             # Docs index
│   ├── AGENTS.md             # Tool ↔ HTTP mapping
│   └── mcp-phase2/
│       ├── CONSUMER.md       # API expectations
│       └── tool-prompts.md   # Sample prompts for evals
├── plugins/
│   └── fuul-mcp/             # Claude Code plugin
│       ├── .claude-plugin/
│       │   └── plugin.json
│       ├── .mcp.json         # MCP server config
│       └── skills/
│           └── fuul/
│               └── SKILL.md  # Tool usage instructions
├── src/                      # TypeScript source
│   ├── affiliate-portal/     # Affiliate analytics
│   ├── agent/                # Write confirmation logic
│   ├── auth/                 # OAuth and tokens
│   ├── config/               # Environment config
│   ├── http/                 # HTTP client
│   ├── metadata/             # Chains, triggers, schemas
│   ├── payouts/              # Payout operations
│   ├── tools/                # MCP tool definitions
│   ├── triggers/             # Trigger operations
│   ├── util/                 # Utilities
│   ├── cli.ts                # CLI entry point
│   └── index.ts              # MCP server entry point
├── dist/                     # Compiled output (gitignored)
├── .env.example              # Environment template
├── CHANGELOG.md              # Release notes
├── package.json
├── release.config.cjs        # semantic-release config
├── tsconfig.json
└── vitest.config.ts

Scripts Reference

Script Description
npm run build Compile TypeScript → dist/
npm start Run MCP server (node dist/index.js)
npm run dev Run MCP server with hot reload (tsx src/index.ts)
npm run cli Run OAuth CLI (tsx src/cli.ts)
npm run lint ESLint on src/
npm run lint:fix Auto-fix lint issues
npm run test Run tests with Vitest
npm run test:ci Run tests in CI mode
npm run format Format code with Prettier

Documentation

Resource Description
docs/README.md Documentation index
docs/AGENTS.md Tool ↔ HTTP endpoint mapping
docs/mcp-phase2/CONSUMER.md Staging/production URLs, API expectations
docs/mcp-phase2/tool-prompts.md Sample prompts for testing and evals
CHANGELOG.md Release notes

CI and Releases

Continuous Integration

On each push/PR to main, master, beta, or alpha, GitHub Actions runs:

  • lint — ESLint checks
  • test — Vitest test suite
  • build — TypeScript compilation

Publishing

Releases are automated via semantic-release and npm Trusted Publishing (OIDC):

  1. Use Conventional Commits: feat:, fix:, BREAKING CHANGE:
  2. Merge to main (or beta/alpha for pre-releases)
  3. GitHub Actions runs semantic-release, which:
    • Determines the next version from commits
    • Updates package.json and CHANGELOG.md
    • Publishes to npm
    • Creates a GitHub release

No manual npm publish or GitHub Release creation needed.

Requirements

  • Node.js 18 or higher
  • A running fuul-server (staging or production) with Agent OAuth configured

License

MIT — see package.json

推荐服务器

Baidu Map

Baidu Map

百度地图核心API现已全面兼容MCP协议，是国内首家兼容MCP协议的地图服务商。

官方
精选
JavaScript
Playwright MCP Server

Playwright MCP Server

一个模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页进行交互，而无需视觉模型或屏幕截图。

官方
精选
TypeScript
Magic Component Platform (MCP)

Magic Component Platform (MCP)

一个由人工智能驱动的工具，可以从自然语言描述生成现代化的用户界面组件，并与流行的集成开发环境（IDE）集成，从而简化用户界面开发流程。

官方
精选
本地
TypeScript
Audiense Insights MCP Server

Audiense Insights MCP Server

通过模型上下文协议启用与 Audiense Insights 账户的交互，从而促进营销洞察和受众数据的提取和分析，包括人口统计信息、行为和影响者互动。

官方
精选
本地
TypeScript
VeyraX

VeyraX

一个单一的 MCP 工具，连接你所有喜爱的工具：Gmail、日历以及其他 40 多个工具。

官方
精选
本地
graphlit-mcp-server

graphlit-mcp-server

模型上下文协议 (MCP) 服务器实现了 MCP 客户端与 Graphlit 服务之间的集成。 除了网络爬取之外，还可以将任何内容（从 Slack 到 Gmail 再到播客订阅源）导入到 Graphlit 项目中，然后从 MCP 客户端检索相关内容。

官方
精选
TypeScript
Kagi MCP Server

Kagi MCP Server

一个 MCP 服务器，集成了 Kagi 搜索功能和 Claude AI，使 Claude 能够在回答需要最新信息的问题时执行实时网络搜索。

官方
精选
Python
e2b-mcp-server

e2b-mcp-server

使用 MCP 通过 e2b 运行代码。

官方
精选
Neon MCP Server

Neon MCP Server

用于与 Neon 管理 API 和数据库交互的 MCP 服务器

官方
精选
Exa MCP Server

Exa MCP Server

模型上下文协议（MCP）服务器允许像 Claude 这样的 AI 助手使用 Exa AI 搜索 API 进行网络搜索。这种设置允许 AI 模型以安全和受控的方式获取实时的网络信息。

官方
精选