AI와 MCP 연결

이 문서는 외부 AI client를 PipelineXLab에 연결해 만드는 개발자를 위한 계약 문서입니다. AI가 호출할 수 있는 Tool 목록, 대상을 지목하는 방법, 응답 형식과 승인 규칙을 정합니다. MCP가 무엇이고 화면에서 AI를 어떻게 쓰는지는 AI로 작업하기에서 먼저 확인하세요.

AI는 Definitions, Report Workbench, PXFLOW Studio와 Python SDK가 사용하는 Project Function, Report, Flow, public port, Node, type, unit과 exact reference를 그대로 사용합니다.

기본 원칙

Report, Flow, Function과 Component마다 동적 MCP Tool을 만들지 않습니다. Tool 목록은 아래 고정 Tool catalog 하나로 정해져 있고, 이들이 늘어도 Tool 수는 그대로입니다.
semantic key와 immutable revisionRef로 exact target을 찾습니다.
읽기, 변경 plan, Apply와 Run을 분리합니다.
Report mapping은 .pxreport, Flow 내부 연결은 .pxflow 또는 SDK source에 적용합니다.
SDK, Studio, Report Workbench와 MCP는 같은 generated application contract를 사용합니다.
현재 지원되는 Function과 product-built first-party Component만 core Flow의 Node·binding·Run operation을 사용합니다. third-party Component는 아래 admission closure 전까지 설치하거나 실행하지 않습니다.
모든 target은 scope를 포함합니다. Project target은 workspaceKey와 projectKey까지 명시하며 열린 화면의 현재 Project를 암묵적으로 사용하지 않습니다.
Project가 소유한 @px.function만 이 Project에서 작성합니다. dependency package가 소유한 Function과 Component source는 해당 package에서 작성하고 consumer Project에서는 읽기 전용으로 봅니다.

고정 Tool catalog

검색과 설명

Tool	역할	상태 변경
`project_search`	접근 가능한 Project 검색	없음
`report_search`	Report 검색	없음
`report_describe`	Report block, authored value, Flow connection과 진단 설명	없음
`pxflow_search`	Flow 검색	없음
`pxflow_describe`	Flow public boundary, Node, 내부 binding과 진단 설명	없음
`function_search`	Project와 검증된 catalog에서 설치됨·설치 가능 Function 검색	없음
`function_describe`	Function owner·version·port·capability와 Project 사용처 설명	없음
`component_search`	exact 요청 Project의 admitted installed contribution과 product built-in 검색; scope를 생략하거나 불완전하게 주면 built-in만 반환	없음
`component_describe`	설치 기록의 최소 Component contract·release·trust 상태 설명; 없으면 `component: null`	없음

검증, 변경과 실행

Tool	역할	상태 변경
`report_plan_change`	typed Report command의 영향과 diff 생성	없음
`report_apply_change`	승인한 Report plan 적용	있음
`function_validate_change`	Project Function draft와 reference update 가능성 검증	없음
`function_plan_change`	Function source diff와 모든 Flow·Report 영향을 하나의 plan으로 생성	없음
`function_apply_change`	승인한 multi-target Function plan을 원자적으로 적용	있음
`pxflow_validate`	exact Flow revision 검증	없음
`pxflow_plan_change`	typed Flow command의 영향과 diff 생성	없음
`pxflow_apply_change`	승인한 Flow plan 적용	있음
`pxflow_run`	saved Flow revision 실행	있음
`run_get`	durable Run 상태 조회	없음
`run_cancel`	취소 가능한 Run에 cancel 요청	있음
`result_read`	named result 또는 resource summary 읽기	없음

Flow 첫 저장도 고정 21-Tool catalog를 늘리지 않습니다. pxflow_plan_change에 검증된 direct document 전체를 담은 단일 CreateFlow command, generation 0, document의 flowKey와 byteDigest를 그대로 쓴 target을 보내고, 같은 target으로 pxflow_apply_change를 호출합니다. 성공 응답의 newRevisionRef는 그 target revisionRef이고 newGeneration은 0입니다. 이미 같은 flowKey의 head가 있으면 FlowHeadAlreadyExists로 거부합니다. 별도 create Tool을 두지 않아 Flow·Report·Function의 생성과 변경 모두 같은 plan→apply 감사 경로와 generation 충돌 검사를 유지합니다.

Report에 저장된 connection을 실행할 때 client는 RunReportFlowConnection command 하나만 보냅니다. 검증된 .pxreport connection을 ordinary pxflow_run 입력으로 materialize하는 일은 Report application service가 맡으므로, client가 Report 본문을 읽어 Run 입력을 다시 조립할 필요가 없습니다. 여러 case를 실행할 때는 RunReportFlowBatch에 검토한 stable caseKey별 input set과 explicit result merge를 같은 application service로 보내면 case마다 ordinary child Run이 만들어집니다.

Semantic target

Report target 예:

json

{
  "scope": {
    "kind": "project",
    "workspaceKey": "structural_team",
    "projectKey": "bridge_package"
  },
  "reportKey": "girder_review",
  "revisionRef": "sha256:report-revision-digest"
}

Flow target 예:

json

{
  "scope": {
    "kind": "project",
    "workspaceKey": "structural_team",
    "projectKey": "bridge_package"
  },
  "flowKey": "girder_check",
  "revisionRef": "sha256:flow-revision-digest"
}

Node와 port는 nodeKey, direction과 portKey를 이어서 지정합니다. Report 위치는 blockKey, fieldKey 또는 slotKey로 지정합니다. Local draft는 trusted host가 발급한 session document handle을 사용하고, package dependency는 package key, version과 digest를 고정합니다. 이 scope는 모든 Search filter, Describe, Plan, Apply와 Run target에 동일하게 들어갑니다.

공통 response envelope

성공 응답:

json

{
  "ok": true,
  "data": {},
  "diagnostics": [],
  "resources": []
}

업무 오류 응답:

json

{
  "ok": false,
  "data": null,
  "diagnostics": [
    {
      "code": "PX_TARGET_NOT_FOUND",
      "path": "/target/flowKey",
      "severity": "error",
      "retryable": false,
      "params": {
        "flowKey": "girder_check"
      },
      "suggestedAction": "SELECT_EXACT_TARGET",
      "diagnosticId": "opaque-correlation"
    }
  ],
  "resources": []
}

업무 검증 실패는 schema-valid diagnostic으로 반환합니다. Transport exception과 자유 형식 문장은 연결 계약의 대체물이 되지 않습니다.

ContextPack과 result budget

ContextPack과 Tool result는 아래 다섯 상한을 각각 적용합니다. 경계값은 허용하고 하나라도 초과하면 그 budget에서 응답을 잘라 이어 읽을 수 있게 합니다.

surface	tokens	bytes	items	tableRows	depth
`contextPack`	200000	2097152	500	1000	8
`result`	200000	2097152	500	1000	8

tokens: 200000은 ordinary Project의 ContextPack이 common model context window 안에 머물게 하면서 prompt 조립과 tokenization 비용을 한 요청에 한정합니다.
bytes: 2097152(2 MiB)는 token 추정이 빗나가거나 binary-like text가 섞여도 server의 request당 메모리와 serialization 비용을 2 MiB payload 경계로 제한합니다.
items: 500은 search candidate, descriptor와 resource fan-out 때문에 한 호출의 객체 수와 validator work가 무한히 늘어나는 것을 막습니다.
tableRows: 1000은 일반 검토에 필요한 tabular preview를 한 번에 제공하면서 row materialization, JSON encoding과 전송 비용을 1,000행으로 제한합니다.
depth: 8은 nested Record/List/Table traversal, validation과 serialization의 재귀 비용을 bounded하게 유지합니다.

이 값들은 ContextPack과 result 모두에서 request당 memory·serialization cost를 제한하고, ordinary Project는 두 번째 왕복 없이 한 ContextPack으로 읽게 하는 보수적 V1 상한입니다. 제품 전체 크기나 durable Result 저장 용량의 약속은 아닙니다.

상한 초과는 절대로 조용히 잘라내지 않습니다. data.truncation은 정확히 truncated, budget, limit, observed, continuation을 담고, continuation은 다음 요청의 cursor member와 opaque value를 알려 줍니다. 따라서 응답은 일부라는 사실, 어떤 budget을 맞았는지, 나머지를 어떻게 요청하는지를 함께 밝힙니다. Silent truncation은 모델이 partial data를 전체로 오인해 확신 있는 engineering 결론을 내리게 하므로 계산 제품에서는 UX 불편이 아니라 correctness failure입니다.

Legacy 요청 거부와 endpoint retirement

아래 21개 entry가 formal V1 endpoint의 exact legacy rejection set입니다. 이 목록은 이 current authority가 소유하며 historical Plan 13은 계속 archive로 남습니다.

kind	legacy entry	stable diagnostic
field	`projectId`	`PX_SCHEMA_UNKNOWN_FIELD`
field	`flowId`	`PX_SCHEMA_UNKNOWN_FIELD`
field	`nodeId`	`PX_SCHEMA_UNKNOWN_FIELD`
field	`projectRoot`	`PX_SCHEMA_UNKNOWN_FIELD`
field	`flowPath`	`PX_SCHEMA_UNKNOWN_FIELD`
payload	`raw-dotted-result-path`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`project.search`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`adapter.search`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`adapter.describe`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`pxflow.search`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`pxflow.describe`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`pxflow.validate`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`pxflow.change`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`pxflow.run`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`report.search`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`report.describe`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`report.change`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`report.render`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`run.get`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`run.cancel`	`PX_SCHEMA_UNSUPPORTED_VERSION`
tool	`result.read`	`PX_SCHEMA_UNSUPPORTED_VERSION`

Formal endpoint는 각 entry를 위 RFC-003 core diagnostic으로 fail closed합니다. Legacy resolver, alias, request/response translator와 call-level fallback은 두지 않습니다. Legacy 호출을 조용히 무시하면 모델에는 성공처럼 보여서 실제로 일어나지 않은 변경을 전제로 다음 engineering 판단을 만들기 때문에, 거부는 안정적인 Diagnostic이어야 합니다.

구 client cohort가 남은 동안에는 reverse proxy가 별도의 격리 legacy endpoint로만 보냅니다. formal endpoint와 legacy endpoint의 telemetry를 분리하고, rollback은 formal contract를 느슨하게 바꾸지 않고 cohort routing만 되돌립니다. zero-use, support, rollback gate를 모두 만족한 뒤 격리 endpoint와 proxy route를 제거합니다.

Search와 describe

Search request는 검색 범위를 먼저 고정하고, opaque cursor로 다음 page를 읽습니다.

json

{
  "scope": {
    "kind": "project",
    "workspaceKey": "structural_team",
    "projectKey": "bridge_package"
  },
  "query": "resistance",
  "limit": 25
}

json

{
  "ok": true,
  "data": {
    "items": [],
    "nextCursor": "opaque-cursor",
    "appliedLimit": 25,
    "truncation": {
      "truncated": true,
      "reason": "page_limit"
    }
  },
  "diagnostics": [],
  "resources": []
}

cursor를 보내는 다음 요청도 같은 scope, query와 filter를 사용합니다. Cursor는 query, filter와 catalog snapshot을 고정합니다. 결과는 scope, target kind, semantic key, exact version/ref/digest 순으로 정렬하며 label과 검색 점수를 tie-break identity로 사용하지 않습니다. nextCursor 또는 truncation 표시 없이 결과를 잘라내지 않습니다.

Describe는 요청 범위에 필요한 정보만 반환합니다.

semantic key와 label
exact target reference와 version
input/result의 type, unit, shape와 constraints
Report source/result 위치와 connection 상태
Flow public boundary, Node setting과 내부 binding 상태
dependency와 Component package availability
capability와 실행 정책 summary
현재 principal에게 허용되는 다음 operation

Source 전체, secret, 전체 Result history와 editor 내부 JSON은 기본 context에서 제외합니다. 응답 크기 때문에 일부 contract나 example을 생략하면 data.truncation에 생략 이유와 수를 표시하고, 이어서 읽을 수 있는 permission-checked resources link를 함께 반환합니다.

Plan과 Apply 공통 transaction

Report, Flow와 Project Function 변경은 같은 transaction envelope를 사용합니다. Plan request는 exact target, 현재 화면이 읽은 generation과 실행 순서가 있는 typed command 배열을 보냅니다.

json

{
  "target": {
    "scope": {
      "kind": "project",
      "workspaceKey": "structural_team",
      "projectKey": "bridge_package"
    },
    "flowKey": "girder_check",
    "revisionRef": "sha256:flow-revision-digest"
  },
  "expectedGeneration": 17,
  "commands": [
    {"kind": "DisconnectInput", "nodeKey": "resistance_check", "portKey": "span"},
    {
      "kind": "ConnectInput",
      "nodeKey": "resistance_check",
      "portKey": "span",
      "binding": {"kind": "flowInput", "portKey": "span"}
    }
  ]
}

Plan response는 검토와 재현에 필요한 기계 정보를 고정합니다.

json

{
  "ok": true,
  "data": {
    "planRef": "plan_...",
    "planDigest": "sha256:plan-digest",
    "expiresAt": "2026-08-02T01:00:00Z",
    "target": {
      "scope": {
        "kind": "project",
        "workspaceKey": "structural_team",
        "projectKey": "bridge_package"
      },
      "flowKey": "girder_check",
      "revisionRef": "sha256:flow-revision-digest"
    },
    "expectedGeneration": 17,
    "base": {
      "revisionRef": "sha256:flow-revision-digest",
      "sourceDigest": "sha256:source-digest"
    },
    "commands": [
      {"kind": "DisconnectInput", "nodeKey": "resistance_check", "portKey": "span"},
      {
        "kind": "ConnectInput",
        "nodeKey": "resistance_check",
        "portKey": "span",
        "binding": {"kind": "flowInput", "portKey": "span"}
      }
    ],
    "atomic": true,
    "touchedSemanticPaths": [
      "/nodes/resistance_check/inputBindings/span"
    ],
    "diff": {},
    "impact": {}
  },
  "diagnostics": [],
  "resources": []
}

planDigest는 tool contract version, full target, expectedGeneration, base revision와 선택적 source digest, normalized ordered commands, atomic과 touchedSemanticPaths의 canonical encoding을 digest한 값입니다. 사용자용 label과 localized 설명은 digest 입력에서 제외합니다.

검토가 끝나면 Apply에는 Plan과 같은 target·generation, plan identity와 idempotency key를 보냅니다.

json

{
  "target": {
    "scope": {
      "kind": "project",
      "workspaceKey": "structural_team",
      "projectKey": "bridge_package"
    },
    "flowKey": "girder_check",
    "revisionRef": "sha256:flow-revision-digest"
  },
  "expectedGeneration": 17,
  "planRef": "plan_...",
  "planDigest": "sha256:plan-digest",
  "commandId": "client-generated-idempotency-key",
  "approvalRef": "approval_..."
}

commands는 배열 순서대로 해석하고 하나의 transaction으로 모두 적용합니다. 한 command나 최종 validation이 실패하면 revision과 source를 하나도 쓰지 않습니다. 일부 command만 적용하려면 그 subset으로 새 Plan을 만듭니다.
Apply는 target, generation, plan digest, expiry, 권한, package, type·unit, capability와 정책을 다시 검사합니다. Project Function과 SDK-linked Flow는 source-safe write, rematerialize와 source↔materialized contract parity까지 한 transaction 결과로 확정합니다.
Plan의 정책이 명시적 승인을 요구하면 Apply의 approvalRef가 필수이며 server가 승인 범위와 principal을 다시 확인합니다. 승인이 필요 없는 정책에서는 이 field를 생략합니다.
commandId는 같은 principal과 target에서 retry identity입니다. 같은 commandId와 같은 Plan을 다시 보내면 최초 Apply 결과를 반환하고, 다른 Plan과 재사용하면 diagnostic을 반환합니다.
유효 시간이 끝나면 PX_PLAN_EXPIRED, generation이 달라지면 PX_GENERATION_STALE, target, plan digest 또는 base digest가 다르면 PX_PLAN_MISMATCH를 반환합니다.

새 revision에 맞춰 다시 계획하기

충돌이 없는 최신 revision으로 옮길 때 Plan request에 rebaseFromPlanRef를 보낼 수 있습니다. Server는 이전 Plan의 touchedSemanticPaths와 base 이후 변경 경로가 겹치지 않고 모든 계약을 다시 검증한 경우에만 새 planRef와 planDigest를 만듭니다. 이전 Plan의 유효성을 되살리지는 않습니다.

경로가 겹치면 PX_MERGE_CONFLICT와 함께 conflicts[]의 {path, base, current, proposed}를 반환합니다. 사용자는 충돌 값을 고른 typed command로 새 Plan을 만듭니다. 이 최소 rebase 규칙은 의미를 추측하는 자동 merge를 피하면서 서로 다른 Node나 Report 위치의 독립 변경은 다시 사용할 수 있게 합니다.

Report connection 변경 plan

Report와 Flow를 연결하는 command는 .pxreport에만 적용됩니다.

text

SetReportFlowInputSource
SetReportFlowResultTarget
RemoveReportFlowMapping
RunReportFlowConnection
RunReportFlowBatch

작성값을 Flow input에 연결하는 plan 예:

json

{
  "target": {
    "scope": {
      "kind": "project",
      "workspaceKey": "structural_team",
      "projectKey": "bridge_package"
    },
    "reportKey": "girder_review",
    "revisionRef": "sha256:report-revision-digest"
  },
  "expectedGeneration": 8,
  "commands": [
    {
      "kind": "SetReportFlowInputSource",
      "connectionKey": "girder_check",
      "mappingKey": "span_input",
      "flowTarget": {
        "scope": {
          "kind": "project",
          "workspaceKey": "structural_team",
          "projectKey": "bridge_package"
        },
        "flowKey": "girder_check",
        "revisionRef": "sha256:flow-revision-digest"
      },
      "portKey": "span",
      "source": {
        "kind": "reportValue",
        "blockKey": "design_basis",
        "fieldKey": "span"
      }
    }
  ]
}

Flow result를 Report 위치에 표시하는 command 예:

json

{
  "kind": "SetReportFlowResultTarget",
  "connectionKey": "girder_check",
  "mappingKey": "utilization_result",
  "portKey": "utilization",
  "target": {
    "kind": "reportResultSlot",
    "blockKey": "check_summary",
    "slotKey": "utilization"
  }
}

Plan은 다음 내용을 구조적으로 반환합니다.

Report source 또는 destination
exact Flow와 revisionRef
public input/result portKey
type·unit·shape·nullability 검사
영향을 받는 Report 위치와 기존 result의 Stale 전환
expected Report generation과 필요한 권한

Apply는 같은 precondition을 다시 검사하고 새 .pxreport revision을 만듭니다. 이 command는 Flow Node와 flow.connect(...) 연결을 변경하지 않습니다.

Flow 내부 변경 plan

pxflow_plan_change는 Node, public port와 Flow 내부 binding을 변경하는 closed command union을 받습니다.

json

{
  "target": {
    "scope": {
      "kind": "project",
      "workspaceKey": "structural_team",
      "projectKey": "bridge_package"
    },
    "flowKey": "girder_check",
    "revisionRef": "sha256:flow-revision-digest"
  },
  "expectedGeneration": 17,
  "commands": [
    {
      "kind": "ConnectInput",
      "nodeKey": "resistance_check",
      "portKey": "span",
      "binding": {
        "kind": "flowInput",
        "portKey": "span"
      }
    }
  ]
}

응답은 변경되는 Node·binding, type·unit 검사, 연결된 Report 영향, dependency impact와 source-safe diff 여부를 보여 줍니다. SDK-linked Flow는 Python diff를 검토한 뒤 rematerialize합니다. PXFLOW-native Flow는 direct .pxflow command를 적용합니다.

Project Function 작성

Project Function의 public write path는 다음 하나입니다.

text

function_search → function_describe
→ function_validate_change → function_plan_change
→ source diff · usage/Flow/Report impact 검토
→ function_apply_change

새 Function은 search 없이 Project scope에서 validate를 시작할 수 있습니다. 기존 Function을 고칠 때는 function_describe가 반환한 exact Project-owned FunctionRef, generation과 source digest를 그대로 사용합니다. Project Function command 이름과 payload 의미는 기능별 사용 위치의 Project Function command가 소유합니다.

function_validate_change와 function_plan_change는 같은 typed command 배열을 받습니다. Function draft는 complete @px.function definition 후보이며 explicit functionKey, 새 immutable version, description, typed input/result contract와 구현을 포함합니다. line patch, 파일 전체 교체나 Python symbol 이름으로 target을 찾는 요청은 받지 않습니다.

사용 중인 Function의 CreateFunctionVersion plan은 다음 정보를 빠짐없이 반환합니다.

old/new FunctionRef와 읽을 수 있는 source-safe diff
현재 editable head에서 그 Function을 쓰는 모든 flowKey·nodeKey
각 Node reference를 새 FunctionRef로 바꿔 materialize할 Flow revision 후보
해당 Flow revision을 pin한 Report connection과 승인 시 함께 이동할 Report revision 후보
contract·unit·capability 변화, Stale result와 재실행 영향
immutable history나 published revision처럼 보존되는 reference와 보존 이유

referencePolicy는 all_current_usages로 고정합니다. 한 Node만 다른 구현을 써야 하면 기존 Function을 부분 수정하지 않고 BranchProjectFunction으로 새 functionKey를 만든 뒤 그 Node의 ReplaceNodeTarget을 같은 plan에 넣습니다. 나머지 Node는 기존 FunctionRef를 유지합니다.

function_apply_change는 승인된 plan digest와 모든 target의 generation·revision·source digest를 다시 확인합니다. 새 Function version, source-safe edit, 승인된 Node reference, 새 Flow revision과 Report connection reference를 하나의 multi-target transaction으로 저장합니다. 한 target이라도 stale이거나 rematerialize parity가 다르면 전체를 취소합니다. 기존 published Function version이나 기존 Flow·Report revision을 덮어쓰지 않습니다.

Installed dependency의 Function/Component는 function_describe/component_describe로 계약과 owning package를 확인할 수 있지만 이 write path의 target이 될 수 없습니다. 수정 요청에는 PX_TARGET_READ_ONLY와 owning package source/release로 이동하는 handoff를 반환합니다.

Function·Component와 package discovery

현재 Component discovery 응답 범위

현재 component_search는 exact (workspaceRef, projectRef)가 모두 있으면 그 Project의 admitted installed contribution과 host-owned product built-in을 합쳐 검색합니다. 둘 중 하나라도 없으면 Project row를 추측하지 않고 product built-in만 반환합니다. component_describe는 full ComponentDescriptor나 signed presentation entry를 반환하지 않습니다. 현재 응답은 설치된 contribution의 componentContract(componentKey, declaredInputKeys), bounded elementContributionFields, exact packageRelease, signature와 revocationList 저장 상태까지이며, 설치되지 않았거나 trust predicate를 통과하지 못한 target은 성공 envelope 안의 {"component": null}입니다. trust authority가 없으므로 signed local-file Component는 기록 전에 거부합니다. 명시적으로 수용된 unsigned install은 absent·not-checked로만 기록하며, product-scope built-in은 registry-verified valid·valid-window여야 합니다. catalog와 detail은 그 저장 상태를 같은 strict predicate로 다시 판단합니다.

현재 exact ProjectScope data-path isolation은 구현됐지만, execution-trust closure를 구성하는 요청 scope와 authenticated principal의 권한 결속, acceptance channel·warning·audit 보존 및 실행 재검증, cryptographic verification과 current revocation 확인은 구현되지 않았습니다. 따라서 third-party Component activation과 production install admission은 계속 차단합니다. Search/Describe는 read-only audit metadata 조회이며 production 설치·실행 승인이 아닙니다.

아래 available catalog, dependency handoff와 typed port·result의 host-owned projection은 계획 계약입니다. 후속 V2 Canvas는 component.declarative@2만 사용하고 settings를 component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그립니다. capability는 package manifest와 sandbox 계약이 소유하며 이 descriptor에 합치지 않습니다. rich surface는 RFC-016의 component-rich-surface-declaration@1이 소유하며 MCP는 그 entry를 열지 않습니다.

계획된 catalog에서는 Function과 Component 검색이 installed·available availability를 사용합니다. Component 검색 결과는 다음 관계를 유지합니다.

계획 계약에서 구조 해석 Component를 검색하면 package가 공개한 analysis Component 목록과 각 input, result, host presentation metadata를 반환합니다. 검색 결과의 availability는 installed 또는 available이고, 각 후보는 exact package version과 digest를 포함합니다. V2에서는 settings가 없거나 빈 객체여야 하고 named execution capability와 Python dependency도 허용하지 않습니다.

향후 component_describe가 admitted declaration의 exact identity·typed port와 bounded host projection metadata를 반환하면, Core host는 이를 host-owned component.declarative@2으로 materialize합니다. V2 package에는 renderer·modal·settings schema나 verified presentation entry가 없으며, settings를 component-declared-settings@1로 선언당 최대 8개까지 받고 host control registry가 그립니다. rich surface는 RFC-016의 component-rich-surface-declaration@1이 소유합니다. 이 host projection은 현재 production Flow surface에 구현되어 있지 않습니다. admission closure 이후 계산 transport는 pxflow_run을 사용하지만, 현재 third-party Component 실행은 거부합니다.

계획된 marketplace catalog에서 아직 Project dependency에 추가하지 않은 Function 또는 Component를 Describe하면 설치 작업을 대신 실행하지 않고 다음 handoff를 반환합니다. 아래는 계획 응답 예입니다.

json

{
  "componentRef": {
    "publisher": "pipelinexlab-labs",
    "packageKey": "structural_analysis",
    "packageVersion": "1.0.0",
    "packageDigest": "sha256:package-digest",
    "releaseByteDigest": "sha256:release-digest",
    "componentKey": "model_analysis",
    "componentContractVersion": 1
  },
  "availability": "available",
  "dependencyHandoff": {
    "handoffRef": "dependency_handoff_...",
    "packageKey": "structural_analysis",
    "packageVersion": "1.0.0",
    "packageDigest": "sha256:package-digest",
    "action": "OPEN_PROJECT_DEPENDENCIES"
  }
}

계획된 Project Dependencies 화면이나 CLI가 권한·license·dependency lock을 확인하고 설치를 수행합니다. Handoff는 해당 화면에 exact release를 전달하는 값이며 승인 기록으로 사용하지 않습니다. 설치가 끝나면 Function 또는 Component를 다시 Describe하고 새 placement Plan을 만듭니다. Exact dependency가 확인되기 전에는 Node 배치를 적용하지 않으며 latest version이나 유사 definition으로 바꾸지 않습니다.

Report connection 실행

Report의 저장된 connection을 실행할 때 client는 exact Report revision과 connectionKey를 보냅니다.

json

{
  "kind": "RunReportFlowConnection",
  "commandId": "client-generated-idempotency-key",
  "target": {
    "scope": {
      "kind": "project",
      "workspaceKey": "structural_team",
      "projectKey": "bridge_package"
    },
    "reportKey": "girder_review",
    "revisionRef": "sha256:report-revision-digest"
  },
  "connectionKey": "girder_check",
  "reason": "user"
}

Report application service는 저장된 source와 exact Flow target을 검증하고 ordinary Flow Run 하나를 시작합니다. 같은 connection의 모든 input mapping은 한 input payload로 전달되며, result mapping은 그 Run의 immutable Result를 Report 위치에 표시합니다. application service는 같은 command retry를 기존 Run 또는 Batch로 resolve합니다. 새 ordinary Run 요청에는 projectionIntentGeneration을 발급하고, 새 Batch 요청에는 Batch 전체가 공유할 generation 하나와 stable caseKey별 최초 currentChildRunKey를 원자적으로 등록합니다. 한 case를 retry하면 그 case의 child Run key만 교체합니다. 늦게 끝난 이전 Run은 history에 남고 current generation 및, Batch child이면 current child Run key까지 일치할 때만 Report의 현재 result projection을 갱신합니다.

Table 또는 List source는 typed collection 하나로 Run 한 번에 전달합니다. Scalar case 여러 개를 각각 실행할 때는 explicit Batch Run plan이 case 수, 비용과 result merge를 먼저 보여 줍니다.

Run 조회, 취소와 Result 읽기

run_get은 state, progress, diagnostics와 available result summary를 반환합니다. run_cancel은 active Run에 cancellation을 요청하며 terminal snapshot은 그대로 유지합니다.

작은 result는 result_read가 typed value를 반환합니다. 큰 Table, model, image, Report output과 PDF는 schema·size·preview와 권한이 검사되는 resource link를 먼저 반환합니다.

json

{
  "runRef": "run_...",
  "resultKey": "utilization"
}

승인과 권한

다음 동작은 Apply 또는 Run 직전에 server가 다시 확인합니다.

Report와 Flow target revision, generation과 edit/run permission
package availability와 entitlement
type, unit, shape와 public port contract
file, network, secret, GPU와 external write capability
effectful 또는 비용이 큰 실행의 approval
큰 result resource의 read permission

AI 작성 이력

AI가 만든 typed command나 source-safe diff를 Apply하면 응답은 새 revision과 함께 저장된 authoringProvenance summary 또는 그 audit resource link를 반환합니다. 이 기록은 승인한 principal, assistant provider·model, tool contract version, structured request digest, planRef·planDigest·commandId, 승인 시각, base와 result revision/generation 및 change digest를 연결합니다.

권한을 행사한 actor는 항상 사용자 또는 service principal입니다. Assistant metadata는 제안의 출처를 기록하고 권한 주체를 대신하지 않습니다. Raw prompt, secret, Report 본문과 전체 Python source는 provenance에 복제하지 않습니다. 저장 형식은 파일 형식과 저장의 Authoring provenance를 따릅니다.

LLM 실패 처리

상황	동작
target이 여러 개	exact 후보와 Project path를 보여 주고 선택 요청
dependency Function/Component 수정 요청	read-only owner와 owning package source/release handoff 표시
사용 중 Function 수정	모든 current Node·Flow·Report 영향과 원자적 reference update plan 표시
Flow public port 변경	영향받는 Report mapping과 contract diff 표시
Component package 미설치	exact package version·digest와 Project Dependencies handoff 제시
type·unit·shape 불일치	Report source와 Flow port 계약을 나란히 표시
revision 충돌	독립 변경이면 `rebaseFromPlanRef`로 새 plan 생성, 겹치면 typed conflict 표시
permission 부족	필요한 권한 요청 경로 표시
result가 큼	summary와 permission-checked resource link 반환

금지 목록

본문 문자열, canvas label 또는 화면 좌표로 target 추측
변경 plan 없이 raw document patch 적용
raw Python patch, Python symbol 이름이나 파일 순서로 Function target 추측
기존 Function version 또는 dependency package source 덮어쓰기
사용 중 Function의 일부 reference만 숨겨서 갱신하거나 plan 밖에서 후속 갱신
Report mapping command로 Flow Python source 수정
Flow command로 Report block과 result 위치 수정
표 선택을 숨은 여러 Run으로 변환
stale revision을 latest head로 자동 교체
scope를 생략하거나 열린 화면의 current Project로 보완
만료되거나 base가 달라진 Plan을 Apply하거나 command 일부만 저장
package handoff를 설치 승인으로 간주하거나 임의의 latest version으로 교체
권한이 확인되지 않은 Result를 AI context에 노출

Runnable MCP wire

Runnable V1 transport는 stateless newline-delimited JSON-RPC 2.0이며 tools/list와 tools/call만 지원합니다. tools/call 업무 결과는 실패를 포함해 isError: false이고 content: []와 원본 OperationOutcome의 structuredContent를 유지합니다. JSON을 읽을 수 없는 params와 router failure는 업무 결과가 아니라 JSON-RPC error입니다. Session, progress retention, initialize negotiation과 Task-to-Run mapping은 V1 entry point가 아닙니다.

AI와 MCP 연결 ​

기본 원칙 ​

고정 Tool catalog ​

검색과 설명 ​

검증, 변경과 실행 ​

Semantic target ​

공통 response envelope ​

ContextPack과 result budget ​

Legacy 요청 거부와 endpoint retirement ​

Search와 describe ​

Plan과 Apply 공통 transaction ​

새 revision에 맞춰 다시 계획하기 ​

Report connection 변경 plan ​

Flow 내부 변경 plan ​

Project Function 작성 ​

Function·Component와 package discovery ​

Report connection 실행 ​

Run 조회, 취소와 Result 읽기 ​

승인과 권한 ​

AI 작성 이력 ​

LLM 실패 처리 ​

금지 목록 ​

Runnable MCP wire ​

이어서 보기 ​

AI와 MCP 연결

기본 원칙

고정 Tool catalog

검색과 설명

검증, 변경과 실행

Semantic target

공통 response envelope

ContextPack과 result budget

Legacy 요청 거부와 endpoint retirement

Search와 describe

Plan과 Apply 공통 transaction

새 revision에 맞춰 다시 계획하기

Report connection 변경 plan

Flow 내부 변경 plan

Project Function 작성

Function·Component와 package discovery

Report connection 실행

Run 조회, 취소와 Result 읽기

승인과 권한

AI 작성 이력

LLM 실패 처리

금지 목록

Runnable MCP wire

이어서 보기