MCP Suggested Actions

Defines how the MCP server surfaces contextual next-step actions to the UI / MCP client after every tool invocation.

Suggested Action Schema

{
  "id": "push_ecosystem",
  "label": "Push changes",
  "tool": "amof_push_ecosystem",
  "args": { "ecosystem": "amof-platform" },
  "scope": "ecosystem",
  "mode_required": "execute",
  "safety": "dangerous-write",
  "confirm": true,
  "priority": 1,
  "description": "Push all committed changes to remote",
  "condition": "status.has_unpushed"
}

Field	Type	Description
id	string	Stable identifier for deduplication and analytics
label	string	Short button/chip label (max 30 chars)
tool	string	MCP tool name to invoke
args	object	Pre-filled arguments
scope	enum	global, ecosystem, run, release, server
mode_required	enum	Minimum mode: ask, plan, execute
safety	enum	read-only, safe-write, dangerous-write
confirm	bool	Whether UI must prompt before executing
priority	int	1 = highest, 5 = lowest

Predefined Action Sets

Global Scope (Default)

Priority	Label	Tool	Safety
1	List ecosystems	amof_list_ecosystems	read-only
2	Server status	amof_get_server_status	read-only
3	Show active runs	amof_get_active_runs	read-only
4	View telemetry	amof_get_global_telemetry	read-only

Ecosystem -- After Sync

Priority	Label	Tool	Safety
1	Check status	amof_get_ecosystem_status	read-only
2	Push changes	amof_push_ecosystem	dangerous-write
3	Show runs	amof_get_active_runs	read-only

Ecosystem -- Dirty Repos

Priority	Label	Tool	Safety
1	Push changes	amof_push_ecosystem	dangerous-write
2	Check status	amof_get_ecosystem_status	read-only
3	Sync repos	amof_sync_ecosystem	safe-write

Run -- Completed (Success)

Priority	Label	Tool	Safety
1	View summary	amof_summarize_run	read-only
2	Show logs	amof_get_run_logs	read-only
3	Back to ecosystem	amof_get_ecosystem_status	read-only

Release -- Alpha

Priority	Label	Tool	Safety
1	Promote to beta	amof_release_promote	dangerous-write
2	Release status	amof_release_status	read-only
3	Validate release	amof_release_validate	read-only

Rendering Protocol

Constraints

Maximum 5 actions per response
Priority ordering: lower number = more prominent position
Mode gating: filter out actions where mode_required > current_mode
Deduplication: same id can only appear once; keep highest priority
Scope gating: only suggest actions for current scope or its parent

Mode Filtering

Current Mode	Allowed Safety Levels
ask	read-only only
plan	read-only, safe-write
execute	read-only, safe-write, dangerous-write

Suppression Rules

Post-Read: Max 3 actions for info queries; no destructive actions unless status indicates need
Same-Action: Never suggest the tool just invoked (exception: refresh for running runs)
Scope Boundary: No ecosystem-scoped actions without entering an ecosystem
Post-Destructive: Only suggest amof_list_ecosystems after discard/destroy
Completion: After async action started, only suggest run_status and run_logs

State Machine

┌──────────────────────────────────────────────────────────────┐
│                         GLOBAL SCOPE                          │
│  Default: [List ecosystems] [Server status] [Active runs]    │
│                                                                │
│  ┌───────────────────────────────────────────────────────┐    │
│  │                    ECOSYSTEM SCOPE                     │    │
│  │  after_install:  [Status] [Sync] [Start ticket]       │    │
│  │  after_sync:     [Status] [Push] [Show runs]          │    │
│  │  dirty_repos:    [Push] [Status] [Sync]               │    │
│  │  no_ticket:      [Start ticket] [List tickets]        │    │
│  │                                                        │    │
│  │  ┌──────────────────────────────────────────────┐     │    │
│  │  │               RUN SCOPE                       │     │    │
│  │  │  running:  [Refresh] [Stream logs]            │     │    │
│  │  │  success:  [Summary] [Logs] [<- Ecosystem]    │     │    │
│  │  │  failed:   [Logs] [Summary] [<- Ecosystem]    │     │    │
│  │  └──────────────────────────────────────────────┘     │    │
│  │                                                        │    │
│  │  ┌──────────────────────────────────────────────┐     │    │
│  │  │            RELEASE SCOPE                      │     │    │
│  │  │  alpha:   [-> Beta] [Status] [Validate]       │     │    │
│  │  │  beta:    [-> RC] [Validate] [History]         │     │    │
│  │  │  rc:      [-> Stable] [Validate] [History]     │     │    │
│  │  │  stable:  [History] [Status]                   │     │    │
│  │  └──────────────────────────────────────────────┘     │    │
│  └───────────────────────────────────────────────────────┘    │
└──────────────────────────────────────────────────────────────┘