kandev/docs/plans/workflow-mcp-export/plan.md

spec, created, status

spec	created	status
docs/specs/integrations/requirements/external-mcp.md	2026-08-19	done

Implementation Plan: Workflow MCP Export

Overview

Add one read-only MCP tool for a single workflow. Reuse the existing workflow export service and the current MCP JSON-text bridge.

The change adds no new export format or persistence path. A second task updates the public MCP reference after the contract is complete.

Confirmed implementation path

workflow.Service.ExportWorkflow already builds the complete WorkflowExport document. The backend wires its provider to the scoped task service.

The MCP server already converts backend response objects to indented JSON text. import_workflow_kandev accepts that JSON text as its document argument.

This path gives a direct round trip for documents within the existing 1 MiB import limit. No new serializer is necessary.

Backend

WebSocket action and dispatcher

• apps/backend/pkg/websocket/actions.go: add ActionMCPExportWorkflow = "mcp.export_workflow" beside the workflow configuration actions.
• apps/backend/internal/mcp/handlers/handlers.go: register the action when the workflow service is available.

Backend export handler

• apps/backend/internal/mcp/handlers/config_workflow_handlers.go: add handleExportWorkflow.
• Decode and require workflow_id.
• Call h.workflowSvc.ExportWorkflow(ctx, workflowID).
• Return the WorkflowExport object through ws.NewResponse.
• Return a generic tool error for service errors. Do not include a partial document or internal error details.

MCP tool and bridge

• apps/backend/internal/mcp/server/config_handlers.go: register export_workflow_kandev in the workflow configuration group.
• Define one required string argument named workflow_id.
• Add exportWorkflowHandler and forward the request through ActionMCPExportWorkflow.
• Keep the shared forwardToBackend conversion. It returns the export object as indented JSON MCP text.

Agent configuration context

• apps/backend/config/prompts/config-context.md: list the export tool, its required argument, and its JSON result.
• State that the result can be the document input for import_workflow_kandev.

Frontend

No frontend code changes are in scope. The existing static tool preview is not the live MCP contract.

Public documentation

• docs/public/automation-and-mcp.md: add workflow export to the external MCP group and update the live tool count from 35 to 36.
• Keep the static-preview caveat. Add export_workflow_kandev to its list of omitted tools.
• docs/public/coverage.json: add export_workflow_kandev to the workflow MCP tool coverage list.

Primary content type: reference.

Tests

• What: The tool is registered on configuration and external surfaces, but not task or Office surfaces. File: apps/backend/internal/mcp/server/server_test.go. How: Inspect the registered tool names and update the exact surface counts.
• What: The server requires workflow_id, sends mcp.export_workflow, and returns the backend envelope as JSON text. File: apps/backend/internal/mcp/server/config_handlers_test.go. How: Call the registered tool against the existing backend stub. Decode its MCP text as WorkflowExport.
• What: The backend exports one complete portable workflow and does not change source state. File: apps/backend/internal/mcp/handlers/config_workflow_handlers_test.go. How: Seed a workflow and steps through the existing test service. Call the backend handler and compare the portable fields.
• What: The exported MCP response can enter the existing import path unchanged. File: apps/backend/internal/mcp/handlers/config_workflow_handlers_test.go. How: Export one workflow, use its JSON payload as the import document for another workspace, and compare imported workflow behavior.
• What: Missing identifiers and export service errors return tool errors without documents. Files: apps/backend/internal/mcp/server/config_handlers_test.go and apps/backend/internal/mcp/handlers/config_workflow_handlers_test.go. How: Use missing arguments and an unknown workflow ID.
• What: The configuration context references a registered tool. File: apps/backend/internal/mcp/server/sysprompt_sync_test.go. How: Run the existing exact-name synchronization test after the context update.
• What: Public documentation remains structurally valid. Files: docs/public/automation-and-mcp.md and docs/public/coverage.json. How: Run both public-document validation scripts.

No browser E2E test is necessary. The feature changes an MCP contract and agent context, not rendered UI behavior.

Verification Results

• go test ./internal/mcp/handlers ./internal/mcp/server ./pkg/websocket: passed, 696 tests across 3 packages.
• PR fixup: the annotation and whitespace-ID regression tests failed before the fix and passed after it.
• go test ./internal/mcp/handlers ./internal/mcp/server ./pkg/websocket: passed, 698 tests across 3 packages after fixup.
• go test ./internal/sysprompt: passed.
• make -C apps/backend lint: passed with 0 issues after fixup.
• node --test scripts/validate-public-docs.test.mjs: passed 61 tests with 0 failures.
• node scripts/validate-public-docs.mjs: validated 41 published docs pages.
• git diff --check: passed.

Implementation Waves And Parallel Candidates

Wave 1:

• Task 01: Expose workflow export through MCP - done.

Wave 2:

• Task 02: Document MCP workflow export - done.

Execution is sequential in the primary conversation. No subagents are authorized.

Risks and out of scope

• The import handler rejects documents larger than 1 MiB. This plan does not change that limit.
• The existing exporter owns field fidelity. The MCP handler must not duplicate export assembly or add a second serializer.
• The existing workflow provider owns authorization. The MCP handler must pass the scoped request context unchanged.
• A workspace-level batch export tool is out of scope.
• The static External MCP settings preview remains incomplete and non-authoritative.