harness-mcp-v2 3.0.6 → 3.0.8

package/README.md

@@ -1,6 +1,6 @@
 ## Harness MCP Server 2.0
 
-An MCP (Model Context Protocol) server that gives AI agents full access to the Harness.io platform through 11 consolidated tools and 188 resource types.
+An MCP (Model Context Protocol) server that gives AI agents full access to the Harness.io platform through 11 consolidated tools and 195 resource types.
 
 ## Why Use This MCP Server
 
@@ -8,10 +8,10 @@ Most MCP servers map one tool per API endpoint. For a platform as broad as Harne
 
 This server is built differently:
 
-- **11 tools, 188 resource types.** A registry-based dispatch system routes `harness_list`, `harness_get`, `harness_create`, etc. to any Harness resource — pipelines, services, environments, orgs, projects, feature flags, cost data, and more. The LLM picks from 11 tools instead of hundreds.
-- **Full platform coverage.** 32 toolsets spanning CI/CD, GitOps, Feature Flags, Cloud Cost Management, Security Testing, Chaos Engineering, Database DevOps, Internal Developer Portal, Software Supply Chain, Governance, Service Overrides, Visualizations, and more. Not just pipelines — the entire Harness platform.
+- **11 tools, 195 resource types.** A registry-based dispatch system routes `harness_list`, `harness_get`, `harness_create`, etc. to any Harness resource — pipelines, services, environments, orgs, projects, feature flags, cost data, and more. The LLM picks from 11 tools instead of hundreds.
+- **Full platform coverage.** 32 default toolsets spanning CI/CD, GitOps, Feature Flags, Cloud Cost Management, Security Testing, Chaos Engineering, Database DevOps, Internal Developer Portal, Software Supply Chain, Governance, Service Overrides, Visualizations, and more. Opt-in IaCM coverage is available when you need Terraform workspace and module data.
 - **Multi-project workflows out of the box.** Agents discover organizations and projects dynamically — no hardcoded env vars needed. Ask "show failed executions across all projects" and the agent can navigate the full account hierarchy.
-- **31 prompt templates.** Pre-built prompts for common workflows: build & deploy apps end-to-end, debug failed pipelines, review DORA metrics, triage vulnerabilities, optimize cloud costs, audit access control, plan feature flag rollouts, review pull requests, approve pending pipelines, and more.
+- **32 prompt templates.** Pre-built prompts for common workflows: build & deploy apps end-to-end, debug failed pipelines, review DORA metrics, triage vulnerabilities, optimize cloud costs, audit access control, plan feature flag rollouts, review pull requests, approve pending pipelines, and more.
 - **Works everywhere.** Stdio transport for local clients (Claude Desktop, Cursor, Windsurf), HTTP transport for remote/shared deployments, Docker and Kubernetes ready.
 - **Zero-config start.** Just provide a Harness API key. Account ID is auto-extracted from PAT tokens, org/project defaults are optional, and toolset filtering lets you expose only what you need.
 - **Extensible by design.** Adding a new Harness resource means adding a declarative data file — no new tool registration, no schema changes, no prompt updates.
@@ -528,7 +528,7 @@ The server automatically loads environment variables from a `.env` file in the p
 | `HARNESS_MAX_BODY_SIZE_MB`  | No       | `10`                        | Max HTTP request body size in MB for `http` transport                                                                                                                                                                                                 |
 | `HARNESS_RATE_LIMIT_RPS`    | No       | `10`                        | Client-side request throttle (requests per second) to Harness APIs                                                                                                                                                                                    |
 | `LOG_LEVEL`                 | No       | `info`                      | Log verbosity: `debug`, `info`, `warn`, `error`                                                                                                                                                                                                       |
-| `HARNESS_TOOLSETS`          | No       | *(all)*                     | Comma-separated toolset list. Empty loads all toolsets. Supports `+name` to explicitly include and `-name` to remove toolsets (see [Toolset Filtering](#toolset-filtering))                                                                           |
+| `HARNESS_TOOLSETS`          | No       | *(defaults)*                | Comma-separated toolset list. Empty loads default toolsets. Supports `+name` to explicitly include opt-in toolsets and `-name` to remove defaults (see [Toolset Filtering](#toolset-filtering))                                                       |
 | `HARNESS_READ_ONLY`         | No       | `false`                     | Block all mutating operations (create, update, delete, execute). Only list and get are allowed. Useful for shared/demo environments                                                                                                                   |
 | `HARNESS_AUTO_APPROVE_RISK` | No       | `none`                      | Risk-based auto-approve threshold for autonomous workflows. Operations at or below this risk proceed without confirmation. Values: `none`, `low_write`, `medium_write`, `high_write`, `all`. See [Elicitation](#elicitation)                          |
 | `HARNESS_SKIP_ELICITATION`  | No       | `false`                     | **Deprecated** — use `HARNESS_AUTO_APPROVE_RISK=all` instead. Kept for backward compatibility                                                                                                                                                         |
@@ -538,6 +538,12 @@ The server automatically loads environment variables from a `.env` file in the p
 | `HARNESS_MCP_AUTH_TOKEN`    | No       | --                          | Bearer token required on `/mcp` HTTP routes when set. Required by default when HTTP transport binds to a non-loopback host                                                                                                                             |
 | `HARNESS_MCP_ALLOW_UNAUTHENTICATED_HTTP` | No | `false`         | Explicitly allow unauthenticated HTTP transport on non-loopback binds. Use only behind another authenticated control                                                                                                                                    |
 | `HARNESS_MCP_LOG_FILE`      | No       | `~/.claude/harness-mcp.log` | File used for stdio disconnect/crash diagnostics when stderr may no longer be available                                                                                                                                                               |
+| `HARNESS_AUDIT_FILE`        | No       | --                          | Append audit events to a newline-delimited JSON file in addition to stderr                                                                                                                                                                             |
+| `HARNESS_AUDIT_WEBHOOK_URL` | No       | --                          | HTTPS endpoint that receives batched audit events. HTTP URLs require `HARNESS_ALLOW_HTTP=true` for local development                                                                                                                                   |
+| `HARNESS_AUDIT_WEBHOOK_TOKEN` | No     | --                          | Optional bearer token sent to the audit webhook                                                                                                                                                                                                        |
+| `HARNESS_AUDIT_WEBHOOK_BATCH_SIZE` | No | `10`                       | Number of audit events to batch before webhook flush                                                                                                                                                                                                   |
+| `HARNESS_AUDIT_WEBHOOK_FLUSH_MS` | No  | `5000`                     | Max time to hold audit events before webhook flush                                                                                                                                                                                                     |
+| `OTEL_EXPORTER_OTLP_ENDPOINT` | No     | --                          | Enables OpenTelemetry audit spans when the optional OpenTelemetry packages are installed                                                                                                                                                               |
 
 
 ### HTTPS Enforcement
@@ -550,7 +556,13 @@ HARNESS_BASE_URL must use HTTPS (got "http://..."). If you need HTTP for local d
 
 ### Audit Logging
 
-All write operations (`harness_create`, `harness_update`, `harness_delete`, `harness_execute`) emit structured audit log entries to stderr. Each entry includes the tool name, resource type, operation, identifiers, and timestamp. This provides an audit trail without requiring external logging infrastructure.
+All write operations (`harness_create`, `harness_update`, `harness_delete`, `harness_execute`) emit structured audit events. The stderr sink is always active; additional sinks are enabled by configuration:
+
+- `HARNESS_AUDIT_FILE` appends newline-delimited JSON events for local collection.
+- `HARNESS_AUDIT_WEBHOOK_URL` posts batched events to an HTTPS webhook, optionally with `HARNESS_AUDIT_WEBHOOK_TOKEN`.
+- `OTEL_EXPORTER_OTLP_ENDPOINT` enables audit spans when the optional OpenTelemetry packages are installed.
+
+Each event includes the tool name, resource type, operation, identifiers, timestamp, and confirmation method. Audit sinks are best-effort telemetry; a webhook delivery issue is logged and does not retry or replay the mutating Harness operation.
 
 ## Tools Reference
 
@@ -558,6 +570,16 @@ The server exposes 11 MCP tools. Most API tools accept `org_id` and `project_id`
 
 **URL support:** Most API-facing tools accept a `url` parameter — paste a Harness UI URL and the server auto-extracts org, project, resource type, resource ID, pipeline ID, and execution ID. `harness_describe` does not accept `url`.
 
+**Scope support:** Resource types with account/org/project variants expose `supportedScopes` in `harness_describe`. Pass `resource_scope` when you need a specific level:
+
+- `resource_scope: "account"` sends only `accountIdentifier`.
+- `resource_scope: "org"` sends `accountIdentifier` and `orgIdentifier`.
+- `resource_scope: "project"` sends account, org, and project identifiers.
+
+Current multi-scope resources include `connector`, `service`, `environment`, `infrastructure`, `secret`, and `template`. If `resource_scope` is omitted, the registry uses the resource's default scope and configured defaults, except resources marked as optional scope may omit org/project unless explicitly passed. Harness URLs can also set the scope automatically when the path contains account-level or project-level context.
+
+**Structured output:** Every tool declares an MCP `outputSchema`. `harness_list` normalizes list-like Harness responses into object-shaped structured content so strict clients can validate it: top-level arrays become `{ "items": [...], "total": <count>, "page": <page> }`, and common wrapper keys such as `content`, `data`, `body`, `objects`, or `features` are hoisted to `items` when needed. The text response still contains the compact JSON payload returned to all clients.
+
 
 | Tool               | Description                                                                                                                                                                                                                                                                                                           |
 | ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
@@ -613,7 +635,8 @@ The server exposes 11 MCP tools. Most API tools accept `org_id` and `project_id`
   "resource_type": "pipeline",
   "action": "run",
   "resource_id": "my-pipeline",
-  "inputs": { "tag": "v1.2.3" }
+  "inputs": { "tag": "v1.2.3" },
+  "wait": true
 }
 ```
 
@@ -766,7 +789,8 @@ Use this sequence to reduce execution-time input errors:
       "action": "run",
       "resource_id": "deploy_app",
       "params": { "pipeline_branch": "feature/new-stage" },
-      "inputs": { "branch": "main" }
+      "inputs": { "branch": "main" },
+      "wait": true
     }
     ```
 4. **Optional: combine both**
@@ -774,6 +798,31 @@ Use this sequence to reduce execution-time input errors:
 
 If required fields are unresolved, the tool returns a pre-flight error with expected keys and suggested input sets. You can inspect available shorthand mappings with `harness_describe(resource_type="pipeline")` (`executeActions.run.inputShorthands`).
 
+### Pipeline Execute Wait Mode
+
+For `pipeline.run`, `pipeline.retry`, and `pipeline_v1.run`, pass `wait: true` to let the server poll until the execution reaches a terminal status. This keeps a pipeline launch and status check in one tool call instead of asking the client or LLM to run a polling loop.
+
+```json
+{
+  "resource_type": "pipeline",
+  "action": "run",
+  "resource_id": "deploy_app",
+  "inputs": { "branch": "main" },
+  "wait": true,
+  "wait_timeout_seconds": 900,
+  "wait_poll_interval_seconds": 5
+}
+```
+
+Wait mode behavior:
+
+- Default timeout is 600 seconds; allowed range is 10 seconds to 7200 seconds.
+- Initial poll interval defaults to 3 seconds, backs off by 1.5x, and caps at 30 seconds.
+- On success or failure, the response includes fields such as `execution_id`, `execution_status`, `execution_terminal`, `execution_elapsed_ms`, and `execution_poll_count`.
+- If the timeout fires, the original trigger still succeeded; the response includes `execution_timed_out: true` and `_wait.hint` with the last observed status.
+- If polling fails after the trigger succeeds, the response includes `_wait.error` and a recheck hint. Do not blindly rerun the pipeline unless you have confirmed the first execution is not running.
+- Failed terminal statuses include `_diagnose_hint` pointing to `harness_diagnose(resource_type="execution", options={execution_id: "..."})`.
+
 **Ask the AI DevOps Agent to create a pipeline:**
 
 ```json
@@ -991,7 +1040,7 @@ Harness pipelines can be stored in three ways:
 
 ## Resource Types
 
-188 resource types organized across 32 toolsets. Each resource type supports a subset of CRUD operations and optional execute actions.
+195 resource types organized across 32 toolsets. Each resource type supports a subset of CRUD operations and optional execute actions.
 
 ### Platform
 
@@ -1219,23 +1268,37 @@ Use `harness_execute(resource_type="pull_request", action="close", ...)` for an
 ### Chaos Engineering
 
 
-| Resource Type               | List | Get | Create | Update | Delete | Execute Actions        |
-| --------------------------- | ---- | --- | ------ | ------ | ------ | ---------------------- |
-| `chaos_experiment`          | x    | x   |        |        |        | `run`                  |
-| `chaos_probe`               | x    | x   |        |        |        | `enable`, `verify`     |
-| `chaos_experiment_template` | x    |     |        |        |        | `create_from_template` |
-| `chaos_infrastructure`      | x    |     |        |        |        |                        |
-| `chaos_experiment_variable` | x    |     |        |        |        |                        |
-| `chaos_experiment_run`      | x    | x   |        |        |        |                        |
-| `chaos_loadtest`            | x    | x   | x      |        | x      | `run`, `stop`          |
-| `chaos_k8s_infrastructure`  | x    | x   |        |        |        | `check_health`         |
-| `chaos_hub`                 | x    | x   |        |        |        |                        |
-| `chaos_fault`               | x    | x   |        |        |        |                        |
-| `chaos_network_map`         | x    | x   |        |        |        |                        |
-| `chaos_guard_condition`     | x    | x   |        |        |        |                        |
-| `chaos_guard_rule`          | x    | x   |        |        |        |                        |
-| `chaos_recommendation`      | x    | x   |        |        |        |                        |
-| `chaos_risk`                | x    | x   |        |        |        |                        |
+| Resource Type                | List | Get | Create | Update | Delete | Execute Actions        |
+| ---------------------------- | ---- | --- | ------ | ------ | ------ | ---------------------- |
+| `chaos_experiment`           | x    | x   | x      |        | x      | `run`, `stop`          |
+| `chaos_experiment_run`       |      | x   |        |        |        |                        |
+| `chaos_experiment_variable`  | x    |     |        |        |        |                        |
+| `chaos_component_variable`   |      | x   |        |        |        |                        |
+| `chaos_input_set`            | x    | x   | x      | x      | x      |                        |
+| `chaos_experiment_template`  | x    | x   |        |        | x      | `create_from_template` |
+| `chaos_probe`                | x    | x   | x      |        | x      | `enable`, `verify`     |
+| `chaos_probe_in_run`         | x    |     |        |        |        |                        |
+| `chaos_probe_template`       | x    | x   |        |        | x      |                        |
+| `chaos_infrastructure`       | x    |     |        |        |        |                        |
+| `chaos_k8s_infrastructure`   | x    | x   |        |        |        | `check_health`         |
+| `chaos_environment`          | x    |     |        |        |        |                        |
+| `chaos_hub`                  | x    | x   | x      | x      | x      |                        |
+| `chaos_hub_fault`            | x    |     |        |        |        |                        |
+| `chaos_fault`                | x    | x   |        |        | x      |                        |
+| `chaos_fault_template`       | x    | x   |        |        | x      |                        |
+| `chaos_fault_experiment_run` | x    |     |        |        |        |                        |
+| `chaos_action`               | x    | x   |        |        | x      |                        |
+| `chaos_action_template`      | x    | x   |        |        | x      |                        |
+| `chaos_loadtest`             | x    | x   | x      |        | x      | `run`, `stop`          |
+| `chaos_application_map`      | x    | x   |        |        |        |                        |
+| `discovered_namespace`       | x    |     |        |        |        |                        |
+| `discovered_service`         | x    |     |        |        |        |                        |
+| `discovered_network_map`     | x    |     |        |        |        |                        |
+| `chaos_guard_condition`      | x    | x   |        |        | x      |                        |
+| `chaos_guard_rule`           | x    | x   |        |        | x      | `enable`               |
+| `chaos_recommendation`       | x    | x   |        |        |        |                        |
+| `chaos_risk`                 | x    | x   |        |        |        |                        |
+| `chaos_dr_test`              | x    |     | x      |        |        |                        |
 
 
 ### Cloud Cost Management (CCM)
@@ -1446,15 +1509,15 @@ Inline PNG chart visualizations rendered from Harness data. These are metadata-o
 
 ## Toolset Filtering
 
-By default, 32 of 33 toolsets are enabled. One toolset (`ai-evals`) is opt-in — excluded by default to avoid polluting the resource list for users who don't need it.
+By default, 32 of 33 toolsets are enabled. The `iacm` toolset is opt-in because Harness IaCM APIs are project-scoped and add Terraform workspace/module concepts that many users do not need. The `ai-evals` toolset is default-enabled.
 
 ### Adding toolsets with `+` prefix
 
-Use the `+` prefix to explicitly include toolsets alongside all defaults (useful if a toolset becomes opt-in in the future):
+Use the `+` prefix to explicitly include opt-in toolsets alongside all defaults:
 
 ```bash
-# Explicitly include ai-evals alongside all defaults
-HARNESS_TOOLSETS=+ai-evals
+# Explicitly include IaCM alongside all defaults
+HARNESS_TOOLSETS=+iacm
 ```
 
 ### Removing default toolsets
@@ -1469,8 +1532,8 @@ HARNESS_TOOLSETS=-chaos,-ccm
 ### Combining + and -
 
 ```bash
-# Add ai-evals, remove chaos
-HARNESS_TOOLSETS=+ai-evals,-chaos
+# Add IaCM, remove chaos
+HARNESS_TOOLSETS=+iacm,-chaos
 ```
 
 ### Explicit allowlist
@@ -1506,7 +1569,7 @@ Available toolset names:
 | `pull-requests`         | pull_request, pr_reviewer, pr_comment, pr_check, pr_activity                                                                                                                                                                                                                                    |
 | `feature-flags`         | fme_workspace, fme_environment, fme_feature_flag, fme_feature_flag_definition, fme_rollout_status, fme_rule_based_segment, fme_rule_based_segment_definition, feature_flag                                                                                                                      |
 | `gitops`                | gitops_agent, gitops_application, gitops_cluster, gitops_repository, gitops_applicationset, gitops_repo_credential, gitops_app_event, gitops_pod_log, gitops_managed_resource, gitops_resource_action, gitops_dashboard, gitops_app_resource_tree                                               |
-| `chaos`                 | chaos_experiment, chaos_probe, chaos_experiment_template, chaos_infrastructure, chaos_experiment_variable, chaos_experiment_run, chaos_loadtest, chaos_k8s_infrastructure, chaos_hub, chaos_fault, chaos_network_map, chaos_guard_condition, chaos_guard_rule, chaos_recommendation, chaos_risk |
+| `chaos`                 | chaos_experiment, chaos_experiment_run, chaos_experiment_variable, chaos_component_variable, chaos_input_set, chaos_experiment_template, chaos_probe, chaos_probe_in_run, chaos_probe_template, chaos_infrastructure, chaos_k8s_infrastructure, chaos_environment, chaos_hub, chaos_hub_fault, chaos_fault, chaos_fault_template, chaos_fault_experiment_run, chaos_action, chaos_action_template, chaos_loadtest, chaos_application_map, discovered_namespace, discovered_service, discovered_network_map, chaos_guard_condition, chaos_guard_rule, chaos_recommendation, chaos_risk, chaos_dr_test |
 | `ccm`                   | cost_perspective, cost_breakdown, cost_timeseries, cost_summary, cost_recommendation, cost_anomaly, cost_anomaly_summary, cost_category, cost_account_overview, cost_filter_value, cost_recommendation_stats, cost_recommendation_detail, cost_commitment                                       |
 | `sei`                   | sei_metric, sei_productivity_metric, sei_dora_metric, sei_team, sei_team_detail, sei_org_tree, sei_org_tree_detail, sei_business_alignment, sei_ai_usage, sei_ai_adoption, sei_ai_impact, sei_ai_raw_metric                                                                                     |
 | `scs`                   | scs_artifact_source, artifact_security, scs_artifact_component, scs_artifact_remediation, scs_chain_of_custody, scs_compliance_result, code_repo_security, scs_sbom                                                                                                                             |
@@ -1519,6 +1582,7 @@ Available toolset names:
 | `settings`              | setting                                                                                                                                                                                                                                                                                         |
 | `visualizations`        | visual_timeline, visual_stage_flow, visual_health_dashboard, visual_pie_chart, visual_bar_chart, visual_timeseries, visual_architecture                                                                                                                                                         |
 | `ai-evals`              | eval_dataset, eval_dataset_item, evaluation, eval_run, eval_run_item, eval_run_by_eval, eval_metric, eval_metric_set, eval_metric_set_entry, eval_suite, eval_suite_evaluation, eval_suite_run, eval_target, eval_model, eval_annotation, eval_analytics, eval_git_settings, eval_registry_item |
+| `iacm` *(opt-in)*       | iacm_workspace, iacm_resource, iacm_module, iacm_workspace_costs, iacm_activity_resource_change                                                                                                                                                                                                 |
 
 
 ## Architecture
@@ -1537,7 +1601,7 @@ Available toolset names:
                  +--------v---------+
                 |    Registry       |  <-- Declarative resource definitions
                 |  32 Toolsets      |      (data files, not code)
-                |  188 Resource Types|
+                |  195 Resource Types|
                  +--------+---------+
                           |
                  +--------v---------+
@@ -1553,10 +1617,11 @@ Available toolset names:
 
 1. **Tools** are generic verbs: `harness_list`, `harness_get`, etc. They accept a `resource_type` parameter that routes to the correct API endpoint.
 2. **The Registry** maps each `resource_type` to a `ResourceDefinition` — a declarative data structure specifying the HTTP method, URL path, path/query parameter mappings, and response extraction logic.
-3. **Dispatch** resolves the resource definition, builds the HTTP request (path substitution, query params, scope injection), calls the Harness API through `HarnessClient`, and extracts the relevant response data.
+3. **Dispatch** resolves the resource definition, builds the HTTP request (path substitution, query params, `resource_scope`-aware account/org/project injection), calls the Harness API through `HarnessClient`, and extracts the relevant response data.
 4. **Toolset filtering** (`HARNESS_TOOLSETS`) controls which resource definitions are loaded into the registry at startup.
-5. **Deep links** are automatically appended to responses, providing direct Harness UI URLs for every resource.
-6. **Compact mode** strips verbose metadata from list results, keeping only actionable fields (identity, status, type, timestamps, deep links) to minimize token usage.
+5. **Structured output** is declared with MCP `outputSchema`; `harness_list` coerces arrays and common list wrappers into object-shaped `structuredContent` for strict clients.
+6. **Deep links** are automatically appended to responses, providing direct Harness UI URLs for every resource.
+7. **Compact mode** strips verbose metadata from list results, keeping only actionable fields (identity, status, type, timestamps, deep links) to minimize token usage.
 
 ### Adding a New Resource Type
 
@@ -1643,7 +1708,7 @@ src/
       ccm.ts
       access-control.ts
       ...
-  tools/                            # 10 generic MCP tools
+  tools/                            # 11 generic MCP tools
     harness-list.ts
     harness-get.ts
     harness-create.ts
@@ -1654,6 +1719,7 @@ src/
     harness-diagnose.ts
     harness-describe.ts
     harness-status.ts
+    harness-schema.ts
 
   resources/                        # MCP resource providers
     pipeline-yaml.ts
@@ -1820,10 +1886,13 @@ The Harness MCP server pairs well with **[Harness Skills](https://github.com/har
 | HTTP `Invalid request`                                                           | Invalid JSON body or request body exceeded `HARNESS_MAX_BODY_SIZE_MB`                                | Validate JSON payload size/shape; increase `HARNESS_MAX_BODY_SIZE_MB` if needed                                                      |
 | `Unknown resource_type "..."` from tools                                         | Resource type is misspelled or filtered out via `HARNESS_TOOLSETS`                                   | Call `harness_describe` (with optional `search_term`) to discover valid types                                                        |
 | `Missing required field "... for path parameter ..."`                            | A project/org scoped call is missing identifiers                                                     | Set `HARNESS_ORG`/`HARNESS_PROJECT` or pass `org_id`/`project_id` per tool call                                                      |
+| `resource_scope "org" requires org_id...` or `resource_scope "project" requires project_id...` | A multi-scope resource was forced to org/project scope without enough identifiers                     | Pass the missing `org_id`/`project_id`, configure `HARNESS_ORG`/`HARNESS_PROJECT`, or use `resource_scope: "account"` when supported |
 | `Read-only mode is enabled ... operations are not allowed`                       | `HARNESS_READ_ONLY=true` blocks create/update/delete/execute                                         | Set `HARNESS_READ_ONLY=false` if write operations are intended                                                                       |
 | Pipeline run fails pre-flight with unresolved required inputs                    | Provided `inputs` did not cover required runtime placeholders                                        | Fetch `runtime_input_template`, supply missing simple keys, or use `input_set_ids` for structural inputs                             |
 | Pipeline CI shorthand (`branch`, `tag`, `pr_number`, `commit_sha`) did not apply | `inputs.build` was already provided, so shorthand expansion was intentionally skipped                | Remove `inputs.build` to use shorthand expansion, or keep full explicit `build` structure                                            |
 | Pipeline run loaded the wrong YAML revision                                     | The pipeline definition is stored in Git and the run did not specify the desired pipeline branch      | Pass `params.pipeline_branch` on the `run` action; this maps to Harness `pipelineBranchName`                                         |
+| `wait: true` returned `_wait.error`                                              | The pipeline trigger succeeded, but server-side polling failed                                       | Recheck the `execution_id` with `harness_get(resource_type="execution", ...)` before deciding whether to rerun                        |
+| `wait: true` returned `execution_timed_out: true`                                | The execution did not reach a terminal status before `wait_timeout_seconds`                          | Use the returned `execution_id` to recheck status or diagnose the still-running execution                                             |
 | Execution logs are empty or blob downloads return 403                           | Harness-hosted log blob URLs require the configured Harness client/auth path, especially for internal or self-managed hosts | Keep `HARNESS_BASE_URL` pointed at the target Harness host and use `harness_get(resource_type="execution_log", ...)` or `harness_diagnose(..., include_logs=true)` rather than bypassing the MCP client |
 | `Operation declined by user`                                                     | User declined the elicitation confirmation dialog                                                    | The user chose not to proceed — verify the operation details and retry if intended                                                   |
 | `body.template_yaml (or body.yaml) is required` for template create/update       | Template APIs expect full YAML payload                                                               | Provide full `template_yaml` string in `body`; for deletes, pass `version_label` to delete one version (omit to delete all versions) |

package/build/client/types.d.ts

@@ -58,5 +58,10 @@ export interface RequestOptions {
     /** Retry policy from OperationPolicy. When "do_not_retry", transient errors
      *  (5xx, timeouts) throw immediately instead of retrying. */
     retryPolicy?: "safe" | "idempotency_key_required" | "do_not_retry";
+    /** Internal tracing metadata. Never serialized into HTTP headers/query/body. */
+    tracing?: {
+        /** API name that produced this concrete request path. */
+        route?: string;
+    };
 }
 //# sourceMappingURL=types.d.ts.map

package/build/client/types.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxC,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mCAAmC;AACnC,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAC1E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,gFAAgF;IAChF,OAAO,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC5B;0FACsF;IACtF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;iEAC6D;IAC7D,WAAW,CAAC,EAAE,MAAM,GAAG,0BAA0B,GAAG,cAAc,CAAC;CACpE"}
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,+CAA+C;AAC/C,MAAM,WAAW,eAAe,CAAC,CAAC;IAChC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxC,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,EAAE,OAAO,CAAC;CACpB;AAED,yDAAyD;AACzD,MAAM,WAAW,mBAAmB,CAAC,CAAC;IACpC,MAAM,EAAE,SAAS,GAAG,OAAO,GAAG,SAAS,CAAC;IACxC,IAAI,CAAC,EAAE;QACL,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;QACd,aAAa,CAAC,EAAE,MAAM,CAAC;QACvB,UAAU,CAAC,EAAE,MAAM,CAAC;QACpB,SAAS,CAAC,EAAE,MAAM,CAAC;QACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;QAClB,KAAK,CAAC,EAAE,OAAO,CAAC;KACjB,CAAC;IACF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,aAAa,CAAC,EAAE,MAAM,CAAC;CACxB;AAED,mCAAmC;AACnC,MAAM,WAAW,qBAAqB,CAAC,CAAC;IACtC,KAAK,CAAC,EAAE,CAAC,EAAE,CAAC;IACZ,IAAI,CAAC,EAAE,MAAM,CAAC;IACd,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB;AAED,MAAM,WAAW,cAAc;IAC7B,MAAM,CAAC,EAAE,KAAK,GAAG,MAAM,GAAG,KAAK,GAAG,OAAO,GAAG,QAAQ,CAAC;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,oGAAoG;IACpG,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,EAAE,GAAG,SAAS,CAAC,CAAC;IAC1E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACjC,uFAAuF;IACvF,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,oEAAoE;IACpE,OAAO,CAAC,EAAE,OAAO,CAAC;IAClB,oFAAoF;IACpF,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,gEAAgE;IAChE,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,iGAAiG;IACjG,YAAY,CAAC,EAAE,MAAM,GAAG,QAAQ,CAAC;IACjC,gFAAgF;IAChF,OAAO,CAAC,EAAE,SAAS,GAAG,KAAK,CAAC;IAC5B;0FACsF;IACtF,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B;iEAC6D;IAC7D,WAAW,CAAC,EAAE,MAAM,GAAG,0BAA0B,GAAG,cAAc,CAAC;IACnE,gFAAgF;IAChF,OAAO,CAAC,EAAE;QACR,yDAAyD;QACzD,KAAK,CAAC,EAAE,MAAM,CAAC;KAChB,CAAC;CACH"}

package/build/data/schemas/v0/pipeline.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../../src/data/schemas/v0/pipeline.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CAqkjH/B,CAAC;AACF,eAAe,MAAM,CAAC"}
+{"version":3,"file":"pipeline.d.ts","sourceRoot":"","sources":["../../../../src/data/schemas/v0/pipeline.ts"],"names":[],"mappings":"AAGA,QAAA,MAAM,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,GAAG,CA0sjH/B,CAAC;AACF,eAAe,MAAM,CAAC"}