livetap 0.1.3 → 0.1.4

package/README.md

@@ -28,56 +28,24 @@ Then ask your agent:
 
 ## Setup with Claude Code (for AI agents)
 
-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).
+If you are Claude Code or another AI agent, run `npx livetap --llm-help` for structured setup instructions.
 
-### Step 1: Install with Bun (NOT npm)
+Quick version:
 
 ```bash
-bun init -y              # if no package.json exists
-bun add livetap          # MUST use bun, not npm — postinstall needs bun
-bun pm trust livetap     # required — bun blocks untrusted postinstall scripts
+npm install livetap          # Step 1: install
+npx livetap setup            # Step 2: creates .mcp.json
+# Step 3: tell user to restart Claude Code with:
+#   claude --dangerously-load-development-channels server:livetap --continue
 ```
 
-### Step 2: Verify .mcp.json was created
+**IMPORTANT — do NOT:**
+- Add livetap to `~/.claude/mcp.json` — it goes in `.mcp.json` in the project root
+- Configure livetap as `type: "http"` — it is a stdio MCP server (command + args)
+- Start the daemon manually — the MCP proxy auto-starts it on Claude restart
+- Guess field names — always `read_stream` first to see actual payload structure
 
-The postinstall creates `.mcp.json` in the project root. Check it:
-
-```bash
-cat .mcp.json
-```
-
-It should look like this (path will vary):
-```json
-{
-  "mcpServers": {
-    "livetap": {
-      "command": "bun",
-      "args": ["/path/to/node_modules/livetap/src/mcp/channel.ts"]
-    }
-  }
-}
-```
-
-**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.
-
-If `.mcp.json` was not created, create it manually:
-```bash
-echo '{"mcpServers":{"livetap":{"command":"bun","args":["'$(pwd)'/node_modules/livetap/src/mcp/channel.ts"]}}}' > .mcp.json
-```
-
-### Step 3: Tell the user to restart Claude Code
-
-You CANNOT restart yourself. Tell the user exactly this:
-
-> "livetap is installed and configured. Please restart Claude Code with:
-> ```
-> claude --dangerously-load-development-channels server:livetap
-> ```
-> Then ask me to connect to your data source."
-
-Do NOT try to start the daemon yourself — the MCP proxy auto-starts it when Claude Code restarts.
-
-### Step 4: After restart — use MCP tools
+### After restart — use MCP tools
 
 Once restarted with the channel flag, you have 12 MCP tools available. Follow this workflow:
 

package/bin/livetap.ts

@@ -16,6 +16,7 @@ const commands: Record<string, () => Promise<void>> = {
   watch:    () => import('../src/cli/watch.js').then((m) => m.run(args)),
   unwatch:  () => import('../src/cli/unwatch.js').then((m) => m.run(args)),
   watchers: () => import('../src/cli/watchers.js').then((m) => m.run(args)),
+  setup:    () => import('../src/cli/setup.js').then((m) => m.run(args)),
   mcp:      () => import('../src/mcp/channel.js'),
   help:     () => import('../src/cli/help.js').then((m) => m.run(args)),
 }

package/package.json

@@ -1,13 +1,12 @@
 {
   "name": "livetap",
-  "version": "0.1.3",
-  "description": "Push live data streams into your AI coding agent. Connect MQTT brokers, WebSocket feeds, or tail log files.",
+  "version": "0.1.4",
+  "description": "Push live data streams into your AI coding agent. LLM/AI agent? Run: npx livetap --llm-help",
   "type": "module",
   "bin": {
     "livetap": "./bin/livetap.js"
   },
   "scripts": {
-    "postinstall": "bun ./scripts/postinstall.ts",
     "test": "bun test"
   },
   "keywords": [
@@ -24,7 +23,6 @@
   "files": [
     "bin/",
     "src/",
-    "scripts/postinstall.ts",
     "README.md",
     "LICENSE"
   ],

package/src/cli/setup.ts

@@ -0,0 +1,70 @@
+/**
+ * livetap setup — creates .mcp.json and prints restart instructions.
+ * Works with both npm and bun. Node-compatible (no bun APIs).
+ */
+
+import { existsSync, readFileSync, writeFileSync } from 'fs'
+import { resolve } from 'path'
+
+export async function run(_args: string[]) {
+  const root = process.cwd()
+  const mcpPath = resolve(root, '.mcp.json')
+
+  // Find the channel.ts path relative to where livetap is installed
+  const channelPaths = [
+    resolve(root, 'node_modules', 'livetap', 'src', 'mcp', 'channel.ts'),
+    resolve(root, 'node_modules', '.store', 'livetap', 'src', 'mcp', 'channel.ts'),
+    // Local dev: running from the repo itself
+    resolve(root, 'src', 'mcp', 'channel.ts'),
+  ]
+
+  let channelPath = channelPaths.find((p) => existsSync(p))
+  if (!channelPath) {
+    // Try to resolve from require
+    try {
+      const pkg = require.resolve('livetap/package.json')
+      channelPath = resolve(pkg, '..', 'src', 'mcp', 'channel.ts')
+      if (!existsSync(channelPath)) channelPath = undefined
+    } catch { /* not found */ }
+  }
+
+  if (!channelPath) {
+    console.error('Error: Could not find livetap channel.ts. Is livetap installed?')
+    console.error('Run: npm install livetap')
+    process.exit(1)
+  }
+
+  const mcpEntry = {
+    livetap: {
+      command: 'bun',
+      args: [channelPath],
+    },
+  }
+
+  // Read or create .mcp.json
+  let config: any = {}
+  if (existsSync(mcpPath)) {
+    try {
+      config = JSON.parse(readFileSync(mcpPath, 'utf-8'))
+    } catch {
+      console.error('Warning: .mcp.json exists but is malformed. Overwriting.')
+    }
+  }
+
+  if (config.mcpServers?.livetap) {
+    console.log('✓ livetap already configured in .mcp.json')
+  } else {
+    if (!config.mcpServers) config.mcpServers = {}
+    config.mcpServers.livetap = mcpEntry.livetap
+    writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n')
+    console.log('✓ .mcp.json created with livetap MCP server entry')
+  }
+
+  console.log('')
+  console.log('→ Next step: restart Claude Code with:')
+  console.log('  claude --dangerously-load-development-channels server:livetap --continue')
+  console.log('')
+  console.log('→ After restart, MCP tools are available. Ask Claude to:')
+  console.log('  "Connect to mqtt://broker.emqx.io:1883/sensors/#"')
+  console.log('  "Watch for temperature > 50 and summarize alerts"')
+}

package/src/shared/catalog-generators.ts

@@ -15,8 +15,9 @@ export function generateHelpText(): string {
     'Usage:',
   ]
 
-  // Group: daemon, connections, sampling, watchers
+  // Group: setup, daemon, connections, sampling, watchers
   const groups: { label: string; commands: string[] }[] = [
+    { label: '', commands: ['setup'] },
     { label: '', commands: ['start', 'stop', 'status'] },
     { label: '', commands: ['tap', 'untap', 'taps'] },
     { label: '', commands: ['sip'] },
@@ -50,8 +51,23 @@ export function generateHelpText(): string {
 export function generateLlmHelp(): object {
   return {
     name: 'livetap',
-    version: '0.1.0',
+    version: '0.1.4',
     description: 'Push live data streams into your AI coding agent',
+    setup: {
+      steps: [
+        'Step 1: npm install livetap (skip if already installed)',
+        'Step 2: npx livetap setup (creates .mcp.json in project root — do NOT create it manually)',
+        'Step 3: Tell user to restart Claude Code: claude --dangerously-load-development-channels server:livetap --continue',
+        'Step 4: After restart, use create_connection to connect, read_stream to sample, create_watcher to alert',
+      ],
+      do_not: [
+        'Do NOT add livetap to ~/.claude/mcp.json — it goes in .mcp.json in the project root',
+        'Do NOT configure livetap as type:http — it is a stdio MCP server (command + args)',
+        'Do NOT start the daemon manually — the MCP proxy auto-starts it on Claude restart',
+        'Do NOT guess field names — always read_stream first to see actual payload structure',
+        'Do NOT use npm init — use the existing project directory',
+      ],
+    },
     commands: CLI_COMMANDS,
     mcp_tools: TOOLS,
   }

package/src/shared/command-catalog.ts

@@ -22,6 +22,12 @@ export interface CatalogCommand {
  * are generated from this array.
  */
 export const CLI_COMMANDS: CatalogCommand[] = [
+  // --- Setup ---
+  {
+    name: 'setup',
+    usage: 'livetap setup',
+    description: 'Configure .mcp.json for Claude Code and print restart instructions. Run this after npm install.',
+  },
   // --- Daemon ---
   {
     name: 'start',

package/scripts/postinstall.ts

@@ -1,75 +0,0 @@
-#!/usr/bin/env bun
-/**
- * Postinstall script — auto-configures .mcp.json for Claude Code.
- * Runs after `bun add livetap` or `npm install livetap`.
- */
-
-import { existsSync, readFileSync, writeFileSync } from 'fs'
-import { resolve } from 'path'
-
-const MCP_ENTRY = {
-  livetap: {
-    command: 'bun',
-    args: [resolve(import.meta.dir, '..', 'src', 'mcp', 'channel.ts')],
-  },
-}
-
-function findProjectRoot(): string {
-  // If we're inside node_modules, walk up past it to find the project root
-  const scriptDir = resolve(import.meta.dir)
-  const nmIdx = scriptDir.lastIndexOf('node_modules')
-  if (nmIdx !== -1) {
-    const root = scriptDir.slice(0, nmIdx).replace(/\/$/, '')
-    if (existsSync(resolve(root, 'package.json'))) return root
-  }
-  // Fallback to cwd (e.g. when running postinstall directly for testing)
-  return process.cwd()
-}
-
-function run() {
-  // Skip in CI or when explicitly disabled
-  if (process.env.CI || process.env.LIVETAP_SKIP_POSTINSTALL) return
-
-  const root = findProjectRoot()
-  const mcpPath = resolve(root, '.mcp.json')
-
-  let config: any = {}
-  if (existsSync(mcpPath)) {
-    try {
-      config = JSON.parse(readFileSync(mcpPath, 'utf-8'))
-    } catch {
-      console.warn('\n  ⚠ .mcp.json exists but is malformed. Skipping auto-config.')
-      console.warn('    Add the livetap entry manually (see below).\n')
-      printManualInstructions()
-      return
-    }
-  }
-
-  // Don't overwrite if livetap entry already exists
-  if (config.mcpServers?.livetap) {
-    console.log('\n  ✓ livetap already configured in .mcp.json\n')
-    printRestartInstructions()
-    return
-  }
-
-  // Add livetap entry
-  if (!config.mcpServers) config.mcpServers = {}
-  config.mcpServers.livetap = MCP_ENTRY.livetap
-  writeFileSync(mcpPath, JSON.stringify(config, null, 2) + '\n')
-
-  console.log('\n  ✓ livetap added to .mcp.json\n')
-  printRestartInstructions()
-}
-
-function printRestartInstructions() {
-  console.log('  To enable live data streaming in Claude Code, restart with:\n')
-  console.log('    claude --dangerously-load-development-channels server:livetap\n')
-  console.log('  Then ask Claude: "Connect to mqtt://broker.emqx.io:1883/sensors/#"\n')
-}
-
-function printManualInstructions() {
-  console.log('  Add to .mcp.json:\n')
-  console.log('    ' + JSON.stringify({ mcpServers: MCP_ENTRY }, null, 2).split('\n').join('\n    ') + '\n')
-}
-
-run()