feat(mcp-server): add triggerWorkflow tool (PRD-738)

[christophebrun-forest]

MS6 — triggerWorkflow MCP tool

Exposes the triggerWorkflow tool so an LLM can start a run on a specific record and get a runId back. Non-blocking by design — the run continues server-side and status is observed via getWorkflowRun (MS8).

fixes PRD-738

What's in it

• New tool packages/mcp-server/src/tools/trigger-workflow.ts: args { workflowId, recordId }, identity from the OAuth auth context (forestServerToken + renderingId), wrapped in withActivityLog (action triggerWorkflow) so MCP-triggered runs get a local MCP audit entry under the caller.
• forestadmin-client: WorkflowsService.triggerMcpWorkflow + ForestHttpApi call the MS5 endpoint over HTTP (POST /api/workflow-orchestrator/mcp-workflows/:workflowId/start, body { recordId }, forest-rendering-id header). No private-api internals imported.
• Server errors bubble up as tool errors (isError: true) with the server's message passed through — 404 (not MCP-enabled / unknown workflow), 409 (run already ongoing, no resume), 403 (unauthorized). No status-specific remapping is done client-side. recordId not validated at trigger time.
• collectionId is derived server-side (MS5, aligned on the webhook), so the tool contract stays { workflowId, recordId }.

Tests

mcp-server 631/631, forestadmin-client 292/292, lint clean.

Stacking & dependencies

• Stacked on feat(mcp-server): add listWorkflows tool (PRD-736) #1771 (MS4 listWorkflows) — this branch was cut from PRD-736 since its WorkflowsService/http-client plumbing isn't in the integration branch yet. Until feat(mcp-server): add listWorkflows tool (PRD-736) #1771 merges into feature/prd-49-…, this PR's diff also shows the MS4 commit; it narrows to MS6-only afterwards. Review/merge feat(mcp-server): add listWorkflows tool (PRD-736) #1771 first.
• Server-side counterpart MS5 (PRD-737) is a separate PR on forestadmin-server; needed for end-to-end. Unit tests here are mocked against the HTTP contract.

🤖 Generated with Claude Code

Note

Add triggerWorkflow tool to the MCP server

• Registers a new triggerWorkflow MCP tool in server.ts that lets agents trigger Forest Admin workflow runs, implemented in trigger-workflow.ts.
• The tool validates the requested workflowId against the list of MCP-enabled workflows, then POSTs to /api/workflow-orchestrator/mcp-workflows/{workflowId}/start via a new triggerMcpWorkflow method on WorkflowsService.
• Activity logs are emitted for each invocation, classified as write operations.
• The HTTP path for listMcpEnabledWorkflows is updated from /workflows to /mcp-workflows.
• Behavioral Change: WorkflowsService.listMcpEnabledWorkflows now throws if the configured transport does not implement the method, instead of calling undefined.

^{Macroscope summarized 5b0499c.}

[linear-code]

PRD-738

[qltysh]

1 new issue

Tool	Category	Rule	Count
qlty	Structure	Function with many parameters (count = 4): triggerMcpWorkflow	1

[macroscopeapp]

🟡 Medium src/forest-admin-client-with-cache.ts:36

Adding workflowsService in the middle of the ForestAdminClientWithCache constructor's positional argument list breaks existing JavaScript consumers that instantiate this class directly. Existing calls using the previous argument order still run, but each argument after the insertion point shifts by one: authService receives the model-customization service, and eventsHandler becomes undefined, causing runtime failures. Consider appending the new dependency at the end of the parameter list instead of inserting it in the middle.

    public readonly activityLogsService: ActivityLogsService,
-    public readonly workflowsService: WorkflowsService,
    public readonly authService: ForestAdminAuthServiceInterface,
    public readonly modelCustomizationService: ModelCustomizationService,
    public readonly mcpServerConfigService: McpServerConfigService,
    protected readonly eventsSubscription: BaseEventsSubscriptionService,
    protected readonly eventsHandler: RefreshEventsHandlerService,
+    public readonly workflowsService: WorkflowsService,
  ) {}

🚀 Reply "fix it for me" or copy this AI Prompt for your agent:

In file @packages/forestadmin-client/src/forest-admin-client-with-cache.ts around lines 36-42:

Adding `workflowsService` in the middle of the `ForestAdminClientWithCache` constructor's positional argument list breaks existing JavaScript consumers that instantiate this class directly. Existing calls using the previous argument order still run, but each argument after the insertion point shifts by one: `authService` receives the model-customization service, and `eventsHandler` becomes `undefined`, causing runtime failures. Consider appending the new dependency at the end of the parameter list instead of inserting it in the middle.

[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/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/tools/trigger-workflow.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.