@fload-ai/mcp 0.1.0 → 0.1.1

package/README.md

@@ -1,359 +1,80 @@
-# @fload/mcp
+# @fload-ai/mcp
 
-**Fload MCP Server** - Model Context Protocol server for AI agents to access Fload's mobile app analytics, reviews, and growth insights.
+MCP server for Fload — gives AI assistants access to your mobile app analytics, reviews, growth metrics, and more.
 
-## What is MCP?
+## Quick Start
 
-[Model Context Protocol (MCP)](https://modelcontextprotocol.io/) is an open standard by Anthropic that enables AI applications to securely connect to data sources and tools. This package implements an MCP server that exposes Fload's mobile analytics capabilities to AI agents like Claude, ChatGPT, and custom AI tools.
+### 1. Get your API key
 
-## Features
+Go to [platform.fload.com](https://platform.fload.com/settings/api-keys) > Settings > API Keys > Create Key.
 
-- **🎯 Core Tools (Phase 1)**
-  - `list_apps` - List all apps in your organization
-  - `get_app_details` - Get detailed app information
-  - `get_reviews` - Query reviews with flexible filters
-  - `get_analytics_summary` - Get metric summaries with timeseries data
+### 2. Add to Claude Desktop
 
-- **🔒 Authentication**
-  - API key-based authentication
-  - Organization-scoped access
-  - Secure credential management
-
-- **🚀 Fast & Reliable**
-  - Direct database queries (Drizzle ORM)
-  - TimescaleDB for analytics
-  - Optimized for AI agent workflows
-
-## Installation
-
-### From Monorepo (Development)
-
-```bash
-cd ~/www/fload
-pnpm install
-pnpm build
-```
-
-### From NPM (Production)
-
-```bash
-npm install -g @fload/mcp
-# or
-npx @fload/mcp
-```
-
-## Setup
-
-### 1. Generate API Key
-
-🚧 **Coming Soon:** API key management UI in Fload web app.
-
-For now, contact your Fload admin to generate an API key.
-
-### 2. Configure Environment
-
-**Option A: Environment Variables (Recommended)**
-
-```bash
-export FLOAD_API_KEY=fload_sk_your_key_here
-export DATABASE_URL=postgresql://user:pass@host:port/fload
-```
-
-**Option B: Config File**
-
-Create `~/.fload/config.json`:
-
-```json
-{
-  "apiKey": "fload_sk_your_key_here",
-  "databaseUrl": "postgresql://user:pass@host:port/fload",
-  "organizationId": "your-org-id"
-}
-```
-
-### 3. Test the Server
-
-```bash
-# From monorepo
-pnpm --filter @fload/mcp dev
-
-# Or via npx
-npx @fload/mcp
-```
-
-You should see:
-```
-[Fload MCP] Starting server...
-[Fload MCP] Configuration loaded
-[Fload MCP] Database connected
-[Fload MCP] Server running on stdio
-```
-
-## Usage
-
-### With Claude Desktop
-
-Add to your `claude_desktop_config.json`:
-
-**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`  
-**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+Edit `~/Library/Application Support/Claude/claude_desktop_config.json` (macOS):
 
 ```json
 {
   "mcpServers": {
     "fload": {
       "command": "npx",
-      "args": ["@fload/mcp"],
+      "args": ["-y", "@fload-ai/mcp"],
       "env": {
-        "FLOAD_API_KEY": "fload_sk_your_key_here",
-        "DATABASE_URL": "postgresql://..."
+        "FLOAD_API_KEY": "fload_sk_your_key_here"
       }
     }
   }
 }
 ```
 
-Restart Claude Desktop, and you'll see the Fload tools available!
-
-### With Custom MCP Client
-
-```typescript
-import { McpClient } from '@modelcontextprotocol/sdk/client/mcp.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+Restart Claude Desktop. You'll see 16 Fload tools available.
 
-const client = new McpClient({
-  name: 'my-client',
-  version: '1.0.0',
-});
+### 3. Add the Fload skill (optional, recommended)
 
-const transport = new StdioClientTransport({
-  command: 'npx',
-  args: ['@fload/mcp'],
-  env: {
-    FLOAD_API_KEY: 'fload_sk_...',
-    DATABASE_URL: 'postgresql://...',
-  },
-});
+The Fload skill teaches your AI agent how to use Fload tools effectively — common workflows, tips, and best practices.
 
-await client.connect(transport);
-
-// List apps
-const result = await client.callTool('list_apps', { limit: 10 });
-console.log(result);
-```
-
-## Tools Reference
-
-### `list_apps`
-
-List all mobile apps in your organization.
-
-**Input:**
-```typescript
-{
-  platform?: 'ios' | 'android',  // Filter by platform
-  limit?: number                  // Max results (1-100, default: 50)
-}
-```
-
-**Output:**
-```json
-{
-  "total": 2,
-  "apps": [
-    {
-      "id": "uuid",
-      "name": "My Awesome App",
-      "bundleId": "com.example.app",
-      "platform": "ios",
-      "iconUrl": "https://...",
-      "category": "Games",
-      "addedAt": "2024-01-15T10:30:00Z"
-    }
-  ]
-}
+```bash
+npx skills add fload-ai/mcp --skill fload
 ```
 
-### `get_app_details`
+Works with Claude Code, Cursor, Cline, GitHub Copilot, and [18+ other agents](https://skills.sh).
 
-Get detailed information about a specific app.
+## Tools
 
-**Input:**
-```typescript
-{
-  assetId?: string,    // App UUID (provide either this or bundleId)
-  bundleId?: string    // App bundle ID
-}
-```
-
-**Output:** Full app metadata + connected data sources + sync status
+| Tool | Description |
+|------|-------------|
+| `list_apps` | List all apps in your organization |
+| `get_app_details` | Get detailed app info by ID or bundle ID |
+| `get_reviews` | Get reviews with filtering (rating, date, platform) |
+| `get_analytics_summary` | Metric timeseries (downloads, revenue, users, etc.) |
+| `list_agents` | List AI agents (review, monitoring, growth, etc.) |
+| `get_agent_details` | Get agent config for a specific app |
+| `get_agent_run_history` | Agent execution history |
+| `get_anomalies` | Detected metric anomalies (surges/declines) |
+| `get_ads_performance` | Ad campaign data (ASA, Google, Meta, TikTok) |
+| `get_growth_audit` | Comprehensive growth assessment |
+| `get_growth_score` | 0-100 growth score with grade |
+| `get_forecasts` | Valuation forecasts and trend analysis |
+| `get_dashboard_overview` | Organization portfolio overview |
+| `list_pending_actions` | Pending AI-generated review replies |
+| `approve_action` | Approve a pending review reply |
+| `reject_action` | Reject a pending review reply |
 
-### `get_reviews`
+## Configuration
 
-Get app reviews with flexible filtering.
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `FLOAD_API_KEY` | Yes | — | Your API key (`fload_sk_...`) |
+| `FLOAD_API_URL` | No | `https://api.fload.com` | API URL (override for self-hosted) |
 
-**Input:**
-```typescript
-{
-  assetId?: string,           // App UUID
-  bundleId?: string,          // App bundle ID
-  platform?: 'ios' | 'android',
-  rating?: 1 | 2 | 3 | 4 | 5, // Filter by star rating
-  replied?: boolean,          // Has reply?
-  startDate?: string,         // ISO date (YYYY-MM-DD)
-  endDate?: string,
-  limit?: number,             // Max results (1-200, default: 50)
-  sortBy?: 'date' | 'rating'  // Sort order
-}
-```
+Or use `~/.fload/config.json`:
 
-**Output:**
 ```json
 {
-  "summary": {
-    "totalReviews": 25,
-    "averageRating": "4.20",
-    "repliedCount": 10,
-    "unrepliedCount": 15
-  },
-  "reviews": [
-    {
-      "id": "uuid",
-      "rating": 5,
-      "title": "Great app!",
-      "body": "Love the new features...",
-      "author": "John Doe",
-      "date": "2024-02-20T14:30:00Z",
-      "version": "2.1.0",
-      "country": "US",
-      "hasReply": true,
-      "reply": "Thank you for your feedback!",
-      "replyDate": "2024-02-21T09:00:00Z"
-    }
-  ]
-}
-```
-
-### `get_analytics_summary`
-
-Get analytics summary with timeseries data.
-
-**Input:**
-```typescript
-{
-  assetId?: string,
-  bundleId?: string,
-  metric: 'downloads' | 'revenue' | 'active_users' | 'sessions' | 'retention' | 'crashes',
-  period?: '7d' | '30d' | '90d',          // Default: '30d'
-  granularity?: 'day' | 'week' | 'month'  // Default: 'day'
-}
-```
-
-**Output:**
-```json
-{
-  "app": {
-    "id": "uuid",
-    "name": "My App",
-    "bundleId": "com.example.app",
-    "platform": "ios"
-  },
-  "metric": "downloads",
-  "period": "30d",
-  "dateRange": {
-    "start": "2024-01-25",
-    "end": "2024-02-25"
-  },
-  "summary": {
-    "total": 125000,
-    "average": 4167,
-    "min": 3200,
-    "max": 5800,
-    "trend": "+12.5%"
-  },
-  "timeseries": [
-    { "date": "2024-01-25", "value": 4200 },
-    { "date": "2024-01-26", "value": 4350 }
-  ]
+  "apiKey": "fload_sk_your_key_here",
+  "apiUrl": "https://api.fload.com"
 }
 ```
 
-## Development
-
-### Project Structure
-
-```
-packages/fload-mcp/
-├── src/
-│   ├── index.ts              # Main entry point (STDIO)
-│   ├── server.ts             # MCP server setup
-│   ├── config.ts             # Configuration loading
-│   ├── auth.ts               # API key validation
-│   ├── tools/                # Tool implementations
-│   │   ├── apps.ts
-│   │   ├── reviews.ts
-│   │   └── analytics.ts
-│   └── lib/
-│       ├── db-client.ts      # Database connection
-│       └── format.ts         # Response formatting
-├── bin/
-│   └── fload-mcp.js          # CLI executable
-└── package.json
-```
-
-### Build
-
-```bash
-pnpm build
-```
-
-### Test
-
-```bash
-pnpm test
-```
-
-### Typecheck
-
-```bash
-pnpm typecheck
-```
-
-### Lint
-
-```bash
-pnpm lint
-```
-
-## Roadmap
-
-- **Phase 1** ✅ - Core tools (apps, reviews, analytics)
-- **Phase 2** 🚧 - Full tool suite (revenue, ratings, ASO, competitors, growth audit)
-- **Phase 3** 📋 - Resources & Prompts
-- **Phase 4** 📋 - CLI wrapper
-- **Phase 5** 📋 - HTTP/SSE transport (hosted MCP server)
-
-## Security
-
-- **API keys** should be kept secret and never committed to version control
-- **Scoped access** - API keys only access their organization's data
-- **Audit logging** - All tool calls are logged for compliance
-- **Rate limiting** - Prevents abuse (coming in Phase 2)
-
-## Contributing
-
-This package is part of the Fload monorepo. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
-
 ## License
 
-MIT © Fload
-
-## Support
-
-- **Documentation:** [Design Doc](../../docs/cli-mcp-design.md)
-- **Issues:** GitHub Issues
-- **Email:** support@fload.io
-
----
-
-**Built with ❤️ for AI agents**
+MIT