@readymadeit/mcp 0.0.0-stage → 0.1.0

package/bundle/docs/content/services/trigger-pad.md

@@ -0,0 +1,68 @@
+# Trigger Pad
+
+A grid of assignable buttons; pressing a pad sends its configured payload into the pipeline.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/trigger-pad` |
+
+---
+
+## What it does
+
+TriggerPad displays a grid of pads in its service card. Each pad can
+have an arbitrary JSON payload assigned to it. When a pad is pressed
+(or triggered programmatically) it fires that payload through the
+downstream pipeline.
+
+The service has an "armed" pad concept: one pad is designated the
+currently active pad, and it can be advanced programmatically.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `padAssignments` | `Record<number, any>` | `{}` | Map of pad index → payload to emit |
+| `armedPad` | `number` | `0` | Index of the currently active/armed pad |
+
+### Commands
+
+Send as `command.action` to trigger behaviour programmatically:
+
+| Action | Params | Description |
+|---|---|---|
+| `"trigger-pad"` | `{ padIndex: number }` | Fire the payload of the specified pad |
+| `"clear-pad"` | `{ padIndex: number }` | Remove the payload assignment for a pad |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Ignored (pads fire independently on user interaction) |
+| **Output** | The JSON payload assigned to the triggered pad |
+
+---
+
+## Example: assign payloads to three pads
+
+```json
+{
+  "padAssignments": {
+    "0": { "action": "start", "speed": 1.0 },
+    "1": { "action": "stop" },
+    "2": { "action": "reset", "speed": 0.5 }
+  },
+  "armedPad": 0
+}
+```
+
+Pressing pad 0 emits `{ "action": "start", "speed": 1.0 }` into the
+pipeline.

package/bundle/docs/content/services/uuid-generator.md

@@ -0,0 +1,48 @@
+# UUID Generator
+
+Generates a UUID on every pipeline tick and emits it or merges it into the incoming object.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/uuid-generator` |
+
+---
+
+## What it does
+
+UUID Generator produces a new UUID each time `process()` is called (or when triggered via `configure({ action: "generate" })`). The UUID version is configurable, and the output mode controls whether the UUID is emitted as a plain string or merged into the incoming value.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `method` | `"v1"` \| `"v4"` | `"v4"` | UUID version. `v4` is random; `v1` is time-based. |
+| `mode` | `"plain"` \| `"merge"` | `"plain"` | Output mode. `plain` emits the UUID string directly; `merge` adds a `uuid` key to the incoming object. |
+| `action: "generate"` | — | — | Triggers immediate UUID generation and emission via `app.next()` |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value (only used in `merge` mode) |
+| **Output (plain)** | UUID string, e.g. `"a3bb189e-8bf9-3888-9912-ace4e6543002"` |
+| **Output (merge)** | `{ ...params, uuid: "<generated-uuid>" }` |
+
+---
+
+## Example: tag each pipeline value with a unique ID
+
+```json
+{ "method": "v4", "mode": "merge" }
+```
+
+Input: `{ "data": "hello" }`
+Output: `{ "data": "hello", "uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479" }`

package/bundle/docs/content/services/wav-reader.md

@@ -0,0 +1,66 @@
+# WAV Reader
+
+Reads a WAV audio file from disk and emits its samples as a float array.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| hkp-rt | `wav-reader` |
+
+Runs on hkp-rt, and reads only inside the folders that runtime gives boards
+(see [Filesystem](./filesystem.md#where-the-files-are)). Not available in the
+browser runtime.
+
+---
+
+## What it does
+
+WAV Reader opens a WAV file at a configured path, decodes it, and emits
+the audio samples as an array of floating-point values. The samples are
+normalised to the range `[-1.0, 1.0]`.
+
+The service can operate in one-shot mode (emit all samples once) or
+streaming mode (emit samples in blocks suitable for downstream processing
+services such as FFT).
+
+---
+
+## Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `filePath` | `string` | The `.wav` file, inside the folders boards are given; a relative path is taken from the default one |
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Any value (trigger to start reading) |
+| **Output** | Array of `float` samples in `[-1.0, 1.0]`, or a ring-buffer compatible with audio processing services |
+
+---
+
+## Typical use
+
+### Offline spectrum analysis
+
+```
+wav-reader → fft → monitor
+```
+
+Feed a WAV file through FFT to visualise its frequency content without
+a live microphone.
+
+### Audio processing chain
+
+```
+timer (trigger) → wav-reader → fft → map → ifft → core-output
+```
+
+Apply frequency-domain effects to a pre-recorded file and play the
+result through the system speakers.

package/bundle/docs/content/services/websocket.md

@@ -0,0 +1,189 @@
+# WebSocket
+
+Four hkp-rt services for bidirectional WebSocket communication: reader, writer, server, and client. hkp-node has the reader.
+
+---
+
+## Available in
+
+| Runtime | Service IDs |
+|---|---|
+| hkp-rt | `websocket-reader`, `websocket-writer`, `websocket-server`, `websocket-client` |
+| hkp-node | `websocket-reader` |
+
+These services are not available in the browser runtime. For browser-side
+WebSocket connectivity use [Input](./input.md) and [Output](./output.md).
+
+---
+
+## Overview
+
+The four services cover the two axes of WebSocket communication:
+
+| | Accepts connections (passive) | Initiates connections (active) |
+|---|---|---|
+| **Receives data** | `websocket-reader` | `websocket-client` |
+| **Sends data** | `websocket-server` | `websocket-writer` |
+
+Mix and match based on which side initiates and which side produces data.
+
+---
+
+## websocket-reader
+
+Listens on a local port for an incoming WebSocket connection. When a
+client connects and sends a message, the message is emitted downstream as
+a pipeline trigger.
+
+### Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `host` | `string` | Interface to listen on (e.g. `"0.0.0.0"`) |
+| `port` | `string` | Port number to bind |
+| `path` | `string` | URL path to accept connections on (e.g. `"/stream"`) |
+
+### Input / Output
+
+- **Input**: ignored
+- **Output**: each received WebSocket message, parsed as JSON if valid
+
+### On hkp-node
+
+hkp-node binds no ports: the reader is served at a mount its runtime assigns,
+published in `__hkpMount` like every hkp-node endpoint, and a
+[websocket-writer](#websocket-writer) points at it with
+`hkp-mount://<runtime>/<service>`. Because that address is public, a client
+must present a key.
+
+| Property | Type | Description |
+|---|---|---|
+| `key` | `string` | What a client must present, as `Authorization: Bearer <key>` — never in the query string, where proxies and logs would keep it; usually `{{secret.<alias>}}`. Unset, nobody is let in. Changing it closes every connection, and a secret given a new value takes no more messages from a client that connected with the old one (closed with code 1008) |
+| `exclusive` | `boolean` | One client at a time: a new one closes the one before, which is what a client reconnecting after its network dropped looks like from here. Default `false`, every client's messages are handed on |
+| `mountName` | `string` | Names the mount; renaming it rotates the address |
+
+Each message is a pass of its own through the services after the reader and
+on to the next runtime, in the order they arrive: a binary message as bytes
+(a `Buffer`), a text message parsed as JSON where it is JSON and as a string
+otherwise. What passes through the reader itself is handed on unchanged.
+
+State reports `connections`: each client's `address`, `seconds` connected,
+`messages` and `bytesReceived`. `host`, `port` and `path` are accepted and
+ignored, so a board written for hkp-rt still loads.
+
+---
+
+## websocket-writer
+
+Sends what passes through to a WebSocket somewhere else, one message per pass,
+and hands the pass on unchanged. It connects **outward**, so a runtime behind a
+NAT can feed a server that could never reach it. For example, a home machine
+can stream to a relay in the cloud ([Live Radio (Cloud, direct)](../boards/live-radio-cloud-direct-demo-board.md)).
+
+### Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `url` | `string` | `ws://…` or `wss://…`. An `http(s)://` address is taken to mean the WebSocket at the same place. `hkp-mount://<runtime>/<service>` names an endpoint instead (see below) |
+| `path` | `string` | Appended to a mount's address, e.g. `/live.mp3` |
+| `headers` | `object` | Sent with the handshake; `{{secret.<alias>}}` in a value is resolved for the host being connected to |
+| `maxQueueBytes` | `number` | How much may wait while the connection is slow or down (default 16384, about a second at 128 kbit/s); past it the oldest messages are dropped |
+
+**Nothing waits on the network.** Each pass is queued and handed on at once. A
+thread of the service's own connects, writes one message at a time, and
+reconnects with backoff (0.5 s, doubling to 10 s) when the connection drops.
+Keep-alive pings detect a connection that died without closing. For anything
+live, the newest data is what matters, which is why the queue drops the oldest.
+
+**A mount reference** works like [http-client](./http.md#calling-an-endpoint-whose-address-is-assigned-at-load-time):
+the board's coordinator writes the endpoint's address into `__hkpMount`, and the
+writer connects to that address plus `path`. Until then its status is `waiting`.
+
+### Input / Output
+
+- **Input**: bytes are sent as binary messages; text and JSON as text
+  messages; MixedData's binary as bytes; a ring buffer as its serialised samples
+- **Output**: the input, unchanged
+
+State reports `status` (`idle`, `waiting`, `connecting`, `connected`,
+`reconnecting`), the last `error`, the `target` actually dialled, and
+`sentBytes`, `droppedMessages` and `reconnects`.
+
+**The older form.** Boards that give `host`, `port` and `path` instead of `url`
+connect over plain `ws://` and open with the `{"type":"writer"}` hello that
+hkp-rt's own websocket-server uses to pair a writer.
+
+---
+
+## websocket-server
+
+Hosts a WebSocket server and broadcasts each upstream pipeline value to
+all currently connected clients.
+
+### Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `host` | `string` | Interface to bind (e.g. `"0.0.0.0"`) |
+| `port` | `string` | Port to listen on |
+| `path` | `string` | Accepted connection path |
+
+### Input / Output
+
+- **Input**: any JSON value — broadcast to all connected clients
+- **Output**: passes through to next service
+
+---
+
+## websocket-client
+
+Connects to a remote WebSocket server and emits each incoming message
+from the server as a pipeline trigger (mirroring `websocket-reader` but
+on the initiating side).
+
+### Configuration
+
+| Property | Type | Description |
+|---|---|---|
+| `host` | `string` | Remote server hostname |
+| `port` | `string` | Remote server port |
+| `path` | `string` | URL path on the remote server |
+
+### Input / Output
+
+- **Input**: ignored
+- **Output**: each message received from the remote server
+
+---
+
+## Typical patterns
+
+### Bridge: browser → hkp-rt
+
+Browser Output sends to a WebSocket URL; hkp-rt websocket-reader receives:
+
+```
+Browser:  Timer → Map → Output (ws://hkp-rt:9000/in)
+hkp-rt:   websocket-reader (port 9000) → FFT → monitor
+```
+
+### Relay: hkp-rt at home → hkp-node in the cloud
+
+The writer connects outward, so the home machine needs no open port; the
+reader's key decides who may feed the relay:
+
+```
+hkp-rt:   core-input → audio-encode → websocket-writer (hkp-mount://relay/ingest) → stopper
+hkp-node: websocket-reader "ingest" (key) → http-server-subservices (stream) → stopper
+```
+
+See [Live Radio (Cloud, direct)](../boards/live-radio-cloud-direct-demo-board.md).
+
+### Bridge: hkp-rt → browser
+
+hkp-rt websocket-server pushes to browser Input:
+
+```
+hkp-rt:   core-input → fft → websocket-server (port 9001)
+Browser:  Input (ws://hkp-rt:9001) → Canvas
+```

package/bundle/docs/content/services/workflow-board-builder.md

@@ -0,0 +1,65 @@
+# Workflow Board Builder
+
+Generates a complete HKP board JSON from a natural language description using an AI model.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/workflow-board-builder` |
+
+---
+
+## What it does
+
+Workflow Board Builder sends a natural language workflow description to a large language model (Claude, OpenAI, or Gemini) and asks it to produce a valid HKP board JSON. The generated board is displayed in an embedded editor where it can be reviewed, edited, and loaded into the runtime.
+
+The prompt sent to the model includes a detailed system prompt that describes the board JSON schema, the available services and their configuration, and example boards.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `provider` | `"claude"` \| `"openai"` \| `"gemini"` | `"claude"` | AI provider to use |
+| `model` | `string` | Provider-specific default | Model name (e.g. `"claude-3-7-sonnet-latest"`, `"gpt-4.1-mini"`, `"gemini-2.0-flash"`) |
+| `description` | `string` | Example description | Natural language description of the desired board |
+| `inputBoardSource` | `string` | `""` | Optional existing board JSON to refine or extend |
+| `generatedBoardSource` | `string` | Default board | The generated board JSON (editable in the UI) |
+
+### Default models per provider
+
+| Provider | Default model |
+|---|---|
+| `claude` | `claude-3-7-sonnet-latest` |
+| `openai` | `gpt-4.1-mini` |
+| `gemini` | `gemini-2.0-flash` |
+
+### API keys
+
+API keys are read from the user vault:
+- Claude: `claude-api-key`
+- OpenAI: `openai-api-key`
+- Gemini: `gemini-api-key`
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Ignored (generation is triggered through the UI) |
+| **Output** | None — the generated board is loaded via the UI |
+
+---
+
+## How it works
+
+1. The user writes a description in the UI (e.g. "Fetch the top Hacker News stories every minute and display them").
+2. Clicking **Generate** sends the description + an optional input board to the model with the HKP system prompt.
+3. The model returns a board JSON.
+4. The JSON is shown in the embedded Monaco editor.
+5. The user clicks **Load Board** to apply it to the runtime.

package/bundle/docs/content/services/xy-pad.md

@@ -0,0 +1,60 @@
+# XY Pad
+
+A 2D touch/drag surface that emits normalised x/y coordinates on every interaction.
+
+---
+
+## Available in
+
+| Runtime | Service ID |
+|---|---|
+| Browser | `hookup.to/service/xy-pad` |
+
+---
+
+## What it does
+
+XYPad displays an interactive 2D surface in its service card. As the
+user moves a pointer (mouse or touch) across the surface, it
+continuously emits the current position as a JSON object. The pad
+optionally divides its area into a grid of discrete cells.
+
+---
+
+## Configuration
+
+| Property | Type | Default | Description |
+|---|---|---|---|
+| `gridRows` | `number` | `0` | Number of discrete rows; `0` = continuous |
+| `gridCols` | `number` | `0` | Number of discrete columns; `0` = continuous |
+
+When `gridRows` and `gridCols` are both `0`, the pad emits a continuous
+normalised position. When set, the pad snaps to cell centres and emits
+the cell index alongside the position.
+
+---
+
+## Input / Output
+
+| | Shape |
+|---|---|
+| **Input** | Ignored — XYPad generates its own triggers on interaction |
+| **Output** | `{ x: number, y: number, eventType: string, timestamp: number }` |
+
+- **`x`**, **`y`**: normalised position in the range `[0, 1]`; `(0, 0)` is the top-left corner
+- **`eventType`**: the pointer event type (`"pointermove"`, `"pointerdown"`, `"pointerup"`)
+- **`timestamp`**: `performance.now()` at the time of the event
+
+In grid mode, additional fields `col` and `row` (zero-indexed integers)
+are included.
+
+---
+
+## Example uses
+
+- Feed `x` and `y` into a Map service to control audio parameters, canvas
+  positions, or API request values.
+- Gate output through a Filter that only passes `eventType === "pointerdown"`
+  to react to click/tap events only.
+- Use a `gridRows: 4, gridCols: 4` configuration as a 16-step pad
+  controller.