livetap 0.1.1 → 0.1.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +85 -0
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -26,6 +26,91 @@ Then ask your agent:
|
|
|
26
26
|
|
|
27
27
|
> "Connect to the IoT demo at mqtt://broker.emqx.io on topic justinx/demo/# and watch for temperature above 23 degrees"
|
|
28
28
|
|
|
29
|
+
## Setup with Claude Code (for AI agents)
|
|
30
|
+
|
|
31
|
+
If you are Claude Code or another AI agent and a user asks you to install and use livetap, follow these steps **exactly**. Do NOT improvise — livetap uses stdio MCP (not HTTP), and requires Bun (not npm/node).
|
|
32
|
+
|
|
33
|
+
### Step 1: Install with Bun (NOT npm)
|
|
34
|
+
|
|
35
|
+
```bash
|
|
36
|
+
bun init -y # if no package.json exists
|
|
37
|
+
bun add livetap # MUST use bun, not npm — postinstall needs bun
|
|
38
|
+
bun pm trust livetap # required — bun blocks untrusted postinstall scripts
|
|
39
|
+
```
|
|
40
|
+
|
|
41
|
+
### Step 2: Verify .mcp.json was created
|
|
42
|
+
|
|
43
|
+
The postinstall creates `.mcp.json` in the project root. Check it:
|
|
44
|
+
|
|
45
|
+
```bash
|
|
46
|
+
cat .mcp.json
|
|
47
|
+
```
|
|
48
|
+
|
|
49
|
+
It should look like this (path will vary):
|
|
50
|
+
```json
|
|
51
|
+
{
|
|
52
|
+
"mcpServers": {
|
|
53
|
+
"livetap": {
|
|
54
|
+
"command": "bun",
|
|
55
|
+
"args": ["/path/to/node_modules/livetap/src/mcp/channel.ts"]
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
}
|
|
59
|
+
```
|
|
60
|
+
|
|
61
|
+
**IMPORTANT:** livetap is a **stdio MCP server** (command + args), NOT an HTTP MCP server. Do NOT add it to `~/.claude/mcp.json` as `"type": "http"`. The `.mcp.json` in the project root is correct.
|
|
62
|
+
|
|
63
|
+
If `.mcp.json` was not created, create it manually:
|
|
64
|
+
```bash
|
|
65
|
+
echo '{"mcpServers":{"livetap":{"command":"bun","args":["'$(pwd)'/node_modules/livetap/src/mcp/channel.ts"]}}}' > .mcp.json
|
|
66
|
+
```
|
|
67
|
+
|
|
68
|
+
### Step 3: Tell the user to restart Claude Code
|
|
69
|
+
|
|
70
|
+
You CANNOT restart yourself. Tell the user exactly this:
|
|
71
|
+
|
|
72
|
+
> "livetap is installed and configured. Please restart Claude Code with:
|
|
73
|
+
> ```
|
|
74
|
+
> claude --dangerously-load-development-channels server:livetap
|
|
75
|
+
> ```
|
|
76
|
+
> Then ask me to connect to your data source."
|
|
77
|
+
|
|
78
|
+
Do NOT try to start the daemon yourself — the MCP proxy auto-starts it when Claude Code restarts.
|
|
79
|
+
|
|
80
|
+
### Step 4: After restart — use MCP tools
|
|
81
|
+
|
|
82
|
+
Once restarted with the channel flag, you have 12 MCP tools available. Follow this workflow:
|
|
83
|
+
|
|
84
|
+
1. **CONNECT** — `create_connection({ type: "mqtt", broker: "broker.emqx.io", port: 1883, tls: false, topics: ["justinx/demo/#"] })`
|
|
85
|
+
2. **SAMPLE** — `read_stream({ connectionId: "conn_xxx", backfillSeconds: 60, maxEntries: 10 })` — ALWAYS sample first to see field paths
|
|
86
|
+
3. **WATCH** — `create_watcher({ connectionId: "conn_xxx", conditions: [{ field: "sensors.temperature.value", op: ">", value: 50 }], match: "all", cooldown: 60 })`
|
|
87
|
+
|
|
88
|
+
### Supported source types
|
|
89
|
+
|
|
90
|
+
| Type | create_connection params | CLI |
|
|
91
|
+
|------|------------------------|-----|
|
|
92
|
+
| MQTT | `{ type: "mqtt", broker: "host", port: 1883, tls: false, topics: ["topic/#"] }` | `livetap tap mqtt://host:1883/topic/#` |
|
|
93
|
+
| WebSocket | `{ type: "websocket", url: "wss://..." }` | `livetap tap wss://...` |
|
|
94
|
+
| File | `{ type: "file", path: "/var/log/app.log" }` | `livetap tap file:///var/log/app.log` |
|
|
95
|
+
|
|
96
|
+
### Data shape by source
|
|
97
|
+
|
|
98
|
+
- **MQTT/WebSocket (JSON):** payload is parsed. Use dot-paths: `sensors.temperature.value`
|
|
99
|
+
- **File (plain text):** field is `payload`. Use: `{ field: "payload", op: "contains", value: "ERROR" }` or `{ field: "payload", op: "matches", value: "5[0-9]{2}" }`
|
|
100
|
+
- **File (JSON lines):** parsed. Use dot-paths: `level`, `msg`
|
|
101
|
+
- **IMPORTANT:** always `read_stream` first. The field is `payload`, NOT `line` or `message`.
|
|
102
|
+
|
|
103
|
+
### Watcher operators
|
|
104
|
+
|
|
105
|
+
`>`, `<`, `>=`, `<=`, `==`, `!=`, `contains`, `matches` (regex)
|
|
106
|
+
|
|
107
|
+
### If the daemon is not running
|
|
108
|
+
|
|
109
|
+
The MCP proxy auto-starts the daemon. If it fails, run:
|
|
110
|
+
```bash
|
|
111
|
+
livetap start
|
|
112
|
+
```
|
|
113
|
+
|
|
29
114
|
## What it does
|
|
30
115
|
|
|
31
116
|
livetap runs a background daemon that connects to live data sources, buffers messages in embedded Redis, and pushes alerts into your Claude Code session via the [Channels API](https://code.claude.com/docs/en/channels). Your agent sees the data in real-time and can create expression-based watchers that fire when conditions match.
|