@fload-ai/mcp 0.1.0

package/README.md

@@ -0,0 +1,359 @@
+# @fload/mcp
+
+**Fload MCP Server** - Model Context Protocol server for AI agents to access Fload's mobile app analytics, reviews, and growth insights.
+
+## What is MCP?
+
+[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.
+
+## Features
+
+- **🎯 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
+
+- **🔒 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`
+
+```json
+{
+  "mcpServers": {
+    "fload": {
+      "command": "npx",
+      "args": ["@fload/mcp"],
+      "env": {
+        "FLOAD_API_KEY": "fload_sk_your_key_here",
+        "DATABASE_URL": "postgresql://..."
+      }
+    }
+  }
+}
+```
+
+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';
+
+const client = new McpClient({
+  name: 'my-client',
+  version: '1.0.0',
+});
+
+const transport = new StdioClientTransport({
+  command: 'npx',
+  args: ['@fload/mcp'],
+  env: {
+    FLOAD_API_KEY: 'fload_sk_...',
+    DATABASE_URL: 'postgresql://...',
+  },
+});
+
+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"
+    }
+  ]
+}
+```
+
+### `get_app_details`
+
+Get detailed information about a specific app.
+
+**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
+```
+
+### 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**