Port mentra-console MCP incident tools to the Cloud V2 admin reports API - #3388
Port mentra-console MCP incident tools to the Cloud V2 admin reports API#3388PhilippeFerreiraDeSousa wants to merge 5 commits into
Conversation
The legacy server at cloud/packages/console-mcp reads V1 incidents via
GET /api/agent/incidents with X-Agent-Key, but the cloud/ tree is frozen
and V1 incidents are superseded by Cloud V2 reports. Recreate the MCP
server at cloud-v2/packages/console-mcp on the admin reports API:
- incident_list / incident_get / incident_get_logs become report_list /
report_get / report_get_logs against GET /api/admin/reports[/:id],
plus report_get_artifact for raw payloads (screenshots inline as MCP
image content, JSON/text inline as text, binaries by pointer to
scripts/fetch-incident-logs.sh)
- report_get_logs downloads every logs artifact ({entries: [...]}
bundles uploaded by phone/glasses), merges them oldest-first tagged
with the artifact source, and keeps the V1 level/grep/limit filters;
unreadable bundles degrade to a warning instead of failing the call
- auth mirrors the ported fetch-incident-logs.sh: Authorization: Bearer
MENTRA_ADMIN_TOKEN (org msk_ key allowlisted via
CLOUD_CORE_ADMIN_EMAILS, or a WorkOS admin access token), host from
MENTRA_CORE_URL or MENTRA_ENV=prod|staging|dev (default prod)
- short id prefixes resolve against the most recent 600 reports using
the before cursor; 401/403/404 map to actionable hints
- mentra://reports resources, debug-report prompt, run-mcp.sh launcher,
smoke test, and bun unit tests ported to the new shapes
The legacy package is left untouched (its V1 app/org/admin tools die
with the cloud/ tree); AGENTS.md now points V2 report triage at the new
package.
📋 PR Review Helper📱 Mobile App Build✅ Ready to test! (commit 🕶️ ASG Client Build⏳ Waiting for build... 🔀 Test Locallygh pr checkout 3388 |
![cursor[bot]](https://avatars.githubusercontent.com/in/1210556?s=60&v=4){kind=small}
![chatgpt-codex-connector[bot]](https://avatars.githubusercontent.com/in/1144995?s=60&v=4){kind=small}
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 23b720ed2a
ℹ️ About Codex in GitHub
Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you
- Open a pull request for review
- Mark a draft as ready
- Comment "@codex review".
If Codex has suggestions, it will comment; otherwise it will react with 👍.
Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".
… the MCP SDK
The mobile and sdk bun workspaces both glob ../cloud-v2/packages/*, so the
new console-mcp package is a member of four workspaces, not two. CI's
mobile frozen-lockfile check failed on the PR merge ref because
mobile/bun.lock (and next in line, sdk/bun.lock) never learned about the
package; regenerate both.
Since the admin console website landed on dev, cloud-v2's isolated
install links @modelcontextprotocol/sdk against zod@4 while this package
pinned zod@3, and typechecking the two zod identities through the SDK's
zod-compat layer explodes (TS2589). Depend on zod ^4.4.3 so the package
and the SDK share one zod everywhere; every schema helper used here is
unchanged in the v4 classic API.
Also read normalized {message} feedback for compact list summaries and
mark the bin entry executable.
Deploying mentra-live-ota-site with
|
| Latest commit: |
deaf666
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://4536d6e3.mentra-live-ota-site.pages.dev |
| Branch Preview URL: | https://claude-bold-agnesi-ea30ec.mentra-live-ota-site.pages.dev |
Deploying dev-augmentos-console with
|
| Latest commit: |
deaf666
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://0697b161.dev-augmentos-console.pages.dev |
| Branch Preview URL: | https://claude-bold-agnesi-ea30ec.dev-augmentos-console.pages.dev |
Deploying mentra-store-dev with
|
| Latest commit: |
deaf666
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://ebaa532c.augmentos-appstore-2.pages.dev |
| Branch Preview URL: | https://claude-bold-agnesi-ea30ec.augmentos-appstore-2.pages.dev |
Deploying prod-augmentos-account with
|
| Latest commit: |
deaf666
|
| Status: | ✅ Deploy successful! |
| Preview URL: | https://92902372.augmentos-e84.pages.dev |
| Branch Preview URL: | https://claude-bold-agnesi-ea30ec.augmentos-e84.pages.dev |
- Canonicalize pasted report ids (lowercase/mixed-case rep_... ULIDs) so the exact lookup and prefix scan both match the uppercase stored form - Replace fetch-incident-logs.sh pointers with a ready-to-run curl against the admin artifacts endpoint: the repo script still targets V1 incidents, so the suggested command would not fetch V2 artifacts - Document that the before-cursor scan can skip rows sharing the boundary millisecond (the list API filters strictly-before; the scan is best-effort and the miss path asks for a full id)
PR Agent Orchestrator State{
"cycle": 2,
"fixRound": 0,
"totalReviewerRuns": 2,
"consecutiveNoNewReviews": 2,
"openFindings": [],
"resolvedFindings": [],
"nitFindings": [],
"phase": "discovery",
"status": "in_progress",
"lastPair": [],
"stagnationFixRounds": 0,
"lastOpenCount": 0,
"fingerprintReopenCounts": {},
"mutedFingerprints": []
} |
🤖 PR Agent Review — cycle 2✅ No blocking findings · 0 blocking · 0 nits No model reviews ran this cycle. Updated automatically by the PR Agent Orchestrator each review cycle. Nits do not block merge. |
There was a problem hiding this comment.
Cursor Bugbot has reviewed your changes using default effort and found 1 potential issue.
❌ Bugbot Autofix is OFF. To automatically fix reported issues with cloud agents, enable autofix in the Cursor dashboard.
Reviewed by Cursor Bugbot for commit a982f3b. Configure here.
| ): Promise<{ report: ReportDetail; assets: ReportAsset[] }> { | ||
| const query = canonicalizeReportId(id); | ||
| try { | ||
| return await client.getReport(query); |
There was a problem hiding this comment.
Empty report ID hits list
Medium Severity
Blank or whitespace-only reportId values are canonicalized to an empty string, so getReport requests /api/admin/reports/ and hits the list route instead of a detail lookup. That returns a successful list payload shaped as { reports: [...] }, which resolveReport treats as a detail result and yields report: undefined to callers like report_get / report_get_logs instead of a clear not-found error.
Additional Locations (1)
Reviewed by Cursor Bugbot for commit a982f3b. Configure here.
| @@ -0,0 +1,27 @@ | |||
| { | |||
| "name": "@mentra/console-mcp", | |||
There was a problem hiding this comment.
calling it the @mentra/console-mcp is kinda a misnomer now that we moved the reports from the dev console to their own admin portal, so this mcp mostly handles incident reports, calling it the @mentra/admin-mcp makes more sense, or just @mentra/mcp if we plan to extend it beyond just the admin portal / incident system...
2 participants
Scope
The mentra-console MCP server (
cloud/packages/console-mcp) still targeted the legacy V1 incidents API (GET /api/agent/incidents[/:id[/logs]],X-Agent-Key). Thecloud/tree is frozen and V1 incidents are superseded by Cloud V2 reports, so this recreates the server atcloud-v2/packages/console-mcpon the admin reports API introduced by #3378:incident_listreport_listGET /api/admin/reports?kind=&status=&limit=&before=incident_getreport_getGET /api/admin/reports/:reportIdincident_get_logsreport_get_logsGET /api/admin/reports/:reportId/artifacts/:artifactIdper logs artifactreport_get_artifactscripts/fetch-incident-logs.shCarried over from V1: bounded log output (default 200 lines) with
level/grep/limitfilters, short-id prefix resolution (rep_...ULIDs, scanned against the ~600 most recent reports via thebeforecursor),mentra://reportsresources, adebug-reportprompt, therun-mcp.shCursor launcher, and the smoke test. New behavior for V2:report_get_logsmerges everylogsartifact ({entries: [{timestamp, level, message, source?}]}bundles from phone/glasses) oldest-first tagged with the uploading device, and an unreadable bundle degrades to a warning instead of failing the call.Auth and host selection mirror the ported
fetch-incident-logs.sh:Authorization: Bearer $MENTRA_ADMIN_TOKEN(orgmsk_key whose synthetic emailapi-key@{keyId}.localis allowlisted viaCLOUD_CORE_ADMIN_EMAILS, or a WorkOS admin access token), host fromMENTRA_CORE_URLorMENTRA_ENV=prod|staging|dev(default prod). 401/403/404 map to actionable hints (env-pinned keys, allowlist, API not deployed).The legacy package is left untouched — its V1 app/org/admin tools keep working until the
cloud/tree is removed. RootAGENTS.mdnow points V2 report triage (rep_...ids) at the new package.Notes for reviewers
/api/admin/reports, i.e. Admin console: report triage (list, detail, screenshots, logs) #3378 merged and deployed. Until then they return the mapped 404 hint. No compile-time dependency on core.scripts/fetch-incident-logs.shto this same API (same env conventions). If it lands first, its AGENTS.md note about the MCP server being unported should be dropped when this merges; the AGENTS.md touch here is kept minimal to make that conflict trivial.bun.lockfiles change: the repo root, mobile, and sdk workspaces all globcloud-v2/packages/*in addition to cloud-v2's own workspace, so each lockfile registers the new package and its@modelcontextprotocol/sdkdep tree.zod ^4.4.3: since the admin console website landed, cloud-v2 links@modelcontextprotocol/sdkagainst zod 4, and mixing a zod-3 identity with it through the SDK's zod-compat types fails typecheck (TS2589). Every schema helper used is identical in the v4 classic API./api/admin/submissions/...) if wanted; kept out of scope here.Test evidence
bun test(package): 28 pass across config / log parsing-merging-filtering / id resolutionbunx tsc --noEmitand roottsc -b packages/console-mcp(new project reference) passbun installat repo root andcloud-v2/regenerate both lockfiles cleanly (CI lockfile check runs frozen install)/api/admin/me— 13/13 checks pass: tool registration,console_auth_status verify, compact list rows, short-prefix resolve,includeContext:false, phone+glasses bundle merge ordering with source tags,level/grep/source/jsonfilters, inline PNG image content, JSON artifact as text, 404 mapping, prefix-miss messagingrun-mcp.shmanual stdio check from the README returns the expectedconsole_auth_statusresultNote
Low Risk
Developer-tooling only (MCP client + docs/lockfiles); no runtime changes to core, mobile, or auth beyond calling existing admin APIs with configured tokens.
Overview
Adds
@mentra/console-mcpundercloud-v2/packages/console-mcp— a stdio MCP server that replaces the frozen V1 incident tools with Cloud V2 admin reports (/api/admin/reports), authenticated viaMENTRA_ADMIN_TOKENandMENTRA_CORE_URL/MENTRA_ENV.Agents get
report_list,report_get,report_get_logs(merged phone/glasses log bundles with filters),report_get_artifact(inline images/text or curl hints), plusconsole_auth_status,mentra://reportsresources, and adebug-reportprompt. Shortrep_...prefix resolution,run-mcp.shfor Cursor, unit tests, and a live smoke script are included.AGENTS.mdnow documents V1 incident fetch viafetch-incident-logs.sh+MENTRA_AGENT_API_KEY, and V2rep_...triage via this MCP package. Root andcloud-v2bun.lockfiles andcloud-v2/tsconfig.jsonregister the new workspace package and its@modelcontextprotocol/sdkdependency tree. The legacycloud/packages/console-mcppackage is unchanged.Reviewed by Cursor Bugbot for commit a982f3b. Bugbot is set up for automated code reviews on this repo. Configure here.