feat(mcp-server): add getWorkflowRun tool (PRD-740)

[christophebrun-forest]

Description

Story MS8 of PRD-49 · Iteration 4 (observation).

Exposes the getWorkflowRun polling tool so the LLM can observe a run's status, closing the discover (listWorkflows) → trigger (triggerWorkflow) → poll (getWorkflowRun) loop.

Report-only in v1: a run parked on a human-gated step reports waitingForHumanInput: true but is not resumable via MCP — such runs are finished from the Forest UI (resume tracked in PRD-441).

Changes

@forestadmin/forestadmin-client

• New types WorkflowRunStep, WorkflowRunStatus, GetMcpWorkflowRunParams; getMcpWorkflowRun added to WorkflowsServiceInterface and ForestAdminServerInterface
• ForestHttpApi.getMcpWorkflowRun() → GET /api/workflow-orchestrator/mcp-workflows/runs/:runId (rendering-id header, url-encoded runId)
• WorkflowsService.getMcpWorkflowRun() delegation + public exports

@forestadmin/mcp-server

• New getWorkflowRun tool (readOnlyHint: true, zod arg runId: string; no activity log since read-only)
• getWorkflowRun on the ForestServerClient http-client
• Registration wiring in server.ts (ToolName union, allTools, allToolNames, SAFE_ARGUMENTS_FOR_LOGGING)

Acceptance criteria

• Returns runState, currentStep, waitingForHumanInput, terminal result/error, scoped to the caller
• Human-gated runs report waitingForHumanInput: true, not resumable via MCP (v1)
• Unknown/forbidden runId → tool error 404/403

Tests

forestadmin-client (299) + mcp-server (667) green; lint + build clean on both packages. Added coverage for the HTTP path/headers/url-encode, service delegation, http-client delegation, and the tool (registration, identity+args forwarding, human-gated reporting, missing auth, 404, 403).

Notes

• Depends on the MS7 server endpoint (PRD-739, forestadmin-server PR #8407).
• ⚠️ Assumes a top-level (non JSON:API-wrapped) response payload, consistent with the existing workflow endpoints — to confirm against the live MS7 response.

fixes PRD-740

🤖 Generated with Claude Code

Note

Add getWorkflowRun MCP tool to fetch workflow run status

• Adds a new getWorkflowRun tool in packages/mcp-server/src/tools/get-workflow-run.ts that accepts a runId, extracts auth context, and returns the workflow run status as JSON.
• Adds getMcpWorkflowRun to WorkflowsService and ForestHttpApi, performing a GET to /api/workflow-orchestrator/mcp-workflows/runs/{runId} with bearer token and rendering ID header.
• Extends WorkflowsServiceInterface, ForestAdminServerInterface, and ForestServerClient with the new method signature, and exports the new WorkflowRunStatus, WorkflowRunStep, and GetMcpWorkflowRunParams types from forestadmin-client.

^{Macroscope summarized e02cf17.}

[linear-code]

PRD-740

[qltysh]

Coverage Impact

Unable to calculate total coverage change because base branch coverage was not found.

Modified Files with Diff Coverage (6)

Rating	File	% Diff	Uncovered Line #s
	packages/mcp-server/src/tools/get-workflow-run.ts	100.0%
	packages/agent-testing/src/forest-admin-client-mock.ts	100.0%
	packages/forestadmin-client/src/workflows/index.ts	100.0%
	packages/mcp-server/src/http-client/mcp-http-client.ts	100.0%
	packages/mcp-server/src/server.ts	100.0%
	packages/forestadmin-client/src/permissions/forest-http-api.ts	100.0%
	Total	100.0%

🚦 See full report on Qlty Cloud »

🛟 Help

• Diff Coverage: Coverage for added or modified lines of code (excludes deleted files). Learn more.

• Total Coverage: Coverage for the whole repository, calculated as the sum of all File Coverage. Learn more.

• File Coverage: Covered Lines divided by Covered Lines plus Missed Lines. (Excludes non-executable lines including blank lines and comments.)

  • Indirect Changes: Changes to File Coverage for files that were not modified in this PR. Learn more.