@unstable-dev/unmeshed-mcp 0.1.0

package/knowledge/steps/JQ.md

@@ -0,0 +1,189 @@
+# JQ Step Schema
+
+`JQ` runs a [jq 1.6](https://jqlang.org/) expression against JSON input inside
+Unmeshed. Use it to extract fields, filter arrays, reshape payloads, or perform
+lightweight JSON transformations without writing JavaScript or Python.
+
+The Unmeshed JQ engine is compatible with jq version `1.6`.
+
+## Definition Input Schema
+
+```json
+{
+  "script": ".color",
+  "input": {
+    "name": "apple",
+    "color": "red",
+    "price": 10
+  }
+}
+```
+
+| Field | Type | Required | Description |
+|---|---|---|---|
+| `script` | string | Yes | jq expression to run against the provided input JSON. |
+| `input` | object, array, string, number, boolean, or null | Yes | JSON value that becomes the jq input document. |
+
+## Runtime Output Schema
+
+The jq result is stored in `output.result`.
+
+```json
+{
+  "result": "red"
+}
+```
+
+Process-level output for a single-step JQ workflow can mirror the JQ step
+output:
+
+```json
+{
+  "result": "red"
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.result` for the entire jq result.
+- `steps.<ref>.output.result.<field>` when the jq result is an object.
+- `steps.<ref>.output.result[0]` when the jq result is an array.
+
+Do not use:
+- `steps.<ref>.output.response`
+- `steps.<ref>.output.results`
+- `steps.<ref>.output.<field>` directly unless the jq result itself is wrapped by another step later
+
+## Generation Rules
+
+- Use uppercase step type: `"JQ"`.
+- Put the jq expression in `input.script`.
+- Put the JSON document to transform in `input.input`.
+- Keep jq scripts deterministic and focused on JSON transformation.
+- Use template references in `input.input` when reading another step's runtime output, for example `{{ steps.fetch_posts_1.output.response }}`.
+- When using native `HTTP` output as JQ input, reference `output.response`, not `output.result`.
+- Prefer JQ for simple extraction and reshaping; switch to `JAVASCRIPT` only when the logic becomes hard to express in jq.
+- Do not hardcode secrets or credentials inside the jq input.
+
+## Debugging Rules
+
+When a JQ step fails or returns an unexpected result:
+- Inspect the exact `input.script` expression.
+- Inspect the concrete JSON under `input.input`.
+- Verify that upstream template references point to the correct producer output path.
+- If the result is empty or null, check whether the jq expression selected a missing path.
+- If the result type is wrong, check whether the jq script emits a scalar, array, or object.
+
+Common failures:
+- Reading native `HTTP` output from `steps.<http_ref>.output.result` instead of `output.response`.
+- Passing a string that looks like JSON instead of an actual JSON object or array.
+- Expecting `output.result.<field>` when the jq result is a scalar like a string or number.
+- Using jq syntax that is incompatible with jq `1.6`.
+- Forgetting to wrap a template reference inside the `input.input` object where the jq script expects it.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "jq_test",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Return a color from a JSON object using jq.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "jq",
+      "type": "JQ",
+      "ref": "jq_1",
+      "optional": false,
+      "createdBy": "system",
+      "updatedBy": "system",
+      "description": "jq step",
+      "label": null,
+      "created": 1700000000000,
+      "updated": 1700000000000,
+      "configuration": {
+        "errorPolicyName": null,
+        "useCache": false,
+        "cacheKey": null,
+        "cacheTimeoutSeconds": 0,
+        "stream": false,
+        "streamAllStatuses": false,
+        "preExecutionScript": null,
+        "constructInputFromScript": false,
+        "scriptLanguage": null,
+        "jqTransformer": null,
+        "rateLimitMaxRequests": 0,
+        "rateLimitWindowSeconds": 0
+      },
+      "children": [],
+      "input": {
+        "script": ".color",
+        "input": {
+          "name": "apple",
+          "color": "red",
+          "price": 10
+        }
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 30050003,
+  "processId": 30050001,
+  "ref": "jq_1",
+  "namespace": "default",
+  "name": "jq",
+  "type": "JQ",
+  "status": "COMPLETED",
+  "input": {
+    "input": {
+      "color": "red",
+      "price": 10,
+      "name": "apple"
+    },
+    "script": ".color",
+    "__currentExecutionStartTime": 1778615106162
+  },
+  "output": {
+    "result": "red"
+  }
+}
+```
+
+## Example: Extract Values From a Native HTTP Response
+
+If a native `HTTP` step with ref `fetch_posts_1` returns a JSON array response,
+use that response as the JQ input:
+
+```json
+{
+  "script": "map(.author.nationality)",
+  "input": "{{ steps.fetch_posts_1.output.response }}"
+}
+```
+
+If you only want items published after 2019, use jq filtering:
+
+```jq
+.bestsellers[] | select(.published_year > 2019) | .author.nationality
+```

package/knowledge/steps/LIST.md

@@ -0,0 +1,279 @@
+# List Step Schema
+
+`LIST` is a container step that runs its child steps sequentially. Use it when a
+workflow branch needs to execute a series of steps in order.
+
+The primary use case is inside another container, such as a `SWITCH`,
+`PARALLEL`, `FOREACH`, or `WHILE`, where each branch/body needs multiple steps.
+It can also appear as a top-level step when a process definition needs a simple
+sequential container.
+
+## Definition Input Schema
+
+LIST usually has no meaningful input:
+
+```json
+{}
+```
+
+The important definition field is `children`, which contains the ordered steps
+to run.
+
+```json
+{
+  "type": "LIST",
+  "ref": "list_1",
+  "children": [
+    {
+      "type": "HTTP",
+      "ref": "http_1"
+    }
+  ],
+  "input": {}
+}
+```
+
+## Runtime Output Schema
+
+The LIST container's own step output is usually an empty object:
+
+```json
+{}
+```
+
+Child steps produce their own outputs under their own refs. For example, an
+HTTP child inside a LIST still exposes:
+
+```json
+{
+  "response": {
+    "randomId": "690a837c-f44f-4bf6-a624-a90bf564024d",
+    "counter": 1
+  },
+  "statusCode": 200
+}
+```
+
+In process run records, child steps are linked back to the LIST by `parentId`
+and `parentRef`.
+
+```json
+{
+  "ref": "http_1",
+  "parentRef": "list_1",
+  "type": "HTTP",
+  "status": "COMPLETED"
+}
+```
+
+## Output Access Paths
+
+Use:
+- `steps.<child_ref>.output...` to access a child step's output directly.
+- `steps.<http_child_ref>.output.response` for a native HTTP child response body.
+- `steps.<javascript_child_ref>.output.result` for a JavaScript child result.
+- `steps.<python_child_ref>.output.result` for a Python child result.
+- `stepRecords[].parentRef` when debugging executed process data.
+
+Do not use:
+- `steps.<list_ref>.output.result`
+- `steps.<list_ref>.output.response`
+- `steps.<list_ref>.children.<child_ref>.output`
+- `steps.<list_ref>.output.<child_ref>`
+
+## Generation Rules
+
+- Use uppercase step type: `"LIST"`.
+- Put ordered child steps in `children`.
+- Use `input: {}` for the LIST container unless a backend-specific field is documented.
+- LIST children must be complete step definitions with the same required fields as top-level steps.
+- Child `ref` values must be unique across the whole workflow, not only inside the LIST.
+- Use LIST as a branch body when a `SWITCH`, `PARALLEL`, `FOREACH`, or `WHILE` branch needs multiple steps.
+- Do not invent a special LIST result wrapper for child outputs.
+- Later steps should reference child outputs by child refs directly.
+
+## Debugging Rules
+
+When debugging a LIST:
+- Check the LIST step record status first.
+- Inspect child step records whose `parentRef` equals the LIST ref.
+- Find the first failed child step if the LIST or process failed.
+- Do not stop at the LIST step's own `output: {}`; inspect child outputs.
+- If process-level output mirrors a child output, explain which child produced it.
+- Use child step type rules to interpret child outputs.
+
+Common failures:
+- Assistant tries to read child output from `steps.<list_ref>.output.result`.
+- A child step fails but the explanation only mentions the LIST container.
+- Duplicate child refs collide with refs elsewhere in the workflow.
+- Branch containers use a single child step directly when a LIST branch is expected.
+- Later steps reference LIST output instead of the child step output.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Run an HTTP step inside a LIST container.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "list",
+      "type": "LIST",
+      "ref": "list_1",
+      "optional": false,
+      "createdBy": "system",
+      "updatedBy": "system",
+      "description": null,
+      "label": null,
+      "created": 1700000000000,
+      "updated": 1700000000000,
+      "configuration": {
+        "errorPolicyName": null,
+        "useCache": false,
+        "cacheKey": null,
+        "cacheTimeoutSeconds": 0,
+        "stream": false,
+        "streamAllStatuses": false,
+        "preExecutionScript": null,
+        "constructInputFromScript": false,
+        "scriptLanguage": null,
+        "jqTransformer": null,
+        "rateLimitMaxRequests": 0,
+        "rateLimitWindowSeconds": 0
+      },
+      "children": [
+        {
+          "orgId": 1,
+          "namespace": "default",
+          "name": "http",
+          "type": "HTTP",
+          "ref": "http_1",
+          "optional": false,
+          "createdBy": "system",
+          "updatedBy": "system",
+          "description": null,
+          "label": null,
+          "created": 1700000000000,
+          "updated": 1700000000000,
+          "configuration": {
+            "errorPolicyName": null,
+            "useCache": false,
+            "cacheKey": null,
+            "cacheTimeoutSeconds": 0,
+            "stream": false,
+            "streamAllStatuses": false,
+            "preExecutionScript": null,
+            "constructInputFromScript": false,
+            "scriptLanguage": null,
+            "jqTransformer": null,
+            "rateLimitMaxRequests": 0,
+            "rateLimitWindowSeconds": 0
+          },
+          "children": [],
+          "input": {
+            "method": "GET",
+            "url": "http://localhost:8080/api/test/get",
+            "headers": {
+              "Content-Type": "application/json",
+              "Accept": "application/json",
+              "Authorization": "Bearer {{secrets.test_token}}"
+            },
+            "params": {
+              "sampleKey": "sampleValue"
+            },
+            "repeatUntilEnabled": null,
+            "repeatUntilCondition": {
+              "script": "(steps, context) => {\n  return steps.__self.output.response.counter === 100;\n}"
+            },
+            "repeatIntervalSeconds": null,
+            "maxRepeatCount": null,
+            "includeFullResponseString": false,
+            "noEncode": false,
+            "extraLongTimeouts": false
+          },
+          "output": null
+        }
+      ],
+      "input": {},
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Records Example
+
+LIST container step record:
+
+```json
+{
+  "id": 28800012,
+  "processId": 28800010,
+  "ref": "list_1",
+  "parentId": null,
+  "parentRef": null,
+  "namespace": "default",
+  "name": "list",
+  "type": "LIST",
+  "status": "COMPLETED",
+  "input": {
+    "__currentExecutionStartTime": 1778183092448
+  },
+  "output": {},
+  "optional": false
+}
+```
+
+HTTP child step record:
+
+```json
+{
+  "id": 28800013,
+  "processId": 28800010,
+  "ref": "http_1",
+  "parentId": 28800012,
+  "parentRef": "list_1",
+  "namespace": "default",
+  "name": "http",
+  "type": "HTTP",
+  "status": "COMPLETED",
+  "output": {
+    "response": {
+      "counter": 1,
+      "randomId": "690a837c-f44f-4bf6-a624-a90bf564024d"
+    },
+    "statusCode": 200
+  },
+  "optional": false
+}
+```
+
+## Example: Read Output From A LIST Child
+
+Use the child ref directly:
+
+```javascript
+(steps, context) => {
+  const response = steps.http_1.output.response || {};
+  return {
+    counter: response.counter,
+    randomId: response.randomId
+  };
+}
+```
+

package/knowledge/steps/NOOP.md

@@ -0,0 +1,165 @@
+# Noop Step Schema
+
+`NOOP` means no-operation. Use it as a placeholder, static data carrier, or
+simple pass-through step. A NOOP step copies its runtime input directly onto its
+output.
+
+If a NOOP is the last step in a process, the NOOP input/output can determine the
+process output.
+
+## Definition Input Schema
+
+NOOP input can be any JSON object.
+
+```json
+{
+  "abc": "def",
+  "myArray": ["a", "n"]
+}
+```
+
+## Runtime Output Schema
+
+NOOP output is the input copied directly, plus runtime-injected fields such as
+`__currentExecutionStartTime`.
+
+```json
+{
+  "abc": "def",
+  "myArray": ["a", "n"],
+  "__currentExecutionStartTime": 1778186395606
+}
+```
+
+NOOP output is not wrapped in `result`.
+
+## Output Access Paths
+
+Use:
+- `steps.<ref>.output.<field>` for fields from the NOOP input.
+- `steps.<ref>.output.abc`
+- `steps.<ref>.output.myArray`
+- `steps.<ref>.output.__currentExecutionStartTime` when debugging runtime timing.
+
+Do not use:
+- `steps.<ref>.output.result`
+- `steps.<ref>.output.response`
+- `steps.<ref>.output.results`
+
+## Generation Rules
+
+- Use uppercase step type: `"NOOP"`.
+- Use `children: []`; NOOP is not a container.
+- Put static/pass-through fields directly in `input`.
+- Use NOOP for constants, placeholders, test output, simple static config, or branch outputs.
+- Use NOOP as the final step when the workflow should return a static or assembled object.
+- Do not use NOOP for computation; use `JAVASCRIPT` or `PYTHON` for logic.
+- Do not invent `script`, `result`, or HTTP-style response fields for NOOP.
+
+## Debugging Rules
+
+When debugging a NOOP:
+- Compare step `input` and `output`; output should copy input fields.
+- Remember runtime may inject fields such as `__currentExecutionStartTime`.
+- If the process output equals the NOOP output, check whether NOOP was the final step.
+- If later steps cannot read a NOOP field, verify they are not looking under `output.result`.
+
+Common failures:
+- Looking for NOOP data at `steps.<ref>.output.result.<field>`.
+- Expecting NOOP to transform data.
+- Forgetting that a final NOOP can define process output.
+- Adding script fields to NOOP instead of using a script step.
+
+## Minimal Process Definition Example
+
+```json
+{
+  "orgId": 1,
+  "namespace": "default",
+  "name": "kebab-case-name",
+  "version": 1,
+  "type": "API_ORCHESTRATION",
+  "description": "Return static data from a NOOP step.",
+  "configuration": null,
+  "steps": [
+    {
+      "orgId": 1,
+      "namespace": "default",
+      "name": "noop",
+      "type": "NOOP",
+      "ref": "noop_1",
+      "optional": false,
+      "createdBy": "system",
+      "updatedBy": "system",
+      "description": null,
+      "label": null,
+      "created": 1700000000000,
+      "updated": 1700000000000,
+      "configuration": {
+        "errorPolicyName": null,
+        "useCache": false,
+        "cacheKey": null,
+        "cacheTimeoutSeconds": 0,
+        "stream": false,
+        "streamAllStatuses": false,
+        "preExecutionScript": null,
+        "constructInputFromScript": false,
+        "scriptLanguage": null,
+        "jqTransformer": null,
+        "rateLimitMaxRequests": 0,
+        "rateLimitWindowSeconds": 0
+      },
+      "children": [],
+      "input": {
+        "abc": "def",
+        "myArray": ["a", "n"]
+      },
+      "output": null
+    }
+  ],
+  "defaultInput": null,
+  "defaultOutput": null,
+  "outputMapping": null,
+  "signature": null,
+  "metadata": null,
+  "tags": null,
+  "dependencies": null,
+  "dependents": null
+}
+```
+
+## Minimal Executed Step Example
+
+```json
+{
+  "id": 28800067,
+  "processId": 28800065,
+  "ref": "noop_1",
+  "namespace": "default",
+  "name": "noop",
+  "type": "NOOP",
+  "status": "COMPLETED",
+  "input": {
+    "myArray": ["a", "n"],
+    "abc": "def",
+    "__currentExecutionStartTime": 1778186395606
+  },
+  "output": {
+    "abc": "def",
+    "myArray": ["a", "n"],
+    "__currentExecutionStartTime": 1778186395606
+  }
+}
+```
+
+## Example: Reading NOOP Output
+
+```javascript
+(steps, context) => {
+  return {
+    value: steps.noop_1.output.abc,
+    items: steps.noop_1.output.myArray
+  };
+}
+```
+