AI and MCP

AI uses the same Project, Flow, Node, input, result, type, unit, and revision keys as the Python SDK and PXFLOW Studio. MCP does not introduce another authoring or execution model.

Current Component Node scope

The production Flow reader currently preserves a Component's exact target, raw settings, and usage-derived partial ports in a read-only unsupported Node. Component settings schemas, the package-to-renderer bridge, editor AI, and editor operations are planned; editor surfaces require RFC-014 approval. A contribution is shown as signed or verified only after RFC-005 marketplace verification is recorded. Future host presentation belongs to the contract_only V2 in Node presentation and third-party UI. Exact ProjectScope data-path isolation is implemented. Production third-party Component activation and install admission stay blocked until Project authorization and execution-trust closure are complete. MCP cannot override either gate; the current reader only preserves the exact target, raw settings, and usage-derived partial ports in read-only recovery.

Use the core action sequence

AI action sequence

1. 1Search and DescribeFind and explain Project, Flow, Node, and port targets
2. 2Resolve exact targetPin the object that may change or run
3. 3Validate or PlanPrepare checks, a change plan, or a Run plan
4. 4ReviewInspect the diff, impact, permissions, and cost
5. 5Apply or RunPerform only the approved action
6. 6Read the ResultOpen the applied change or completed Run Result

AI fixes the exact target and presents the impact before an approved Apply or Run.

Targets use readable semantic keys:

project: bridge_package
flow: girder_review
node: resistance_check
port: utilization

AI does not resolve a target from UUIDs, local paths, canvas coordinates, or similar labels. When multiple candidates match, it presents exact Project and Flow paths for selection.

Choose the right context

Flow context

Use AI from PXFLOW to explain the current selection, propose a connection, inspect an issue, or plan a source-safe change. The plan identifies exact Node and port keys and remains a preview until Apply.

Project context

Use Project AI to search Functions, Components, Flows, Runs, and Results across the current permission scope. Project Activity shows long-running AI and Run activity.

Report context

Use AI in Report Workbench to locate a saved Flow, match an authored value to one of its public inputs, or map a named Flow result to an exact Report position. The approved mapping is stored in the current .pxreport revision. The Flow's Python source and internal Canvas connections remain unchanged.

Planned Extension editor context

After RFC-014 approval, an installed Component package may include an Extension with a focused editor AI entry. It receives the exact current Component Node and only the Extension-owned setting, table, or viewer range selected by the user. It uses the ordinary Node input connections and Flow Run path.

Ask in terms of intent

• “Explain the public results and units of girder_review."
• “Map the Report value design_span to the public input girder_review.span."
• “Place girder_review.utilization in the Report result position check_result."
• “Suggest missing connections using only discoverable inputs in this Flow."
• “Show the impact of upgrading girder_resistance before applying it.”
• “Run the saved revision and summarize the utilization Result.”

AI never silently corrects a near-matching key or assumes the first result port.

Understand the MCP surface

MCP (Model Context Protocol) is an open standard for connecting an external AI program to another service so it can use that service's capabilities. PipelineXLab exposes such an endpoint, so an MCP-capable AI client can find, describe, and run the Flows in this Project. Skip this section when you only use the AI inside the product screens.

A connected client works from a compact, stable operation catalog:

• Project, Flow, Function, and Component search/describe;
• Report search/describe, plan, and approved apply;
• Project Function validate, plan, and approved multi-target apply;
• Flow validate, plan, and approved apply;
• Run, status, cancel, and result read;
• permission-checked resources for large Results; and
• planned Component editor operations; only contributions with recorded RFC-005 marketplace verification are shown as verified.

There is no Tool per Function or per Component package. After successor admission, a Component uses the ordinary pxflow_run operation rather than a package-specific Tool. Current production rejects third-party Component Run planning and execution until the ProjectScope and execution-trust gates above are complete.

Review changes before Apply

The product requires a plan and explicit approval for:

• adding or removing Nodes and connections;
• replacing a Function or Component target;
• changing a semantic key or externally discoverable port;
• editing SDK-linked source;
• applying a document change owned by a Component package; and
• starting a costly or effectful Run.

At Apply or Run time, the service checks the exact revision, type, unit, permission, package availability, and capability again. Concurrent edits produce a refreshed plan instead of an automatic overwrite.

Edit an SDK-linked Flow safely

1. Resolve the semantic target.
2. Build a source-safe edit plan.
3. Show the Python diff and impact.
4. Apply only after approval.
5. Rematerialize and verify semantic parity.

When an update cannot be represented safely, AI offers direct code editing or an explicit PXFLOW-native copy. It does not modify only the canvas projection.

Create or edit a Project Function

AI first presents a complete explicit-key @px.function candidate with its version, typed inputs/results, and calculation meaning. Editing a used Function creates a new immutable version candidate and shows every affected Node, Flow, and connected Report before Apply. An approved Apply writes the new Function version and approved references as one atomic change.

To vary only the selected Node, choose Branch Function for this Node. AI creates a Project Function with a new functionKey and replaces only that Node target. Functions and Components owned by an installed dependency stay read-only in the consumer Project; the product links to the owning package source instead.

Component template source follows the same ownership rule. A template definition belongs to the owning Component package source, while a placed Node's label, connections, and instance settings belong to the Flow revision. Report body content and Report-to-Flow mappings belong to the .pxreport revision.

Keep discovery separate from permission

• connection=True makes a port discoverable by default.
• connection=False hides it from ordinary Flow and AI discovery; the planned Component editor discovery follows the same value.
• This flag is not read, write, Run, or share permission.
• Every resource and Result read checks current Project permission again.
• Installing a Component package does not grant permission to its external systems or secrets.

Keep context small

AI receives only what the task needs:

• Flow, Function, and Component descriptions and versions;
• Node and port keys;
• types, units, constraints, required/default/nullability;
• connection and validation state;
• adjacent Flow bindings; and
• the selected Component editor range in the planned editor AI context.

It does not receive the entire Python workspace, result history, secrets, or editor-internal JSON by default. Large Tables, models, images, Reports, and PDFs expose schema, size, and a preview before permission-checked ranges are read.

Recover from errors

Situation	Safe behavior
Multiple targets match	Show exact candidates and request scope
Required Component package is missing	Preserve the exact target; the planned catalog adds package/version and Install guidance
Port is missing	Show available exact ports
Type or unit differs	Explain expected and current values structurally
Revision is stale	Reload and rebuild the plan
Permission is missing	Explain the required access path
Result is large	Return a summary and resource link

AI explanations do not grant execution authority. Apply and Run always pass through the same server-side validation and authorization as PXFLOW.

Continue

• Use the SDK and PXFLOW Studio
• Use Report Workbench
• Use Components and Component packages
• Understand Runs and recovery