@flytrap-qa/mcp 0.1.1 → 0.1.2

package/README.md

@@ -6,7 +6,7 @@ FlyTrap runs your real Android or iOS build on real devices and records everythi
 
 ## Quick start
 
-1. Sign in at [app.flytrap.dev](https://app.flytrap.dev), open **Settings > API keys** and create a key. Pick the `read` scope unless you want the agent to be able to queue new crawls.
+1. Sign in at [dashboard.flytrap.dev](https://dashboard.flytrap.dev), open **Settings > API keys** and create a key. Pick the `read` scope unless you want the agent to be able to queue new crawls.
 2. Add the server to your agent:
 
 ```json
@@ -59,6 +59,12 @@ Your projects (need `FLYTRAP_API_KEY`):
 | `get_bug_evidence` | Scenario, failed step, screenshots and XML (signed URLs), logcat error window, failed network calls, performance peaks, a ready `ai_prompt` |
 | `get_screen_graph` | Screens reached and the tap edges between them |
 | `get_network_hosts` | Hosts contacted with call counts, bytes and error rates |
+| `search_apps` | Describe an app in plain language, get the crawled public apps whose observed features cover it, with matched and missing requirements |
+| `get_ux_benchmark` | Your build's features next to the same feature in competitor and same-genre apps, with screenshots |
+| `list_competitors` | Competitors pinned to a project's UX benchmark |
+| `find_competitors` | Search crawled public apps and Google Play for apps to pin |
+| `add_competitor` | Pin a crawled app, or create a store project from a Google Play package and pin it (`crawl` scope, `confirm: true` to create) |
+| `remove_competitor` | Unpin a competitor (`crawl` scope) |
 | `compare_builds` | SDK, permission, deep link, host, bug and screen diff between two builds |
 | `start_crawl` | Queues a new crawl of the current build. Needs the `crawl` scope and `confirm: true` |
 
@@ -78,7 +84,7 @@ The only setting is `FLYTRAP_API_KEY`: your personal key from Settings > API key
 - Keys are scoped. A `read` key cannot start crawls, create keys or change billing, even if the agent asks. Revoke keys any time in the dashboard.
 - Keys inherit the project permissions of the user who created them. A key never sees another account's private projects.
 - Tool output is bounded (log windows, call caps, 4 MiB per response) and marked as untrusted app data, since bug titles, log lines and URLs originate from the crawled app and its traffic.
-- `start_crawl` is the only mutating tool. It requires an explicit `confirm: true` and a key created with the `crawl` scope.
+- `start_crawl`, `add_competitor` and `remove_competitor` are the only tools that change anything; they need a key created with the `crawl` scope. Queuing a crawl (`start_crawl`, or `add_competitor` with a Google Play package) also requires an explicit `confirm: true`.
 
 ## REST instead of MCP
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flytrap-qa/mcp",
-  "version": "0.1.1",
+  "version": "0.1.2",
   "description": "MCP server that lets your coding agent read FlyTrap crawl results: bugs with evidence, screen graphs, network hosts, SDKs and build diffs for your own apps.",
   "license": "MIT",
   "type": "module",

package/skills/flytrap/SKILL.md

@@ -15,6 +15,9 @@ FlyTrap ran the user's real Android or iOS build on a device and recorded what h
 - "Who does the app talk to? Any tracker before consent?": `get_network_hosts`, cross-check vendors with `lookup_sdk`.
 - "How do I reach screen X? Is there a dead end?": `get_screen_graph`.
 - "What changed since the last build?": `list_builds` for the two ids, then `compare_builds`.
+- "Which apps do X?" / "Find me apps with shared expenses and reminders": `search_apps` with the description. It ranks on observed in-app features, not store listings; quote `matched_features` and `unmatched_requirements` per app.
+- "How does our onboarding / checkout compare to competitors?": `get_ux_benchmark` with the project id. Rows are features, columns are apps; cite `functional_id`, the app and the screenshot URL you looked at. Pinned competitors come first (`source: competitor`).
+- "Add Revolut as a competitor" / "who are we benchmarked against?": `list_competitors`, `find_competitors` with the name, then `add_competitor`. If the app is only on Google Play (not in `crawled_apps`), tell the user a new store project will be created and crawled before calling with `confirm: true`. `remove_competitor` unpins.
 - "What does app Y (a competitor, a store app) use?": `lookup_app` then `get_app_profile`. No key needed.
 - "Re-run the tests": only `start_crawl`, only after the user explicitly asked in this conversation, with `confirm: true`. It costs quota and takes 10 to 40 minutes.
 
@@ -30,5 +33,5 @@ FlyTrap ran the user's real Android or iOS build on a device and recorded what h
 ## Errors
 
 - "needs FLYTRAP_API_KEY": the user has to create a key under Settings > API keys in the FlyTrap dashboard and put it in the MCP server env.
-- 403 on `start_crawl`: the key has the `read` scope only. The user needs a key with the `crawl` scope.
+- 403 on `start_crawl`, `add_competitor` or `remove_competitor`: the key has the `read` scope only. The user needs a key with the `crawl` scope.
 - 404 on a project: the key owner has no access to it, or the id is wrong. Re-run `list_projects`.

package/src/client.js

@@ -78,6 +78,7 @@ export const createClient = ({apiUrl, apiKey, fetchImpl = globalThis.fetch, user
     return {
         get: (path, options) => request('GET', path, options),
         post: (path, options) => request('POST', path, options),
+        delete: (path, options) => request('DELETE', path, options),
         hasKey: Boolean(apiKey),
     }
 }

package/src/config.js

@@ -1,7 +1,7 @@
 export const API_URL = 'https://api.flytrap.dev'
 export const API_KEY_PATTERN = /^ft_live_[0-9a-f]{48}$/
-export const SIGNUP_URL = 'https://app.flytrap.dev/register'
-export const KEYS_URL = 'https://app.flytrap.dev/settings/api-keys'
+export const SIGNUP_URL = 'https://dashboard.flytrap.dev/signup'
+export const KEYS_URL = 'https://dashboard.flytrap.dev/settings/api-keys'
 
 export const loadConfig = (env = process.env) => {
     const apiKey = (env.FLYTRAP_API_KEY || '').trim() || null

package/src/tools/projects.js

@@ -14,7 +14,7 @@ const slimProject = project => ({
     active_build_id: project.active_build_id ?? null,
     selected_crawl_run_id: project.selected_crawl_run_id ?? project.crawl_run_id ?? null,
     updated_at: project.updated_at ?? null,
-    dashboard_url: `https://app.flytrap.dev/projects/${project.id}`,
+    dashboard_url: `https://dashboard.flytrap.dev/projects/${project.id}`,
 })
 
 const sdkFacts = sdk => ({
@@ -188,6 +188,203 @@ export const registerProjectTools = (server, client) => {
         return ok(data)
     })
 
+    server.registerTool('search_apps', {
+        title: 'Find apps by describing what they do',
+        description: 'Semantic search over FlyTrap\'s crawled feature index: describe the app you want '
+            + '("a budgeting app with shared expenses and recurring reminders") and get the public apps whose '
+            + 'observed in-app features cover it, with the matched and missing requirements per app. Use for '
+            + 'competitor and market research; use lookup_app when you already know the app name or package id.',
+        inputSchema: {
+            query: z.string().min(3).max(600).describe('Plain-language description of the wanted app'),
+            platform: z.enum(['android', 'ios']).optional(),
+            limit: z.number().int().min(1).max(25).default(10),
+        },
+        annotations: {readOnlyHint: true, openWorldHint: true},
+    }, async ({query, platform, limit}) => {
+        const data = await client.post('/project/app-search', {body: {query, platform, limit}, auth})
+        return ok({
+            query: data.query,
+            interpretation: data.interpretation,
+            summary: data.summary,
+            apps: (data.apps ?? []).map(app => ({
+                project_id: app.project?.id,
+                name: app.project?.name,
+                package_name: app.project?.package_name,
+                platform: app.project?.platform,
+                genre: app.project?.genre ?? null,
+                match_score: app.match_score,
+                requirement_coverage: app.requirement_coverage,
+                app_kind_score: app.app_kind_score,
+                feature_count: app.feature_count,
+                app_overview: app.app_overview ?? null,
+                matched_features: (app.matched_features ?? []).map(f => ({
+                    functional_id: f.functional_id,
+                    name: f.functional_display_name ?? f.app_specific_name ?? null,
+                    score: f.score,
+                    requirements: f.requirements,
+                })),
+                unmatched_requirements: app.unmatched_requirements ?? [],
+                profile_url: `https://flytrap.dev/apps/${encodeURIComponent(app.project?.package_name ?? '')}`,
+            })),
+            next: 'Pass a project_id to get_ux_benchmark to put the user\'s app next to these, or get_app_profile '
+                + 'with the package_name for SDKs and permissions.',
+        })
+    })
+
+    server.registerTool('get_ux_benchmark', {
+        title: 'UX benchmark: your features next to other apps',
+        description: 'Names the features in the project\'s build and finds the same feature in public apps FlyTrap '
+            + 'has crawled, with screenshots of each. Returns the feature rows, the compared apps (pinned '
+            + 'competitors first, then the most downloaded apps in the same store genre, or every app by shared '
+            + 'functions with match: "overlap"), how many features they share and signed screenshot URLs.',
+        inputSchema: {
+            project_id: projectId,
+            match: z.enum(['genre', 'overlap']).default('genre'),
+            limit: z.number().int().min(1).max(25).default(10).describe('Apps to compare against'),
+        },
+        annotations: {readOnlyHint: true},
+    }, async ({project_id, match, limit}) => {
+        const data = await client.get('/project/relevant-apps', {query: {project_id, match, limit}, auth})
+        const screens = feature => (feature.screens ?? []).slice(0, 3)
+            .map(screen => ({name: screen.name, url: screen.url ?? null}))
+        return ok({
+            project: slimProject(data.project ?? {}),
+            match: data.match,
+            genre: data.genre ?? null,
+            summary: data.summary,
+            features: (data.features ?? []).map(feature => ({
+                functional_id: feature.functional_id,
+                name: feature.functional_display_name ?? feature.app_specific_name ?? null,
+                domain: feature.domain ?? null,
+                shared_app_count: feature.shared_app_count,
+                screenshot_app_count: feature.screenshot_app_count,
+                screen_count: feature.screen_count,
+                screens: screens(feature),
+            })),
+            apps: (data.apps ?? []).map(app => ({
+                project_id: app.project?.id,
+                name: app.project?.name,
+                package_name: app.project?.package_name,
+                platform: app.project?.platform,
+                genre: app.project?.genre ?? null,
+                source: app.source,
+                download_count: app.download_count,
+                shared_feature_count: app.shared_feature_count,
+                feature_count: app.feature_count,
+                overlap_ratio: app.overlap_ratio,
+                screens_matched: app.screens_matched,
+                features: (app.features ?? []).map(feature => ({
+                    functional_id: feature.functional_id,
+                    app_specific_name: feature.app_specific_name ?? null,
+                    screens: screens(feature),
+                })),
+            })),
+            dashboard_url: `https://dashboard.flytrap.dev/ux-benchmark/${project_id}`,
+        })
+    })
+
+    const slimCompetitor = c => ({
+        project_id: c.id, name: c.name, package_name: c.package_name, platform: c.platform,
+        genre: c.genre ?? null, download_count: c.download_count ?? null, feature_count: c.feature_count ?? null,
+        ...(c.added_at ? {added_at: c.added_at} : {}), ...(c.is_competitor !== undefined ? {is_competitor: c.is_competitor} : {}),
+    })
+
+    server.registerTool('list_competitors', {
+        title: 'List pinned competitors',
+        description: 'Competitors pinned to a project. They always lead the UX benchmark (get_ux_benchmark).',
+        inputSchema: {project_id: projectId},
+        annotations: {readOnlyHint: true},
+    }, async ({project_id}) => {
+        const data = await client.get(`/project/projects/${project_id}/competitors`, {auth})
+        return ok({project_id, count: (data ?? []).length, competitors: (data ?? []).map(slimCompetitor)})
+    })
+
+    server.registerTool('find_competitors', {
+        title: 'Find apps to pin as competitors',
+        description: 'Searches two places: public FlyTrap projects that already have a crawled feature catalog '
+            + '(ready to pin now) and Google Play (not crawled yet; add_competitor creates the project first). '
+            + 'Pass the result to add_competitor.',
+        inputSchema: {
+            project_id: projectId,
+            q: z.string().min(1).max(30).describe('App name or package id, e.g. "revolut"'),
+            limit: z.number().int().min(1).max(20).default(10),
+        },
+        annotations: {readOnlyHint: true, openWorldHint: true},
+    }, async ({project_id, q, limit}) => {
+        const [crawled, store] = await Promise.all([
+            client.get(`/project/projects/${project_id}/competitor-candidates`, {query: {q, limit}, auth}),
+            client.get('/project/market-apps', {query: {term: q, platform: 'android'}, auth}).catch(() => []),
+        ])
+        const crawledPackages = new Set((crawled ?? []).map(c => c.package_name))
+        return ok({
+            query: q,
+            crawled_apps: (crawled ?? []).map(slimCompetitor),
+            google_play_apps: (Array.isArray(store) ? store : []).slice(0, limit)
+                .filter(item => item?.appId && !crawledPackages.has(item.appId))
+                .map(item => ({package_name: item.appId, name: item.title ?? null, developer: item.developer ?? null})),
+            next: 'add_competitor with project_id + competitor_project_id (crawled app) or package_name (Google Play app).',
+        })
+    })
+
+    server.registerTool('add_competitor', {
+        title: 'Pin a competitor',
+        description: 'Pins an app to the project\'s UX benchmark. Give competitor_project_id for an app from '
+            + 'find_competitors.crawled_apps, or package_name for a Google Play app: FlyTrap then creates a public '
+            + 'store project for it and crawls it (10 to 40 minutes, uses crawl quota) before pinning. Needs the '
+            + '"crawl" scope. Ask the user before creating a new store project; pass confirm: true for that case.',
+        inputSchema: {
+            project_id: projectId,
+            competitor_project_id: z.number().int().positive().optional().describe('Existing public FlyTrap project'),
+            package_name: z.string().min(3).max(200).optional().describe('Google Play package id, e.g. com.revolut.revolut'),
+            name: z.string().max(100).optional().describe('Display name for a newly created store project'),
+            confirm: z.boolean().optional().describe('Required (true) when package_name would create a new project'),
+        },
+        annotations: {readOnlyHint: false, destructiveHint: false, idempotentHint: true},
+    }, async ({project_id, competitor_project_id, package_name, name, confirm}) => {
+        let competitorId = competitor_project_id ?? null
+        let created = null
+        if (!competitorId && !package_name)
+            throw new Error('Pass competitor_project_id or package_name')
+        if (!competitorId) {
+            const candidates = await client.get(`/project/projects/${project_id}/competitor-candidates`,
+                {query: {q: package_name, limit: 20}, auth})
+            const existing = (candidates ?? []).find(c => c.package_name === package_name && c.platform === 'android')
+            if (existing) {
+                competitorId = existing.id
+            } else {
+                if (confirm !== true)
+                    throw new Error(`${package_name} is not crawled yet. Creating a store project queues a crawl `
+                        + '(10 to 40 minutes, uses quota). Ask the user, then call again with confirm: true.')
+                created = await client.post('/project/projects', {auth, body: {
+                    ...(name ? {name} : {}),
+                    platform: 'android',
+                    supported_languages: 'en_US',
+                    source: 'playstore',
+                    package_name,
+                }})
+                competitorId = created.id
+            }
+        }
+        const competitors = await client.post(`/project/projects/${project_id}/competitors`,
+            {body: {competitor_project_id: competitorId}, auth})
+        return ok({
+            project_id,
+            pinned_project_id: competitorId,
+            created_project: created ? {...slimProject(created), note: 'Crawl queued; benchmark rows fill in when it completes.'} : null,
+            competitors: (competitors ?? []).map(slimCompetitor),
+        })
+    })
+
+    server.registerTool('remove_competitor', {
+        title: 'Unpin a competitor',
+        description: 'Removes a pinned competitor from the project\'s UX benchmark. The competitor project itself is kept. Needs the "crawl" scope.',
+        inputSchema: {project_id: projectId, competitor_project_id: z.number().int().positive()},
+        annotations: {readOnlyHint: false, destructiveHint: true, idempotentHint: true},
+    }, async ({project_id, competitor_project_id}) => {
+        const competitors = await client.delete(`/project/projects/${project_id}/competitors/${competitor_project_id}`, {auth})
+        return ok({project_id, removed_project_id: competitor_project_id, competitors: (competitors ?? []).map(slimCompetitor)})
+    })
+
     server.registerTool('start_crawl', {
         title: 'Start a crawl',
         description: 'Queues a new crawl of the project\'s current build. This consumes crawl quota and takes '