feat(mcp-server): add listWorkflows tool (PRD-736)

[christophebrun-forest]

MS4 of PRD-49 — listWorkflows MCP tool

Exposes MCP-enabled workflows to LLM clients through a new listWorkflows tool in @forestadmin/mcp-server, so a client can discover workflows in its context before triggering one.

fixes PRD-736

What it does

• New tool listWorkflows with args { collectionName?: string }, registered like the existing list / update / executeAction tools (registerToolWithLogging, read-only).
• Calls the Forest server MS3 endpoint GET /api/workflow-orchestrator/workflows over the HTTP contract — Bearer forestServerToken + forest-rendering-id header + optional collectionName query. No private-api import.
• Identity read from extra.authInfo.extra (forestServerToken + renderingId).
• Returns [{ workflowId, name, collectionName }]. Errors (403/404/…) map to MCP tool errors via the typed errors of ServerUtils + registerToolWithLogging.

Implementation

forestadmin-client

• WorkflowsService + ForestHttpApi.listMcpEnabledWorkflows (transport, via ServerUtils.queryWithBearerToken)
• New types McpWorkflow, ListMcpWorkflowsParams, WorkflowsServiceInterface

mcp-server

• listWorkflows tool + http-client wiring (WorkflowsService)
• Extracted shared getAuthContext util (reused by activity-logs-creator)
• Server wiring: ToolName, allTools, allToolNames, SAFE_ARGUMENTS_FOR_LOGGING

Notes

• description is intentionally not returned — deferred to a separate product ticket (excluded from MS3 on purpose).
• No withActivityLog on this read-only discovery tool.

Tests

• forestadmin-client: 288 pass (WorkflowsService + transport)
• mcp-server: 620 pass (+ new list-workflows tool tests)
• Lint clean; manual test validated via MCP Inspector and Claude Desktop.

🤖 Generated with Claude Code

Note

Add listWorkflows MCP tool and in-process agent dispatcher to MCP server

• Adds a new listWorkflows MCP tool in list-workflows.ts that calls forestServerClient.listMcpWorkflows with optional collectionName filtering, returning MCP-enabled workflows as JSON.
• Introduces an in-process dispatcher (InProcessDispatcher) that routes MCP tool requests directly to the agent's Koa stack via light-my-request, bypassing the network while still running JWT auth and permission checks.
• Refactors all tool declaration functions to accept a unified ToolContext object (with forestServerClient, logger, collectionNames, and optional agentDispatcher) and pass agentDispatcher through to buildClient/buildClientWithActions.
• Adds WorkflowsService to ForestAdminClient and wires it through the MCP server's HTTP client so listMcpWorkflows is available server-side.
• Improves getActionForm tool responses to include per-field description and allowedValues (normalized to {value, label}) for multiple-choice widgets.
• Risk: In-process dispatch skips any host-app middleware mounted before the agent router; tool calls now target agentUrl (or the in-process stack) instead of the public api_endpoint.

^{Macroscope summarized 8a9449b.}

[linear-code]

PRD-736

[qltysh]

7 new issues

Tool	Category	Rule	Count
qlty	Structure	Function with high complexity (count = 12): declareGetActionFormTool	3
qlty	Structure	Function with many returns (count = 4): fetchCapabilities	2
qlty	Structure	Function with many parameters (count = 14): constructor	2

[qltysh]

Coverage Impact

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

Modified Files with Diff Coverage (53)

Rating	File	% Diff	Uncovered Line #s
	packages/agent/src/utils/forest-schema/generator-fields.ts	100.0%
	packages/agent-client/src/action-fields/field-form-states.ts	100.0%
	...agent-client/src/action-fields/action-field-multiple-choice.ts	100.0%
	packages/agent-testing/src/forest-admin-client-mock.ts	50.0%	66
	packages/agent/src/utils/query-string.ts	100.0%
	packages/agent/src/agent.ts	100.0%
	packages/agent-client/src/domains/collection.ts	100.0%
	packages/agent-client/src/http-requester.ts	100.0%
	packages/agent/src/embedded-workflow-executor.ts	100.0%
	...ages/datasource-customizer/src/decorators/binary/collection.ts	100.0%
	packages/agent/src/mcp-in-process-dispatcher.ts	100.0%
	packages/datasource-customizer/src/typing-generator.ts	100.0%
	packages/agent-client/src/index.ts	100.0%
	packages/agent/src/framework-mounter.ts	100.0%
	packages/agent-client/src/action-fields/action-field.ts	100.0%
	packages/mcp-server/src/tools/associate.ts	100.0%
	packages/datasource-mongoose/src/utils/schema/fields.ts	100.0%
	packages/mcp-server/src/http-client/index.ts	100.0%
	packages/forestadmin-client/src/forest-admin-client-with-cache.ts	100.0%
	packages/forestadmin-client/src/workflows/index.ts	100.0%
	packages/forestadmin-client/src/index.ts	100.0%
	packages/mcp-server/src/forest-oauth-provider.ts	100.0%
	packages/mcp-server/src/http-client/mcp-http-client.ts	100.0%
	packages/mcp-server/src/tools/create.ts	100.0%
	packages/mcp-server/src/tools/delete.ts	100.0%
	packages/mcp-server/src/in-process-http-requester.ts	100.0%
	packages/forestadmin-client/src/build-application-services.ts	100.0%
	packages/mcp-server/src/server.ts	100.0%
	packages/datasource-toolkit/src/validation/type-getter.ts	100.0%
	packages/forestadmin-client/src/permissions/forest-http-api.ts	100.0%
	packages/mcp-server/src/utils/activity-logs-creator.ts	100.0%
	packages/mcp-server/src/tools/execute-action.ts	100.0%
	packages/mcp-server/src/utils/agent-caller.ts	100.0%
	packages/workflow-executor/src/build-workflow-executor.ts	100.0%
	packages/plugin-flattener/src/flatten-column/helpers.ts	100.0%
	packages/mcp-server/src/tools/list.ts	100.0%
	packages/plugin-flattener/src/flatten-column/customization.ts	100.0%
	packages/mcp-server/src/tools/update.ts	100.0%
	packages/mcp-server/src/tools/get-action-form.ts	100.0%
	packages/mcp-server/src/tools/list-workflows.ts	100.0%
	packages/mcp-server/src/tools/describe-collection.ts	100.0%
	packages/mcp-server/src/tools/dissociate.ts	100.0%
	packages/mcp-server/src/utils/normalize-agent-url.ts	100.0%
	...ages/workflow-executor/src/adapters/agent-client-agent-port.ts	100.0%
	packages/workflow-executor/src/crypto/credential-encryption.ts	100.0%
	packages/mcp-server/src/utils/auth-context.ts	100.0%
	packages/workflow-executor/src/adapters/step-definition-mapper.ts	100.0%
	packages/workflow-executor/src/cli-core.ts	100.0%
	packages/mcp-server/src/tools/list-related.ts	100.0%
	packages/workflow-executor/src/stores/schema-migrations.ts	100.0%
	...workflow-executor/src/executors/update-record-step-executor.ts	100.0%
	...-executor/src/executors/trigger-record-action-step-executor.ts	100.0%
	packages/workflow-executor/src/types/validated/collection.ts	100.0%
	Total	99.6%

🤖 Increase coverage with AI coding...

In the `feature/prd-736-mcp-ms4-listworkflows-tool` branch, add test coverage for this new code:
- `packages/agent-testing/src/forest-admin-client-mock.ts` -- Line 66

🚦 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.