scanruler-mcp 0.1.0 → 0.3.0

package/src/config.js

@@ -20,7 +20,7 @@ export function configDir(env = process.env, platform = process.platform) {
 }
 
 /** A new token: 24 random bytes, URL-safe — it travels in a link. */
-export const newToken = () => randomBytes(24).toString('base64url')
+const newToken = () => randomBytes(24).toString('base64url')
 
 /** The command list the last connected page sent, or null. */
 export function loadRemembered(dir = configDir()) {

package/src/engine.js

@@ -0,0 +1,69 @@
+// SPDX-License-Identifier: AGPL-3.0-only
+// The headless backend: ScanRuler itself run in this process, with no
+// browser — no scan, no viewport, nobody watching — in place of the page.
+// The engine is a build of the app for Node (npm run build:engine in a
+// ScanRuler checkout writes dist-engine/engine.mjs), found by its path and
+// loaded as it is: this package names nothing in it and imports nothing from
+// the app. It offers the commands that run without the page, with the same
+// names, inputs and answers as the page's; the rest answer `unavailable`,
+// naming the page mode. One engine to a process — its state is the app's
+// own — so two servers started headless share nothing.
+
+import { EventEmitter } from 'node:events'
+import { existsSync } from 'node:fs'
+import { fileURLToPath, pathToFileURL } from 'node:url'
+import { toolName } from './tools.js'
+
+/** Where --headless looks: the engine built in the ScanRuler checkout this
+ *  package is part of. */
+export const CHECKOUT_ENGINE = fileURLToPath(new URL('../../dist-engine/engine.mjs', import.meta.url))
+
+/** Load and start the engine at `file`. Throws, saying what to do, when
+ *  there is none there or it is no engine. */
+export async function loadEngine(file) {
+  if (!existsSync(file)) throw new Error(`There is no ScanRuler engine at ${file}. Build one with "npm run build:engine" in the ScanRuler checkout, or give --engine the path of one.`)
+  const mod = await import(pathToFileURL(file).href)
+  if (typeof mod.startEngine !== 'function') throw new Error(`${file} is not a ScanRuler engine: it has no startEngine().`)
+  return mod.startEngine()
+}
+
+/** The engine, as the page link is to the server (link.js): always
+ *  connected, its commands what a page would say it has. */
+export class EngineLink extends EventEmitter {
+  /** @param {{ app: string, version: string, plugins: string[], listCommands(): object[], pageCommands(): string[], run(name: string, input: unknown, onProgress?: (text: string) => void): Promise<unknown>, stop(): Promise<void> }} engine */
+  constructor(engine, file) {
+    super()
+    this.engine = engine
+    this.file = file
+    this.backend = 'headless'
+    this.role = 'headless'
+    this.error = null
+    this.page = { app: engine.app, version: engine.version, origin: null, plugins: engine.plugins, viewport: false, commands: engine.listCommands() }
+  }
+
+  get connected() {
+    return true
+  }
+
+  /** A command run in the engine; refused with { code, message } as the
+   *  page refuses one. */
+  run(name, input, _binaryKey, onProgress) {
+    return this.engine.run(name, input, onProgress).catch((e) => Promise.reject({ code: e?.code ?? 'failed', message: e?.message ?? String(e) }))
+  }
+
+  /** The command behind a tool that needs the page, by the tool's name —
+   *  null for one the engine has not got at all. */
+  pageCommand(tool) {
+    return this.engine.pageCommands().find((name) => toolName({ name }) === tool) ?? null
+  }
+
+  waitForPage() {
+    return Promise.resolve(true)
+  }
+
+  start() {}
+
+  close() {
+    void this.engine.stop()
+  }
+}

package/src/link.js

@@ -17,7 +17,7 @@ import { decoder, encode } from './framing.js'
 
 /** The hosted app. Loopback pages — a dev server, `--serve` — are allowed
  *  on any port; anything else takes `--allow-origin`. */
-export const HOSTED_ORIGINS = ['https://scanruler.com', 'https://www.scanruler.com']
+const HOSTED_ORIGINS = ['https://scanruler.com', 'https://www.scanruler.com']
 
 const LOOPBACK = new Set(['localhost', '127.0.0.1', '[::1]'])
 
@@ -43,7 +43,7 @@ const HEARTBEAT_MS = 15_000
 const HELLO_MS = 10_000
 
 /** Where a result carries a file's bytes, if it does. */
-export const resultBinary = (result) => (result?.file?.bytes instanceof Uint8Array ? 'result.file.bytes' : undefined)
+const resultBinary = (result) => (result?.file?.bytes instanceof Uint8Array ? 'result.file.bytes' : undefined)
 
 /** A socket's frame, as the decoder takes it. */
 export const frameOf = (data, isBinary) => (isBinary ? new Uint8Array(data.buffer, data.byteOffset, data.byteLength) : data.toString('utf8'))
@@ -247,6 +247,14 @@ export class PageLink extends Asker {
   }
 
   #receive(message) {
+    // The tab hidden or shown again — in the background, its window
+    // covered, the screen locked — for the status to say.
+    if (message.event === 'visibility') {
+      this.page = { ...this.page, hidden: message.hidden === true }
+      this.#tellPeers()
+      this.emit('visibility', this.page.hidden)
+      return
+    }
     if (message.event === 'commands' && Array.isArray(message.commands)) {
       this.page = { ...this.page, commands: message.commands }
       this.#tellPeers()

package/src/main.js

@@ -6,17 +6,20 @@
 // else. Everything this prints goes to stderr — stdout is the MCP channel.
 
 import { readFileSync } from 'node:fs'
-import { parseArgs } from 'node:util'
+import { resolve } from 'node:path'
+import { format, parseArgs } from 'node:util'
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js'
 import { openInBrowser } from './browser.js'
 import { configDir, loadConfig, loadRemembered, saveRemembered } from './config.js'
+import { CHECKOUT_ENGINE, EngineLink, loadEngine } from './engine.js'
 import { originAllowed } from './link.js'
-import { createMcpServer } from './mcp.js'
+import { createMcpServer, TOOL_MODES } from './mcp.js'
 import { SharedLink } from './relay.js'
+import { createTrace } from './trace.js'
 import { httpServer } from './serve.js'
 
-export const DEFAULT_PORT = 7317
-export const HOSTED_APP = 'https://scanruler.com/'
+const DEFAULT_PORT = 7317
+const HOSTED_APP = 'https://scanruler.com/'
 
 const VERSION = JSON.parse(readFileSync(new URL('../package.json', import.meta.url), 'utf8')).version
 
@@ -30,16 +33,64 @@ Usage: scanruler-mcp [options]
   --serve <dir>          also serve a built ScanRuler from <dir> at http://127.0.0.1:<port>/
   --allow-origin <url>   let a ScanRuler page from another origin connect (repeatable)
   --app <url>            the ScanRuler address the pairing link opens (default ${HOSTED_APP})
+  --engine <file>        run ScanRuler headless in this process, from an engine built
+                         with "npm run build:engine" (SCANRULER_ENGINE) — no browser,
+                         no page: modelling and files only
+  --headless             the same, with the engine built in the ScanRuler checkout
+                         this server is part of
+  --tools <mode>         full (the default) lists each of ScanRuler's commands as a tool;
+                         compact lists five and the commands that return a picture, the
+                         rest read through scanruler_tools and run through scanruler_batch
+                         — for a small context window
+  --trace <dir>          write a line per tool call — tool, ms, bytes each way, error,
+                         whether the tab was hidden — to a new file in <dir>, for
+                         measuring a run (scripts/trace-summary.mjs in the ScanRuler
+                         repository sums it up); off by default
+  --trace-args           with --trace, also write each call's arguments (otherwise
+                         only their size)
   --pair                 print the pairing token and link, and exit
   --help                 this
 
 The pairing token is made on the first run and kept in ${join2(configDir(), 'config.json')};
-SCANRULER_MCP_TOKEN overrides it. The agent's scanruler_open tool opens ScanRuler
+SCANRULER_MCP_TOKEN overrides it. SCANRULER_MCP_PORT, SCANRULER_MCP_TOOLS and
+SCANRULER_MCP_TRACE stand in for --port, --tools and --trace. The agent's scanruler_open tool opens ScanRuler
 in the default browser, paired. By hand: open the pairing link once, or in
 ScanRuler go to Settings → Agents → Local agent connection and enter the port
 and the token.
 `
 
+/** ScanRuler run in this process from the engine at `file`, in place of
+ *  the page — no port, no pairing. */
+async function headless(file, { cwd, outDir, tools, trace }) {
+  // stdout is the MCP channel, the transport's alone: whatever else writes
+  // to it — the app's logging, the kernel's own reports — goes to stderr.
+  const stdout = process.stdout
+  const write = stdout.write.bind(stdout)
+  const channel = { write, once: (event, listener) => stdout.once(event, listener) }
+  stdout.write = (...args) => process.stderr.write(...args)
+  for (const name of ['log', 'info', 'warn', 'debug']) console[name] = (...args) => process.stderr.write(`${format(...args)}\n`)
+  const engine = await loadEngine(file)
+  const link = new EngineLink(engine, file)
+  log(`Running ScanRuler ${engine.version} headless from ${file}, with ${link.page.commands.length} commands.`)
+  const server = createMcpServer({
+    link,
+    version: VERSION,
+    cwd,
+    outDir,
+    connectHelp: () => 'This server runs ScanRuler headless, in its own process; no page connects to it.',
+    serverInfo: () => ({ name: 'scanruler-mcp', version: VERSION, backend: 'headless', engine: file, tools, outDir, ...(trace ? { trace: trace.file } : {}) }),
+    remembered: null,
+    tools,
+    trace,
+  })
+  server.onclose = () => {
+    link.close()
+    process.exit(0)
+  }
+  await server.connect(new StdioServerTransport(process.stdin, channel))
+  log('Ready, headless.')
+}
+
 function join2(a, b) {
   return `${a}${a.includes('\\') ? '\\' : '/'}${b}`
 }
@@ -55,6 +106,11 @@ export async function main(argv = process.argv.slice(2)) {
       serve: { type: 'string' },
       'allow-origin': { type: 'string', multiple: true },
       app: { type: 'string' },
+      engine: { type: 'string' },
+      headless: { type: 'boolean' },
+      tools: { type: 'string' },
+      trace: { type: 'string' },
+      'trace-args': { type: 'boolean' },
       pair: { type: 'boolean' },
       help: { type: 'boolean' },
     },
@@ -66,12 +122,16 @@ export async function main(argv = process.argv.slice(2)) {
   }
   const port = Number(values.port ?? process.env.SCANRULER_MCP_PORT ?? DEFAULT_PORT)
   if (!Number.isInteger(port) || port < 1 || port > 65535) throw new Error(`--port ${values.port} is not a port.`)
+  const tools = values.tools ?? (process.env.SCANRULER_MCP_TOOLS || 'full')
+  if (!TOOL_MODES.includes(tools)) {
+    throw new Error(`${values.tools === undefined ? 'SCANRULER_MCP_TOOLS' : '--tools'} ${tools} is not one of ${TOOL_MODES.join(', ')}.`)
+  }
   const config = loadConfig()
   const token = process.env.SCANRULER_MCP_TOKEN || config.token
   const app = values.app ?? (values.serve ? `http://127.0.0.1:${port}/` : HOSTED_APP)
   const pairing = `${app.replace(/#.*$/, '')}#agent=${port}:${token}`
   const connectHelp = () =>
-    `Open ScanRuler — ${app} — in Chrome or Edge and either open this pairing link once: ${pairing} — or in ScanRuler go to Settings → Agents, switch on "Local agent connection", and enter port ${port} and token ${token}.`
+    `Open ScanRuler — ${app} — in Chrome, Edge or Firefox and either open this pairing link once: ${pairing} — or in ScanRuler go to Settings → Agents, switch on "Local agent connection", and enter port ${port} and token ${token}.`
   if (values.pair) {
     process.stdout.write(`Port:  ${port}\nToken: ${token}\nLink:  ${pairing}\n`)
     return
@@ -79,6 +139,11 @@ export async function main(argv = process.argv.slice(2)) {
 
   const cwd = process.cwd()
   const outDir = values.out ? (values.out.match(/^([A-Za-z]:)?[\\/]/) ? values.out : `${cwd}/${values.out}`) : cwd
+  const traceDir = values.trace ?? process.env.SCANRULER_MCP_TRACE
+  const trace = traceDir ? createTrace(resolve(cwd, traceDir), { args: values['trace-args'] === true }) : null
+  if (trace) log(`Tracing every call to ${trace.file}${trace.args ? ', arguments too' : ''}.`)
+  const engineFile = values.engine ?? process.env.SCANRULER_ENGINE ?? (values.headless ? CHECKOUT_ENGINE : null)
+  if (engineFile) return headless(resolve(cwd, engineFile), { cwd, outDir, tools, trace })
   const origins = values['allow-origin'] ?? []
   const http = httpServer({ serve: values.serve, allowOrigin: (origin) => originAllowed(origin, origins), version: VERSION })
   // The port, or — when another copy holds it — the relay through that one.
@@ -96,9 +161,11 @@ export async function main(argv = process.argv.slice(2)) {
     cwd,
     outDir,
     connectHelp: () => (link.error ? `${link.error} ` : '') + connectHelp(),
-    serverInfo: () => ({ name: 'scanruler-mcp', version: VERSION, port, role: link.role, outDir, config: config.file, ...(link.error ? { error: link.error } : {}) }),
+    serverInfo: () => ({ name: 'scanruler-mcp', version: VERSION, port, role: link.role, tools, outDir, config: config.file, ...(trace ? { trace: trace.file } : {}), ...(link.error ? { error: link.error } : {}) }),
     remembered: { load: () => loadRemembered(), save: (commands) => saveRemembered(commands) },
     openPage: () => openInBrowser(pairing),
+    tools,
+    trace,
   })
   const transport = new StdioServerTransport()
   server.onclose = () => {