@solidrt/cli 0.0.24 → 0.0.25

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@solidrt/cli",
-  "version": "0.0.24",
+  "version": "0.0.25",
   "license": "MIT",
   "author": "Antoine van Wel",
   "type": "module",
@@ -17,17 +17,18 @@
     "@babel/core": "^7.0.0",
     "@babel/plugin-syntax-jsx": "^7.0.0",
     "@babel/preset-typescript": "^7.0.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "babel-preset-solid": "2.0.0-beta.15",
     "bonjour-service": "^1.4.0",
     "qrcode-generator": "^2.0.4"
   },
   "optionalDependencies": {
-    "@solidrt/darwin-arm64": "0.0.24",
-    "@solidrt/linux-x64-gnu": "0.0.24",
-    "@solidrt/win32-x64-msvc": "0.0.24"
+    "@solidrt/darwin-arm64": "0.0.25",
+    "@solidrt/linux-x64-gnu": "0.0.25",
+    "@solidrt/win32-x64-msvc": "0.0.25"
   },
   "peerDependencies": {
-    "@solidrt/core": "0.0.24",
+    "@solidrt/core": "0.0.25",
     "typescript": "^6"
   },
   "devDependencies": {

package/scaffold/AGENTS.md

@@ -84,3 +84,19 @@ Authoritative references ship inside the installed packages - read them:
 - bunx srt render src/index.tsx --size 480x640 --duration 1 --fps 2 - headless
   render to PNG frames (proves it renders; see the cli AGENTS.md for where the
   frames land)
+
+## MCP: inspect the running app
+
+The project ships an MCP server (.mcp.json, `srt mcp`) that talks to the dev
+server `bunx srt run` starts. When it is loaded in your environment, prefer
+its tools over guessing at runtime state:
+
+- list_clients: connected app clients, their platform and runtime capabilities
+- get_logs: console output and runtime errors (seq cursor; `wait_ms` long-poll
+  to catch output right after a reload)
+- get_render_tree: what the app actually rendered - node kinds, text, and
+  window-relative boxes
+- get_stats: fps, CPU/memory, frame phase timings, setProperty rate
+
+The tools need a running app: if list_clients is empty, ask the user to start
+`bunx srt run src/index.tsx`.

package/scaffold/mcp.json

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "solidrt": {
+      "command": "bun",
+      "args": ["node_modules/@solidrt/cli/bin/srt", "mcp"]
+    }
+  }
+}

package/scaffold/package.json

@@ -9,12 +9,12 @@
     "android": "srt client --android"
   },
   "dependencies": {
-    "@solidrt/core": "0.0.24",
-    "@solidrt/components": "0.0.24"
+    "@solidrt/core": "0.0.25",
+    "@solidrt/components": "0.0.25"
   },
   "devDependencies": {
-    "@solidrt/cli": "0.0.24",
-    "@solidrt/flux-types": "0.0.24",
+    "@solidrt/cli": "0.0.25",
+    "@solidrt/flux-types": "0.0.25",
     "typescript": "^6"
   }
 }

package/src/args.ts

@@ -75,6 +75,7 @@ Commands:
   bundle <file>          Transpile TS/JS/TSX/JSX to JS or bytecode
   render <file.tsx|jsx>  Replay a script (optional) and render frames for video generation
   pack <file>            Bundle + compile to a standalone executable (experimental)
+  mcp                    MCP server (stdio) exposing the running dev server to coding agents
 
 init options:
   -t, --template <name>  Start from a named template (skips the interactive picker)

package/src/commands/init.ts

@@ -16,6 +16,7 @@ const TEMPLATE_FILES: Array<{ from: string; to: string }> = [
   { from: "package.json", to: "package.json" },
   { from: "tsconfig.json", to: "tsconfig.json" },
   { from: "gitignore", to: ".gitignore" },
+  { from: "mcp.json", to: ".mcp.json" },
   { from: "AGENTS.md", to: "AGENTS.md" },
 ]
 

package/src/commands/mcp.ts

@@ -0,0 +1,128 @@
+// The MCP bridge: a stdio Model Context Protocol server exposing the dev
+// server's control API (/__control__/) as tools for coding agents. Stateless
+// glue: every tool call is one HTTP request to the running dev server, so the
+// bridge works no matter which process (or how many agents) spawned it.
+//
+// stdout is the JSON-RPC channel; nothing here may print to it.
+
+import { DEV_PORT } from "../dev-server"
+
+const CONTROL_BASE = `http://127.0.0.1:${DEV_PORT}/__control__`
+
+type ControlResult = { ok: true; body: any } | { ok: false; message: string }
+
+async function control(path: string): Promise<ControlResult> {
+  let resp
+  try {
+    resp = await fetch(CONTROL_BASE + path)
+  } catch {
+    return {
+      ok: false,
+      message: "Dev server not running. Start it in the project first: srt run src/index.tsx (or srt server)",
+    }
+  }
+  let body: any = null
+  try {
+    body = await resp.json()
+  } catch {}
+  if (!resp.ok) return { ok: false, message: String(body?.error ?? `Dev server responded with HTTP ${resp.status}`) }
+  return { ok: true, body }
+}
+
+let TOOLS = [
+  {
+    name: "list_clients",
+    description:
+      "List the app clients connected to the SolidRT dev server. Each entry has id (pass it as `client` to the other tools), platform, runtime version, and the capability names compiled into that client's runtime.",
+    inputSchema: { type: "object", properties: {}, additionalProperties: false },
+  },
+  {
+    name: "get_logs",
+    description:
+      "Read console output and runtime errors from connected app clients. Returns entries (seq, at, client, level, text) plus `latest`, the newest seq. Pass `since` (a seq or `latest` from a previous call) to only get newer entries; pass `wait_ms` to hold the call until new output arrives, e.g. right after triggering a reload.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        since: {
+          type: "integer",
+          description: "Only return entries with seq greater than this (default 0: the whole buffer)",
+        },
+        wait_ms: {
+          type: "integer",
+          description: "If nothing is newer than `since`, wait up to this many milliseconds for new output (max 30000)",
+        },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_stats",
+    description:
+      "Performance statistics from a running app client: fps, CPU%, memory, smoothed JS/layout/paint/hover frame times (ms), setProperty writes per frame, demand-gate reuse/skip counts per second, and live texture count.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        client: { type: "integer", description: "Client id from list_clients (default: the only connected client)" },
+      },
+      additionalProperties: false,
+    },
+  },
+  {
+    name: "get_render_tree",
+    description:
+      "Snapshot of a running app client's render tree: node id, kind, window-relative box (x, y, width, height), text content, and children. Use it to verify what the app actually rendered and where.",
+    inputSchema: {
+      type: "object",
+      properties: {
+        client: { type: "integer", description: "Client id from list_clients (default: the only connected client)" },
+      },
+      additionalProperties: false,
+    },
+  },
+]
+
+function clientParam(args: any): string {
+  return typeof args?.client === "number" ? `?client=${args.client}` : ""
+}
+
+async function callTool(name: string, args: any): Promise<ControlResult> {
+  switch (name) {
+    case "list_clients":
+      return control("/clients")
+    case "get_logs": {
+      let params = new URLSearchParams()
+      if (typeof args?.since === "number") params.set("since", String(args.since))
+      if (typeof args?.wait_ms === "number") params.set("wait", String(args.wait_ms))
+      let qs = params.toString()
+      return control(qs ? `/logs?${qs}` : "/logs")
+    }
+    case "get_stats":
+      return control(`/stats${clientParam(args)}`)
+    case "get_render_tree":
+      return control(`/tree${clientParam(args)}`)
+    default:
+      return { ok: false, message: `Unknown tool: ${name}` }
+  }
+}
+
+export async function runMcpCommand() {
+  let { Server } = await import("@modelcontextprotocol/sdk/server/index.js")
+  let { StdioServerTransport } = await import("@modelcontextprotocol/sdk/server/stdio.js")
+  let { ListToolsRequestSchema, CallToolRequestSchema } = await import("@modelcontextprotocol/sdk/types.js")
+
+  let server = new Server({ name: "solidrt", version: "0.0.0" }, { capabilities: { tools: {} } })
+
+  server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
+
+  server.setRequestHandler(CallToolRequestSchema, async (request: any) => {
+    let result = await callTool(request.params.name, request.params.arguments ?? {})
+    if (!result.ok) {
+      return { content: [{ type: "text", text: result.message }], isError: true }
+    }
+    return { content: [{ type: "text", text: JSON.stringify(result.body, null, 2) }] }
+  })
+
+  // The stdin read keeps the process alive; it exits when the agent host
+  // closes the pipe.
+  await server.connect(new StdioServerTransport())
+}

package/src/control.ts

@@ -0,0 +1,119 @@
+import { state } from "./util"
+
+// The control API under /__control__/: read-only introspection of connected
+// app clients, served next to the file routes. The MCP bridge (srt mcp) is the
+// primary consumer. Two shapes: server-held data answered directly (clients,
+// logs) and queries forwarded to a client over its websocket and correlated
+// back by id (tree, stats).
+
+export type LogEntry = { seq: number; at: number; client: number; level: string; text: string }
+
+// Ring buffer of forwarded client logs. Capped so a chatty app cannot grow the
+// server without bound; readers page through it with the `since` cursor.
+const LOG_CAP = 2000
+const QUERY_TIMEOUT_MS = 5000
+const MAX_WAIT_MS = 30000
+
+let logs: LogEntry[] = []
+let logSeq = 0
+// Pending long-poll wakeups (see handleLogs). Flushed on every append; a
+// waiter that already timed out resolves again harmlessly.
+let logWaiters: Array<() => void> = []
+
+let nextQueryId = 1
+let pendingQueries = new Map<number, (msg: any) => void>()
+
+/// A `log` message arrived from a client: buffer it and wake long-polls.
+export function appendLog(client: number, level: string, text: string) {
+  logs.push({ seq: ++logSeq, at: Date.now(), client, level, text })
+  if (logs.length > LOG_CAP) logs.splice(0, logs.length - LOG_CAP)
+  let waiters = logWaiters
+  logWaiters = []
+  for (let wake of waiters) wake()
+}
+
+/// A `result` message arrived from a client: hand it to the awaiting query.
+export function resolveQuery(msg: { id?: number }) {
+  if (typeof msg.id !== "number") return
+  let resolve = pendingQueries.get(msg.id)
+  if (resolve) {
+    pendingQueries.delete(msg.id)
+    resolve(msg)
+  }
+}
+
+function clientList() {
+  return [...state.clients.values()].map((info) => ({
+    id: info.id,
+    platform: info.platform,
+    version: info.version,
+    capabilities: info.capabilities,
+  }))
+}
+
+// Resolve the target client for a query: an explicit ?client=<id>, or the only
+// connected client when the parameter is omitted.
+function findClient(param: string | null): { ws: any } | { error: Response } {
+  let entries = [...state.clients.entries()]
+  if (param === null) {
+    if (entries.length === 1) return { ws: entries[0]![0] }
+    if (entries.length === 0) return { error: Response.json({ error: "No connected clients" }, { status: 503 }) }
+    return { error: Response.json({ error: "Multiple clients connected; pass ?client=<id>" }, { status: 400 }) }
+  }
+  let id = parseInt(param, 10)
+  let entry = entries.find(([, info]) => info.id === id)
+  if (!entry) return { error: Response.json({ error: `No client with id ${param}` }, { status: 404 }) }
+  return { ws: entry[0] }
+}
+
+async function handleQuery(url: URL, kind: string): Promise<Response> {
+  let target = findClient(url.searchParams.get("client"))
+  if ("error" in target) return target.error
+  let id = nextQueryId++
+  let reply = new Promise<any>((resolve) => {
+    pendingQueries.set(id, resolve)
+  })
+  target.ws.send(JSON.stringify({ type: "query", kind, id }))
+  let msg = await Promise.race([reply, Bun.sleep(QUERY_TIMEOUT_MS)])
+  pendingQueries.delete(id)
+  if (!msg) return Response.json({ error: "Query timed out" }, { status: 504 })
+  if (msg.error) return Response.json({ error: msg.error }, { status: 502 })
+  return Response.json(msg.data)
+}
+
+// GET /__control__/logs?since=N&wait=MS: entries with seq > since, plus the
+// latest seq as the next cursor. With `wait`, holds the response until a new
+// entry arrives or the timeout passes (long-poll), so a caller can follow the
+// stream without tight polling.
+async function handleLogs(url: URL): Promise<Response> {
+  let since = parseInt(url.searchParams.get("since") ?? "0", 10) || 0
+  let wait = Math.min(parseInt(url.searchParams.get("wait") ?? "0", 10) || 0, MAX_WAIT_MS)
+  let entries = logs.filter((e) => e.seq > since)
+  if (entries.length === 0 && wait > 0) {
+    await new Promise<void>((resolve) => {
+      let timer = setTimeout(resolve, wait)
+      logWaiters.push(() => {
+        clearTimeout(timer)
+        resolve()
+      })
+    })
+    entries = logs.filter((e) => e.seq > since)
+  }
+  return Response.json({ entries, latest: logSeq })
+}
+
+export async function handleControl(req: Request, path: string): Promise<Response> {
+  let url = new URL(req.url)
+  switch (path) {
+    case "/__control__/clients":
+      return Response.json(clientList())
+    case "/__control__/logs":
+      return handleLogs(url)
+    case "/__control__/tree":
+      return handleQuery(url, "tree")
+    case "/__control__/stats":
+      return handleQuery(url, "stats")
+    default:
+      return Response.json({ error: "Unknown control endpoint" }, { status: 404 })
+  }
+}

package/src/dev-server.ts

@@ -7,6 +7,7 @@ import qrcode from "qrcode-generator"
 import { state, print } from "./util"
 import { values } from "./args"
 import * as cache from "./cache"
+import { appendLog, handleControl, resolveQuery } from "./control"
 
 export const DEV_HOST = "127.0.0.1"
 export const DEV_PORT = 0x8844
@@ -128,6 +129,10 @@ export function startServer() {
         return handleProxy(req)
       }
 
+      if (path.startsWith("/__control__/")) {
+        return handleControl(req, path)
+      }
+
       let filePath = resolve(state.sourceDir, "." + path)
       if (!filePath.startsWith(state.sourceDir)) {
         return new Response("Forbidden", { status: 403 })
@@ -169,12 +174,51 @@ export function startServer() {
         return Response.json(entries, { headers: { "X-SRT-Type": "directory" } })
       }
 
-      return new Response(Bun.file(filePath), { headers: { "X-SRT-Type": "file" } })
+      let file = Bun.file(filePath)
+      let baseHeaders: Record<string, string> = { "X-SRT-Type": "file", "Accept-Ranges": "bytes" }
+
+      // Honor a single byte-range request (e.g. streaming audio decoding on the
+      // client, which seeks and reads on demand). Only the common "bytes=a-b" /
+      // "bytes=a-" / "bytes=-n" forms; anything else falls through to the whole
+      // file. Range makes proxied streaming viable without pulling the whole
+      // track over the wire.
+      let range = req.headers.get("range")
+      let match = range ? /^bytes=(\d*)-(\d*)$/.exec(range.trim()) : null
+      if (match) {
+        let size = stat.size
+        let start: number
+        let end: number
+        if (match[1] === "") {
+          // Suffix range: the last N bytes.
+          let n = parseInt(match[2], 10)
+          start = isNaN(n) ? 0 : Math.max(0, size - n)
+          end = size - 1
+        } else {
+          start = parseInt(match[1], 10)
+          end = match[2] === "" ? size - 1 : Math.min(parseInt(match[2], 10), size - 1)
+        }
+        if (start > end || start >= size) {
+          return new Response("Range not satisfiable", {
+            status: 416,
+            headers: { ...baseHeaders, "Content-Range": `bytes */${size}` },
+          })
+        }
+        return new Response(file.slice(start, end + 1), {
+          status: 206,
+          headers: {
+            ...baseHeaders,
+            "Content-Range": `bytes ${start}-${end}/${size}`,
+            "Content-Length": String(end - start + 1),
+          },
+        })
+      }
+
+      return new Response(file, { headers: baseHeaders })
     },
     websocket: {
       open(ws) {
         let id = state.nextClientId++
-        state.clients.set(ws, { platform: "unknown", version: "unknown", id })
+        state.clients.set(ws, { platform: "unknown", version: "unknown", id, capabilities: [] })
         print(`[cli] Client connected ${ws.remoteAddress}`)
         // Advertise our real LAN address so clients dialed over the adb loopback
         // can show/remember the directly reachable address (see connection.rs).
@@ -204,8 +248,19 @@ export function startServer() {
               platform: data.platform ?? "unknown",
               version: data.version ?? "unknown",
               id: existing?.id ?? state.nextClientId++,
+              capabilities: Array.isArray(data.capabilities) ? data.capabilities.map(String) : [],
             })
             print(`[cli] Client info ${ws.remoteAddress} ${data.platform} (${data.version})`)
+          } else if (data.type === "log") {
+            // Forwarded console output / runtime errors from the client's
+            // engine logger, buffered for the control API (see control.ts).
+            // Not printed here: the local client already writes to this
+            // terminal, so echoing would duplicate every line.
+            let device = state.clients.get(ws)?.id ?? -1
+            appendLog(device, String(data.level ?? "log"), String(data.text ?? ""))
+          } else if (data.type === "result") {
+            // Reply to a query the control API forwarded to this client.
+            resolveQuery(data)
           } else if (data.type === "capture" && state.capture) {
             let device = state.clients.get(ws)?.id ?? -1
             // Milliseconds, integer: Date.now() is already integer ms, so the

package/src/main.ts

@@ -7,6 +7,7 @@ import { runPackCommand } from "./commands/pack"
 import { runRenderCommand } from "./commands/render"
 import { runServerCommand } from "./commands/server"
 import { runClientCommand } from "./commands/client"
+import { runMcpCommand } from "./commands/mcp"
 import { spawnClient } from "./dev-client"
 
 // -- Validate args --
@@ -51,6 +52,8 @@ if (command === "init") {
 } else if (command === "run") {
   await runServerCommand()
   spawnClient()
+} else if (command === "mcp") {
+  await runMcpCommand()
 } else {
   printUsage()
   process.exit(1)

package/src/util.ts

@@ -6,7 +6,7 @@ import type { Server as BunServer } from "bun"
 import type { Bonjour } from "bonjour-service"
 
 export let state = {
-  clients: new Map<any, { platform: string; version: string; id: number }>(),
+  clients: new Map<any, { platform: string; version: string; id: number; capabilities: string[] }>(),
   nextClientId: 0,
   currentCode: null as string | null,
   source: undefined as string | undefined,