@fuul/mcp-server 1.0.1 → 1.1.1

package/README.md

@@ -1,231 +1,628 @@
 # @fuul/mcp-server
 
-Fuul [Model Context Protocol](https://modelcontextprotocol.io/) server: OAuth CLI (`fuul-mcp`), stdio MCP entry (`fuul-mcp-server`), metadata tools, project and affiliate analytics, incentive and payout operations (reads plus `dry_run` / `confirmed` writes), and rate-limit-aware errors.
+Fuul [Model Context Protocol](https://modelcontextprotocol.io/) server for managing affiliate programs, analytics, incentives, and payouts through MCP-compatible clients (Claude Code, Cursor, Claude Desktop).
 
-## Documentation
+[![npm version](https://img.shields.io/npm/v/@fuul/mcp-server.svg)](https://www.npmjs.com/package/@fuul/mcp-server)
+[![Node.js](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](https://nodejs.org/)
 
-| Resource | Purpose |
-| -------- | ------- |
-| [docs/README.md](docs/README.md) | Index of all docs in this repo |
-| [docs/AGENTS.md](docs/AGENTS.md) | Tool ↔ HTTP map (audit, support, PR review) |
-| [docs/mcp-phase2/CONSUMER.md](docs/mcp-phase2/CONSUMER.md) | Staging/production URLs, API expectations |
-| [docs/mcp-phase2/tool-prompts.md](docs/mcp-phase2/tool-prompts.md) | Sample prompts for tooling and evals |
-| [CHANGELOG.md](CHANGELOG.md) | Release notes |
+---
+
+## Table of Contents
 
-## Install (pick one path)
+- [Quick Start](#quick-start)
+- [Installation Methods](#installation-methods)
+  - [Claude Code Plugin (Recommended)](#1-claude-code-plugin-recommended)
+  - [Cursor IDE](#2-cursor-ide)
+  - [npx (Any MCP Client)](#3-npx-any-mcp-client)
+  - [Local Development (Clone)](#4-local-development-clone)
+- [Authentication](#authentication)
+- [Configuration](#configuration)
+- [MCP Tool Reference](#mcp-tool-reference)
+- [Troubleshooting](#troubleshooting)
+- [Repository Layout](#repository-layout)
+- [Scripts Reference](#scripts-reference)
+- [Documentation](#documentation)
+- [CI and Releases](#ci-and-releases)
+- [License](#license)
 
-### 1. Claude Code plugin (marketplace)
+---
 
-Adds the MCP server plus a **skill** that documents how to use Fuul tools.
+## Quick Start
 
-In **Claude Code**:
+```bash
+# 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
 
 ```text
 /plugin marketplace add kuyen-labs/mcp_server
 /plugin install fuul-mcp@fuul-mcp
 ```
 
-One-time OAuth in a terminal (same tokens the MCP uses):
+#### 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`:
+
+```json
+{
+  "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
+
+```text
+/reload-plugins
+```
+
+#### Step 4: Authenticate (one-time)
+
+Open a terminal and run:
 
 ```bash
-npx -y @fuul/mcp-server@latest fuul-mcp login
-npx -y @fuul/mcp-server@latest fuul-mcp whoami
+npx -y --package=@fuul/mcp-server@latest fuul-mcp login
 ```
 
-Optional: set **staging** in the plugin’s user settings — `FUUL_API_BASE_URL` = `https://api.stg.fuul.xyz`. Default is production `https://api.fuul.xyz`.
+This opens your browser for OAuth. Tokens are saved to `~/.fuul/tokens.json`.
+
+#### Step 5: Verify
+
+```bash
+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:**
+
+   ```bash
+   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`:
 
-Requires **`@fuul/mcp-server@0.2.0`** or newer on npm (for the `fuul-mcp-server` binary). After the first release with this version, `npx @latest` resolves correctly.
+   ```json
+   {
+     "mcpServers": {
+       "fuul": {
+         "command": "npx",
+         "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"],
+         "env": {
+           "FUUL_API_BASE_URL": "https://api.fuul.xyz"
+         }
+       }
+     }
+   }
+   ```
 
-### 2. npm / npx (any MCP client)
+#### Option B: Using local clone
 
-Use the published package without cloning:
+1. **Clone and build:**
 
-| Command | Role |
-| ------- | ---- |
-| `npx -y @fuul/mcp-server@latest fuul-mcp-server` | Stdio MCP server (what clients spawn) |
-| `npx -y @fuul/mcp-server@latest fuul-mcp login` | Browser OAuth; writes `~/.fuul/tokens.json` |
-| `npx -y @fuul/mcp-server@latest fuul-mcp whoami` | `GET /api/v1/auth/user` |
+   ```bash
+   git clone https://github.com/kuyen-labs/mcp_server.git
+   cd mcp_server
+   npm ci
+   npm run build
+   ```
 
-Point your client at `fuul-mcp-server` with `cwd` optional; config can be passed via `env` (see **Configuration**).
+2. **Authenticate:**
 
-### 3. Clone (development)
+   ```bash
+   npm run cli -- login
+   npm run cli -- whoami
+   ```
+
+3. **Configure MCP in Cursor:**
+
+   ```json
+   {
+     "mcpServers": {
+       "fuul": {
+         "command": "node",
+         "args": ["C:\\path\\to\\mcp_server\\dist\\index.js"],
+         "cwd": "C:\\path\\to\\mcp_server"
+       }
+     }
+   }
+   ```
+
+   On macOS/Linux:
+
+   ```json
+   {
+     "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:
+
+```json
+{
+  "command": "npx",
+  "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"]
+}
+```
+
+---
+
+### 4. Local Development (Clone)
 
 ```bash
 git clone https://github.com/kuyen-labs/mcp_server.git
 cd mcp_server
 npm ci
-cp .env.example .env   # optional; defaults match production Agent OAuth
+cp .env.example .env   # Optional: edit for staging/custom settings
 npm run build
 ```
 
-Run the CLI from the repo:
+#### Run CLI commands:
 
 ```bash
 npm run cli -- login
 npm run cli -- whoami
+npm run cli -- logout
 ```
 
-Run the MCP server:
+#### Run MCP server:
 
 ```bash
-npm start
-# or: npm run dev
+npm start              # Production (uses dist/)
+npm run dev            # Development (uses tsx, watches src/)
 ```
 
-## Configuration
+#### Debug with MCP Inspector:
+
+```bash
+npm run build
+npx @modelcontextprotocol/inspector node dist/index.js
+```
 
-Environment variables are read from `process.env` and, when present, a **`.env` file in the current working directory** (`dotenv`). See [.env.example](.env.example).
+---
 
-| Variable | Purpose |
-| -------- | ------- |
-| `FUUL_API_BASE_URL` | API origin only, no trailing slash. Production: `https://api.fuul.xyz`. Staging: `https://api.stg.fuul.xyz`. |
-| `FUUL_OAUTH_CLIENT_ID` | OAuth client id (default `fuul-agent`). |
-| `FUUL_OAUTH_REDIRECT_URI` | Loopback callback (default `http://127.0.0.1:8765/callback`). |
-| `FUUL_MCP_TOOL_TIMEOUT_MS` | Per-tool timeout in ms (default `90000`). |
-| `FUUL_MCP_DEBUG` | Set to `1` or `true` for debug logging. |
+## Authentication
 
-**Note:** Values in `.env` are local dev convenience; they are **not** published in the npm package (`package.json` only ships `dist/`). OAuth **tokens** live in `~/.fuul/tokens.json`, not in `.env`.
+Authentication uses OAuth with the Fuul dashboard. Tokens are stored locally and shared by the CLI and MCP server.
 
-## MCP tool examples
+### Token location
 
-Clients send JSON arguments; shapes match [docs/AGENTS.md](docs/AGENTS.md). Illustrative only — use real UUIDs from your tenant.
+| OS | Path |
+|----|------|
+| macOS/Linux | `~/.fuul/tokens.json` |
+| Windows | `%USERPROFILE%\.fuul\tokens.json` |
 
-**Session**
+### Login flow
+
+```bash
+npx -y --package=@fuul/mcp-server@latest fuul-mcp login
+```
 
-- `ping` → `{}` (no API call)
-- `whoami` → `{}` (requires login)
+This opens your default browser to the Fuul OAuth page. After authorizing, tokens are saved automatically.
 
-**Metadata**
+### Verify session
 
-- `list_chains`, `list_trigger_types`, `list_payout_schemas` → `{}`
+```bash
+npx -y --package=@fuul/mcp-server@latest fuul-mcp whoami
+```
 
-**Projects**
+### Clear tokens
 
-- `list_projects` → `{ "page": 1, "query": "acme" }`
-- `get_project` → `{ "project_id": "<uuid>" }`
-- `list_incentives` / `get_incentive` / `get_trigger` → see tool descriptions in the client
+```bash
+npx -y --package=@fuul/mcp-server@latest fuul-mcp logout
+```
 
-**Affiliate analytics**
+---
 
-- `get_affiliate_portal_stats` → `project_id`, `user_identifier` (e.g. `evm:0x...`)
-- `get_project_affiliate_total_stats` → `project_id`, optional `dateRange`, filters
-- `get_project_affiliates_breakdown` → `project_id`, **`groupBy`** (`audience` \| `tier` \| `region` \| `status`)
+## Configuration
 
-**Writes (two steps: `dry_run: true` then `confirmed: true`)**
+Environment variables are read from `process.env` and, when present, a `.env` file in the current working directory.
 
-- `create_incentive_program`, `update_incentive_program`, `approve_payouts`, `reject_payouts`
+| 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_DEBUG` | `false` | Set to `1` or `true` for debug logging |
 
-## Run and debug
+### Example `.env` file
 
 ```bash
-npm run build && npm start
+FUUL_API_BASE_URL=https://api.stg.fuul.xyz
+FUUL_MCP_DEBUG=1
 ```
 
-MCP Inspector:
+> **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`.
 
-```bash
-npm run build
-npx @modelcontextprotocol/inspector node dist/index.js
+---
+
+## 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` |
+| **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
+
+```json
+// ping (no auth required)
+{}
+
+// whoami (requires login)
+{}
+```
+
+#### Metadata queries
+
+```json
+// list_chains, list_trigger_types, list_payout_schemas
+{}
 ```
 
-## Client setup
+#### Project operations
 
-### Cursor
+```json
+// list_projects
+{ "page": 1, "query": "acme" }
 
-1. Complete **Clone** or use **npx** so `dist/index.js` or `fuul-mcp-server` exists; run **`fuul-mcp login`** once.
-2. **Settings → MCP** (or user `mcp.json`): spawn stdio with `command` + `args`, and set **`cwd`** to a folder that contains `.env` if you use one.
+// get_project
+{ "project_id": "550e8400-e29b-41d4-a716-446655440000" }
+```
 
-Example:
+#### Incentives
 
 ```json
+// list_incentives
+{ "project_id": "<uuid>" }
+
+// get_incentive
+{ "project_id": "<uuid>", "conversion_id": "<uuid>" }
+
+// get_trigger
+{ "project_id": "<uuid>", "trigger_id": "<uuid>" }
+```
+
+#### Affiliate analytics
+
+```json
+// get_affiliate_portal_stats (single affiliate)
 {
-  "mcpServers": {
-    "fuul": {
-      "command": "node",
-      "args": ["C:\\path\\to\\mcp_server\\dist\\index.js"],
-      "cwd": "C:\\path\\to\\mcp_server"
-    }
-  }
+  "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`
+
+#### Payout operations
+
+```json
+// list_payouts_pending_approval
+{ "project_id": "<uuid>", "page": 1, "page_size": 50 }
+
+// list_rewards_payouts
+{ "project_id": "<uuid>", "page": 1 }
 ```
 
-Or with npx:
+### 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
 
 ```json
+// Step 1: Preview
 {
-  "mcpServers": {
-    "fuul": {
-      "command": "npx",
-      "args": ["-y", "@fuul/mcp-server@latest", "fuul-mcp-server"],
-      "env": {
-        "FUUL_API_BASE_URL": "https://api.fuul.xyz"
-      }
-    }
-  }
+  "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
 }
 ```
 
-### Claude Desktop
+Write tools: `approve_payouts`, `reject_payouts`, `update_project_tier`, `update_audience`, `update_trigger`, `update_payout_term`
 
-Use the same `mcpServers` idea in the app’s developer config. See [Anthropic MCP docs](https://docs.anthropic.com/en/docs/mcp).
+---
 
-### Claude Code (manual MCP, without the plugin)
+## Troubleshooting
 
-Configure stdio per your Claude Code version: `node` + path to `dist/index.js`, or `npx` + `fuul-mcp-server` as above.
+### MCP server fails to start
 
-## Repository layout
+**Symptom:** Error like `Cannot find package '@fuul/mcp-server'` or binary not found.
 
-```text
+**Solution:** Ensure you use the `--package=` format in args:
+
+```json
+{
+  "args": ["-y", "--package=@fuul/mcp-server@latest", "fuul-mcp-server"]
+}
+```
+
+**Wrong:**
+```json
+{
+  "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:
+   ```bash
+   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:
+   ```bash
+   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:
+   ```json
+   {
+     "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:
+
+```json
+{
+  "args": ["C:\\Users\\me\\mcp_server\\dist\\index.js"]
+}
+```
+
+Or:
+
+```json
+{
+  "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/             # Plugin: MCP config + skill
+│   └── fuul-mcp/             # Claude Code plugin
 │       ├── .claude-plugin/
 │       │   └── plugin.json
-│       ├── .mcp.json
-│       └── skills/fuul/SKILL.md
+│       ├── .mcp.json         # MCP server config
+│       └── skills/
+│           └── fuul/
+│               └── SKILL.md  # Tool usage instructions
 ├── src/                      # TypeScript source
-├── docs/                     # Maintainer and integrator docs
-├── .github/workflows/        # ci.yml, release.yml (semantic-release; name must match npm Trusted Publishing)
-├── release.config.cjs        # semantic-release plugins and branches
-└── dist/                     # `npm run build` (gitignored)
+│   ├── 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
 ```
 
-## Requirements
+---
 
-- **Node.js** 18+
-- A running **fuul-server** (staging or production) with **Agent OAuth** configured
+## Scripts Reference
 
-## CI and releases
+| 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 |
 
-On each push/PR to `main` / `master`, GitHub Actions runs **lint**, **test**, and **build** in parallel (see [.github/workflows/ci.yml](.github/workflows/ci.yml)). Pushes to `beta` / `alpha` also run CI on those branches.
+---
 
-## Publishing
+## Documentation
 
-**npm** releases are performed by **semantic-release** in GitHub Actions (same approach as [fuul-sdk](https://github.com/kuyen-labs/fuul-sdk)). You do not need to create a GitHub Release manually or run `npm publish` locally for the default flow.
+| Resource | Description |
+|----------|-------------|
+| [docs/README.md](docs/README.md) | Documentation index |
+| [docs/AGENTS.md](docs/AGENTS.md) | Tool ↔ HTTP endpoint mapping |
+| [docs/mcp-phase2/CONSUMER.md](docs/mcp-phase2/CONSUMER.md) | Staging/production URLs, API expectations |
+| [docs/mcp-phase2/tool-prompts.md](docs/mcp-phase2/tool-prompts.md) | Sample prompts for testing and evals |
+| [CHANGELOG.md](CHANGELOG.md) | Release notes |
 
-1. **npm — [Trusted publishing](https://docs.npmjs.com/trusted-publishers) (OIDC):** [.github/workflows/release.yml](.github/workflows/release.yml) uses the same **steps and permissions** as [fuul-sdk](https://github.com/kuyen-labs/fuul-sdk)’s release job (`id-token: write`, no `NPM_TOKEN` in the workflow). The **filename** is **`release.yml`** here so it matches what you enter in npm’s trusted-publisher form (fuul-sdk uses **`versioning.yml`** instead — that name is only for that repo). On npmjs.com, **`@fuul/mcp-server`** must list workflow **`.github/workflows/release.yml`** for **`kuyen-labs` / `mcp_server`**. If npm still shows **`OIDC … 404`**, the path/org/repo in npm does not match this file.  
-   **About `NPM_TOKEN` in caps:** npm docs use that name for **classic token** auth. With **Trusted Publishing** you do **not** put a token value into npm for OIDC; GitHub provides the identity. You also do **not** need a GitHub secret named `NPM_TOKEN` for this flow. (If the npm UI showed `NPM_TOKEN`, it is usually help text for the non-OIDC case.)
-2. **Branches**: on **push** to `main`, `beta`, or `alpha`, that workflow runs `npm ci`, **build**, **`npm run test:ci`**, then `npx semantic-release` on push only.
-3. **Config**: [release.config.cjs](release.config.cjs) matches fuul-sdk’s plugin list and order; `@semantic-release/exec` uses the same **`verifyReleaseCmd`** writing `src/release.json` (placeholder [src/release.json](src/release.json)); `@semantic-release/git` commits **`package.json`** only.
-4. **Commits**: use [Conventional Commits](https://www.conventionalcommits.org/) on releasable branches (e.g. `feat:`, `fix:`, `BREAKING CHANGE:`) so the next version is computed; if nothing warrants a release, the job exits without publishing (expected).
+---
 
-Local dry run of the same CLI: `npm run semantic-release` (needs a clean git state, tags, and env vars; in practice CI after merge is enough).
+## CI and Releases
 
-## Scripts
+### Continuous Integration
 
-| Script | Description |
-| ------ | ----------- |
-| `npm run build` | Compile TypeScript → `dist/` |
-| `npm start` | Run MCP server (`node dist/index.js`) |
-| `npm run cli` | OAuth CLI via `tsx` (`src/cli.ts`) |
-| `npm run dev` | MCP via `tsx` (`src/index.ts`) |
-| `npm run lint` | ESLint on `src/` |
-| `npm run test` | Vitest |
-| `npm run test:ci` | Vitest (same as `test`; used by `release.yml` like fuul-sdk’s `test:ci` in `versioning.yml`) |
-| `npm run semantic-release` | Run semantic-release locally (CI runs `npx semantic-release` on eligible pushes) |
+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](https://www.conventionalcommits.org/): `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`.
+MIT — see [package.json](package.json)

package/dist/tools/tool-descriptions.d.ts

@@ -3,7 +3,7 @@
  */
 export declare const PING_DESCRIPTION = "Health check: returns \"pong\" if the MCP process is running. No API calls. Example: invoke with empty input {}.";
 export declare const WHOAMI_DESCRIPTION = "Returns the current Fuul dashboard user as JSON from GET /api/v1/auth/user. Requires prior CLI login (tokens in ~/.fuul/tokens.json). Example: {} after `npm run cli -- login`.";
-export declare const LIST_CHAINS_DESCRIPTION = "Lists supported blockchain chains from GET /public-api/v1/metadata/chains. Uses server metadata (not a hardcoded catalog); responses are cached with ETag/Cache-Control. Params: none (pass {}). Pagination: not exposed by this tool until the API adds cursor/limit.";
+export declare const LIST_CHAINS_DESCRIPTION = "Lists supported blockchain chains from GET /public-api/v1/metadata/chains. Uses server metadata (not a hardcoded catalog); responses are cached with ETag/Cache-Control. Each chain includes snake_case fields such as chain_id, is_testnet, optional svm_network and webapp_capabilities, and can_be_used_for_payouts (boolean: true where Fuul reward/payout infra is deployed). Params: none (pass {}). Pagination: not exposed by this tool until the API adds cursor/limit.";
 export declare const LIST_TRIGGER_TYPES_DESCRIPTION = "Lists trigger type metadata from GET /public-api/v1/metadata/trigger-types (cached). Use ids from this response when building programs/triggers. Params: {}.";
 export declare const LIST_PAYOUT_SCHEMAS_DESCRIPTION = "Lists payout schema metadata from GET /public-api/v1/metadata/payout-schemas (cached). Params: {}.";
 export declare const LIST_PROJECTS_DESCRIPTION = "Lists dashboard projects for the current user: GET /api/v1/projects with optional ?page= (1-based) and ?query=. Example: {\"page\":1} or {\"query\":\"acme\"}.";

package/dist/tools/tool-descriptions.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tool-descriptions.d.ts","sourceRoot":"","sources":["../../src/tools/tool-descriptions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,gBAAgB,qHAAmH,CAAC;AAEjJ,eAAO,MAAM,kBAAkB,oLACoJ,CAAC;AAEpL,eAAO,MAAM,uBAAuB,2QACsO,CAAC;AAE3Q,eAAO,MAAM,8BAA8B,iKACqH,CAAC;AAEjK,eAAO,MAAM,+BAA+B,uGAAuG,CAAC;AAEpJ,eAAO,MAAM,yBAAyB,mKACsH,CAAC;AAE7J,eAAO,MAAM,uBAAuB,4HACmF,CAAC;AAExH,eAAO,MAAM,2BAA2B,0IAC6F,CAAC;AAEtI,eAAO,MAAM,yBAAyB,qJACsG,CAAC;AAE7I,eAAO,MAAM,uBAAuB,2LAC8I,CAAC;AAEnL,eAAO,MAAM,8BAA8B,QAGwF,CAAC;AAEpI,eAAO,MAAM,+BAA+B,QAEyF,CAAC;AAEtI,eAAO,MAAM,2BAA2B,QAEgF,CAAC;AAEzH,eAAO,MAAM,0BAA0B,QAEgE,CAAC;AAExG,eAAO,MAAM,yCAAyC,0LAC2H,CAAC;AAElL,eAAO,MAAM,gCAAgC,mMAC+I,CAAC;AAE7L,eAAO,MAAM,2BAA2B,oQACiN,CAAC;AAE1P,eAAO,MAAM,0BAA0B,2GAA2G,CAAC;AAInJ,eAAO,MAAM,sCAAsC,QAIlC,CAAC;AAElB,eAAO,MAAM,6CAA6C,QAIzC,CAAC;AAElB,eAAO,MAAM,4CAA4C,QAIxC,CAAC"}
+{"version":3,"file":"tool-descriptions.d.ts","sourceRoot":"","sources":["../../src/tools/tool-descriptions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,eAAO,MAAM,gBAAgB,qHAAmH,CAAC;AAEjJ,eAAO,MAAM,kBAAkB,oLACoJ,CAAC;AAEpL,eAAO,MAAM,uBAAuB,qdACgb,CAAC;AAGrd,eAAO,MAAM,8BAA8B,iKACqH,CAAC;AAEjK,eAAO,MAAM,+BAA+B,uGAAuG,CAAC;AAEpJ,eAAO,MAAM,yBAAyB,mKACsH,CAAC;AAE7J,eAAO,MAAM,uBAAuB,4HACmF,CAAC;AAExH,eAAO,MAAM,2BAA2B,0IAC6F,CAAC;AAEtI,eAAO,MAAM,yBAAyB,qJACsG,CAAC;AAE7I,eAAO,MAAM,uBAAuB,2LAC8I,CAAC;AAEnL,eAAO,MAAM,8BAA8B,QAGwF,CAAC;AAEpI,eAAO,MAAM,+BAA+B,QAEyF,CAAC;AAEtI,eAAO,MAAM,2BAA2B,QAEgF,CAAC;AAEzH,eAAO,MAAM,0BAA0B,QAEgE,CAAC;AAExG,eAAO,MAAM,yCAAyC,0LAC2H,CAAC;AAElL,eAAO,MAAM,gCAAgC,mMAC+I,CAAC;AAE7L,eAAO,MAAM,2BAA2B,oQACiN,CAAC;AAE1P,eAAO,MAAM,0BAA0B,2GAA2G,CAAC;AAInJ,eAAO,MAAM,sCAAsC,QAIlC,CAAC;AAElB,eAAO,MAAM,6CAA6C,QAIzC,CAAC;AAElB,eAAO,MAAM,4CAA4C,QAIxC,CAAC"}

package/dist/tools/tool-descriptions.js

@@ -3,7 +3,7 @@
  */
 export const PING_DESCRIPTION = 'Health check: returns "pong" if the MCP process is running. No API calls. Example: invoke with empty input {}.';
 export const WHOAMI_DESCRIPTION = 'Returns the current Fuul dashboard user as JSON from GET /api/v1/auth/user. Requires prior CLI login (tokens in ~/.fuul/tokens.json). Example: {} after `npm run cli -- login`.';
-export const LIST_CHAINS_DESCRIPTION = 'Lists supported blockchain chains from GET /public-api/v1/metadata/chains. Uses server metadata (not a hardcoded catalog); responses are cached with ETag/Cache-Control. Params: none (pass {}). Pagination: not exposed by this tool until the API adds cursor/limit.';
+export const LIST_CHAINS_DESCRIPTION = 'Lists supported blockchain chains from GET /public-api/v1/metadata/chains. Uses server metadata (not a hardcoded catalog); responses are cached with ETag/Cache-Control. Each chain includes snake_case fields such as chain_id, is_testnet, optional svm_network and webapp_capabilities, and can_be_used_for_payouts (boolean: true where Fuul reward/payout infra is deployed). Params: none (pass {}). Pagination: not exposed by this tool until the API adds cursor/limit.';
 export const LIST_TRIGGER_TYPES_DESCRIPTION = 'Lists trigger type metadata from GET /public-api/v1/metadata/trigger-types (cached). Use ids from this response when building programs/triggers. Params: {}.';
 export const LIST_PAYOUT_SCHEMAS_DESCRIPTION = 'Lists payout schema metadata from GET /public-api/v1/metadata/payout-schemas (cached). Params: {}.';
 export const LIST_PROJECTS_DESCRIPTION = 'Lists dashboard projects for the current user: GET /api/v1/projects with optional ?page= (1-based) and ?query=. Example: {"page":1} or {"query":"acme"}.';

package/dist/tools/tool-descriptions.js.map

@@ -1 +1 @@
-{"version":3,"file":"tool-descriptions.js","sourceRoot":"","sources":["../../src/tools/tool-descriptions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,gHAAgH,CAAC;AAEjJ,MAAM,CAAC,MAAM,kBAAkB,GAC7B,iLAAiL,CAAC;AAEpL,MAAM,CAAC,MAAM,uBAAuB,GAClC,wQAAwQ,CAAC;AAE3Q,MAAM,CAAC,MAAM,8BAA8B,GACzC,8JAA8J,CAAC;AAEjK,MAAM,CAAC,MAAM,+BAA+B,GAAG,oGAAoG,CAAC;AAEpJ,MAAM,CAAC,MAAM,yBAAyB,GACpC,0JAA0J,CAAC;AAE7J,MAAM,CAAC,MAAM,uBAAuB,GAClC,qHAAqH,CAAC;AAExH,MAAM,CAAC,MAAM,2BAA2B,GACtC,mIAAmI,CAAC;AAEtI,MAAM,CAAC,MAAM,yBAAyB,GACpC,0IAA0I,CAAC;AAE7I,MAAM,CAAC,MAAM,uBAAuB,GAClC,gLAAgL,CAAC;AAEnL,MAAM,CAAC,MAAM,8BAA8B,GACzC,yIAAyI;IACzI,kIAAkI;IAClI,iIAAiI,CAAC;AAEpI,MAAM,CAAC,MAAM,+BAA+B,GAC1C,mKAAmK;IACnK,mIAAmI,CAAC;AAEtI,MAAM,CAAC,MAAM,2BAA2B,GACtC,sRAAsR;IACtR,sHAAsH,CAAC;AAEzH,MAAM,CAAC,MAAM,0BAA0B,GACrC,2NAA2N;IAC3N,qGAAqG,CAAC;AAExG,MAAM,CAAC,MAAM,yCAAyC,GACpD,+KAA+K,CAAC;AAElL,MAAM,CAAC,MAAM,gCAAgC,GAC3C,0LAA0L,CAAC;AAE7L,MAAM,CAAC,MAAM,2BAA2B,GACtC,uPAAuP,CAAC;AAE1P,MAAM,CAAC,MAAM,0BAA0B,GAAG,wGAAwG,CAAC;AAEnJ,MAAM,eAAe,GAAG,sFAAsF,CAAC;AAE/G,MAAM,CAAC,MAAM,sCAAsC,GACjD,2GAA2G;IAC3G,kHAAkH;IAClH,iEAAiE;IACjE,eAAe,CAAC;AAElB,MAAM,CAAC,MAAM,6CAA6C,GACxD,0GAA0G;IAC1G,yHAAyH;IACzH,gFAAgF;IAChF,eAAe,CAAC;AAElB,MAAM,CAAC,MAAM,4CAA4C,GACvD,+IAA+I;IAC/I,4HAA4H;IAC5H,wEAAwE;IACxE,eAAe,CAAC"}
+{"version":3,"file":"tool-descriptions.js","sourceRoot":"","sources":["../../src/tools/tool-descriptions.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,gHAAgH,CAAC;AAEjJ,MAAM,CAAC,MAAM,kBAAkB,GAC7B,iLAAiL,CAAC;AAEpL,MAAM,CAAC,MAAM,uBAAuB,GAClC,kdAAkd,CAAC;AAGrd,MAAM,CAAC,MAAM,8BAA8B,GACzC,8JAA8J,CAAC;AAEjK,MAAM,CAAC,MAAM,+BAA+B,GAAG,oGAAoG,CAAC;AAEpJ,MAAM,CAAC,MAAM,yBAAyB,GACpC,0JAA0J,CAAC;AAE7J,MAAM,CAAC,MAAM,uBAAuB,GAClC,qHAAqH,CAAC;AAExH,MAAM,CAAC,MAAM,2BAA2B,GACtC,mIAAmI,CAAC;AAEtI,MAAM,CAAC,MAAM,yBAAyB,GACpC,0IAA0I,CAAC;AAE7I,MAAM,CAAC,MAAM,uBAAuB,GAClC,gLAAgL,CAAC;AAEnL,MAAM,CAAC,MAAM,8BAA8B,GACzC,yIAAyI;IACzI,kIAAkI;IAClI,iIAAiI,CAAC;AAEpI,MAAM,CAAC,MAAM,+BAA+B,GAC1C,mKAAmK;IACnK,mIAAmI,CAAC;AAEtI,MAAM,CAAC,MAAM,2BAA2B,GACtC,sRAAsR;IACtR,sHAAsH,CAAC;AAEzH,MAAM,CAAC,MAAM,0BAA0B,GACrC,2NAA2N;IAC3N,qGAAqG,CAAC;AAExG,MAAM,CAAC,MAAM,yCAAyC,GACpD,+KAA+K,CAAC;AAElL,MAAM,CAAC,MAAM,gCAAgC,GAC3C,0LAA0L,CAAC;AAE7L,MAAM,CAAC,MAAM,2BAA2B,GACtC,uPAAuP,CAAC;AAE1P,MAAM,CAAC,MAAM,0BAA0B,GAAG,wGAAwG,CAAC;AAEnJ,MAAM,eAAe,GAAG,sFAAsF,CAAC;AAE/G,MAAM,CAAC,MAAM,sCAAsC,GACjD,2GAA2G;IAC3G,kHAAkH;IAClH,iEAAiE;IACjE,eAAe,CAAC;AAElB,MAAM,CAAC,MAAM,6CAA6C,GACxD,0GAA0G;IAC1G,yHAAyH;IACzH,gFAAgF;IAChF,eAAe,CAAC;AAElB,MAAM,CAAC,MAAM,4CAA4C,GACvD,+IAA+I;IAC/I,4HAA4H;IAC5H,wEAAwE;IACxE,eAAe,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fuul/mcp-server",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "description": "Fuul MCP server for program management via MCP-compatible clients",
   "keywords": [
     "Fuul",