diff --git a/README.md b/README.md index 0afd8d8..0fede4e 100644 --- a/README.md +++ b/README.md @@ -174,7 +174,7 @@ For automation, `unic resources --json` runs a read-only AWS query using Inspector runs outside `resources` because it is a scan, not a resource listing. `unic inspect --json` runs every built-in security and cost/waste rule pack against the active context and returns the same v1 envelope, with `data` carrying `scanned_at`, `scanner_count`, `finding_count`, `severity_counts`, and the `findings` array. Rule packs that fail — most often a denied API call — appear in `warnings` rather than being dropped, so a partially blocked scan is never reported as a clean one. The equivalent MCP tool is `run_security_inspector`. The root `--checklist` flag is inherited but rejected here: Checklist Inspector produces a different report shape and has no agent contract yet, so it fails loudly rather than returning security findings in its place. -The same operations are exposed by `unic-mcp` as read-only tools. Call `get_mcp_capabilities` to discover their versioned input contracts, strict input schemas, output contracts, pagination behavior, and required IAM permissions. The operation permissions are `ec2:DescribeInstances`, `rds:DescribeDBInstances`, `elasticache:DescribeCacheClusters`, `elasticache:DescribeReplicationGroups`, `cloudwatch:DescribeAlarms`, `ecs:DescribeServices`, `ecs:DescribeTaskDefinition`, `cloudtrail:LookupEvents`, `cloudformation:DescribeStacks`, `elasticloadbalancing:DescribeTargetGroups`, `elasticloadbalancing:DescribeTargetHealth`, `sns:ListTopics`, `sns:GetTopicAttributes`, `sns:ListSubscriptionsByTopic`, `sns:GetSubscriptionAttributes`, `sqs:ListQueues`, and `sqs:GetQueueAttributes`; AWS Backup retains the permissions documented below. CLI and MCP output never includes resolved credentials. +The same operations are exposed by `unic-mcp` as read-only tools. Call `get_mcp_capabilities` to discover their versioned input contracts, strict input schemas, output contracts, pagination behavior, and required IAM permissions. The operation permissions are `ec2:DescribeInstances`, `rds:DescribeDBInstances`, `elasticache:DescribeCacheClusters`, `elasticache:DescribeReplicationGroups`, `cloudwatch:DescribeAlarms`, `ecs:DescribeServices`, `ecs:DescribeTaskDefinition`, `cloudtrail:LookupEvents`, `cloudformation:DescribeStacks`, `states:ListExecutions`, `elasticloadbalancing:DescribeTargetGroups`, `elasticloadbalancing:DescribeTargetHealth`, `sns:ListTopics`, `sns:GetTopicAttributes`, `sns:ListSubscriptionsByTopic`, `sns:GetSubscriptionAttributes`, `sqs:ListQueues`, and `sqs:GetQueueAttributes`; AWS Backup retains the permissions documented below. CLI and MCP output never includes resolved credentials. ### MCP server @@ -266,6 +266,11 @@ The server exposes the read-only resource operations listed above—including `l - `Show the AWS capabilities available through unic.` - `List my AWS Backup vaults in ap-northeast-2.` - `Show failed or rollback CloudFormation stacks and their status reasons.` +The server exposes the read-only resource operations listed above—including `list_step_function_executions`—plus capability discovery, Security Inspector, and context-sync preview tools. Agents should call `get_mcp_capabilities` first because it describes only operations callable through MCP, including permissions and output contracts. Example prompts: + +- `Show the AWS capabilities available through unic.` +- `List my AWS Backup vaults in ap-northeast-2.` +- `Show the recent failed executions for this STANDARD Step Functions state machine ARN.` - `Preview a unic context sync without changing config.` The context-sync tool is preview-only: it never passes `--apply` or writes configuration. If a client cannot start the server, verify `unic-mcp` is on the client's `PATH` and that the required AWS profile or SSO session is available in the client process environment. diff --git a/docs/development.md b/docs/development.md index 3e931e0..3cbf41d 100644 --- a/docs/development.md +++ b/docs/development.md @@ -30,6 +30,8 @@ unic schema resources elasticache-resources --json unic schema resources sns-topics --json unic schema resources cloudformation-stacks --json + +unic schema resources step-function-executions --json ``` Discovery output is deterministic, versioned JSON. New executable commands should set the `unic.dev/read-only`, `unic.dev/destructive`, and `unic.dev/output-version` annotations when their defaults do not describe the command accurately. @@ -42,6 +44,8 @@ Read-only automation commands live under `internal/cli/`; keep their `--json` ou `unic resources cloudformation-stacks --json` reuses the browser's failure-first stack ordering and returns status reasons, drift state, parameters, and outputs. Recent events remain a separate per-stack detail lookup and are not implied by this listing contract. +`unic resources step-function-executions --state-machine --json` reuses the browser's failure-first ordering for up to 200 recent STANDARD workflow executions. The JSON pagination metadata reports the cap; EXPRESS workflow execution history is not available through this API. + The stdio MCP entry point lives at `cmd/unic-mcp` and delegates tool calls to those same CLI commands through `internal/cli.ExecuteAutomation`. Keep the MCP layer limited to protocol handling and argument mapping; AWS and config behavior belongs in the existing CLI, auth, and service packages. MCP mutation tools remain preview-only until their trust boundary is reviewed. The repository root is also the portable agent-plugin package. Keep shared MCP guidance in `skills/unic-aws`, Kiro metadata in `plugin.json` and `mcp.json`, and client-specific manifests in `.codex-plugin`, `.claude-plugin`, and `.mcp.json`. All clients must launch the released `unic-mcp` binary from `PATH`; do not add client-specific MCP implementations. diff --git a/internal/cli/resources.go b/internal/cli/resources.go index e5da56e..37ca033 100644 --- a/internal/cli/resources.go +++ b/internal/cli/resources.go @@ -100,13 +100,23 @@ func cloudFormationValuesJSON(values []awsservice.CloudFormationValue) []cloudFo return result } -func cloudFormationTimeJSON(value time.Time) string { +func resourceTimeJSON(value time.Time) string { if value.IsZero() { return "" } return value.UTC().Format(time.RFC3339) } +type stepFunctionExecutionJSON struct { + ARN string `json:"arn"` + Name string `json:"name"` + StateMachineARN string `json:"state_machine_arn"` + Status string `json:"status"` + StartedAt string `json:"started_at"` + StoppedAt string `json:"stopped_at,omitempty"` + NeedsAttention bool `json:"needs_attention"` +} + var loadBackupVaults = func(ctx context.Context) ([]awsservice.BackupVault, []error, error) { configPath, err := config.DefaultPath() if err != nil { @@ -130,7 +140,7 @@ func newResourcesCmd() *cobra.Command { cmd := &cobra.Command{Use: "resources", Short: "Read-only resource queries for automation"} cmd.AddCommand(newBackupVaultsCmd()) cmd.AddCommand(newEC2InstancesCmd(), newRDSInstancesCmd(), newCloudFormationStacksCmd(), newAlarmsCmd()) - cmd.AddCommand(newECSRolloutCmd(), newCloudTrailEventsCmd(), newELBTargetHealthCmd(), newSQSQueuesCmd(), newElastiCacheResourcesCmd(), newSNSTopicsCmd()) + cmd.AddCommand(newECSRolloutCmd(), newCloudTrailEventsCmd(), newELBTargetHealthCmd(), newSQSQueuesCmd(), newElastiCacheResourcesCmd(), newSNSTopicsCmd(), newStepFunctionExecutionsCmd()) return cmd } diff --git a/internal/cli/resources_operations.go b/internal/cli/resources_operations.go index b636e58..0408945 100644 --- a/internal/cli/resources_operations.go +++ b/internal/cli/resources_operations.go @@ -4,6 +4,7 @@ import ( "context" "encoding/json" "errors" + "strings" "time" "github.com/spf13/cobra" @@ -91,6 +92,13 @@ var ( } return repo.ListCloudFormationStacks(ctx) } + loadStepFunctionExecutions = func(ctx context.Context, stateMachineARN string) ([]awsservice.StepFunctionExecution, error) { + repo, err := resourceRepository(ctx) + if err != nil { + return nil, err + } + return repo.ListStepFunctionExecutions(ctx, stateMachineARN) + } loadSQSQueues = func(ctx context.Context) ([]awsservice.SQSQueue, error) { repo, err := resourceRepository(ctx) if err != nil { @@ -287,7 +295,7 @@ func newCloudFormationStacksCmd() *cobra.Command { data = append(data, cloudFormationStackJSON{ ID: stack.ID, Name: stack.Name, Description: stack.Description, Status: stack.Status, StatusReason: stack.StatusReason, DriftStatus: stack.DriftStatus, Region: stack.Region, - LastDriftCheck: cloudFormationTimeJSON(stack.LastDriftCheck), CreatedAt: cloudFormationTimeJSON(stack.CreatedAt), UpdatedAt: cloudFormationTimeJSON(stack.UpdatedAt), + LastDriftCheck: resourceTimeJSON(stack.LastDriftCheck), CreatedAt: resourceTimeJSON(stack.CreatedAt), UpdatedAt: resourceTimeJSON(stack.UpdatedAt), TerminationProtection: stack.TerminationProtection, Parameters: cloudFormationValuesJSON(stack.Parameters), Outputs: cloudFormationValuesJSON(stack.Outputs), }) @@ -295,3 +303,44 @@ func newCloudFormationStacksCmd() *cobra.Command { return data, err }) } + +func newStepFunctionExecutionsCmd() *cobra.Command { + var stateMachineARN string + var jsonOutput bool + cmd := &cobra.Command{ + Use: "step-function-executions", + Short: "List recent Step Functions executions in triage order as JSON", + Args: cobra.NoArgs, + RunE: func(cmd *cobra.Command, _ []string) error { + if !jsonOutput { + return errors.New("this automation command supports JSON output only") + } + if strings.TrimSpace(stateMachineARN) == "" { + return errors.New("state-machine is required") + } + executions, err := loadStepFunctionExecutions(cmd.Context(), stateMachineARN) + if err != nil { + return err + } + data := make([]stepFunctionExecutionJSON, 0, len(executions)) + for _, execution := range executions { + data = append(data, stepFunctionExecutionJSON{ + ARN: execution.ARN, Name: execution.Name, StateMachineARN: execution.StateMachineARN, + Status: execution.Status, StartedAt: resourceTimeJSON(execution.StartDate), + StoppedAt: resourceTimeJSON(execution.StopDate), NeedsAttention: execution.NeedsAttention(), + }) + } + complete := len(data) < 200 + warnings := []string{} + if !complete { + warnings = append(warnings, "results reached the 200-execution limit") + } + return writeResourceJSON(cmd, data, complete, warnings) + }, + } + cmd.Annotations = map[string]string{annotationReadOnly: "true", annotationOutputVersion: "v1"} + cmd.Flags().StringVar(&stateMachineARN, "state-machine", "", "STANDARD state machine ARN") + cmd.Flags().BoolVar(&jsonOutput, "json", true, "Emit stable machine-readable JSON") + _ = cmd.MarkFlagRequired("state-machine") + return cmd +} diff --git a/internal/cli/resources_operations_test.go b/internal/cli/resources_operations_test.go index 328b5b2..f933ab7 100644 --- a/internal/cli/resources_operations_test.go +++ b/internal/cli/resources_operations_test.go @@ -347,3 +347,91 @@ func TestCloudFormationStacksLoaderErrorEmitsNoEnvelope(t *testing.T) { t.Fatalf("expected no success envelope, got %s", output.String()) } } + +func TestStepFunctionExecutionsJSONContract(t *testing.T) { + original := loadStepFunctionExecutions + defer func() { loadStepFunctionExecutions = original }() + started := time.Date(2026, 9, 15, 18, 0, 0, 0, time.FixedZone("KST", 9*60*60)) + loadStepFunctionExecutions = func(context.Context, string) ([]awsservice.StepFunctionExecution, error) { + return []awsservice.StepFunctionExecution{ + {ARN: "arn:execution", Name: "failed-run", StateMachineARN: "arn:machine", Status: "FAILED", StartDate: started, StopDate: started.Add(time.Minute)}, + {ARN: "arn:running", Name: "running", StateMachineARN: "arn:machine", Status: "RUNNING", StartDate: started}, + }, nil + } + cmd := NewRootCmd() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetArgs([]string{"resources", "step-function-executions", "--state-machine", "arn:machine", "--json"}) + if err := cmd.Execute(); err != nil { + t.Fatal(err) + } + var result struct { + SchemaVersion string `json:"schema_version"` + Data []struct { + ARN string `json:"arn"` + StateMachineARN string `json:"state_machine_arn"` + Status string `json:"status"` + StartedAt string `json:"started_at"` + StoppedAt string `json:"stopped_at"` + NeedsAttention bool `json:"needs_attention"` + } `json:"data"` + Warnings []string `json:"warnings"` + Pagination jsonPagination `json:"pagination"` + } + if err := json.Unmarshal(output.Bytes(), &result); err != nil { + t.Fatal(err) + } + if result.SchemaVersion != "v1" || len(result.Data) != 2 || result.Data[0].ARN != "arn:execution" || + result.Data[0].StateMachineARN != "arn:machine" || result.Data[0].Status != "FAILED" || + result.Data[0].StartedAt != "2026-09-15T09:00:00Z" || result.Data[0].StoppedAt != "2026-09-15T09:01:00Z" || + !result.Data[0].NeedsAttention || result.Data[1].StoppedAt != "" || result.Data[1].NeedsAttention || + result.Warnings == nil || !result.Pagination.Complete { + t.Fatalf("unexpected result: %+v", result) + } +} + +func TestStepFunctionExecutionsReportsCap(t *testing.T) { + original := loadStepFunctionExecutions + defer func() { loadStepFunctionExecutions = original }() + loadStepFunctionExecutions = func(context.Context, string) ([]awsservice.StepFunctionExecution, error) { + return make([]awsservice.StepFunctionExecution, 200), nil + } + cmd := NewRootCmd() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetArgs([]string{"resources", "step-function-executions", "--state-machine", "arn:machine", "--json"}) + if err := cmd.Execute(); err != nil { + t.Fatal(err) + } + if !bytes.Contains(output.Bytes(), []byte(`"complete":false`)) || !bytes.Contains(output.Bytes(), []byte("200-execution limit")) { + t.Fatalf("missing execution cap signal: %s", output.String()) + } +} + +func TestStepFunctionExecutionsRejectsMissingARNAndLoaderErrors(t *testing.T) { + cmd := NewRootCmd() + cmd.SetArgs([]string{"resources", "step-function-executions", "--json"}) + if err := cmd.Execute(); err == nil { + t.Fatal("missing state-machine ARN must fail") + } + cmd = NewRootCmd() + cmd.SetArgs([]string{"resources", "step-function-executions", "--state-machine", " ", "--json"}) + if err := cmd.Execute(); err == nil { + t.Fatal("blank state-machine ARN must fail") + } + + original := loadStepFunctionExecutions + defer func() { loadStepFunctionExecutions = original }() + wantErr := errors.New("execution lookup failed") + loadStepFunctionExecutions = func(context.Context, string) ([]awsservice.StepFunctionExecution, error) { return nil, wantErr } + cmd = NewRootCmd() + var output bytes.Buffer + cmd.SetOut(&output) + cmd.SetArgs([]string{"resources", "step-function-executions", "--state-machine", "arn:machine", "--json"}) + if err := cmd.Execute(); !errors.Is(err, wantErr) { + t.Fatalf("expected loader error, got %v", err) + } + if output.Len() != 0 { + t.Fatalf("expected no success envelope, got %s", output.String()) + } +} diff --git a/internal/mcp/agent_surface_test.go b/internal/mcp/agent_surface_test.go index 7997d0d..01f3e94 100644 --- a/internal/mcp/agent_surface_test.go +++ b/internal/mcp/agent_surface_test.go @@ -33,6 +33,7 @@ var agentSurfaceByFeature = map[domain.FeatureKind]agentSurface{ domain.FeatureRDSBrowser: {command: "rds-instances", tool: "list_rds_instances"}, domain.FeatureSQSBrowser: {command: "sqs-queues", tool: "list_sqs_queues"}, domain.FeatureSNSBrowser: {command: "sns-topics", tool: "list_sns_topics"}, + domain.FeatureStepFunctionsBrowser: {command: "step-function-executions", tool: "list_step_function_executions", arguments: json.RawMessage(`{"state_machine":"arn:machine"}`)}, } var agentSurfaceExempt = map[domain.FeatureKind]string{ @@ -60,7 +61,6 @@ var agentSurfaceExempt = map[domain.FeatureKind]string{ domain.FeatureSecretsBrowser: "secret values require operator-controlled reveal and copy handling", domain.FeatureSSMParameterBrowser: "parameter values require operator-controlled reveal and copy handling", domain.FeatureSSMSession: "starts an interactive shell session instead of returning resource data", - domain.FeatureStepFunctionsBrowser: "the failure-first execution view has no curated agent contract yet", domain.FeatureVPCBrowser: "no bounded VPC and subnet query is defined yet", domain.FeatureWAFWebACLBrowser: "the regional and global joined view has no agent contract yet", } diff --git a/internal/mcp/server.go b/internal/mcp/server.go index d8dd84a..1e223eb 100644 --- a/internal/mcp/server.go +++ b/internal/mcp/server.go @@ -186,6 +186,14 @@ var tools = []tool{ OutputContract: "unic.resources.sqs-queues.v1", Paginated: true, }, }, + { + Name: "list_step_function_executions", Description: "List up to 200 recent STANDARD Step Functions executions in failure-first triage order.", + InputSchema: awsContextSchema(map[string]any{ + "state_machine": map[string]any{"type": "string", "minLength": 1, "description": "STANDARD state machine ARN"}, + }, []string{"state_machine"}), + Annotations: annotations{ReadOnlyHint: true, IdempotentHint: true, OpenWorldHint: true}, + Metadata: toolMetadata{RequiredPermissions: []string{"states:ListExecutions"}, OutputContract: "unic.resources.step-function-executions.v1", Paginated: true}, + }, { Name: "plan_context_sync", Description: "Preview an SSO context sync plan. This tool never writes configuration.", InputSchema: objectSchema(map[string]any{ @@ -497,6 +505,19 @@ func toolArgs(name string, raw json.RawMessage) ([]string, error) { return nil, errors.New("load_balancer is required") } return withAWSContext([]string{"resources", "elb-target-health", "--load-balancer", args.LoadBalancer, "--json"}, args.Profile, args.Region), nil + case "list_step_function_executions": + var args struct { + StateMachine string `json:"state_machine"` + Profile string `json:"profile"` + Region string `json:"region"` + } + if err := decodeArguments(raw, &args); err != nil { + return nil, err + } + if strings.TrimSpace(args.StateMachine) == "" { + return nil, errors.New("state_machine is required") + } + return withAWSContext([]string{"resources", "step-function-executions", "--state-machine", args.StateMachine, "--json"}, args.Profile, args.Region), nil case "plan_context_sync": var args struct { BaseContext string `json:"base_context"` diff --git a/internal/mcp/server_test.go b/internal/mcp/server_test.go index 35f316f..ed28794 100644 --- a/internal/mcp/server_test.go +++ b/internal/mcp/server_test.go @@ -62,6 +62,7 @@ func TestReadOnlyOperationToolArgs(t *testing.T) { {"get_ecs_service_rollout", `{"cluster":"prod","service":"api"}`, []string{"resources", "ecs-rollout", "--cluster", "prod", "--service", "api", "--json"}}, {"list_cloudtrail_events", `{"since":"6h","mutations_only":true}`, []string{"resources", "cloudtrail-events", "--since", "6h", "--json", "--mutations-only"}}, {"get_elb_target_health", `{"load_balancer":"arn:lb"}`, []string{"resources", "elb-target-health", "--load-balancer", "arn:lb", "--json"}}, + {"list_step_function_executions", `{"state_machine":"arn:machine","profile":"prod","region":"eu-west-1"}`, []string{"resources", "step-function-executions", "--state-machine", "arn:machine", "--json", "--profile", "prod", "--region", "eu-west-1"}}, {"run_security_inspector", `{}`, []string{"inspect", "--json"}}, {"run_security_inspector", `{"profile":"prod","region":"eu-west-1"}`, []string{"inspect", "--json", "--profile", "prod", "--region", "eu-west-1"}}, } @@ -85,6 +86,9 @@ func TestReadOnlyOperationToolValidation(t *testing.T) { if _, err := toolArgs("get_elb_target_health", json.RawMessage(`{"load_balancer":""}`)); err == nil { t.Fatal("empty load balancer must fail") } + if _, err := toolArgs("list_step_function_executions", json.RawMessage(`{"state_machine":" "}`)); err == nil { + t.Fatal("empty state machine must fail") + } } func TestMCPCapabilitiesStayAlignedWithRegisteredTools(t *testing.T) { @@ -106,8 +110,11 @@ func TestMCPCapabilitiesStayAlignedWithRegisteredTools(t *testing.T) { if _, ok := listed[i]["required_permissions"].([]string); !ok { t.Fatalf("tool %s permissions are not a stable array", registered.Name) } - if registered.Name == "list_cloudformation_stacks" { - want := []string{"cloudformation:DescribeStacks", "cloudformation:ListStacks"} + wantPermissions := map[string][]string{ + "list_cloudformation_stacks": {"cloudformation:DescribeStacks", "cloudformation:ListStacks"}, + "list_step_function_executions": {"states:ListExecutions"}, + } + if want, ok := wantPermissions[registered.Name]; ok { if !reflect.DeepEqual(listed[i]["required_permissions"], want) { t.Fatalf("tool %s permissions = %#v, want %#v", registered.Name, listed[i]["required_permissions"], want) } diff --git a/skills/unic-aws/SKILL.md b/skills/unic-aws/SKILL.md index 9c0ff86..6a20472 100644 --- a/skills/unic-aws/SKILL.md +++ b/skills/unic-aws/SKILL.md @@ -12,6 +12,8 @@ Use the `unic` MCP server for supported AWS inspection and context planning. 3. Call `get_command_schema` before composing an automation command contract. 4. Call a discovered read-only resource tool with optional `profile` and `region` arguments; for example, `list_backup_vaults` or `list_sns_topics`. 4. Call a discovered read-only resource tool with optional `profile` and `region` arguments; for example, `list_backup_vaults` or `list_cloudformation_stacks`. + +4. Call a discovered read-only resource tool with optional `profile` and `region` arguments; for example, `list_backup_vaults` or `list_step_function_executions`. 5. Call `plan_context_sync` to preview SSO context changes. It never applies or writes configuration. The server inherits local unic and AWS configuration from its process environment. Never request, store, or place AWS credentials in plugin configuration. Report structured permission errors and partial-result warnings to the user.