@fload-ai/mcp 0.1.0 → 0.2.1

package/README.md

@@ -1,359 +1,113 @@
-# @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](https://fload.com) — connects any MCP-compatible AI client (Claude, ChatGPT, Cursor, VS Code, Cline) to your mobile app's App Store Connect / Google Play reviews, metrics, ad campaigns, anomalies, and ASO data.
 
-## What is MCP?
+37 tools across 10 domains. OAuth 2.1 for remote connections, API key for scripts and CI.
 
-[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.
+## Two ways to connect
 
-## Features
+### Remote (recommended) — OAuth 2.1 via `mcp-remote`
 
-- **🎯 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
+For Claude Desktop, Cursor, ChatGPT, and any client that supports remote MCP servers. No API keys to manage, per-organization scoping, revoke anytime from Fload Settings → Connected Apps.
 
-- **🔒 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`
+**Claude Desktop** (`~/Library/Application Support/Claude/claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "fload": {
       "command": "npx",
-      "args": ["@fload/mcp"],
-      "env": {
-        "FLOAD_API_KEY": "fload_sk_your_key_here",
-        "DATABASE_URL": "postgresql://..."
-      }
+      "args": ["-y", "mcp-remote", "https://api.fload.com/mcp"]
     }
   }
 }
 ```
 
-Restart Claude Desktop, and you'll see the Fload tools available!
+Restart Claude Desktop. On first use, `mcp-remote` opens a browser for OAuth consent. Pick which Fload organization to share, approve scopes, done.
 
-### With Custom MCP Client
+**Cursor:** Settings → MCP → Add remote server → `https://api.fload.com/mcp`. Cursor handles Dynamic Client Registration and the consent flow automatically.
 
-```typescript
-import { McpClient } from '@modelcontextprotocol/sdk/client/mcp.js';
-import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
+**ChatGPT (Team / Enterprise):** Admin portal → Connectors → Add custom connector → server URL `https://api.fload.com/mcp`.
 
-const client = new McpClient({
-  name: 'my-client',
-  version: '1.0.0',
-});
+### Local stdio — API key
 
-const transport = new StdioClientTransport({
-  command: 'npx',
-  args: ['@fload/mcp'],
-  env: {
-    FLOAD_API_KEY: 'fload_sk_...',
-    DATABASE_URL: 'postgresql://...',
-  },
-});
+For scripts, CI, headless environments, or anyone who wants a long-lived machine credential. Install this package and point an MCP client at the binary:
 
-await client.connect(transport);
+1. Create an API key at [platform.fload.com/settings/api-keys](https://platform.fload.com/settings/api-keys).
 
-// List apps
-const result = await client.callTool('list_apps', { limit: 10 });
-console.log(result);
-```
+2. Add to your MCP config:
 
-## Tools Reference
+   ```json
+   {
+     "mcpServers": {
+       "fload": {
+         "command": "npx",
+         "args": ["-y", "@fload-ai/mcp"],
+         "env": {
+           "FLOAD_API_KEY": "fload_sk_your_key_here"
+         }
+       }
+     }
+   }
+   ```
 
-### `list_apps`
+   Or use `~/.fload/config.json`:
 
-List all mobile apps in your organization.
+   ```json
+   {
+     "apiKey": "fload_sk_your_key_here",
+     "apiUrl": "https://api.fload.com"
+   }
+   ```
 
-**Input:**
-```typescript
-{
-  platform?: 'ios' | 'android',  // Filter by platform
-  limit?: number                  // Max results (1-100, default: 50)
-}
-```
+## What you can ask your agent
 
-**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"
-    }
-  ]
-}
-```
+- "Why did iOS installs drop yesterday?"
+- "Draft replies to my last 5 one-star reviews in my brand voice, then approve the good ones."
+- "What's my ROAS across all ad platforms this week?"
+- "Audit my ASO for my top-grossing app and suggest title changes."
+- "List anomalies across my portfolio this week — acknowledge the ones on my dummy app."
 
-### `get_app_details`
+## Tools
 
-Get detailed information about a specific app.
+37 tools grouped by domain. Full list with annotations + scope requirements at [fload.com/docs/mcp](https://fload.com/docs/mcp).
 
-**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
-
-### `get_reviews`
-
-Get app reviews with flexible filtering.
-
-**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
-}
-```
-
-**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 }
-  ]
-}
-```
-
-## 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
-```
+| Domain | Tools |
+|---|---|
+| Apps | `list_apps`, `get_app_details` |
+| Reviews | `get_reviews`, `generate_review_reply`, `send_review_reply`, `translate_review` |
+| Analytics | `discover_metrics`, `get_metrics`, `discover_dimensions` (30+ metrics, dimensional breakdowns) |
+| Agents | `list_agents`, `get_agent_details`, `get_agent_run_history`, `trigger_agent_run`, `pause_agent`, `resume_agent`, `get_agent_activity` |
+| Anomalies | `get_anomalies`, `get_anomaly_detail`, `acknowledge_anomaly`, `dismiss_anomaly` |
+| Ads | `get_ads_performance` (Apple Search Ads, Google Ads, Meta Ads, TikTok Ads) |
+| ASO | `get_aso_summary`, `get_aso_recommendations`, `get_aso_keywords`, `get_aso_experiments`, `get_aso_locale_snapshots`, `trigger_aso_analysis` |
+| Growth | `get_growth_audit`, `get_growth_score` |
+| Forecasting | `get_forecasts` |
+| Dashboard | `get_dashboard_overview` |
+| Actions | `list_pending_actions`, `approve_action`, `reject_action` |
+| Chat | `list_conversations`, `get_conversation_messages`, `send_chat_message` |
 
-### Test
+Every tool carries an MCP `readOnlyHint` or `destructiveHint` annotation so clients can surface the scope of each action to users before calling.
 
-```bash
-pnpm test
-```
-
-### Typecheck
-
-```bash
-pnpm typecheck
-```
-
-### Lint
+## OAuth scopes (remote only)
 
-```bash
-pnpm lint
-```
+16 scopes. Agents request the minimum they need; users approve per-scope on the consent screen and can revoke from [platform.fload.com/settings/connected-apps](https://platform.fload.com/settings/connected-apps).
 
-## Roadmap
+- **OIDC identity:** `openid`, `email`, `profile`, `offline_access`
+- **Reads:** `read:apps`, `read:reviews`, `read:analytics`, `read:anomalies`, `read:ads`, `read:aso`, `read:agents`
+- **Writes:** `write:reviews`, `write:ads`, `write:aso`, `write:agents`, `write:chat`
 
-- **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)
+## Configuration (stdio mode)
 
-## Security
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `FLOAD_API_KEY` | Yes (stdio) | — | API key, format `fload_sk_...` |
+| `FLOAD_API_URL` | No | `https://api.fload.com` | API URL (override for self-hosted) |
 
-- **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)
+## Issues & feedback
 
-## Contributing
-
-This package is part of the Fload monorepo. See [CONTRIBUTING.md](../../CONTRIBUTING.md) for guidelines.
+File bugs or feature requests at [github.com/fload-ai/mcp/issues](https://github.com/fload-ai/mcp/issues). For integration support: support@fload.com.
 
 ## 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