scanruler-mcp 0.1.0 → 0.2.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/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'))

package/src/main.js

@@ -15,8 +15,8 @@ import { createMcpServer } from './mcp.js'
 import { SharedLink } from './relay.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
 
@@ -71,7 +71,7 @@ export async function main(argv = process.argv.slice(2)) {
   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

package/src/mcp.js

@@ -1,14 +1,15 @@
 // SPDX-License-Identifier: AGPL-3.0-only
 // The MCP side: the tools an agent lists and calls. Each of the page's
-// commands is a tool (tools.js); two more are this server's own —
+// commands is a tool (tools.js); four more are this server's own —
 // scanruler_status, to see whether a ScanRuler page is connected and how to
 // connect one; scanruler_open, to open one in the user's browser, paired;
-// and scanruler_wait, to wait for it or for it to be idle.
+// scanruler_wait, to wait for it or for it to be idle; and scanruler_batch,
+// to run several of the page's tools in one call.
 
 import { readFileSync } from 'node:fs'
 import { Server } from '@modelcontextprotocol/sdk/server/index.js'
 import { CallToolRequestSchema, ListToolsRequestSchema } from '@modelcontextprotocol/sdk/types.js'
-import { imageContent, inputFor, saveFileResult, toolFor, toolName } from './tools.js'
+import { agentJson, imageContent, inputFor, saveFileResult, toolFor, toolName } from './tools.js'
 
 /** The app's own commands as of this release, so the tools are there before
  *  a page connects — unless a page has connected before, whose list was
@@ -17,16 +18,17 @@ import { imageContent, inputFor, saveFileResult, toolFor, toolName } from './too
  *  (tests/mcpCommands.test.ts). */
 export const SNAPSHOT = JSON.parse(readFileSync(new URL('./commands.json', import.meta.url), 'utf8'))
 
-export const INSTRUCTIONS = [
+const INSTRUCTIONS = [
   'These tools drive ScanRuler, a measuring app for 3D scans, in the browser tab the user has open: the user watches every step in the viewport and can undo it there.',
   'Start with scanruler_status. If no ScanRuler page is connected, call scanruler_open: it opens ScanRuler in the user’s browser, paired with this server, and waits for it. If that leaves it unconnected, tell the user what howToConnect says, then call scanruler_wait.',
-  'Read session_state before acting and after: the scan’s bounding box says where the part lies, the elements and dimensions what is measured. Lengths are millimetres, angles degrees.',
+  'Read session_state before acting and after: the scan’s bounding box says where the part lies, the elements and dimensions what is measured. Lengths are millimetres, angles degrees; answers give numbers to six significant digits.',
   'A place on the scan is { point: [x, y, z] } (the nearest scan vertex is taken) or { vertex: n }. To fit a feature, aim at its middle, not at an edge.',
   'Every tool that changes the session is one step of the undo history; history_undo takes the last back. report_get gives the report as JSON (format "json") or as the text the panel copies (format "text").',
   'view_render shows you the 3D view as a picture; view_set turns it to a standard view or fits it.',
+  'scanruler_batch runs several tools in one call, in order — many scan_nearest or element_fit calls, say — and stops at the first that is refused unless told to go on.',
 ].join(' ')
 
-const text = (value) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : JSON.stringify(value) }] })
+const text = (value, exact = false) => ({ content: [{ type: 'text', text: typeof value === 'string' ? value : agentJson(value, exact) }] })
 const failure = (e) => {
   const code = e?.code ?? 'failed'
   const message = e?.message ?? String(e)
@@ -178,15 +180,100 @@ export function createMcpServer({
     })
   }
 
-  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
-    const { name, arguments: args } = request.params
-    const mine = own.find((t) => t.name === name)
-    if (mine) return mine.call(args)
+  /** One of the page's tools run on the page: the result as MCP content,
+   *  or a failure. */
+  const runPageTool = async (name, args, onProgress) => {
     const command = commands().find((c) => toolName(c) === name)
     if (!command) return failure({ code: 'unknown_command', message: `There is no tool ${name}.` })
     if (!link.connected && !(await link.waitForPage(pageTimeoutMs))) {
       return failure({ code: 'unavailable', message: `No ScanRuler page is connected; scanruler_open opens one. ${connectHelp()}` })
     }
+    try {
+      const { input, binaryKey } = await inputFor(command, args, { cwd })
+      const result = await link.run(command.name, input, binaryKey, onProgress)
+      const image = command.returnsImage ? await imageContent(result, args, { cwd, outDir }) : null
+      if (image) return { content: image }
+      return text(await saveFileResult(result, args, { cwd, outDir }), Boolean(command.exact))
+    } catch (e) {
+      return failure(e)
+    }
+  }
+
+  // Several of the page's tools in one call — what cuts a run of twenty
+  // scan_nearest calls to one round trip. Each answer is the tool's own; a
+  // picture comes back as the text beside it (where it was written, if a
+  // path was given), not as an image.
+  own.push({
+    name: 'scanruler_batch',
+    title: 'Run several ScanRuler tools',
+    description:
+      'Run several of the ScanRuler tools in one call, in order, each with its own arguments — a run of scan_nearest, element_fit or section_get calls, say. Returns results, one per call in order: { tool, ok, result } or { tool, ok: false, error: { code, message } }. The first refused stops the rest (stopped says which index) unless stopOnError is false. Each call that changes the session is still its own undo step. A tool that returns a picture gives its text here, the picture written to a file only if its call gave path. The server’s own tools (scanruler_status, _open, _wait, _batch) cannot be batched.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        calls: {
+          type: 'array',
+          minItems: 1,
+          maxItems: 200,
+          description: 'The calls, in order.',
+          items: {
+            type: 'object',
+            properties: {
+              tool: { type: 'string', minLength: 1, description: 'A tool’s name, as listed — scan_nearest, element_fit.' },
+              arguments: { type: 'object', description: 'Its arguments, as the tool takes them; {} for none.' },
+            },
+            required: ['tool'],
+            additionalProperties: false,
+          },
+        },
+        stopOnError: { type: 'boolean', description: 'Stop at the first refused call (the default), or run every call and report each.' },
+      },
+      required: ['calls'],
+      additionalProperties: false,
+    },
+    annotations: { readOnlyHint: false, openWorldHint: false },
+    call: async (args) => {
+      const calls = Array.isArray(args?.calls) ? args.calls : []
+      if (calls.length === 0) return failure({ code: 'invalid_input', message: 'calls: give at least one call.' })
+      const stopOnError = args?.stopOnError !== false
+      const results = []
+      let stopped
+      // A batch holding an exact answer (a plane's frame, say) keeps
+      // every answer exact: the rounding is one pass over the whole.
+      let exact = false
+      for (let i = 0; i < calls.length; i++) {
+        const c = calls[i] ?? {}
+        const tool = String(c.tool ?? '')
+        const one = own.some((t) => t.name === tool)
+          ? failure({ code: 'invalid_input', message: `${tool} is the server’s own and is not batched — call it on its own.` })
+          : await runPageTool(tool, c.arguments ?? {}, undefined)
+        if (!one.isError && commands().find((x) => toolName(x) === tool)?.exact) exact = true
+        const body = one.content.find((x) => x.type === 'text')?.text ?? ''
+        if (one.isError) {
+          const m = /^([a-z_]+): ([\s\S]*)$/.exec(body)
+          results.push({ tool, ok: false, error: m ? { code: m[1], message: m[2] } : { code: 'failed', message: body } })
+          if (stopOnError) {
+            stopped = i
+            break
+          }
+        } else {
+          let parsed
+          try {
+            parsed = JSON.parse(body)
+          } catch {
+            parsed = body
+          }
+          results.push({ tool, ok: true, result: parsed })
+        }
+      }
+      return text({ results, ran: results.length, of: calls.length, ...(stopped !== undefined ? { stopped } : {}) }, exact)
+    },
+  })
+
+  server.setRequestHandler(CallToolRequestSchema, async (request, extra) => {
+    const { name, arguments: args } = request.params
+    const mine = own.find((t) => t.name === name)
+    if (mine) return mine.call(args)
     // Progress lines from the page, for a client that asked for them.
     const token = request.params._meta?.progressToken
     let step = 0
@@ -196,15 +283,7 @@ export function createMcpServer({
         : (line) => {
             extra.sendNotification({ method: 'notifications/progress', params: { progressToken: token, progress: ++step, message: line } }).catch(() => {})
           }
-    try {
-      const { input, binaryKey } = await inputFor(command, args, { cwd })
-      const result = await link.run(command.name, input, binaryKey, onProgress)
-      const image = command.returnsImage ? await imageContent(result, args, { cwd, outDir }) : null
-      if (image) return { content: image }
-      return text(await saveFileResult(result, args, { cwd, outDir }))
-    } catch (e) {
-      return failure(e)
-    }
+    return runPageTool(name, args, onProgress)
   })
 
   return server

package/src/serve.js

@@ -31,7 +31,7 @@ const TYPES = {
 }
 
 /** The file a URL path names under `root`, or null for one outside it. */
-export function fileFor(root, urlPath) {
+function fileFor(root, urlPath) {
   const path = decodeURIComponent(urlPath.split('?')[0].split('#')[0])
   const file = resolve(root, normalize('.' + (path.endsWith('/') ? `${path}index.html` : path)))
   return file === root || file.startsWith(root + sep) ? file : null

package/src/tools.js

@@ -37,6 +37,28 @@ const imagePath = {
   description: 'Also write the picture to a file: a file path, or a folder to write it into under the name ScanRuler gives it. Without it, it is only shown.',
 }
 
+/** How many significant digits a number keeps in an answer, and the finest
+ *  step it is given to: six digits is a micrometre on a part under a metre
+ *  and a millionth of a unit vector; past them the page's doubles are
+ *  noise the agent pays for — 0.9483828176573491 in place of 0.948383. */
+const DIGITS = 6
+const STEP = 1e6
+
+const tidy = (v) => {
+  const r = Number(v.toPrecision(DIGITS))
+  return Math.abs(r) < 9e9 ? Math.round(r * STEP) / STEP || 0 : r
+}
+
+/** An answer as the agent reads it: JSON, every number that is not whole
+ *  kept to DIGITS significant digits and no finer than a millionth — 1e-17,
+ *  a zero's rounding error, is 0. Whole numbers — ids, indices, counts —
+ *  are as they were. An `exact` answer is one whose numbers are handed
+ *  back as inputs — a plane's frame, say — and keeps every digit:
+ *  shortened, what is built on them is a hair off what it was meant to
+ *  meet. */
+export const agentJson = (value, exact = false) =>
+  exact ? JSON.stringify(value) : JSON.stringify(value, (_key, v) => (typeof v === 'number' && Number.isFinite(v) && !Number.isInteger(v) ? tidy(v) : v))
+
 /** A command as the MCP tool an agent sees. */
 export function toolFor(command, { outDir }) {
   const input = structuredClone(command.input ?? { type: 'object' })
@@ -105,7 +127,7 @@ export async function imageContent(result, args, { cwd, outDir }) {
   if (!file || !(file.bytes instanceof Uint8Array) || !String(file.mimeType ?? '').startsWith('image/')) return null
   const saved = args?.path ? await saveFileResult(result, args, { cwd, outDir }) : { ...result, file: { name: file.name, mimeType: file.mimeType, size: file.bytes.byteLength } }
   return [
-    { type: 'text', text: JSON.stringify(saved) },
+    { type: 'text', text: agentJson(saved) },
     { type: 'image', data: Buffer.from(file.bytes.buffer, file.bytes.byteOffset, file.bytes.byteLength).toString('base64'), mimeType: file.mimeType },
   ]
 }