(CODUX-105) Expose MCP node-flow automation

[numnx]

🧩 Task: Expose MCP node-flow automation

Automated task PR opened by Code UX for T03.

📋 Summary

Sprint: Sprint 173 · Repeatable node flows · Task: T03

Implement repeatable n8n-style node workflows in Code UX with durable flow definitions, node invocation execution, MCP automation, agent skill attachment, scheduler support, an editable dashboard canvas, and current documentation.

🤖 Model & Provider

Provider	Codex CLI
Model	gpt-5.5

⏱️ Timing

Started	2026-07-07 11:13:06 UTC
Finished	2026-07-07 11:54:44 UTC
Duration	41m 38s

📊 Token Usage

Metric	Value
Input tokens	242,679
Cached input tokens	9,200,512
Output tokens	27,173
Total tokens	9,470,364
Invocations	2
Tool calls	117
Active time	11m 39s

Included usage estimate (subscription/local login): $6.63

✅ QA Review

⏳ QA review runs after this PR is opened. Check the task card in the dashboard for the outcome once it lands.

📝 Full Task Prompt

## Objective
Expose node workflows through MCP management tooling, including automated flow creation from structured graph specs, runtime execution, and attaching flows as skills to agent presets.

## Scope
- Edit `src/contracts/mcp-tool-definitions.ts`
- Edit `src/contracts/internal-management-types.ts`
- Edit `src/api/mcp/tool-registry.ts`
- Edit `src/mcp/management-tool-handler.ts`
- Create `src/mcp/management/node-flow-actions.ts`
- Edit `src/mcp/management/agent-actions.ts` only if needed to expose or preserve agent `mcpAccess` updates for node-flow skill attachment
- Edit `src/repositories/settings-defaults.ts`, `src/repositories/settings-sanitizer.ts`, and related tests if the default MCP tool toggle list must include `manage_node_flows`
- Add backend tests under `tests/backend/mcp/` and `tests/backend/services/agent-mcp-access.test.ts` if tool access changes are required

## Implementation Requirements
1. Add `manage_node_flows` to the MCP tool definitions with actions `list`, `get`, `create`, `update`, `delete`, `validate`, `run`, `list_runs`, `get_run`, `attach_to_agent`, and `detach_from_agent`.
2. Add a typed `ManageNodeFlowsArgs` contract supporting `projectId`, `flowId`, `name`, `description`, `graph`, `widgets`, `input`, `agentPresetId`, `skillAlias`, and destructive-action approval where deletion is involved.
3. Implement `NodeFlowActions` using `NodeFlowService` and `NodeFlowRuntimeService`; normalize blank strings, reject malformed graphs before repository writes, and return compact JSON envelopes consistent with other management actions.
4. Wire `manage_node_flows` through `ManagementToolHandler`, `ToolRegistry`, MCP availability, and default/internal MCP tool toggles so specialist agents can be granted this tool like existing orchestration tools.
5. Add or update agent management behavior so an agent can be configured with access to `manage_node_flows` and attached node-flow skills without losing existing `mcpAccess`, memory config, labels, avatar config, provider, or model settings.
6. Include senior-grade helper text in the tool description explaining that agents should build Code UX-adapted node flows, not clone n8n one-to-one, and should provide dynamic widget schemas for editable node fields.
7. Add regression tests covering tool registration, action routing, validation failure output, run delegation, deletion approval, and attach/detach skill behavior.

## Constraints
- Do not bypass the node-flow validation and runtime services.
- Do not expose raw secret values in MCP responses.
- Do not make `manage_node_flows` available to runtime roles that do not already receive project-manager management tools.
- Preserve existing `manage_agents`, `manage_scheduler`, and deprecated `manage_code_ux` behavior.

## Verification
- Run focused MCP tests for tool definitions, registry dispatch, management routing, and node-flow actions.
- Run `pnpm run test:backend`.
- Run `pnpm run lint` and confirm the MCP contract remains strictly typed.

🌿 Branch Info

Base: feature/CODUX-173-repeatable-node-flows
Head: task/feature-codux-173-repeatable-node-flows-t03-codex-mrajvq2e

---

🤖 Generated by Code UX