Add admin/app/proxy cleanup parity tools

[IlyaasK]

Summary

Adds the small MCP parity cleanup slice after browser pools:

• manage_apps
  • adds delete_deployment
  • passes version through to deployment listing as the SDK's app_version filter
  • exposes app query search on list_apps
  • validates that deployment version filtering includes app_name, matching the SDK/API requirement
• manage_proxies
  • adds get
  • adds check with optional check_url
  • validates check_url as HTTP(S) at the MCP boundary
• manage_profiles
  • adds get
  • exposes profile query, limit, and offset for paginated listing instead of forcing agents to enumerate every profile
  • uses profile search during setup's existing-name check
• manage_projects
  • adds get_limits and update_limits for per-project caps
• manage_extensions
  • keeps list/delete behavior but moves responses onto the shared response helpers for consistent errors
• README now reflects the actual 15-tool surface on this stack.

Review Question

The main question for this PR is not whether the SDK calls work; it is whether we want this functionality exposed through MCP at all.

My current read:

• Yes for proxy get/check, profile get/search pagination, and app deployment list/delete because they map to concrete agent workflows: prepare a browser with a working proxy, reuse the right profile, and clean up an app deployment after testing.
• manage_projects get_limits/update_limits is the most admin-passthrough-shaped part of this PR. Keep it if we want MCP to support lightweight project administration; split or drop it if we want this MCP to stay strictly browser/workflow-oriented.

If accepted, I would treat this as the last small parity/admin cleanup slice, not as precedent that every SDK endpoint automatically deserves MCP exposure.

Why

These are the remaining small SDK passthroughs that do not belong in the managed-auth PR. They close agent-facing gaps without adding another large workflow surface:

• agents can clean up deployments after testing an app version
• agents can filter deployments by app version instead of scanning all deployments
• agents can verify proxy connectivity against a specific target URL before launching browsers through that proxy
• agents can search and page through profiles safely in larger orgs
• admins can inspect and update project resource caps without leaving MCP

Agent Experience / Flow

Typical app cleanup flow:

1. Agent calls manage_apps { action: "list_apps", query: "..." } to find the app/version.
2. Agent calls manage_apps { action: "list_deployments", app_name, version } to narrow to the deployment for that app version.
3. Agent calls manage_apps { action: "get_deployment", deployment_id } before destructive action.
4. If the deployment is stale or explicitly requested for cleanup, agent calls manage_apps { action: "delete_deployment", deployment_id }.

Typical proxy verification flow:

1. Agent calls manage_proxies { action: "list" } or get to identify the proxy.
2. Agent calls manage_proxies { action: "check", proxy_id, check_url: "https://target.example" } when site-specific reachability matters.
3. Agent only passes that proxy into browser/session creation after the check result looks healthy.

Typical profile discovery flow:

1. Agent calls manage_profiles { action: "list", query, limit } instead of pulling every profile.
2. Agent calls manage_profiles { action: "get", profile_name } before reuse or deletion.
3. Agent uses setup only when the desired profile does not already exist, or with update_existing: true when intentionally refreshing it.

Typical admin limit flow:

1. Agent calls manage_projects { action: "get", project_id } to confirm the target project.
2. Agent calls manage_projects { action: "get_limits", project_id } to inspect current caps.
3. Agent calls update_limits only with the specific cap fields requested by the user; omitted fields are left unchanged.

Implementation Notes

• This PR deliberately does not touch Mason's managed-auth tools from add managed auth tools (manage_auth_connections, manage_credentials, manage_credential_providers) #104.
• Binary extension upload/download is not added here because that would be a separate agent workflow with different safety and payload-size concerns.
• Shared textResponse, jsonResponse, and errorMessage helpers are used in touched handlers to keep tool output consistent.

Verification

• bunx prettier --check README.md src/lib/mcp/tools/apps.ts src/lib/mcp/tools/proxies.ts src/lib/mcp/tools/profiles.ts src/lib/mcp/tools/projects.ts src/lib/mcp/tools/extensions.ts
• git diff --check
• bun run build with dummy auth env. Build passes; network access was needed because Next/Turbopack fetches Google Fonts during build.
• Local MCP smoke against http://localhost:3002/mcp with dummy bearer token:
  • tools/list returned 15 tools
  • verified registration for manage_apps, manage_proxies, manage_profiles, manage_projects, and manage_extensions
  • verified validation responses for deployment version filtering without app_name, deployment delete without deployment_id, proxy check without proxy_id, profile get without profile identifier, project get_limits without project_id, and non-HTTP(S) check_url schema rejection.

---

Note

Medium Risk
Adds destructive operations (delete_deployment) and admin limit updates, but changes are bounded SDK passthroughs with input validation at the MCP layer.

Overview
This PR extends several manage_* MCP tools with SDK parity actions and refactors their responses through shared helpers in responses.ts (jsonListResponse, paginatedJsonResponse, textResponse, errorMessage).

manage_apps gains delete_deployment, app query on list_apps, and deployment listing filtered by version (mapped to app_version) with validation that app_name is required when filtering by version.

manage_proxies adds get and check (optional HTTP(S) check_url validated at the schema boundary).

manage_profiles adds get, paginated/searchable list (query, limit, offset), and uses profile search during setup’s duplicate-name check instead of full enumeration.

manage_projects adds get_limits and update_limits for per-project concurrency and pool caps.

manage_extensions behavior is unchanged; list/delete now use the shared response helpers.

The README is updated to document the 15-tool surface and the expanded capabilities above.

^{Reviewed by Cursor Bugbot for commit 8fbfcf4. Bugbot is set up for automated code reviews on this repo. Configure here.}

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
mcp	Ready	Preview, Comment	Jun 1, 2026 7:36pm

[firetiger-agent]

Firetiger deploy monitoring skipped

This PR didn't match the auto-monitor filter configured on your GitHub connection:

PRs in the kernel, infra, hypeman, and hypeship repos. kernel is a ~mono repo with many logical services underneath, ensure to focus on the implicated service for the PR

Reason: PR is from the browser-pools-parity-mcp-tool branch (not a standard repo) and lacks clear repository context; please confirm this targets one of the monitored repos (kernel, infra, hypeman, hypeship) and opt in manually if needed.

To monitor this PR anyway, reply with @firetiger monitor this.

[cursor]

Cursor Bugbot has reviewed your changes 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 8fbfcf4. Configure here.}

[cursor]

Empty page shows zero-profile text

Medium Severity

The new paginated manage_profiles list action passes a fixed emptyText into paginatedJsonResponse. Any empty page—including when offset is past the last profile—returns that plain-text “no profiles” setup hint instead of JSON with empty items and has_more/next_offset, which breaks paging and misstates whether profiles exist.

Additional Locations (1)

• src/lib/mcp/responses.ts#L26-L27

 

^{Reviewed by Cursor Bugbot for commit 8fbfcf4. Configure here.}