feat(api): agent-friendly flow graph endpoints

[Empreiteiro]

Summary

Adds four endpoints under /api/v1/flows/{flow_id}/{components,edges} so AI agents (and any HTTP client) can inspect and edit a flow without round-tripping the full ReactFlow payload stored in Flow.data.

Method	Path	Purpose
GET	/flows/{flow_id}/components	List nodes with inputs/outputs and handle types
GET	/flows/{flow_id}/edges	List edges with source/target endpoints + types
POST	/flows/{flow_id}/components	Append a component from the catalog
POST	/flows/{flow_id}/edges	Connect two components (with type-compatibility check)

The write endpoints are thin wrappers over the existing pure helpers in lfx.graph.flow_builder (add_component, add_connection), which already handle ID generation, ReactFlow handle encoding (œ-quoted JSON), idempotency, and types_compatible validation.

LangflowClient (the MCP HTTP client) gets typed methods for all four operations, so MCP server tools and other Python consumers don't need to assemble the URLs by hand.

Why

Today, an agent that wants to add a node has to PATCH the entire Flow.data blob — which means parsing it, mutating nested ReactFlow structures, and writing back. This burns context and any schema drift breaks the whole flow. Granular endpoints reduce blast radius and produce localized error messages (e.g. Type mismatch: output 'model_output' produces ['LanguageModel'], but input 'input_value' accepts ['Message']).

The catalog endpoint already exists (GET /api/v1/all); this PR does not duplicate it.

Notable design choices

• No new validation logic. Edge type-compatibility is delegated to the existing types_compatible() from lfx.graph.edge.base. Source/target types are auto-resolved from the flow.
• Idempotent edge creation. Posting the same (source, source_output, target, target_input) twice returns the existing edge.
• No optimistic locking. Concurrent edits use last-write-wins, matching the existing PATCH /flows/{flow_id} behavior. Worth revisiting if it becomes an issue.
• Auth model unchanged. Endpoints use the same CurrentActiveUser + ownership check (Flow.user_id == user.id) as every other flow endpoint.

Test plan

• Unit tests in src/lfx/tests/unit/mcp/test_client_flow_graph.py (8 passing) covering all four LangflowClient methods, including the 400 propagation on type mismatch.
• Smoke test against Basic Prompting.json confirming the helper flow end-to-end (add component → connect → idempotency check → mismatch rejection).
• ruff check + ruff format --check clean across all touched files.
• Manual end-to-end against a running Langflow instance (curl + a real flow).
• Decide whether to refactor existing MCP tools (list_components, get_flow_info) to use these endpoints instead of parsing flow.data locally — left as follow-up.

Files

• New: src/backend/base/langflow/api/v1/flow_graph.py
• New: src/lfx/tests/unit/mcp/test_client_flow_graph.py
• Modified: src/backend/base/langflow/api/router.py, src/backend/base/langflow/api/v1/__init__.py, src/lfx/src/lfx/mcp/client.py

🤖 Generated with Claude Code

[coderabbitai]

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Run ID: a376b551-a448-4716-a314-ac553c3df709

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agent-friendly-flow-endpoints

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands and usage tips.}