@wootsup/mcp 0.1.0 → 0.4.0

package/skills/apimapper/reference/jmespath-cookbook.md

@@ -0,0 +1,241 @@
+# JMESPath Cookbook
+
+Copy-paste recipes for the Transform node. Every recipe below is verified
+against the actual API Mapper JMESPath engine (same one the Transform pipeline
+runs). For the trap list and date/number primitive reference, see
+`jmespath-pitfalls`. For joining two sources, see `merge-two-sources-on-key`.
+
+> **Iterate with `apimapper_jmespath_test`.** Before you wire an expression into
+> a Transform node, dry-run it: `apimapper_jmespath_test({ expression, sample_rows })`
+> returns `{ result, row_count }`, and a bad expression returns the SAME
+> teaching hint (arithmetic, depth-split) you'd hit at flow time — but instantly,
+> with no flow to clean up. Grab real rows with `apimapper_connection_data` first.
+
+---
+
+## If / else — `conditional()` (preferred) or the `(cond && X) || Y` ternary
+
+JMESPath has no native `if/else` statement. API Mapper ships a `conditional()`
+primitive AND the classic short-circuit ternary; pick whichever reads cleaner.
+
+### `conditional(condition, then_value [, else_value])`
+
+```jmespath
+[*].{
+  name: name,
+  status: conditional(stock > `0`, 'in stock', 'sold out')
+}
+# {stock:5} → "in stock"   {stock:0} → "sold out"
+```
+
+Returns `then_value` when `condition` is truthy, `else_value` (default `null`
+when omitted) when falsy. Truthiness mirrors the engine: `false`, `null`,
+`''`, `[]`, `{}` are falsy; **everything else — including `0` — is truthy**.
+
+It is flatter and more readable than the ternary for a simple two-way branch,
+and it **side-steps the ternary's falsy-`X` trap**: `conditional(cond, '', Y)`
+returns the empty string verbatim, whereas `(cond && '') || Y` would wrongly
+fall through to `Y`. (It is not "free" against the depth cap — a function call
+still costs +1 nesting level — but for the simple case it reads better.)
+
+### Ternary — `(cond && X) || Y`
+
+The short-circuit idiom: when `cond` is truthy the `&&` yields `X`; otherwise
+the `||` falls through to `Y`.
+
+```jmespath
+[*].{
+  name: name,
+  status: (stock > `0` && 'in stock') || 'sold out'
+}
+# {stock:5} → "in stock"   {stock:0} → "sold out"
+```
+
+**Gotcha:** if `X` itself can be falsy (e.g. the string `''`, `0`, `false`), the
+`|| Y` branch fires even when `cond` was true. Keep `X` a non-empty constant,
+use `conditional()` instead, or restructure. For a numeric comparison on a
+string field, cast first: `(to_number(price) > \`100\` && 'premium') || 'standard'`.
+You can chain ternaries for >2 branches (`(a && 'x') || (b && 'y') || 'z'`);
+`conditional()` covers the two-way case.
+
+---
+
+## String composition — `join`
+
+`join(separator, array_of_strings)` concatenates. All elements must be strings —
+cast numbers with `to_string()`.
+
+```jmespath
+# "A - 5"
+[*].join(' - ', [name, to_string(stock)])
+
+# Prefix a currency symbol onto a formatted number
+[*].{price: join('', ['$', format_number(price)])}
+# {price:"890000"} → "$890,000"
+
+# Build a full address from parts
+[*].{label: join(', ', [street, city, country])}
+```
+
+To concatenate with no separator, pass `''` as the first arg.
+
+---
+
+## Empty / filled field as a condition (result-pattern)
+
+To branch on whether a field is present-and-non-empty, reuse the ternary —
+an empty string, `null`, or `[]` is falsy:
+
+```jmespath
+[*].{
+  name: name,
+  has_tags: (tags && 'yes') || 'no'
+}
+# {tags:["x"]} → "yes"   {tags:[]} → "no"   {missing} → "no"
+```
+
+To FILTER to only the filled rows:
+
+```jmespath
+[?image_url]                       # keeps rows whose image_url is non-empty
+[?length(tags) > `0`]              # keeps rows with at least one tag
+[?contains(keys(@), 'price')]      # keeps rows where the KEY exists (any value)
+```
+
+(See pitfall #8 in `jmespath-pitfalls` for empty-array vs missing-key.)
+
+---
+
+## Sorting — `sort_by`
+
+`sort_by(array, &field)` sorts ascending by a field. Wrap in `reverse(...)` for
+descending. The `&` makes an expression-reference (don't forget it).
+
+```jmespath
+# Ascending by price
+sort_by([*], &price)
+
+# Descending by date, then take the first 3
+reverse(sort_by([*], &published_at))[:3]
+
+# Sort, then project just the names
+sort_by([*], &stock)[*].name
+```
+
+`sort_by` needs a comparable key. If the field is a numeric STRING, sorting is
+lexical (`"100" < "20"`); normalise upstream or accept string order.
+
+---
+
+## Coordinate keys for a Map element
+
+YOOtheme's Map element binds a `coordinates` array `[lat, lng]`. Build it inline:
+
+```jmespath
+[*].{
+  title: title,
+  coordinates: [lat, lng]
+}
+# → [{ title: "HQ", coordinates: [52.5, 13.4] }]
+```
+
+If lat/lng arrive as strings, cast: `coordinates: [to_number(lat), to_number(lng)]`.
+
+---
+
+## Number formatting — `format_number`
+
+`format_number(value [, decimals=0 [, decimal_sep='.' [, thousands_sep=',']]])`
+groups thousands. Accepts numbers OR numeric strings; returns `null` on
+non-numeric input.
+
+```jmespath
+# 890000 → "890,000"
+[*].{name: name, price: format_number(price)}
+
+# Two decimals: 1234.5 → "1,234.50"
+format_number(`1234.5`, `2`)
+
+# European grouping: 1234567.89 → "1.234.567,89"
+format_number(price, `2`, ',', '.')
+
+# Guard a column with stray non-numeric rows
+[*].coalesce_empty(format_number(price), 'n/a')
+```
+
+---
+
+## Date primitives — weekday / time / date / window
+
+JMESPath has no native date support; API Mapper ships four primitives. The
+optional last arg is an IANA timezone (`'Europe/Berlin'`, `'America/New_York'`,
+`'UTC'`); omit it to keep the offset already in the string. All return `null`
+(or `false` for `time_in_window`) on malformed input.
+
+```jmespath
+# Calendly slot → Sheet-comparable weekday + local time
+[*].{
+  day:        date_weekday(start_time, 'Europe/Berlin'),     # "Wednesday"
+  local_time: date_iso_to_time(start_time, 'Europe/Berlin'), # "09:30"
+  ymd:        date_iso_to_date(start_time, 'Europe/Berlin')  # "2026-06-03"
+}
+
+# Keep only slots inside business hours
+[?time_in_window(date_iso_to_time(start_time, 'Europe/Berlin'), '09:00', '17:00')]
+
+# Cross-midnight window (10pm..2am): from > to is supported
+[?time_in_window(local_time, '22:00', '02:00')]
+```
+
+See `merge-two-sources-on-key` for using these to join a weekday-name source
+against an ISO-datetime source.
+
+---
+
+## Two-Transform split against the depth limit
+
+Expression depth is capped at **10** levels of bracket / pipe nesting. A pipe
+`|` resets the depth counter, so the universal fix for a "too deeply nested"
+422 is to **split one Transform into two piped together** — either inside one
+expression with a pipe, or as two separate Transform nodes wired in series.
+
+```jmespath
+# Too deep — slice + multi-level hash in one breath
+[1:][*].{day: [0], hours: {open: [1], close: [2], extra: {note: [3]}}}
+
+# Fixed — pipe resets, second stage starts fresh and shallow
+[1:] | [*].{day: [0], hours: {open: [1], close: [2]}}
+```
+
+If you hit the cap, also reconsider whether you need the nesting at all — flat
+`[*].{a: x, b: y}` bucket shapes are almost always enough for a YOOtheme
+binding. (Full walk-through: `jmespath-pitfalls` → "Depth-cap warning".)
+
+---
+
+## GIBT-ES-NICHT — things JMESPath does NOT have (and the workaround)
+
+Stop trying these — they raise a syntax error (now annotated with a hint) or
+silently misbehave. Use the workaround.
+
+| You want… | Does NOT exist | Workaround |
+|-----------|----------------|------------|
+| Arithmetic `a + b`, `a - b`, `a * b`, `a / b` | No arithmetic operators at all. `price + tax` is a **syntax error** (annotated *"JMESPath has no arithmetic operators"*). | Compute upstream (in the API, a spreadsheet, or an n8n step), or in a YOOtheme element. For display-only concatenation use `join('', [a, b])`. |
+| Split a string `split(s, ',')` | No `split`. | Pre-split upstream, or if the API returns an array use it directly. For a CSV cell, request a structured endpoint instead. |
+| Regex match / replace | No regex. | Use `contains(@, 'substr')`, `starts_with`, `ends_with` for membership. For replace, normalise the data upstream. |
+| `if / else` / `switch` | No statement forms. | `conditional(cond, X, Y)` (flat, two-way) or the ternary `(cond && X) || Y` (above). Chain ternaries for >2 branches: `(a && 'x') || (b && 'y') || 'z'`. |
+| Uppercase / lowercase | No case functions. | Normalise casing upstream (the source API or a Transform-feeding step). |
+| Sum / count-with-condition | No `sum`/aggregate over a predicate. | `length([?cond])` counts matching rows. For a real sum, aggregate upstream. |
+| Date math (`+ 1 day`) | No date arithmetic. | Use the date primitives for extraction/formatting/windowing only; do calendar math upstream. |
+
+When in doubt, paste the expression into `apimapper_jmespath_test` — a failing
+expression tells you exactly which of these you tripped over.
+
+---
+
+## See also
+
+- `jmespath-pitfalls` — the 9 traps + primitive reference + depth-cap detail.
+- `merge-two-sources-on-key` — joining two sources, with date-primitive bridging.
+- `conditional-style-multi-items` — per-row YOOtheme styles from a row field.
+- `yootheme-source-to-builder-handoff` — where the empty/filled string fields you build here drive a theme layout's `_condition` (`'!'`/`'!!'`) in the `#parent` repeater form.

package/skills/apimapper/reference/jmespath-pitfalls.md

@@ -0,0 +1,189 @@
+# JMESPath Pitfalls
+
+The nine traps that bite every Transform JMESPath expression in API Mapper, plus the date-primitive functions added in 2.0.8 that finally make weekday-name ↔ ISO-datetime joins tractable.
+
+## The 9 traps
+
+1. **Top-level vs item-level scope.** A flat `[].name` projects across items; bare `name` reads the wrapper object. Mixing the two is the most common cause of `null` everywhere.
+2. **Implicit numeric coercion.** `[?price > 100]` reads `price` as a string when the API returns a string. Cast first with `to_number(price) > \`100\`` or normalize upstream.
+3. **`@` vs nothing.** Inside multi-select hashes the `@` refers to the current item — `{name: @.name}` is shorthand. Forgetting `@` inside a filter expression (`[?@.x == 'y']`) is silently parsed as a function call.
+4. **String-quoted literals.** JSON literals use backticks: `\`100\``, `\`true\``, `\`null\``. Single-quoted strings (`'red'`) are raw strings. Mixing them up yields lexer errors that the engine reports far from the actual typo.
+5. **`null` propagation through pipes.** `items | [].name | [?contains(@, 'foo')]` returns `null` (not `[]`) when an item has no `name`. Wrap with `coalesce_empty(@, '')` or filter `not_null(@)`.
+6. **`length()` on null.** Vendor `length(null)` throws. Use `length(@.items || \`[]\`)` to default.
+7. **Backslash-escapes inside raw strings.** Single-quoted strings do NOT honour `\n` / `\t`. To embed a literal `'` use `'\\''` (close, escape, open).
+8. **Empty-array vs missing-key.** `[?tags]` keeps items whose `tags` is non-empty AND non-null. To match items with the *key* present regardless of value, use `[?contains(keys(@), 'tags')]`.
+9. **Multi-projection collapse on header-skip slices.** `[1:][*].{weekday: [0], open: [1]}` looks like "slice off the header row, then map each remaining row into a hash", but JMESPath parses `[1:][*]` as a *chained multi-projection* that flattens row boundaries before the hash runs. The fix is one pipe: `[1:] | [*].{weekday: [0], open: [1]}`. See "Symptom / Cause / Fix" below.
+
+### Pitfall 9 in detail (header-skip slice → hash projection)
+
+**Symptom.** Output schema auto-detection returns flat columns prefixed with the row index, like:
+
+```
+0_weekday, 0_open, 0_close,
+1_weekday, 1_open, 1_close,
+2_weekday, 2_open, 2_close, ...
+```
+
+Each row also reads as `null` in the actual data preview. Every binding in the Multi-Items element lands on the wrapper object instead of the row.
+
+**Cause.** `[1:][*]` is two consecutive projections. JMESPath flattens them: the inner array index dissolves, so the trailing `.{weekday: [0], ...}` operates on the wrapper object's positional slots, not on each row. The auto-detected schema reflects that flattened shape.
+
+**Fix.** Insert a pipe between the slice and the hash projection so the second stage starts fresh:
+
+```jmespath
+# Working — pipe resets the projection so [*] iterates row-by-row
+[1:] | [*].{
+  weekday: [0],
+  open:    [1],
+  close:   [2]
+}
+```
+
+This recipe is the canonical shape for "Google Sheets export with a header row" sources. If you find yourself debugging `0_*` / `1_*` / `2_*` column names in the YOOtheme source field picker, this is almost always the cause.
+
+## Date-primitive functions (new in 2.0.8)
+
+JMESPath has no built-in date support. API Mapper ships four custom date primitives so weekday-name ↔ ISO-datetime joins (Calendly → Sheet schedule, HubSpot meeting-times → office-hours, etc.) become possible without exporting to a sidecar service.
+
+| Function | Signature | Returns |
+|----------|-----------|---------|
+| `date_weekday` | `date_weekday(iso_string [, tz])` | English weekday name `"Monday"`..`"Sunday"`, or `null` on bad input |
+| `date_iso_to_time` | `date_iso_to_time(iso_string [, tz])` | `"HH:MM"` 24-hour time, or `null` |
+| `date_iso_to_date` | `date_iso_to_date(iso_string [, tz])` | `"YYYY-MM-DD"` calendar date, or `null` |
+| `time_in_window` | `time_in_window(time, from, to)` | `true` if `time` is in `[from, to)`. Supports cross-midnight when `from > to`. `false` on any malformed input |
+
+### Timezone rules
+
+- `tz` is an IANA timezone string (`"Europe/Berlin"`, `"America/New_York"`, `"UTC"`).
+- If `tz` is omitted, the offset already encoded in the input string is preserved. A Calendly payload `"2026-06-04T09:00:00+02:00"` returns `"09:00"` from `date_iso_to_time(@, )` (no second arg) — i.e. the customer's local time.
+- If `tz` IS supplied, the datetime is shifted into that zone first.
+- An unknown timezone (typo, mistaken country code) returns `null`. This is the same graceful-failure mode as malformed datetimes — one bad row never crashes the flow.
+
+### The Maria recipe (Calendly + Sheet weekday-join)
+
+```
+# Source A — Calendly available_times
+[].{
+  day: date_weekday(start_time, 'Europe/Berlin'),
+  local_time: date_iso_to_time(start_time, 'Europe/Berlin'),
+  start_time: start_time
+}
+```
+
+Now each Calendly slot carries a Sheet-comparable `day` (e.g. `"Wednesday"`) AND a comparable `local_time` (e.g. `"09:30"`). See `merge-two-sources-on-key` for the full join pattern.
+
+### Slot-against-business-hours filter
+
+```
+[?time_in_window(date_iso_to_time(start_time, 'Europe/Berlin'),
+                 '09:00', '17:00')]
+```
+
+Cross-midnight windows (bars, support shifts):
+
+```
+[?time_in_window(local_time, '22:00', '02:00')]   # 10pm..2am
+```
+
+## Number formatting — `format_number()`
+
+JMESPath has no arithmetic and no number-format support, so a price field
+arrives as raw digits and renders as `$890000` instead of `$890,000`. The
+`format_number()` primitive (new in 2.0.13) groups thousands and fixes
+decimals — the number-format analogue of the date primitives above.
+
+| Signature | Returns |
+|-----------|---------|
+| `format_number(value [, decimals [, decimal_sep [, thousands_sep]]])` | grouped string, or `null` on non-numeric input |
+
+- `value` — a number OR a numeric string (Sheets/REST often deliver `"1250000"`). Anything non-numeric (including `true`/arrays/empty string) → `null`.
+- `decimals` — digits after the decimal separator (default `0`). Rounds half-up.
+- `decimal_sep` — default `"."`.
+- `thousands_sep` — default `","`.
+
+```jmespath
+# US dollars, no cents — the SunWest case
+[*].{name: name, price_display: format_number(price)}
+#   890000   → "890,000"
+#   1450000  → "1,450,000"
+```
+
+```jmespath
+# Two decimals
+format_number(`1234.5`, `2`)            # "1,234.50"
+
+# European grouping (1.234.567,89)
+format_number(price, `2`, ',', '.')
+```
+
+Prefix the currency symbol in the same expression with `join`:
+
+```jmespath
+[*].{price: join('', ['$', format_number(price)])}   # "$890,000"
+```
+
+Because `format_number` returns `null` on bad input, wrap it with
+`coalesce_empty` when a column may contain stray non-numeric rows:
+
+```jmespath
+coalesce_empty(format_number(price), 'n/a')
+```
+
+> Reminder: JMESPath still has **no arithmetic operators** (`+ - * /`). If you
+> try `price + tax` the engine raises a syntax error now annotated with
+> *"JMESPath has no arithmetic operators"*. Compute totals upstream, in a
+> YOOtheme element, or concatenate strings with `join('', [a, b])`.
+
+## Logic primitive — `conditional()`
+
+JMESPath has no `if/else` statement. The classic workaround is the
+short-circuit ternary `(cond && X) || Y`, but it has a sharp edge: when `X` is
+itself falsy (`''`, `0`, `false`) the `|| Y` branch fires even though `cond` was
+true. The `conditional()` primitive is a flat, readable if/else without that
+trap.
+
+| Signature | Returns |
+|-----------|---------|
+| `conditional(condition, then_value [, else_value])` | `then_value` when `condition` is truthy; `else_value` (default `null`) when falsy |
+
+Truthiness mirrors the engine: `false`, `null`, `''` (empty string), `[]`
+(empty array) and `{}` (empty object) are falsy — **everything else, including
+`0`, is truthy**.
+
+```jmespath
+# per-row in-stock badge from a stock field
+[*].{name: name, in_stock: conditional(stock > `0`, 'in stock', 'sold out')}
+#   {stock:5} → "in stock"   {stock:0} → "sold out"
+
+# returns a falsy then-value verbatim — no ternary fall-through
+[*].{label: conditional(is_featured, '', 'standard')}
+#   is_featured truthy → ""   (the ternary (is_featured && '') || 'standard' would
+#   have wrongly returned "standard")
+```
+
+`conditional()` is **flatter and more readable** than the ternary for a simple
+two-way branch — but it does NOT dodge the depth cap: a function call still
+costs `+1` nesting level. For >2 branches, chain ternaries
+(`(a && 'x') || (b && 'y') || 'z'`); `conditional()` covers the two-way case.
+
+## Depth-cap warning
+
+JMESPath expression depth is capped at **10 levels** of bracket / pipe nesting. Above that, the engine returns `expression too deeply nested (N levels)`.
+
+**As of 2.0.8 this is caught at flow-write time** (HTTP 422 on `flow_create` / `flow_update`) with per-node `jmespathErrors`. The response payload looks like:
+
+```json
+{
+  "success": false,
+  "error": "1 JMESPath expression exceeded the depth limit of 10",
+  "jmespathErrors": { "t1": "JMESPath expression too deeply nested (13 levels). Maximum: 10" },
+  "status": 422
+}
+```
+
+If you hit this, the cure is almost always to split the expression into TWO transform nodes piped together — that resets the depth counter and is easier to debug.
+
+## See also
+
+- `merge-two-sources-on-key` — joining two sources on a shared key, with date-primitive bridging.
+- `troubleshooting` — broader error triage.

package/skills/apimapper/reference/joomla.md

@@ -70,7 +70,7 @@ Joomla extensions install as a `.zip` (system plugin). The MCP server bundles a
 To verify the plugin is loaded:
 ```
 apimapper_health
-# → { platform: "joomla", version: "2.0.7", plugin: "enabled" }
+# → { platform: "joomla", version: "2.0.13", plugin: "enabled" }
 ```
 
 If `plugin: "disabled"`, enable via Joomla admin → Extensions → Plugins → search "API Mapper".

package/skills/apimapper/reference/library-template-discovery.md

@@ -0,0 +1,65 @@
+# Library template discovery
+
+Inspect a library template's contract BEFORE you activate it, so the connection
+lands fully configured the first time.
+
+## Why this matters
+
+The library is the mandatory first stop for any new API (see the library-first
+guard below). But before you call `apimapper_library_activate`, you want to know
+what the template actually declares: which base URL and endpoints it ships, which
+auth scheme it needs, and which placeholder values (`extra_fields`) you must pass.
+Activating blind is the single most common cause of an empty source that is hard
+to debug from downstream tool calls.
+
+## The discovery sequence
+
+```
+apimapper_library_featured({})                       # 1. the curated short-list
+apimapper_library_list({ search: '<api-name>' })     # 2. search the full catalog by name (param is `search`, 3+ chars)
+apimapper_library_connection_detail({ id: '<id>' })  # 3. read the template's full contract
+apimapper_credential_list({})                        # 4. find a matching credential (auth-protected templates)
+apimapper_library_activate({ id, credential_id, extra_fields })  # 5. activate, fully configured
+```
+
+Steps 1-2 are routed first-class; step 3 routes through the gateway:
+`apimapper_advanced({ tool: 'apimapper_library_connection_detail', arguments: { id } })`.
+
+## What `library_connection_detail` tells you
+
+Read these fields off the returned template before activating:
+
+| Field | What to do with it |
+|-------|--------------------|
+| `base_url` | The upstream host. Confirms which API the template targets. |
+| `endpoints` | The named requests the template ships (list/detail/search). The activated connection exposes these. |
+| `auth` scheme | `none`, `bearer`, `api_key`, or `oauth`. Tells you whether step 4 (credential) is required. |
+| `extra_fields` | The placeholder values YOU must supply at activation time (e.g. `spreadsheet_id` for Google Sheets, `api_key` for Pexels). Required `extra_fields` left unset land a broken connection. |
+
+## Then activate, not create
+
+Once you have read the contract:
+
+- **Auth-protected template** (Google Sheets, Notion, Airtable, Pexels,
+  OpenWeatherMap, Calendly, GitHub, ...): call `apimapper_credential_list({})`
+  first, then pass the right `credential_id` explicitly to `library_activate`.
+  The activation auto-links a credential only when exactly ONE matching one
+  exists for the provider; otherwise it returns a structured
+  `credential_required` / `credential_ambiguous` error listing the candidates.
+- Pass any required `extra_fields` the template declared in step 3.
+
+## The library-first guard (why you discover instead of hand-rolling)
+
+`apimapper_connection_create` is the fallback for niche or unknown APIs ONLY. The
+server enforces this: a custom `connection_create` whose endpoint host is covered
+by a curated template is rejected with HTTP 409 `error_code:
+library_template_available`. The error names the template and the exact
+`apimapper_library_activate({ id })` call to run instead, with a structured
+`library_suggestion`. Always inspect-then-activate before reaching for a custom
+connection.
+
+## Cross-references
+
+- `apimapper_get_skill({ topic: 'getting-started' })` — Step 1 (mandatory): check the library first.
+- `apimapper_get_skill({ topic: 'oauth' })` — wiring OAuth-protected templates.
+- `apimapper_library_connection_detail` — the tool this topic is about.