MCP tools reference
Auto-generated from packages/mcp/src/catalog.ts. Do not edit by hand — run pnpm gen:mcp-tools-doc.
117 tools · 8 resources · 4 prompts
Read tools (mcp:read)
| Tool | Title | Description |
|---|---|---|
get_recent_reports | Recent bug reports | List recent bug reports for a project, newest first. Returns { reports: [{ id, status, category, severity, summary, component, created_at, processing_error }], total }; includeRaw=true returns every list column instead. Reporter identifiers (end-user id, reporter token hash, session id, display name) are never returned. Optional filters: status (new|classified|grouped|fixing|fixed|verified|reopened|dismissed|…), category (bug|slow|visual|confusing|other), severity (critical|high|medium|low), limit (default 20, max 100). Use to survey open reports; for one report use get_report_detail, to find a bug by text use search_reports. |
get_report_detail | Report detail | Fetch the full record for one bug report by id: description, console logs, network requests, screenshot URL, classification (stage 1/2), fix history, the paste-ready fix packet and the inventory action it is filed against. Returns { report } with the documented fields; includeRaw=true returns every column the detail route has instead. Reporter identifiers (end-user id, reporter token hash, session id, display name) are never returned. Read-only. Use when you have a reportId and need everything about it; for evidence only use get_report_evidence, for the activity thread use get_report_timeline, for a one-call fix bundle use get_fix_context. |
get_report_timeline | Unified report timeline | Return the ordered activity timeline for one report (oldest to newest), merging reporter comments, fix events, QA runs, skill-pipeline steps, and Ask Mushi turns into one lane. Returns { events: [{ ts, kind, actor, summary }] }. Read-only. Use to see what happened end-to-end on a report thread; use get_report_detail for the static record or get_fix_timeline to debug one fix attempt. |
search_reports | Search reports | Search reports by meaning and keyword (pgvector similarity server-side; falls back to summary/description substring if embeddings are unavailable). Returns ranked { results: [{ id, summary, similarity }] }. Read-only. Use to find reports by free text (“checkout flakiness”); use get_similar_bugs to dedupe a known component/bug, or get_recent_reports to list without a query. |
get_similar_bugs | Similar bugs | Find existing bugs similar to a component, page, or description via pgvector nearest-neighbour search (same backend as search_reports, tuned for “have we seen this before?”). Returns ranked { reports: [{ id, summary, similarity }] }. Read-only. Use to dedupe before filing or group regressions; use search_reports for general free-text search. |
get_fix_context | Fix context bundle | Bundle everything an agent needs to fix one bug in a single call: a paste-ready fixPrompt (plain-English diagnosis + reproduction + suggested fix + relevant code + blast radius), plus report detail, repro steps, component, root cause, ontology tags, and the inventory action (with its expected_outcome contract) the report is filed against, plus recipe: a ≤4 KB excerpt with the app’s tokens (CSS var / TS names), the design deviance score and deviance findings in the files this fix touches, so the fix uses the app’s tokens instead of literals, and recipe.context: the tables the stack trace names with their columns from the latest schema snapshot (and any it says do not exist), whether the last merged fix is live, and the open hole-check findings, each section with its own state and note. Returns { report, fixPrompt, reproductionSteps, component, rootCause, bugOntologyTags, inventoryAction, recipe }; recipe is always { state, note, … } with state ok | drift | unknown | not_connected | error, never null. Read-only; no second LLM key needed. Use before writing a fix; use triage_issue for a multi-report review packet, or suggest_fix for just the Stage-2 hint. |
get_fix_timeline | Fix timeline | Return the ordered lifecycle of one fix attempt: dispatched, started, branch, commit, PR opened, CI, completed/failed, with timestamps and the PR URL. Returns { events: [{ ts, stage, detail }] }. Read-only. Use to debug “why did this fix fail?” after dispatch_fix; use refresh_ci to re-poll GitHub CI, or get_report_timeline for the whole report thread. |
get_blast_radius | Blast radius | Return the other components/pages a bug group touches, via knowledge-graph traversal from the report node. Returns { nodes: [{ id, label, type }], edges }. Read-only. Use before dispatch_fix to scope a change safely; use get_knowledge_graph to traverse from an arbitrary seed, or analyze_codebase_impact for file-level import impact. |
get_knowledge_graph | Knowledge graph traversal | Traverse the knowledge graph from a seed component or page. Returns { nodes: [{ id, label, node_type }], edges: [{ source_node_id, target_node_id, edge_type }] } within a depth budget (default 2, max 4 hops). Read-only. Use to see how a component connects to the rest of the app; use get_blast_radius for a bug’s impact area, or get_graph_neighborhood for a tighter BFS around one node. |
run_nl_query | Ask your data (NL → SQL) | Answer a natural-language question about your project data by generating and running a read-only SQL query (no privileged schemas, rate-limited to 60/hour). Returns { sql, rows }. Use for ad-hoc analytics (“which components had the most critical bugs this week?”); use get_recent_reports/search_reports for plain report lookups, or search_mushi_docs for documentation questions. |
get_inventory | Inventory snapshot | Return the current inventory.yaml snapshot for a project: latest ingest, validation errors, and a per-action status summary. Returns { snapshot, validationErrors, actions: [{ id, status }] }. Requires the inventory_v2 plan. Read-only. Use for the full current state; use diff_inventory to compare two commits, or list_gate_findings for the latest gate results. |
diff_inventory | Inventory diff | Diff two ingested inventory commits (fromSha to toSha): added/removed nodes and edges. Returns { added, removed, changed }. Requires inventory_v2. Read-only. Use before merging a PR that touches inventory.yaml to see what changed; use get_inventory for the current snapshot. |
list_gate_findings | Gate findings | List recent inventory gate runs and their findings for a project, newest first. Returns { runs: [{ id, gate, status, findings_count, … }], findings: [{ severity, rule_id, message, file_path, node_id, … }] }. Filter by gate (dead_handler | mock_leak | api_contract | crawl | status_claim | spec_drift | orphan_endpoint | unknown_call | schema_drift | code_health | design_drift | ci_drift | deploy_drift | env_drift | radar | portfolio_radar | portfolio_radar_ci | store_review) or finding severity (info | warn | error). The *_drift gates are the App Recipe checks: design_drift is code that drifts off the design tokens, ci_drift / deploy_drift / env_drift are CI, deploy and env vars that drift from the recipe; radar is the Mushi setup checks (a rejected provider key, no spend cap or AI budget, a webhook that never delivered, a stale code index), each with a suggested_fix (a spend-cap fix is applied in the console by a signed-in project admin, not through an API key); portfolio_radar / portfolio_radar_ci / store_review are the app hole checks (prefer get_radar). Available on every plan. Read-only. Use to see which CI gates failed on the last crawl; use diff_inventory to compare two commits, or get_inventory for the full snapshot. |
get_app_recipe | App recipe | Return the App Recipe for a project: one card per element (schema, design, routes, gates, ci, deploy, env, integrations), each with a state, a plain-English reason, key facts, a findings count and console links, plus the worst state overall and the mushi.recipe.json manifest status. Every element is exactly one of ok | drift | unknown | not_connected | error. unknown means configured but not observed recently and never means healthy; not_connected means nothing is configured. Returns { projectId, worst, elements: { <element>: { state, reason, facts, findingsCount, lastCheckedAt, links } }, manifest, snapshotHash }. Read-only. Use to see how the app is put together and which part is drifting; use get_design_tokens for the token values, get_design_deviance for code that drifts off them, or list_gate_findings for gate detail. |
get_design_tokens | Design tokens | Return the app’s normalized design tokens (DTCG: path, type, resolved value, hex / px, alias, CSS var, TS and RN names, description, defining file) for the active token set, plus nameMap (CSS var or TS name → token path). This is the tool that makes a fix use the app’s tokens instead of hard-coded literals: look up the token for a colour, spacing, radius or font before writing one. Optional filters: group (first path segment, e.g. color, space), type (color | dimension | fontFamily | …), direction (a named token set instead of the active one). Returns { projectId, set, tokens, nameMap, total }; at most 500 tokens. Read-only. Use get_design_deviance to see where code drifts off these tokens, or get_app_recipe for the overall state. |
get_design_deviance | Design deviance | Return how far the code drifts off the design system: the latest 0–100 deviance score (lower is better; null means not scored yet), its per-rule breakdown, the score trend, a scan still running if any, the top findings (file, line, literal value, rule, and the nearest token to use instead), and the active rules (off_token_color, off_token_font, off_scale_spacing, off_scale_radius, contrast_below_aa, raw_interactive_element). Optional limit: findings to return (1–200, default 25). Returns { projectId, latest, running, trend, findings, rules }. Read-only. Use to find and fix off-token code; use get_design_tokens for the full token list. |
get_portfolio | Portfolio — every app at once | Return every project in one organization as a card: the worst App Recipe state (ok | drift | unknown | not_connected | error; unknown and not_connected never mean healthy), open reports, the latest release, the Mushi SDK version against the latest release of the same package, the hole-check (radar) status with open findings by severity (never_run means not checked yet), and the 30-day LLM spend Mushi itself used. Optional organizationId (UUID); omitted, the only organization of the key owner is used, and a 400 ORG_REQUIRED lists the choices when there are several. Needs an account-level key; a project-bound key gets 403. Returns { organizationId, organizationName, cards, totalProjects, repeatedGroups, holes, readErrors }. A read that failed or was cut short is listed in readErrors and in the unreadable list of each card: those columns are unknown, never zero, “no cap” or “none yet” (holes is null when the integrations could not be read). Read-only. Use list_portfolio_findings for the problems open in two or more apps. |
list_portfolio_findings | Portfolio findings — fix once | Return what to fix across the apps of one organization: groups of the same finding rule open in two or more projects (rule, gate, highest severity, affected projectIds, a sample message and one paste-ready fix prompt), the Mushi SDK version per project and package (current | behind | unknown), and integrations most sibling projects have but one lacks. Open means the latest completed gate run per project and gate, not allowlisted; info findings are left out. Optional organizationId as for get_portfolio. Needs an account-level key. Returns { organizationId, groups, sdkSkew, holes, crossProject, readErrors }; a part named in readErrors is unknown, not empty. Read-only. Fix a group repo by repo with list_gate_findings in each project. |
get_recipe_drift | Recipe drift | Return what drifted from the app recipe, with a fix for each: CI workflows (no concurrency or timeout, macOS on every run, long artifact retention, crons more than daily, the default branch red), deploys (a merged fix not live yet, a failed version probe, web and mobile on different versions), env names declared but missing in CI, migrations in the repo but not applied, and off-token design values. For each gate it says when it last ran (never_run means not checked, never healthy). Returns { projectId, gates: { <gate>: { status, checkedAt, commitSha } }, findings: [{ gate, ruleId, severity, message, filePath, line, suggestedFix }] }. Read-only. Mushi never runs DDL or edits workflows: apply schema and CI fixes from your editor. |
list_connectors | Connectors | List the sources connected to an organization: each connector instance with its kind, status (connected | not_connected | blocked | error; blocked means an outside party refuses, for example an App Store agreement not accepted), the scopes it was granted, enabled capabilities and the projects it is bound to, plus the kinds that can be added and those still planned. Never returns credentials. Optional organizationId; account-level key needed. Returns { organizationId, available, planned, instances, legacy }. Read-only. |
get_store_status | Store review status | Return the latest store review of an app: listing text in the repo vs what is live on the App Store and Google Play (listing_drift, a language out of sync, store length limits), listing claims checked against the code (listing_claim_contradicts_code: for example “never leaves your phone” while the code uploads, or “open source” for a private repo), privacy labels vs data-collecting SDKs, iOS screenshots that look Android-shaped or older than recent releases, and a pre-submission checklist with a risk per item. Each result is ok | finding | unknown (not checked, never healthy). This is a check against the code, not legal advice. status never_run means it has not run yet; it runs from the console. Returns { projectId, checkedAt, status, results, checklist, findings }. Read-only. |
get_radar | Hole checks (radar) | Return the hole checks that catch a problem before a user hits it: store names that differ between the App Store and Google Play, a store listing missing a language, a domain or HTTPS certificate about to expire, missing security headers, a broken privacy link, storage rows deleted with SQL (files left behind and billed), and an Android target SDK or iOS build that the stores will refuse. scope “project” (default; projectId optional) returns every check with state ok | finding | unknown | error, a plain-English reason, and each finding with its fix; unknown means not checked and never means healthy. scope “organization” (organizationId optional, account-level key) returns the open findings of every app. Read-only. To run the checks again, use the console Recipe page. |
get_release_calendar | Release calendar | Return the release calendar of one organization: per app, what is live, the fixes merged since (waiting to ship) and the store state, plus a suggested batch of apps to release now versus next that respects the estimated CI minutes of each build. Mushi only proposes the batch; your CI builds and submits. Optional organizationId (UUID); omitted, the only organization of the key owner is used, and a 400 ORG_REQUIRED lists the choices when there are several. Needs an account-level key; a project-bound key gets 403. Returns { rows, batchSuggestion, note }. Read-only. |
get_code_health | Code health | Return the code health your CI pushed for one project: files over the size budget (god files) from the latest code_health run, each with severity, file, line, message and suggested fix, the bundle-size and largest-file trends, and a summary { error_count, warn_count, max_loc, latest_bundle_kb }. latestRunAt null means CI has never pushed (add MUSHI_INGEST_KEY to CI). Optional projectId and days (trend window, 1–365, default 30); a project-bound key reads its own project, an account-level key must pass projectId (400 PROJECT_REQUIRED otherwise). Returns { trends, godFiles, latestRunAt, latestRunStatus, summary }. Read-only. Use explain_finding with a god-file id for its fix; split the file before adding to it. |
explain_finding | Explain one finding | Explain one gate finding by its id (from list_gate_findings, get_radar, get_recipe_drift, get_code_health, get_store_status or the console): which check raised it and what that check is for, the rule, why it fired (reason), the file, line and column or the target it is about, the fix in one sentence (fix.text, with fix.kind, fix.command, fix.consolePath and the stored fix object in fix.detail), and whether it is still open: state open (in the latest run of that check, the latest run found the same problem in the same file or target, or no finished run has looked again yet), not_in_latest_run (the latest run checked that rule clean and no longer has it: fixed or moved), unknown (the latest run could not confirm a fix: it errored or skipped, stored only part of its findings, did not run or could not decide the rule, or read only part of the project; stateReason says which) or allowlisted. The latest run is the newest one that looked at the same thing: a design server scan is compared only with server scans and a CI push only with CI pushes, and a run scoped to another story is skipped. Treat unknown as still open. A finding in a project the key cannot reach is a 404. Returns { id, projectId, gate, gateLabel, gateMeaning, ruleId, rule, severity, reason, fix, location, state, stateReason, run, latestRun }. Read-only. |
get_auto_release_status | Auto-release blocker | Return the automatic release draft that is blocking auto-release for one project, if any. Only one automatic draft can exist at a time, so a draft whose publish failed stops every later automatic release until a person publishes or deletes it (mushi releases publish / delete, or the console Releases page). Optional projectId (defaults to the configured project). Returns { blockingDraft: { id, version, createdAt, autoSource, stale } | null }. Read-only. |
get_design_settings | Design score actions | Return what the design deviance score may do on its own for one project: threshold (0–100; the actions fire above it), failCi (mushi recipe check —push fails CI above it), autofix (new warn/error findings above it dispatch a fix) and autofixEnabled (the project auto-fix switch, without which the design auto-fix does nothing), plus canEdit. Optional projectId. Read-only. |
get_recipe_sources | Recipe source files | Return the repo files a recipe change may edit for one part of the recipe: element gates (mushi.recipe.json budgets and cadence), env (.env.example declarations) or routes (the inventory file). Each file has { path, exists, content, sha, writable, reason }, read from the default branch head; a file over 512 KB or one containing something shaped like a secret has content null. Pass each sha as baseSha to propose_recipe_change so a file that changed since is refused. Optional projectId. Returns { ok, element, branch, headSha, files } or { ok: false, reason }. Read-only. |
get_recipe_change | Recipe change status | Return one recipe change job by jobId (the jobId propose_recipe_change returned): { id, element, status, pr_url, pr_number, branch, error, batch_id, created_at, started_at, finished_at }. status moves queued → running → pr_opened, or ends rejected or failed with the reason in error; a job stuck past its deadline reads as failed. Optional projectId. Read-only. |
get_store_reviews | Store reviews as reports | Return the store review intake of one project: settings { enabled, maxRating, lastPulledAt, lastStatus, lastError }, the App Store and Google Play sources bound through connectors (connected false when the stored key cannot be read), the 20 reviews seen most recently { store, reviewId, rating, reportId, reviewCreatedAt, seenAt } (reportId set when the review was filed as a report), and canManage / canPull for the caller. Off by default. Optional projectId. Read-only. |
get_accounts_register | Accounts register | Return the accounts and resilience register of one organization: the accounts recorded (provider, name, owner email, two-factor declared, recovery contact, admin count, auto-renew), the domains the caller’s apps use with their declared auto-renew, and the open rules (account_single_owner: one person and no recovery contact; registrar_autorenew_off). Names and contacts only, never secrets. canEdit says whether the caller (or the key owner) may change it. Optional organizationId; needs an account-level key. Returns { organizationId, canEdit, accounts, domains, findings }. Read-only. |
get_spend_ledger | Spend ledger | Return the 30-day spend ledger of one organization, per app: Mushi LLM spend, provider AI spend from llm_usage connectors, estimated CI cost, Supabase, and imported bills, with totals, the AI spend not bound to an app, whether every source was read (complete), and the 10 latest bill imports. Optional organizationId; needs an account-level key. Returns { organizationId, from, to, days, apps, totals, unattributedProviderUsd, complete, imports }. Read-only. |
get_graph_neighborhood | Graph neighborhood | Return the BFS neighborhood around one graph node by id or label: { nodes: [{ id, label, node_type }], edges: [{ source_node_id, target_node_id, edge_type }] } within a depth budget (default 2, max 4). Read-only. Tuned for “what touches this action?”; use get_knowledge_graph to traverse from a component seed, or get_graph_node for a single node’s row. |
get_graph_node | Graph node detail | Fetch one knowledge-graph node row by id. Returns { node: { id, node_type, label, metadata } } including the v2 derived status on Action nodes (ok | stale | broken). Read-only. Use to inspect a single node’s status; use get_graph_neighborhood to see what connects to it. |
suggest_fix | Suggested fix (from triage) | Return the Stage-2 suggested-fix slice for one report: root cause, suggested fix, repro steps, summary, and component — faster than get_report_detail when you only need the human-readable hint. Returns { reportId, rootCause, suggestedFix, reproductionSteps, summary, component }. Read-only; reads the existing classification (run triage_issue first if unclassified). Use for a quick “what should we try?”; use get_fix_context for the full paste-ready bundle. |
diagnose_setup | Unified setup diagnose | Diagnose Mushi setup health and return the single best next action. mode=full (default) runs both SDK-ingest and fix-dispatch preflight checks; mode=ingest runs ingest checks only (project exists, active API key, SDK heartbeat, at least one report); mode=dispatch runs dispatch readiness only (GitHub connected, codebase indexed, LLM key present, autofix enabled). Returns { ready, steps: [{ label, complete, required, hint }], nextAction }. Read-only. The one setup-diagnosis entry point — use this instead of separate connection/ingest checks. |
check_sdk_version | Check SDK freshness | Compare a published @mushi-mushi/* package version against the catalog (GET /v1/sdk/latest-version). Returns { package, current, latest, outdated } and, when outdated, suggestedActions (Sentry-style, max 1) pointing at search_mushi_docs plus the mushi-sdk-upgrade skill. Read-only. Use when Dependabot or mushi upgrade —check reports a drift, or before dispatching a fix that assumes a current SDK. Does not bump the pin — that stays a human/Dependabot change. |
search_mushi_docs | Search Mushi documentation | Search the official Mushi documentation (guides, MCP setup, inventory, QA, skills) by keyword — titles, section headings and summaries are indexed. Returns ranked { results: [{ title, url, excerpt, score }] }. Read-only; works without an API key. Use before guessing API shapes, tool names, or RPC names, then get_mushi_doc to read a page; use run_nl_query for questions about your own project data, not the docs. |
get_mushi_doc | Read a Mushi docs page | Fetch one official Mushi docs page as Markdown, by a url from search_mushi_docs or a route such as “/quickstart/mcp”. Returns { title, url, markdown, truncated }; markdown is capped at 8,000 characters and says where to read the rest. Only indexed docs pages resolve. Read-only; works without an API key. Use after search_mushi_docs when an excerpt is not enough. |
list_top_contributors | Top contributors leaderboard | Return the top N contributors for the organization, ranked by points in a time window (30d | 90d | all). Each row includes display name, tier, total points, report count, and anti-fraud flag. Use this to identify your most engaged power users, write them a thank-you message, or decide who deserves a bonus. |
list_projects | List accessible projects | List all Mushi projects accessible to this API key. For project-scoped keys returns a single-item list; for org-scoped keys (account mode) returns every project owned by this account. Call this first when MUSHI_PROJECT_ID is not configured — use the returned id with subsequent tool calls. If multiple projects are returned, pass the target projectId explicitly to project-scoped tools. Multi-project tip: run mushi setup --all-projects in your terminal to create one named MCP server entry per project in .cursor/mcp.json. |
get_account_overview | Account overview — all projects | Return an enriched summary of every Mushi project accessible to this API key: id, name, recent report count (last 30 days), number of connected MCP keys, and last-seen heartbeat timestamp. For project-scoped keys this is a one-item list; for org-scoped (account) keys it lists every owned project. Also includes toolCount, resourceCount, promptCount so agents know how many tools are available. Call this at the start of a multi-repo or multi-app triage session to orient yourself. |
get_project_context | Project context snapshot | Return a rich context snapshot for a project: name, repo URL, SDK heartbeat, ingest status, open report count, autofix readiness, your LLM key config, plan tier, and active integration health. Equivalent to a merged preflight + activation + settings read. Agents should call this at the start of a review session to orient themselves. |
get_pipeline_logs | Recent pipeline logs | Pull recent log entries from the Mushi pipeline services: fix-worker, qa-story-runner, pipeline, or all. Accepts projectId, service, since (ISO-8601), limit (max 200), and level (info | warn | error | fatal) filters. Returns structured log rows with timestamp, level, service, message, and a trace_id/report_id when available. Use this when a fix failed, a QA story keeps erroring, or an ingest pipeline went silent. |
get_report_evidence | Bug report evidence | Return the full evidence package for a single bug report covering all three observability pillars: (1) LOGS — console_logs (error/warn/info/debug entries with timestamps), breadcrumbs (SDK ring buffer: navigation, clicks, network, lifecycle events with category/level), repro_timeline (merged SDK event stream: route/click/request/log/screen), and the reporter’s own comments thread; (2) TRACES — network_requests (SDK-captured fetch/XHR with method/status/duration/traceId), backend_spans (server-side spans joined by W3C trace_id: name/duration_ms/parentSpanId/status), and Sentry trace correlation IDs (sentry_trace_id, sentry_event_id) for deeplinks; (3) METRICS — performance_metrics (Web Vitals snapshot: LCP/CLS/INP/TTFB/FCP + INP attribution + page timing + connection info), anomalies (statistical provenance when auto-filed by CI metric regression: baseline_mean/std, score in σ, threshold); plus screenshot_url, browser environment (user agent, URL, viewport, SDK version), and tags. Reporter identifiers (session id, end-user id) are never returned. This is the same data an engineer would collect for a root-cause investigation. Faster than calling get_report_detail + report timeline separately. |
triage_issue | Triage issue end-to-end | Read-only combined tool: merges report detail, the reporter thread, similar bugs (matched on the report summary), the fix context (paste-ready fix prompt, repro steps, root cause), the blast radius of the inventory action the report is filed against, and recent pipeline warnings into a single structured review packet. Returns the packet plus prioritised recommended_actions, partial_errors for any source that failed, and notes for any source that does not apply (e.g. no blast radius when the report is not anchored to an inventory action). Equivalent to a Sentry “Analyze with Seer” flow grounded in user-felt reports. Pass reportId to kick off review. Call this before dispatch_fix. |
triage_next_steps | What should I work on now? | Prioritised “do this next” list for the project: blocked auto-fixes first (with the unblock action), then reporters waiting for an answer (they replied in the in-app thread since you last looked), then in-flight fixes to shepherd to merge, then user-felt classified reports by severity, with robot/cron chores (dependency bumps) last. Returns { steps: [{ priority, action, reason, tool, args }], summary }. Read-only. Call this first when the user asks “what needs my attention / what should I triage or fix”. |
query_lessons | Query lessons for diff context | Retrieve the learning rules (“lessons”) most relevant to a given code diff or PR context, packed within a token budget. Uses bi-encoder retrieval + severity-weighted scoring; pass the diff/description as diffText and a maxTokens budget (default 3000). Returns ranked { lessons: [{ title, rule, severity }] }. Read-only. Use before writing a fix or opening a PR; use list_lessons to browse all lessons unfiltered. |
list_lessons | List project lessons | List promoted learning rules (“lessons”) for the current project, highest-frequency first. Returns { lessons: [{ id, rule_text, severity, frequency, anti_pattern, … }] }. Read-only. Use to browse the full catalog of encoded heuristics; use query_lessons to retrieve only lessons relevant to a specific diff or PR within a token budget. |
activation_status | Activation cockpit status | Return the unified activation posture — SDK heartbeat, ingested reports, GitHub, MCP readiness, QA stories, and the next best action. Read this before guessing which onboarding step is blocking the user. Also available as the mushi://activation resource for resource-reader clients. Returns { sdkActive, reportsIngested, githubConnected, mcpConnected, qaStoriesCreated, nextBestAction }. |
query_funnel | Ordered funnel over product events | Where do users drop off? Ordered funnel over Mushi.track() events for this project. Pass 2–8 step event names in order (e.g. [“landing_view”, “signup_completed”, “first_report_received”]); each step counts distinct users who did the previous step then this one within stepWindow (default 7d), over the trailing windowDays (default 30). Optional breakdown property (e.g. “utm_source”, “$surface”) splits every step. Returns { steps: [{ name, entered, converted, pct, median_secs }], breakdown: [{ value, entered, steps }] } (pct is conversion from step 1; breakdown is empty unless requested). Read-only. Use to find the biggest drop-off before changing onboarding; use get_product_events_summary to discover event names, or get_user_paths to see what users did after a step. |
get_product_events_summary | Product events summary | Summarise the Mushi.track() product events this project received in the trailing windowDays (default 30): event names with counts and distinct users, daily volume, and top properties. Returns { window_days, events_total, persons, identified, anonymous, events_per_day: [{ day, count }], top_events: [{ name, count, persons }] }. Read-only. Use first to learn which event names exist before calling query_funnel or get_user_paths; use run_nl_query for ad-hoc SQL over the same rows. |
get_user_paths | Paths users take after an event | What did users do next? Rank the events users fired immediately after fromEvent within the trailing windowDays (default 30), most common first, up to limit rows (default 20, max 50). Returns { from_event, total, next: [{ name, count, pct }] }. Read-only. Use to see where users go after a step instead of guessing the funnel order; use query_funnel once you know the ordered steps, or get_product_events_summary for event names. |
get_map_run_status | Story map run status | Poll the status and results of a story_map_run started by map_user_stories. Returns { status: pending|running|completed|failed, pages_crawled, proposal_id (once done), cursor_pr_url (if Cursor Cloud refined the draft) }. Read-only. Use to know when a crawl has finished and which inventory_proposals row to review next. |
list_byok_keys | List your API key pool | List the project’s BYOK API keys grouped by provider (anthropic | openai | openrouter | firecrawl | browserbase | cursor | supabase). Returns pooled { keys: [{ id, provider_slug, label, priority, status, cooldown_until, test_status, key_hint, base_url, last_tested_at, last_used_at }] } plus read-only { legacyKeys } metadata for credentials saved before the pooled lifecycle — never the raw secret. Read-only. Use to see which keys are validated, active, pending, legacy, or rate-limited; use add_byok_key to add one. |
list_pending_review_stories | List QA stories pending review | List auto-generated QA/TDD stories in approval_status=pending_review — the queue waiting for human sign-off before they run on schedule. Returns { stories: [{ id, title, source, target_url, created_at }] }. Read-only. Use to find what needs review today; then approve_qa_story to approve or reject each. |
list_reporter_outbox | List held reporter updates | List pipeline messages waiting for review before they reach reporters (projects in review mode hold “fix in progress”, “fixed”, “shipped in vX” and “closed” messages). Each row has { id, report_id, report_title, notification_type, text, body_override, created_at }; text is exactly what the reporter will see. Read-only. Use before release_reporter_update; an empty list means nothing is waiting (or the project sends updates automatically). |
get_two_way_comms_health | Two-way communication health | Summarize SDK ↔ admin two-way reporter health for a host app: last SDK heartbeat, app version/platform last seen, unread reporter messages, recent reporter replies, and pending QA/TDD follow-ups. Use after wiring @mushi-mushi/web in a Vite/Capacitor app to confirm reports land in the console and admin/MCP replies reach the in-app widget. |
list_qa_story_runs | Recent QA story runs | Return the most recent runs for a given QA story, newest first. Each row includes status (passed/failed/error/running), latency_ms, created_at, error_message headline, and assertion_failures (up to 10). Use this to understand whether a story is currently healthy, what the last failure was, and whether a manual run has completed. |
get_qa_story_run | QA story run detail | Fetch the full detail for a single qa_story_run: status, error_message, assertion_failures, latency_ms, provider_session_url (Browserbase replay link when available), and screenshot URLs from qa_story_evidence. Use this to drill into a specific failing run and understand the exact error before deciding whether to improve the story script or fix the app. |
get_usage | Usage & billing summary | Read-only diagnoses quota and billing summary for the current project: diagnoses used / limit / percentage, spend cap, period start/end, plan name, and whether the project is approaching or over its quota. Use this to answer “how many diagnoses do I have left?” or “am I close to my spend cap?”. |
list_skills | List agent skills | List the agent skills in the catalog, optionally filtered by category or search text. Returns { skills: [{ slug, title, description, category, chain_slugs }] }. Read-only. Use to find the right skill slug before start_skill_pipeline; use get_skill to read one skill’s full instructions. |
get_skill | Get skill detail | Fetch one agent skill by slug, including the complete SKILL.md body and the resolved chain of sub-skills. Returns { slug, title, body, chain: [{ slug, title }] }. Read-only. Use to read what a skill instructs before executing a pipeline step; use list_skills to discover slugs. |
get_pipeline_run | Get pipeline run detail | Fetch a skill pipeline run by id: { status, context_packet, steps: [{ index, slug, status }] }. Read-only. Use to retrieve the context_packet when a pipeline was started from the console or another agent; then checkin_pipeline_step as you complete each step. Use start_skill_pipeline to begin a new run. |
get_backend_health | Get backend health for a project | Return the current backend health state for a linked Supabase project: table list (with RLS enabled status), recent API and Postgres error logs, and DB advisor findings. Uses the read-only Supabase MCP client via the stored PAT. Returns { tables, logs, advisors, projectRef } when the backend is linked, or { reason: “no_supabase_pat” | “no_project_ref” } when it is not configured. This is the read-only fast path — use run_fullstack_audit for the full scorecard including gate results. |
use_mushi | Mushi — where to start | CALL THIS FIRST if you are new to this Mushi project or unsure which tool to use. Pass your intent as a short natural-language phrase (“fix the top bug”, “check what I should work on”, “run QA tests”, “set up Mushi”, …). Returns: (1) a curated list of the 5–12 tool names most relevant to that intent, (2) a one-paragraph orientation to the Mushi project and dashboard state, and (3) the single recommended first tool to call. Only tools this connection exposes are recommended; relevant tools hidden by the active feature groups are named with how to enable them. Avoids loading the full tool catalog into context when only a small subset is needed. Read-only; does not call any downstream tools itself. |
get_file_summary | Plain-English file summary | Return a plain-English summary of one indexed file or symbol (lazily generated on first call, then cached until content_hash changes on re-index). Returns { path, summary, symbols }. Requires codebase indexing. Read-only. Use to understand a single file fast; use ask_codebase for cross-file questions, or get_codebase_tour for an onboarding walkthrough. |
get_codebase_tour | Guided codebase tour | Return a dependency-ordered onboarding tour of the repo (~6-10 stops); each stop lists node ids, file paths, architectural layer, and why it matters. Returns { stops: [{ title, paths, layer, rationale }] }. Cached per index fingerprint. Requires codebase indexing. Read-only. Use to get oriented in an unfamiliar repo; use get_codebase_domains for a business-domain map, or get_file_summary for one file. |
search_codebase | Semantic codebase search | Search the indexed repo by plain-English meaning via embeddings. Returns { results: [{ file_path, line_start, line_end, content_preview, similarity, … }], query, mode } ordered by similarity. Requires codebase indexing enabled. Read-only. Use to locate where something lives (“where do we verify webhooks?”); use ask_codebase for a synthesized answer with citations, or analyze_codebase_impact to find dependents of a file. |
get_codebase_domains | Business domain map | Extract the business domains, flows, and steps in the repo, each mapped to the file paths that implement it. Returns { domains: [{ name, flows: [{ name, steps, paths }] }] }. Cached per index fingerprint. Requires codebase indexing. Read-only. Use to see what the app does at a product level; use get_codebase_tour for a dependency-ordered code walkthrough instead. |
analyze_codebase_impact | Diff impact analysis | Find files that depend on a set of changed paths by walking the reverse import graph. Source paths from: manual list, last push, a GitHub compare range, or a fix PR’s files. Returns { changed_paths, source, affected_file_paths, affected_node_ids, meta }. Requires codebase indexing. Read-only. Use to gauge a diff’s blast radius before merging; use get_blast_radius for a bug’s component impact, or search_codebase to locate files. |
analyze_wiki_knowledge | Wiki knowledge graph | Return the wiki/docs knowledge-graph nodes and their sources for the project. Returns { nodes: [{ id, label, source_url }], sources }. Read-only. Use to see what doc entities exist; pass include_wiki=true to ask_codebase to merge this corpus into a grounded answer. |
get_repo_digest | Repo digest (paste-ready code) | Return the connected GitHub repo as one paste-ready text digest at a pinned commit: a directory tree plus file contents, ranked README → manifests → entry points → source → tests and cut to a token budget (budgetTokens, default 50,000, max 200,000; counts are estimates). Scope it to a folder (path) or to one bug (reportId: the report’s stack-frame files, fix files and related code first, then the files that import them). Sensitive files (.env, keys) are never included, and a file that looks like it holds a secret is replaced with a notice. Returns { sha, ref, total_tokens, budget_tokens, files: [{ path, tokens, truncated }], dropped_counts, redacted, scope, text }. Works without codebase indexing. Read-only. Use to hand yourself the code around a bug before fixing it; use get_fix_context for the diagnosis, or search_codebase to find one thing. |
get_repo_diagram | Architecture diagram | Return the latest architecture diagram of the connected repo: its parts (nodes with a label, group, repo path and one-line description), how they connect (edges), the commit it was drawn at, and whether a public page is published for it (url, outdated, indexable). diagram is null when none has been drawn yet: one is drawn from the console Repo page (one AI call per commit). overlay: true also returns the open bug reports and code findings placed on each part (by stack frames, fix files and finding paths). Optional projectId. Returns { diagram, publication } and, with overlay, overlay: { diagram_id, nodes, unplaced, frames_matched, considered } (null while there is no diagram). Works without codebase indexing. Read-only. Use to see where a bug sits in the app before reading code; use get_repo_digest for the code itself. |
Write tools (mcp:write)
| Tool | Title | Description |
|---|---|---|
propose_recipe_change | Propose a recipe change (draft PR) | Propose edits to files the app recipe allows (design tokens, budgets in mushi.recipe.json, .env.example declarations, store listing text under store.listingDir) as ONE draft pull request. Dry run by default: returns the diff of each file, with the baseSha it was taken against, and any path that is not writable (workflows, env files, lockfiles, generated exports and migrations never are) or whose new content would not parse (mushi.recipe.json, the inventory). Send each baseSha back on the confirm so a file that changed since is refused. confirm: true opens the draft PR; it stays a draft so the repo CI does not run until the owner marks it ready, and nothing is merged or published. Confirm with the user before confirm: true. Returns { dryRun, files, denied } or { jobId, status, prUrl }. Write. |
propose_portfolio_change | Fix once across apps (draft PRs) | Propose the same kind of recipe edit in up to 10 repos of one organization, one draft PR per repo with a shared batch id. Dry run by default (the diff and denied paths of each repo); confirm: true opens the drafts. One repo failing never rolls back the others; each result says what happened. Needs an account-level key. Confirm with the user before confirm: true. Returns { dryRun, plans } or { batchId, opened, results }. Write. |
request_connector_action | Request a store action (needs approval) | Ask for one connector action, for example set_rollout or promote_track on a Google Play connector. This only creates a request: nothing runs until a team owner or admin approves it in the console and then runs it there. An API key or this tool can never approve or run it. The approval binds the exact payload and expires after an hour. Confirm with the user first. Returns { id, status: “pending_approval”, payloadSha256 }. Write. |
run_radar | Run the hole checks now | Start the hole checks (radar) for one project now instead of waiting for the daily run: store names, listing languages, domain and certificate expiry, security headers, the privacy link, and the connector-backed checks. The checks run in the background; poll get_radar until checkedAt changes. At most one run per project every 10 minutes (429 RATE_LIMITED with Retry-After otherwise). Optional projectId (defaults to the server-configured project). Returns { started, projectId, startedAt }. Write: it records a new gate run; nothing in your app or repo changes. |
refresh_recipe | Refresh the app recipe | Read mushi.recipe.json and the design-token files from the connected repo again and store a new recipe snapshot, instead of waiting for the daily refresh. At most once per project every 5 minutes (429 RATE_LIMITED otherwise). Optional projectId. Returns { ok, state, reason, snapshotId, tokensHash, manifestPresent, tokenCount, issues } where state is ok | drift | unknown | not_connected | error and issues lists manifest problems with their path. Write: it stores a snapshot; nothing in the repo changes. Use after editing mushi.recipe.json or the tokens; then read get_app_recipe or get_design_tokens. |
run_design_deviance | Run the design deviance scan | Refresh the design tokens and start a new deviance scan of the repo (off-token colours, fonts, spacing, radius, contrast below AA, raw interactive elements). The scan reads up to 1,500 files in the background: the result is { refresh, run } with run.status “running” (poll get_design_deviance until running clears), or run null when the repo has no tokens to compare against (refresh says why). At most one scan per project every 5 minutes (429 RATE_LIMITED otherwise). Optional projectId. Write: it records a scan; nothing in the repo changes. |
run_store_review | Run the store review | Run the store review for one project now: listing text in the repo against what is live on the App Store and Google Play, listing claims against the code, privacy labels against data-collecting SDKs, screenshots, length limits and the pre-submission checklist. Each result is ok | finding | unknown (not checked, never healthy). This is a check against the code, not legal advice. At most one review per project every 30 minutes (429 RATE_LIMITED otherwise). Optional projectId. Returns { projectId, checkedAt, status, results, checklist, findings, note }; read it again later with get_store_status. Write: it records a gate run; nothing is submitted to a store. |
set_design_settings | Set design score actions | Change what the design deviance score may do for one project: threshold (0–100), failCi (true fails mushi recipe check --push above the threshold) and autofix. Send at least one. An API key can turn autofix off but never on: turning it on lets the project spend on fixes by itself, so it needs a signed-in owner or admin in the console (403 otherwise). Project owners and admins only. Optional projectId. Returns the saved settings. Write. |
pull_store_reviews | Pull store reviews now | Pull the latest App Store and Google Play reviews of one project now and file those at or under the star threshold as reports (source store_review), deduplicated against earlier pulls. Intake must be on (400 INTAKE_OFF otherwise), at most one pull every 10 minutes (429 RATE_LIMITED), and not for viewers. It spends the stored store keys read-only and files reports that are then classified. Optional projectId. Returns { status, filed, stores }. Write. |
set_store_review_intake | Set store review intake | Turn store reviews as reports on or off for one project and set the star threshold (maxRating 1–5: reviews at or under it are filed). enabled is required. An API key can turn intake off or change the threshold while it is on, but only a signed-in owner or admin can turn it on in the console (403 HUMAN_REQUIRED), because it decides that public reviews become reports. Project owners and admins only. Optional projectId. Returns the saved settings. Write. |
save_register_account | Save a register account | Record an account in the accounts register, or change one when id is given. provider is one of apple, google_play, aws, supabase, vercel, registrar, stripe, github, cloudflare, other; displayName is required on create. Optional ownerEmail, twoFactorDeclared, recoveryContact (a person, not a code), adminCount (1–100) and autoRenew; null clears a field. A value shaped like a key or token is refused (400 SECRET_DETECTED); the register keeps names and contacts only. A second account with the same provider and name is 409 ACCOUNT_EXISTS. Team owners and admins only; needs an account-level key. Returns { id }. Write. |
remove_register_account | Remove a register account | Remove one account from the accounts register by id (from get_accounts_register). It only deletes the register entry; nothing changes at the provider. Team owners and admins only; needs an account-level key. Confirm with the user first. Returns { deleted: true }. Write. |
set_domain_auto_renew | Declare domain auto-renew | Declare whether one domain renews automatically at its registrar: autoRenew true, false, or null for not known. The domain id comes from get_accounts_register; only a domain one of the caller’s apps uses can be changed (404 otherwise). It records what you declare and checks nothing at the registrar; false opens the registrar_autorenew_off rule. Team owners and admins only; needs an account-level key. Returns { id }. Write. |
import_spend_bill | Import a bill CSV | Import a vendor bill CSV into the spend ledger. vendor is vercel, aws, supabase or other; csv is the file content (FOCUS, AWS CUR or a plain date,service,cost CSV; at most 5 MB). projectId puts every row on one app; omit it to match each row’s app column to an app name or slug. A second import of the same days for the same vendor replaces them instead of adding. Optional filename and organizationId. Team owners and admins only; needs an account-level key. Returns { importId, format, rowsRead, rowsImported, rowsSkipped, skipReasons, unmatchedApps, totalUsd, periodStart, periodEnd }. Write. |
remove_spend_import | Remove a bill import | Remove one bill import from the spend ledger by importId (from get_spend_ledger imports). Its days go back to the next newest import of the same vendor that has them; a retry finishes a removal that failed half-way. Team owners and admins only; needs an account-level key. Confirm with the user first. Returns { importId, rowsRemoved, rowsRestored, restoredFrom }. Write. |
import_portfolio_resources | Import shared resources (CSV) | Record which accounts, domains, buckets or bundle ids your apps share, from a CSV with the columns kind, external_id, project (an app id, slug or name) and optionally role. At most 500 rows and 256 KB; each row is saved on its own, and refused rows are listed with their line number. Read the result with mushi portfolio resources or the console. Optional organizationId; team owners and admins only; needs an account-level key. Returns { imported, errorCount, errors, skippedOverLimit }. Write. |
submit_fix_result | Record a fix outcome | Record a fix outcome from an external agent (e.g. your own Cursor/Claude run): branch, PR URL, files changed, lines added/removed. Creates a fix_attempt row then patches it to completed and links it to the report. Returns { fixAttemptId }. Write; NOT idempotent — each call creates a new fix_attempt, so call once per PR. Use after you opened a PR outside Mushi; use dispatch_fix to have Mushi open the PR instead, or merge_fix once CI is green. |
dispatch_fix | Dispatch Mushi fix agent | Start a Mushi fix agent for a classified report; it writes a branch and opens a signed draft PR. Set agent=“cursor_cloud” to dispatch a Cursor Cloud Agent (default uses the in-repo worker). For a project with several linked repos, set targetRepoId (a project_repos.id) to choose the repo the PR opens against; omit it for the primary repo. Requires GitHub connected + an LLM key (run diagnose_setup mode=dispatch first). Returns { fixId, status } (fixId is the dispatch id; get_fix_timeline accepts it immediately); poll get_fix_timeline for progress and merge_fix when CI is green. Write; pass the same idempotencyKey to retry safely — without it each call starts a new attempt. Report must be classified — run triage_issue if not. |
trigger_judge | Run Sonnet-as-Judge | Queue the Sonnet-as-Judge to grade recent fix quality across accessible projects. Returns { dispatched: number } — one judge-batch job per project; scores land asynchronously in judge_results (read back with run_nl_query). Write; consumes LLM budget. Idempotent within a short window. Use before shipping to vet fix quality; use get_fix_timeline to inspect a single attempt instead. |
test_gen_from_report | Generate Playwright test from report | Generate a Playwright regression test from a classified report using your project LLM key, then open a draft GitHub PR with the spec. Requires the inventory_v2 plan plus GitHub and LLM keys configured. Returns { prUrl, prNumber, branch, path }. Write; consumes LLM budget; NOT idempotent — each call opens a new PR. Use to lock in a regression as an E2E test; use generate_tdd_from_story to build a test from a mapped user story instead. |
transition_status | Move report between states | Move a report to a new workflow state, enforcing the same transition rules as the admin UI. Valid targets: classified, grouped, fixing, fixed, verified, reopened, dismissed. When dismissing, closedReason (duplicate, not_reproducible, wont_fix, working_as_intended, spam) sets what the reporter is told — spam closes silently, and duplicate needs the report grouped under another one first; reporterMessage posts your note to the reporter verbatim. Returns { ok }. Write; idempotent (setting the current status is a no-op); rejects illegal transitions. Use to dismiss a duplicate or mark fixed; use merge_fix to mark fixed via a merged PR, or reopen_report for the reopened path. |
merge_fix | Merge fix PR | Squash-merge the GitHub PR for a fix attempt, mark the linked report fixed, and notify the reporter. Re-readies the PR first if it is still a draft. Returns { merged, reportStatus }. Write; destructive and irreversible from Mushi’s side — once GitHub merges into the target repo’s default branch there is no unmerge endpoint, only a manual revert PR outside this tool. Idempotent — re-running an already-merged attempt is a safe no-op. Prerequisite: CI green (check with refresh_ci); confirm the diff and CI status with the user before calling on a PR you have not reviewed. Use to ship a fix opened by dispatch_fix; use transition_status to change state without merging. |
refresh_ci | Refresh fix CI status | Re-poll GitHub for the latest check-run status of a fix attempt’s PR and persist it on the fix_attempt row (does not merge or mutate GitHub). Returns { check_run_status, check_run_conclusion, check_run_updated_at }. Write; idempotent. Use right before merge_fix to confirm CI is green; use get_fix_timeline for the full attempt lifecycle. |
reopen_report | Reopen report (operator) | Move a previously fixed/verified/dismissed report back to the reopened state for regression review, recording an operator note. Returns { report } with status=reopened. Write; idempotent — reopening an already-reopened report is a no-op. Use when a reporter says “still broken” after a fix shipped; use transition_status for any other state change. |
award_bonus_points | Award bonus points | Award ad-hoc bonus points (1-50000, positive only — there is no way to subtract via this tool) to a contributor by their external user id (as passed to Mushi.identify()). Points post immediately to their total and are audit-logged as bonus_manual. Destructive and effectively irreversible: there is no reversal endpoint, so confirm the amount and recipient with the user before calling. Tier re-evaluation (and any host-side reward_webhooks grant tied to crossing a threshold) is NOT immediate — it only runs on the contributor’s next tracked activity, not on this call. Requires mcp:write scope. Use this to thank a contributor who found a critical bug or to run a one-off promotional campaign. |
set_tier | Override contributor tier | Override a contributor’s tier by tier slug (e.g. “champion”), bypassing the normal points-threshold logic entirely. This is an admin escape hatch for manual promotions — normal tier transitions happen automatically via point thresholds instead. Destructive: it is a label-only override that does NOT replay the automatic tier-evaluation path, so any host_credit_payload grant (Stripe perk, badge, etc.) normally tied to reaching that tier via points will NOT fire — confirm with the user whether they also need the perk granted another way. The override persists until another set_tier call changes it; the prior override stays in the end_user_activity audit trail either way, logged as tier_override_manual. Requires mcp:write scope. |
import_sentry_issues | Import Sentry issues | Pull existing Sentry issues into Mushi’s report queue: by issueIds (numeric ids or short ids like WEB-12, at most 10) or by a Sentry search query (default is:unresolved) within the project’s configured Sentry project, limit 1-10. For a backlog, add sinceDays (1-90) and call again with cursor set to the returned nextCursor until it is null; sentryProject picks another of the project’s Sentry projects. Each issue goes through the same path as a Sentry webhook delivery: deduped per issue, linked, classified. An issue already linked to a report answers linked and is never reopened. Returns { items: [{ input, issueId, shortId, outcome, reportId, error? }], created, linked, failed, indexing, sentryProject, sentryProjects, nextCursor }. Write; idempotent; spends classification budget per new report. Needs the Sentry org slug, project slug and an auth token (event:read, project:read) in Integrations → Sentry. Use for issues that existed before the webhook was wired; then call triage_issue on a created report. |
map_user_stories | Map user stories from live app | Crawl a live application URL (Firecrawl/Browserbase) and have Claude draft an inventory.yaml of pages and user stories, written to an inventory_proposals row (source=live_crawl). Optionally dispatches a Cursor Cloud agent to refine the draft and open a PR. Returns { runId, status: “pending” } immediately — poll get_map_run_status. Write; consumes crawl + LLM budget; NOT idempotent. Use to bootstrap test coverage without hand-writing YAML; then generate_tdd_from_story per accepted story. |
generate_tdd_from_story | Generate TDD test from user story | Generate a full Playwright TypeScript test from a mapped user story id (from accepted inventory) using Claude, and insert a qa_stories row (source=test_gen_from_story). approval_status follows the project automation_mode (auto = enabled immediately; review/approve = pending_review). Optionally opens a draft GitHub PR. Returns { qaStoryId, prUrl, approvalStatus, needsHumanReview }. Write; consumes LLM budget; NOT idempotent. Run map_user_stories first; use test_gen_from_report to build a test from a bug report instead. |
improve_qa_story | Auto-improve a failing QA story | Analyze recently failed qa_story_runs and use Claude to write improved test scripts that address the failures. New tests are created with source=pdca, parent_story_id chained to the original, and approval gated by the original story’s automation_mode. Returns { improvedStoryIds }. Write; consumes LLM budget; NOT idempotent. Use to repair flaky/broken tests; use run_qa_story to re-run as-is, or list_qa_story_runs to inspect failures first. |
run_qa_story | Trigger a manual QA story run | Queue an immediate manual run for an enabled + approved qa_story (equivalent to “Run now” in the console). Returns { runId } right away; poll list_qa_story_runs or get_qa_story_run for progress and results. Write; NOT idempotent — each call creates a new run; returns 409 if the story is disabled or pending review. Use to verify a flow on demand; use improve_qa_story to repair a failing story. |
add_byok_key | Add an API key | Add and immediately validate a BYOK API key for anthropic | openai | openrouter | firecrawl | browserbase | cursor | supabase (a scoped, read-only Supabase access token, checked against the linked supabase_project_ref). The raw key is stored encrypted in Supabase Vault and never returned; failed probes remain quarantined. Optional baseUrl is accepted only for allow-listed OpenAI-compatible HTTPS providers. Write; NOT idempotent. |
test_byok_key | Test an API key | Re-test one pooled BYOK credential by key id. A successful provider probe activates the key; auth, quota, and network failures keep it out of the runtime pool. Returns the sanitized validation result and updated key metadata. Write; idempotent. |
remove_byok_key | Remove an API key | Permanently remove one pooled BYOK credential by key id from the authenticated project, including its Vault secret. Write; destructive; idempotent. |
approve_qa_story | Approve or reject a pending QA story | Approve or reject a qa_story currently in pending_review (pass approve=true|false and an optional note). Approved stories are enabled in the QA schedule immediately; rejected ones are disabled. Returns { id, approval_status }. Write; idempotent — re-approving an approved story is a no-op. Use to clear the review queue from list_pending_review_stories. |
reply_to_reporter | Reply to a reporter | Send a visible message to the end-user who filed a bug report. The reply appears in the in-app Mushi widget as an admin comment and creates an unread notification badge so the reporter sees it immediately. Use this to answer questions, request reproduction steps, or confirm a fix — without leaving the Cursor IDE. |
request_reporter_info | Ask the reporter a question | Ask the end-user who filed a report a question: it appears in their in-app “Your reports” thread, marks the report “Waiting on you”, and the waiting state clears when they answer (their reply reaches Slack and the console). Returns { comment_id, awaiting_reporter }. Write; messages a real end user and is NOT idempotent — each call posts another question, so confirm the wording with the user first. Fails with NO_REPORTER for reports that came from an integration. Use when you need reproduction details; use reply_to_reporter for a plain reply. |
release_reporter_update | Release or discard a held reporter update | Send (action=release, the default) or drop (action=discard) one held reporter message from list_reporter_outbox; bodyOverride replaces its text before sending. Returns { delivered, skipped, failed }. Write; messages a real end user — confirm with the user first. Idempotent in effect: a message that is no longer held returns CONFLICT instead of sending twice. |
test_notification_channel | Send a test notification | Send a test notification to a configured notification channel for the project. Supported channel kinds: “slack” (posts a test Block Kit message to the configured channel), “discord” (posts to the project discord_webhook_url). Returns ok=true if the message was accepted. Use this to verify the integration is working after setup or after changing credentials. |
start_skill_pipeline | Start a skill pipeline | Start a new skill pipeline run for a report. Pass rootSkillSlug and optionally reportId. Returns run_id, context_packet (full instructions + report context), and step list. Read the context_packet — it contains skill instructions plus full report context (repro steps, root cause, RAG files). After executing each step, call checkin_pipeline_step. The PM watching the console sees progress live. |
checkin_pipeline_step | Check in a pipeline step | Report the completion status of a pipeline step (passed, failed, running, or skipped). Optionally include notes, a PR URL, or the Cursor agentId. Updates the live React Flow canvas in the Mushi console so PMs see real-time progress. |
run_fullstack_audit | Run a full-stack health audit | Fan out a full-stack health audit for the current project: DB schema + advisors, API contract gate results (Gates 3–8), recent backend error logs, and RLS gap detection. Returns a PM-readable scorecard with severity-ranked findings and fix hints. Backend analysis needs supabase_project_ref set (Settings → General) and a scoped, read-only Supabase access token added (Settings → AI keys, slug: supabase). The audit completes synchronously in ~10 s. Triggers a background gate run for orphan_endpoint and unknown_call gates if they have not run today. |
ask_codebase | Ask about the indexed codebase | Answer a plain-English question about the connected repo, grounded on pgvector retrieval over project_codebase_files. Returns { answer, citations: [{ path, line }] }. Set include_wiki=true to merge docs/wiki knowledge. Requires codebase indexing + your Anthropic or OpenAI key; consumes LLM budget (write scope). Use for “how does X work?”; use search_codebase for raw file matches without synthesis, or get_file_summary for one file. |
Resources
| Name | URI | Description |
|---|---|---|
| project_dashboard | project://dashboard | Loop health snapshot — stage counts, bottleneck, recent activity (same payload the admin console polls). |
| project_stats | project://stats | Report counts, category breakdown, severity distribution. |
| project_settings | project://settings | Project configuration — autofix agent, plugins enabled, ontology, LLM budgets. |
| privacy_status | privacy://status | Returns the privacy posture for this project: storage region, LLM provider, whether your own LLM key is configured, data retention window, and last audit timestamp. Agents should read this before dispatching a fix to confirm that client data stays within the expected boundary. Reads as project data does not leave the project’s own LLM account when byok_configured=true. |
| evolution_history | evolution://history | Returns the project’s last 30 days of judge scores, prompt promotions, fixed-bug count, and lesson inductions. Agents can read this to see whether the loop is converging (rising judge scores, falling recurrence) or stalling (flat scores, same bugs re-appearing). Use before review to understand which bug classes the loop has already learned to handle, and which still need human attention. |
| activation_status | mushi://activation | Unified setup posture — SDK heartbeat, reports, GitHub, MCP readiness, QA stories, and the next best action. Agents should read this before guessing which onboarding step is blocking the user. |
| project_integration_health | project://integration-health | Live health status of every configured integration channel (Sentry, GitHub, LangFuse, PagerDuty, …). Check this before dispatching a fix to fail-fast on broken channels rather than burning LLM budget and discovering the failure mid-run. |
| inventory_current | inventory://current | Current inventory snapshot for the active project — all Action nodes with their spec contract (expected_outcome), build-gate status, linked reports, and fix attempts. Subscribe to this resource to receive notifications/resources/updated when the inventory is re-crawled. Orchestrators can use this to enumerate work items and pick the next Action to fix. |
Prompts
| Prompt | Description |
|---|---|
summarize_report_for_fix | Turn a Mushi report into a one-line root cause, smallest file set, repro steps, and blast-radius warnings. |
explain_judge_result | Turn raw Sonnet-as-Judge scores into ship / iterate / dismiss guidance. |
triage_next_steps | Five-item priority list drawn from the dashboard + recent classified queue. |
mushi_setup | Walk through activation status, integration health, and the single next command to unblock setup. |
Last updated on