@remcp/runtime 0.2.87 → 0.2.88

package/CHANGELOG.md

@@ -1,5 +1,12 @@
 # Changelog
 
+## 0.2.88 — 2026-09-21
+
+- Added a real compact stdio façade over the same runtime handlers: `read_file` plus up to seven capability-filtered `verb_noun` domain tools.
+- Grouped operations keep their original closed schemas and dispatch through `invokeTool`, so the compact surface changes discovery, not execution or permissions.
+- The normal paired-agent runtime remains the granular 83-operation capability-aware server.
+- Added compact-catalog parity and end-to-end stdio tests.
+
 ## 0.2.87 — 2026-09-21
 
 - macOS `event_log` now streams only the requested head lines from `log show` and terminates the child once the limit is reached.

package/README.md

@@ -23,9 +23,12 @@ To run it directly:
 ```bash
 npx @remcp/runtime --describe   # version, limits, configuration, telemetry state
 npx @remcp/runtime --print-tools
-npx @remcp/runtime              # MCP server over stdio
+npx @remcp/runtime              # granular capability-aware MCP server over stdio
+node ./src/compact.mjs --print-tools  # compact local façade for scanners/local MCP hosts
 ```
 
+`src/compact.mjs` is a second stdio entrypoint over the **same real handlers**. It advertises `read_file` plus up to seven `verb_noun` domain tools (`manage_files`, `run_terminal`, `control_computer`, `view_image`, `control_browser`, `manage_system`, `manage_documents`) and narrows each operation enum to capabilities available on the current host. It exists for directory scanners and local MCP hosts that benefit from a small selection surface; the paired ReMCP agent continues to use the granular capability-aware entrypoint.
+
 ## Tools
 
 83 tools are implemented in this repository: the original 44 filesystem/search/terminal/process tools

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@remcp/runtime",
-  "version": "0.2.87",
+  "version": "0.2.88",
   "description": "First-party ReMCP local device runtime: filesystem, terminal, computer-use, browser, diagnostics and document tools over MCP.",
   "type": "module",
   "license": "MIT",

package/src/compact-catalog.mjs

@@ -0,0 +1,158 @@
+import { TEXT_OUTPUT_SCHEMA, toolDefinitions } from './catalog.mjs';
+import { advertisedExtendedTools, extendedToolDefinitions } from './extended/catalog.mjs';
+
+export const compactRuntimeGroups = Object.freeze({
+  manage_files: Object.freeze([
+    'read_files','read_multiple_files','read_binary','write_binary','hash_file','list_directory','get_file_info',
+    'write_file','write_files','apply_patch','set_permissions','edit_block','replace_lines','replace_in_files','diff_files',
+    'move_to_trash','create_directory','move_file','copy_file','copy_paths','move_paths','delete_path','delete_paths',
+    'create_archive','extract_archive','start_search','get_more_search_results','stop_search','list_searches',
+  ]),
+  run_terminal: Object.freeze([
+    'start_process','read_process_output','interact_with_process','wait_for_process_output','force_terminate','list_sessions',
+  ]),
+  control_computer: Object.freeze([
+    'computer_snapshot','list_windows','ui_snapshot','ui_find','wait_for_ui','display_inventory',
+    'computer_action','window_action','launch_app','ui_action','type_text','keyboard','pointer','drag_drop','scroll',
+    'clipboard','open_path','reveal_path','notification','record_screen',
+  ]),
+  view_image: Object.freeze(['read_image','take_screenshot','screenshot_region']),
+  control_browser: Object.freeze([
+    'browser_tabs','browser_navigate','browser_snapshot','browser_find','browser_action','browser_wait','browser_evaluate',
+  ]),
+  manage_system: Object.freeze([
+    'get_system_info','list_processes','kill_process','get_runtime_info','get_runtime_stats','set_config_value',
+    'service','event_log','network','installed_apps','environment','audio','power_action',
+  ]),
+  manage_documents: Object.freeze(['read_document','edit_spreadsheet','edit_document','pdf_action']),
+});
+
+const groupTitles = Object.freeze({
+  manage_files:'Manage files',
+  run_terminal:'Run terminal operations',
+  control_computer:'Control computer',
+  view_image:'View image or screenshot',
+  control_browser:'Control browser',
+  manage_system:'Manage system',
+  manage_documents:'Manage documents',
+});
+
+const groupDescriptions = Object.freeze({
+  manage_files:'Use this when the task is about files, directories, archives, or filesystem search on this computer. Choose exactly one operation; parameters must contain only that operation’s arguments and are validated against its closed schema. Write, edit, move, permission, and delete operations can change or remove local data, while read and search operations leave files unchanged. Use read_file for one known text file.',
+  run_terminal:'Use this when the task needs a shell command or an existing ReMCP terminal session: start, read, wait, interact, stop, or list sessions. Choose exactly one operation; parameters are validated against that operation’s closed schema. Starting or interacting with commands can change local or external state, and force termination can lose unsaved process work; reading, waiting, and listing do not mutate the session.',
+  control_computer:'Use this for semantic inspection or control of native desktop applications on this computer: windows, accessibility/UI elements, waits, displays, app launch, text/input, clipboard, open/reveal, notifications, or short screen recording. Snapshot/find/wait operations observe state; clicks, typing, window close, app launch, clipboard writes, and recording can change local application state. Prefer semantic targets before raw coordinates.',
+  view_image:'Use this when the result must be pixels from this computer: read an existing image or capture the desktop, one window, monitor, or region. These operations return pixels without interacting with the visible UI. Use control_computer when semantic structure or an action is enough.',
+  control_browser:'Use this for a debuggable Chromium page when the task needs tabs, navigation, DOM/accessibility inspection, element search/actions, waits, or explicit JavaScript evaluation. Snapshot, find, and wait operations observe page state; navigation, clicks, typing, uploads, and JavaScript evaluation can change page or remote-site state. Use control_computer for browser chrome or non-CDP applications.',
+  manage_system:'Use this for operating-system or ReMCP runtime state: system/runtime/process facts, runtime preferences, services, event logs, networking, installed apps, environment, audio, or explicit power actions. Fact, log, and inventory operations only observe state; process termination, preference/service/audio changes, restart, and shutdown can interrupt work or change the machine. Use run_terminal for general shell commands.',
+  manage_documents:'Use this for structured document content: read PDF/DOCX/XLSX, edit DOCX/XLSX directly, or merge, split, extract, or inspect PDFs. DOCX/XLSX edits can replace the input when no separate output is supplied, and PDF write operations create or replace their requested output; read_document itself is read-only. Use read_file for plain line-oriented text.',
+});
+
+const allDefinitions = [...toolDefinitions, ...extendedToolDefinitions];
+const definitionByName = new Map(allDefinitions.map(definition => [definition.name, definition]));
+
+function publicDefinition(definition) {
+  return {
+    name:definition.name,
+    title:definition.title,
+    description:definition.description,
+    inputSchema:structuredClone(definition.inputSchema || { type:'object', properties:{}, additionalProperties:false }),
+    outputSchema:structuredClone(definition.outputSchema || TEXT_OUTPUT_SCHEMA),
+    annotations:{ ...(definition.annotations || {}) },
+  };
+}
+
+function uniqueSchemas(schemas) {
+  const seen = new Set();
+  return schemas.filter(schema => {
+    const key = JSON.stringify(schema);
+    if (seen.has(key)) return false;
+    seen.add(key);
+    return true;
+  });
+}
+
+function groupedInputSchema(members) {
+  const rules = members.map(name => {
+    const definition = definitionByName.get(name);
+    if (!definition) throw new Error(`Unknown compact runtime operation: ${name}`);
+    const schema = structuredClone(definition.inputSchema || { type:'object', properties:{}, additionalProperties:false });
+    const needsParameters = Array.isArray(schema.required) && schema.required.length > 0;
+    return {
+      if:{ properties:{ operation:{ const:name } }, required:['operation'] },
+      then:{
+        properties:{ parameters:schema },
+        ...(needsParameters ? { required:['parameters'] } : {}),
+      },
+    };
+  });
+  return {
+    type:'object',
+    properties:{
+      operation:{ type:'string', enum:[...members], description:'Concrete local runtime operation to execute in this domain.' },
+      parameters:{ type:'object', description:'Arguments for the selected operation; validated against that operation’s original closed schema.' },
+    },
+    required:['operation'],
+    allOf:rules,
+    additionalProperties:false,
+  };
+}
+
+function groupedOutputSchema(memberDefinitions) {
+  const schemas = uniqueSchemas(memberDefinitions.map(definition => structuredClone(definition.outputSchema || TEXT_OUTPUT_SCHEMA)));
+  return schemas.length === 1 ? schemas[0] : { oneOf:schemas };
+}
+
+function groupedDefinition(name, members) {
+  const memberDefinitions = members.map(member => {
+    const definition = definitionByName.get(member);
+    if (!definition) throw new Error(`Missing compact runtime operation: ${member}`);
+    return definition;
+  });
+  return {
+    name,
+    title:groupTitles[name],
+    description:groupDescriptions[name],
+    inputSchema:groupedInputSchema(members),
+    outputSchema:groupedOutputSchema(memberDefinitions),
+    annotations:{
+      title:groupTitles[name],
+      readOnlyHint:memberDefinitions.every(tool => tool.annotations?.readOnlyHint === true),
+      destructiveHint:memberDefinitions.some(tool => tool.annotations?.destructiveHint === true),
+      idempotentHint:memberDefinitions.every(tool => tool.annotations?.idempotentHint === true),
+      openWorldHint:memberDefinitions.some(tool => tool.annotations?.openWorldHint === true),
+    },
+  };
+}
+
+export async function supportedRuntimeOperationNames() {
+  const supportedExtended = new Set((await advertisedExtendedTools()).map(tool => tool.name));
+  return new Set([
+    ...toolDefinitions.map(tool => tool.name),
+    ...extendedToolDefinitions.filter(tool => supportedExtended.has(tool.name)).map(tool => tool.name),
+  ]);
+}
+
+export async function compactRuntimeToolDefinitions() {
+  const supported = await supportedRuntimeOperationNames();
+  const tools = [];
+  const readFile = definitionByName.get('read_file');
+  if (readFile && supported.has('read_file')) tools.push(publicDefinition(readFile));
+  for (const [name, configuredMembers] of Object.entries(compactRuntimeGroups)) {
+    const members = configuredMembers.filter(member => supported.has(member));
+    if (members.length) tools.push(groupedDefinition(name, members));
+  }
+  return tools;
+}
+
+export function resolveCompactRuntimeCall(name, args = {}, definitions = []) {
+  if (name === 'read_file') return { runtimeName:'read_file', runtimeArguments:{ ...args } };
+  const definition = definitions.find(tool => tool.name === name);
+  if (!definition || !compactRuntimeGroups[name]) throw new Error(`Unknown compact runtime tool: ${name}`);
+  const runtimeName = String(args.operation || '').trim();
+  const allowed = definition.inputSchema?.properties?.operation?.enum || [];
+  if (!allowed.includes(runtimeName)) throw new Error(`Unsupported ${name} operation: ${runtimeName || '(empty)'}`);
+  const runtimeArguments = args.parameters && typeof args.parameters === 'object' && !Array.isArray(args.parameters)
+    ? { ...args.parameters }
+    : {};
+  return { runtimeName, runtimeArguments };
+}

package/src/compact-mcp.mjs

@@ -0,0 +1,69 @@
+import { compactRuntimeToolDefinitions, resolveCompactRuntimeCall } from './compact-catalog.mjs';
+import { invokeTool } from './invoke.mjs';
+
+function toolConfig(definition, fromJsonSchema) {
+  return {
+    title:definition.title,
+    description:definition.description,
+    inputSchema:fromJsonSchema(definition.inputSchema || { type:'object' }),
+    ...(definition.outputSchema ? { outputSchema:fromJsonSchema(definition.outputSchema) } : {}),
+    annotations:definition.annotations,
+  };
+}
+
+export async function startCompactRuntimeMcpServer({ version, instructions, onError = () => {} } = {}) {
+  const [{ McpServer, fromJsonSchema }, { serveStdio }] = await Promise.all([
+    import('@modelcontextprotocol/server'),
+    import('@modelcontextprotocol/server/stdio'),
+  ]);
+  const definitions = await compactRuntimeToolDefinitions();
+  let activeServer = null;
+  let closed = false;
+
+  const serverHandle = serveStdio(() => {
+    const server = new McpServer(
+      { name:'remcp-runtime-compact', version },
+      {
+        capabilities:{ tools:{} },
+        instructions,
+        cacheHints:{
+          'tools/list':{ ttlMs:3000, cacheScope:'private' },
+          'server/discover':{ ttlMs:3000, cacheScope:'private' },
+        },
+      },
+    );
+    activeServer = server;
+    for (const definition of definitions) {
+      server.registerTool(
+        definition.name,
+        toolConfig(definition, fromJsonSchema),
+        async (args, context) => {
+          try {
+            const resolved = resolveCompactRuntimeCall(definition.name, args || {}, definitions);
+            return await invokeTool(resolved.runtimeName, resolved.runtimeArguments, { signal:context?.mcpReq?.signal });
+          } catch (error) {
+            return { content:[{ type:'text', text:error instanceof Error ? error.message : String(error) }], isError:true };
+          }
+        },
+      );
+    }
+    return server;
+  }, {
+    legacy:'serve',
+    onerror(error) { onError(error instanceof Error ? error : new Error(String(error))); },
+  });
+
+  return {
+    definitions,
+    async notification(notification) {
+      if (!activeServer) return;
+      await activeServer.server.notification(notification);
+    },
+    async close() {
+      if (closed) return;
+      closed = true;
+      await serverHandle.close();
+      activeServer = null;
+    },
+  };
+}

package/src/compact.mjs

@@ -0,0 +1,68 @@
+#!/usr/bin/env node
+import process from 'node:process';
+import { configurationError } from './config.mjs';
+import { compactRuntimeToolDefinitions } from './compact-catalog.mjs';
+import { shutdownSessions, startSessionSweeper } from './sessions.mjs';
+import { VERSION } from './version.mjs';
+
+const args = process.argv.slice(2);
+
+async function writeStdout(value) {
+  await new Promise((resolve, reject) => process.stdout.write(value, error => error ? reject(error) : resolve()));
+}
+
+if (args.includes('--help') || args.includes('-h')) {
+  process.stdout.write([
+    'ReMCP compact local runtime',
+    '',
+    'Usage: remcp-runtime-compact [--print-tools] [--describe] [--version]',
+    '',
+    'This stdio MCP server exposes the same local ReMCP runtime through a compact verb_noun facade.',
+    'It is intended for directory scanners, local MCP clients, and environments where a small tool surface improves selection.',
+    '',
+  ].join('\n'));
+  process.exit(0);
+}
+
+if (args.includes('--version')) { process.stdout.write(`${VERSION}\n`); process.exit(0); }
+
+const tools = await compactRuntimeToolDefinitions();
+if (args.includes('--print-tools')) { await writeStdout(`${JSON.stringify(tools, null, 2)}\n`); process.exit(0); }
+if (args.includes('--describe')) {
+  await writeStdout(`${JSON.stringify({ version:VERSION, tools:tools.length, toolNames:tools.map(tool => tool.name) }, null, 2)}\n`);
+  process.exit(0);
+}
+
+const configProblem = configurationError();
+if (configProblem) { console.error(`ReMCP compact runtime refuses to start: ${configProblem}`); process.exit(2); }
+
+const instructions = [
+  'This compact runtime executes real ReMCP operations locally on this computer.',
+  'Choose one domain tool, then one operation. Inspect before changing state and use the least invasive operation that satisfies the request.',
+  'The parameters object is validated against the selected operation’s original closed schema.',
+].join(' ');
+
+const { startCompactRuntimeMcpServer } = await import('./compact-mcp.mjs');
+const runtimeServer = await startCompactRuntimeMcpServer({
+  version:VERSION,
+  instructions,
+  onError(error) { console.error(`ReMCP compact runtime MCP error: ${error instanceof Error ? error.message : String(error)}`); },
+});
+
+let shutdownStarted = false;
+async function shutdown(code = 0) {
+  if (shutdownStarted) return;
+  shutdownStarted = true;
+  shutdownSessions();
+  try { await runtimeServer.close(); } catch {}
+  process.exit(code);
+}
+process.stdout.on('error', error => {
+  if (error?.code === 'EPIPE' || error?.code === 'ERR_STREAM_DESTROYED') void shutdown(0);
+  else console.error(`ReMCP compact runtime stdout error: ${error instanceof Error ? error.message : String(error)}`);
+});
+process.on('SIGINT', () => void shutdown(0));
+process.on('SIGTERM', () => void shutdown(0));
+process.on('exit', () => { shutdownSessions(); });
+startSessionSweeper();
+console.error(`ReMCP compact runtime ${VERSION} ready with ${tools.length} domain tools`);