Onyx Documentation MCP Server

Instructions

Implementation Reference

• src/core/mcp-shared.js:134-146 (schema)

  Tool schema definition including name, description, and inputSchema for parameters: wasmPath (required), directory, timeout.
  { name: 'run_wasm', description: 'Execute a WebAssembly (WASM) file using "onyx run file.wasm" command', inputSchema: { type: 'object', properties: { wasmPath: { type: 'string', description: 'Path to the WASM file to execute' }, directory: { type: 'string', description: 'Directory to run the command from (defaults to current working directory)', default: '.' }, timeout: { type: 'number', description: 'Execution timeout in seconds', default: 10 } }, required: ['wasmPath'] } },
• src/core/mcp-shared.js:270-327 (handler)

  Core handler function that resolves paths, validates file/directory existence, spawns 'onyx run' process via executeOnyxCommand, captures output, and returns formatted MCP response.
  async runWasm(wasmPath, directory = '.', timeout = 10) { const toolMessage = `Executing WebAssembly file: ${wasmPath} using "onyx run" command`; try { // Resolve the target directory and WASM file path const targetDir = path.resolve(directory); let fullWasmPath; // If wasmPath is absolute, use it directly; otherwise, resolve relative to target directory if (path.isAbsolute(wasmPath)) { fullWasmPath = wasmPath; } else { fullWasmPath = path.resolve(targetDir, wasmPath); } // Check if directory exists try { await fs.access(targetDir); } catch (error) { throw new Error(`Directory does not exist: ${targetDir}`); } // Check if WASM file exists try { await fs.access(fullWasmPath); } catch (error) { throw new Error(`WASM file does not exist: ${fullWasmPath}`); } // Execute the WASM file using onyx run const result = await this.executeOnyxCommand(['run', fullWasmPath], timeout, targetDir); // Format the response with execution results const response = { success: result.success, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, executionTime: result.executionTime, command: `onyx run ${fullWasmPath}`, wasmPath: fullWasmPath, workingDirectory: targetDir }; return this.formatResponse(JSON.stringify(response, null, 2), toolMessage); } catch (error) { const errorResponse = { success: false, error: error.message, command: `onyx run ${wasmPath}`, wasmPath: wasmPath, workingDirectory: directory }; return this.formatResponse(JSON.stringify(errorResponse, null, 2), toolMessage); } }
• src/core/mcp-shared.js:648-649 (registration)

  Tool registration in the executeTool dispatcher switch statement, routing calls to the runWasm handler.
  case 'run_wasm': return await this.runWasm(args.wasmPath, args.directory, args.timeout);
• src/core/mcp-shared.js:543-617 (helper)

  Supporting utility function executeOnyxCommand that spawns the 'onyx' child process, manages timeouts, collects stdout/stderr, and handles errors. Called by runWasm.
  // Helper method to execute Onyx commands (for build operations) async executeOnyxCommand(args, timeoutSeconds = 30, workingDirectory = null) { return new Promise((resolve) => { const startTime = Date.now(); let stdout = ''; let stderr = ''; let finished = false; // Use specified directory or current working directory const cwd = workingDirectory || process.cwd(); // Execute onyx command in specified directory const child = spawn('onyx', args, { stdio: ['pipe', 'pipe', 'pipe'], cwd: cwd }); // Set up timeout const timer = setTimeout(() => { if (!finished) { finished = true; child.kill('SIGTERM'); resolve({ success: false, exitCode: -1, stdout: stdout, stderr: stderr + '\n[TIMEOUT] Build/command exceeded ' + timeoutSeconds + ' seconds', executionTime: Date.now() - startTime }); } }, timeoutSeconds * 1000); // Collect stdout child.stdout.on('data', (data) => { stdout += data.toString(); }); // Collect stderr child.stderr.on('data', (data) => { stderr += data.toString(); }); // Handle process completion child.on('close', (code) => { if (!finished) { finished = true; clearTimeout(timer); resolve({ success: code === 0, exitCode: code, stdout: stdout, stderr: stderr, executionTime: Date.now() - startTime }); } }); // Handle process errors (e.g., 'onyx' command not found) child.on('error', (error) => { if (!finished) { finished = true; clearTimeout(timer); resolve({ success: false, exitCode: -1, stdout: stdout, stderr: `Error executing Onyx: ${error.message}\n\nNote: Make sure 'onyx' is installed and available in PATH.\nInstall from: https://onyxlang.io/install`, executionTime: Date.now() - startTime }); } }); }); }