funifier-mcp 0.1.0 → 0.2.0

package/README.md

@@ -1,351 +1,182 @@
-# @funifier-ai
-
-Funifier AI toolkit — API client, MCP server, and AI assistant skills for the [Funifier](https://funifier.com) 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 exposing 8 tools + 3 prompts + documentation resources |
-| **Skills** | 15 guided workflows for Claude Code, Codex, Copilot, Continue, and Cursor |
-| **Instructions** | Platform-specific instruction files (AGENTS.md, copilot-instructions.md, cursor rules) |
-
-## Quick Start
-
-1. **Install:**
-
-```bash
-npm install @funifier-ai
-```
-
-2. **Choose your platform** and follow setup instructions:
-
-- [Claude Code](#claude-code) — Claude's official IDE and CLI
-- [Codex CLI](#codex-cli-and-opencode) — Codex command-line agent
-- [OpenCode](#codex-cli-and-opencode) — Open-source agent framework
-- [GitHub Copilot](#github-copilot) — VS Code, JetBrains, GitHub.com
-- [Continue IDE](#continue-ide) — Open-source IDE extension
-- [Cursor IDE](#cursor-ide) — AI-native code editor
-
-For detailed setup instructions, see:
-- **[docs/INSTALL_EXAMPLES.md](docs/INSTALL_EXAMPLES.md)** — Real-world examples
-- **[docs/PLATFORM_SETUP.md](docs/PLATFORM_SETUP.md)** — Full platform guide
-- **[docs/](docs/)** — Complete documentation index
-
-## Installation
-
-### From npm (published)
-
-```bash
-npm install @funifier-ai
-```
-
-### Local development (before publishing)
-
-**Automated setup (recommended):**
-
-From **funifier-ai directory**, run:
-
-```bash
-node scripts/install-local.js /path/to/my-project
-# or relative path:
-node scripts/install-local.js ../my-project
-# or install in current directory:
-node scripts/install-local.js
-```
-
-The script will:
-1. Ask which platforms you're using (Claude Code, Codex, OpenCode, Copilot, Cursor, or all/none)
-2. Build Funifier AI
-3. Create npm link
-4. Copy only the files you need for your selected platforms
-
-Changes to funifier-ai appear immediately in your project.
-
-**Manual setup:**
-
-```bash
-# In funifier-ai directory
-npm run build && npm run bundle && npm link
-
-# In your project
-npm link @funifier-ai
-```
-
-**Direct path (copy mode):**
-
-```bash
-npm install /path/to/funifier-ai
-# or
-npm install file:../funifier-ai
-```
-
-See [docs/PLATFORM_SETUP.md](docs/PLATFORM_SETUP.md#local-development-setup) for details.
-
-## Quick Verification
-
-After local installation, verify everything is working:
-
-```bash
-# From your project directory
-node ../funifier-ai/scripts/test-local.js
-```
-
-This checks:
-- ✓ Symlink is set up correctly
-- ✓ Built files exist (dist/)
-- ✓ Instruction files copied
-- ✓ Can import the package
-- ✓ API client works (if credentials set)
-
-For detailed information on how local testing works, see [docs/LOCAL_TESTING.md](docs/LOCAL_TESTING.md).
-
-If any check fails, see [docs/MCP_SETUP.md](docs/MCP_SETUP.md) for troubleshooting.
-
----
-
-## MCP Server Setup
-
-### With Claude Code
-
-Add to your `.mcp.json` (project or global `~/.claude/.mcp.json`):
-
-```json
-{
-  "mcpServers": {
-    "funifier": {
-      "command": "node",
-      "args": ["node_modules/@funifier-ai/dist/mcp/index.js"],
-      "env": {
-        "FUNIFIER_API_KEY": "your-api-key",
-        "FUNIFIER_SECRET_KEY": "your-secret-key",
-        "FUNIFIER_SERVER_URL": "https://your-instance.funifier.com"
-      }
-    }
-  }
-}
-```
-
-Or place a `funifier.json` in your project root:
-
-```json
-{
-  "apiKey": "your-api-key",
-  "secretKey": "your-secret-key",
-  "serverUrl": "https://your-instance.funifier.com"
-}
-```
-
-### With Claude Desktop
-
-```json
-{
-  "mcpServers": {
-    "funifier": {
-      "command": "npx",
-      "args": ["@funifier-ai"],
-      "env": {
-        "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://..." })
-```
-
-## 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
-
-## API Client (library usage)
-
-```typescript
-import { createAPIClient } from "@funifier-ai";
-
-const api = createAPIClient({
-  apiKey: "your-api-key",
-  secretKey: "your-secret-key",
-  serverUrl: "https://your-instance.funifier.com",
-});
-
-// List all triggers
-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 });
-```
-
-## Skills and Instructions
-
-This package includes generated instruction files for multiple platforms. Each provides guided workflows, code quality standards, MCP tool routing, and documentation search.
-
-### Claude Code
-
-Install skills to your project:
-
-```bash
-cp -r node_modules/@funifier-ai/skills/* .claude/skills/
-```
-
-Invoke any skill with `/funifier-<name>`:
-
-```
-/funifier-create-trigger
-/funifier-debug
-/funifier-help
-```
-
-### Codex CLI and OpenCode
-
-The generated `AGENTS.md` file provides instructions for Codex, OpenCode, and any agent that reads AGENTS.md.
-
-**Codex CLI:**
-
-```bash
-cp node_modules/@funifier-ai/AGENTS.md .
-codex "Create a trigger for player registration"
-```
-
-**OpenCode:**
-
-```bash
-cp node_modules/@funifier-ai/AGENTS.md .
-# Add to .opencode.json:
-# { "instructions": { "file": "./AGENTS.md" } }
-opencode "Debug my scheduler"
-```
-
-See [PLATFORM_SETUP.md](docs/PLATFORM_SETUP.md) for full configuration details.
-
-### GitHub Copilot
-
-```bash
-mkdir -p .github
-cp node_modules/@funifier-ai/.github/copilot-instructions.md .github/
-```
-
-Copilot automatically applies `.github/copilot-instructions.md` to code suggestions, chat, and PR reviews.
-
-### Continue IDE
-
-```bash
-mkdir -p .github
-cp node_modules/@funifier-ai/.github/copilot-instructions.md .github/
-# Configure ~/.continue/config.json with customInstructions and MCP
-```
-
-Continue (VS Code / JetBrains) supports full MCP integration. See [PLATFORM_SETUP.md](docs/PLATFORM_SETUP.md) for configuration.
-
-### Cursor IDE
-
-```bash
-mkdir -p .cursor/rules
-cp node_modules/@funifier-ai/.cursor/rules/funifier.mdc .cursor/rules/
-```
-
-Cursor automatically discovers and applies `.mdc` files in `.cursor/rules/` to all code generation and completions.
-
----
-
-### Available Workflows
-
-Each platform above provides access to these guided workflows:
-
-| Skill | Description |
-|-------|-------------|
-| `funifier-help` | Documentation router and guidance |
-| `funifier-debug` | Systematic debugging workflow |
-| `funifier-create-trigger` | Create server-side event handlers |
-| `funifier-create-scheduler` | Create scheduled Groovy jobs |
-| `funifier-create-aggregate` | Create MongoDB aggregate pipelines |
-| `funifier-create-custom-page` | Create Studio admin pages |
-| `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 stores |
-| `funifier-implement-frontend` | Build frontend consuming Funifier API |
-
-## Generated Files
-
-When you install `@funifier-ai`, the package includes pre-generated instruction and skill files:
-
-| File | Platforms | Purpose |
-|------|-----------|---------|
-| `skills/funifier-*/SKILL.md` | Claude Code | Guided workflows with system prompt, doc search, and steps |
-| `AGENTS.md` | Codex, OpenCode | Agent routing, MCP tools, and skill index |
-| `.github/copilot-instructions.md` | Copilot, Continue | Code quality standards and skill routing |
-| `.cursor/rules/funifier.mdc` | Cursor | Development rules with YAML frontmatter |
-
-All files embed:
-- **Senior developer persona** (SOLID, DRY, KISS, YAGNI)
-- **Skill routing** (which skill to use for each task)
-- **MCP tool reference** (if server is configured)
-- **Lexical search command** (to find relevant docs efficiently)
-
----
-
-## Documentation
-
-- **[docs/README.md](docs/)** — Complete documentation index
-- **[docs/PLATFORM_SETUP.md](docs/PLATFORM_SETUP.md)** — Detailed setup for all platforms
-- **[docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md)** — Copy-paste setup commands
-- **[docs/INSTALL_EXAMPLES.md](docs/INSTALL_EXAMPLES.md)** — Real-world scenarios
-- **[docs/MCP_SETUP.md](docs/MCP_SETUP.md)** — MCP configuration and troubleshooting
-
----
-
-## 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) |
-
-### funifier.json
-
-Place in your project root for automatic configuration:
-
-```json
-{
-  "apiKey": "your-api-key",
-  "secretKey": "your-secret-key",
-  "serverUrl": "https://your-instance.funifier.com"
-}
-```
-
-## License
-
-MIT
+# funifier-mcp
+
+Funifier AI toolkit — API client, MCP server, and AI assistant skills for the [Funifier](https://funifier.com) 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 exposing 8 tools + 3 prompts + documentation resources |
+| **Skills** | 15 guided workflows for Claude Code, Codex, OpenCode, Cursor, Copilot, and Antigravity |
+| **Instructions** | Platform-specific instruction files (AGENTS.md, copilot-instructions.md, cursor rules) |
+| **Init CLI** | `npx funifier-mcp init` — interactive setup for every supported platform |
+
+## Quick Start
+
+```bash
+# 1. Create (or cd into) your project
+npm init -y
+
+# 2. Install
+npm install funifier-mcp
+
+# 3. Run interactive setup
+npx funifier-mcp init
+```
+
+`init` asks which platforms you use, optionally collects Funifier credentials, then:
+
+- Copies the skill/instruction files each platform expects (`.claude/skills/`, `AGENTS.md`, `.cursor/rules/`, etc.)
+- Writes the correct MCP server config for each platform (`.mcp.json`, `.codex/config.toml`, `opencode.json`, `.cursor/mcp.json`, `.antigravity/mcp_config.json`)
+- Writes `funifier.json` with your credentials (and adds it to `.gitignore`), or `funifier.json.example` if you skip credentials
+- Prompts before overwriting anything that already exists
+
+### Supported platforms
+
+- **Claude Code** — Anthropic's official CLI/IDE
+- **Codex CLI** — OpenAI's command-line agent
+- **OpenCode** — open-source agent framework
+- **Cursor IDE** — AI-native code editor
+- **GitHub Copilot** — VS Code, JetBrains, GitHub.com
+- **Google Antigravity** — Gemini-based desktop agent
+
+> Antigravity reads its MCP config from `~/.gemini/antigravity/mcp_config.json`. `init` writes a project-level snippet to `.antigravity/mcp_config.json` and prints the global path so you can merge it in.
+
+## CLI
+
+```bash
+funifier-mcp              # Start the MCP server over stdio (used by MCP clients)
+funifier-mcp init         # Interactive setup
+funifier-mcp --version
+funifier-mcp --help
+```
+
+## 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
+
+## API Client (library usage)
+
+```typescript
+import { createAPIClient } from "funifier-mcp";
+
+const api = createAPIClient({
+  apiKey: "your-api-key",
+  secretKey: "your-secret-key",
+  serverUrl: "https://your-instance.funifier.com",
+});
+
+const triggers = await api.listTriggers();
+const result = await api.executeAggregate("my-aggregate-id", {});
+const players = await api.queryCollection("player", { active: true }, { limit: 10 });
+```
+
+## Manual MCP Setup (if you skip `init`)
+
+Point your MCP client at the bundled server:
+
+```json
+{
+  "mcpServers": {
+    "funifier": {
+      "command": "npx",
+      "args": ["funifier-mcp"],
+      "env": {
+        "FUNIFIER_API_KEY": "your-api-key",
+        "FUNIFIER_SECRET_KEY": "your-secret-key",
+        "FUNIFIER_SERVER_URL": "https://your-instance.funifier.com"
+      }
+    }
+  }
+}
+```
+
+Or drop a `funifier.json` in your project root and the server will pick it up automatically:
+
+```json
+{
+  "apiKey": "your-api-key",
+  "secretKey": "your-secret-key",
+  "serverUrl": "https://your-instance.funifier.com"
+}
+```
+
+If no config is provided at startup, call the `funifier_connect` tool at runtime.
+
+## Available Workflows
+
+| Skill | Description |
+|-------|-------------|
+| `funifier-help` | Documentation router and guidance |
+| `funifier-debug` | Systematic debugging workflow |
+| `funifier-create-trigger` | Create server-side event handlers |
+| `funifier-create-scheduler` | Create scheduled Groovy jobs |
+| `funifier-create-aggregate` | Create MongoDB aggregate pipelines |
+| `funifier-create-custom-page` | Create Studio admin pages |
+| `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 stores |
+| `funifier-implement-frontend` | Build frontend consuming Funifier API |
+
+In Claude Code, invoke any skill with `/funifier-<name>` (e.g. `/funifier-help`).
+
+## 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) |
+
+Resolution order: `funifier.json` in cwd → environment variables → `funifier_connect` tool at runtime.
+
+## Local development
+
+```bash
+git clone https://github.com/funifierinc/funifier-mcp.git
+cd funifier-mcp
+npm install
+npm run build         # tsc → dist/
+npm run bundle        # build + esbuild single-file bundle
+npm test              # vitest
+```
+
+To test `init` against a scratch project:
+
+```bash
+npm link
+cd /tmp/scratch && npm init -y && npm link funifier-mcp
+npx funifier-mcp init
+```
+
+## Documentation
+
+- **[docs/PLATFORM_SETUP.md](docs/PLATFORM_SETUP.md)** — Detailed setup for all platforms
+- **[docs/QUICK_REFERENCE.md](docs/QUICK_REFERENCE.md)** — Copy-paste setup commands
+- **[docs/INSTALL_EXAMPLES.md](docs/INSTALL_EXAMPLES.md)** — Real-world scenarios
+- **[docs/MCP_SETUP.md](docs/MCP_SETUP.md)** — MCP configuration and troubleshooting
+
+## License
+
+MIT