Onyx Documentation MCP Server

Instructions

Implementation Reference

• src/core/mcp-shared.js:270-327 (handler)

  Main handler function that executes the specified WASM file using the 'onyx run' command. Validates paths, handles timeouts, captures stdout/stderr, and formats the 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:134-146 (registration)

  Tool registration in the TOOL_DEFINITIONS array, defining the tool name, description, and input schema.
  { 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:137-145 (schema)

  Input schema defining parameters for the run_wasm tool: wasmPath (required), directory, and timeout.
  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:648-649 (handler)

  Dispatch case in the executeTool method that routes calls to the runWasm handler.
  case 'run_wasm': return await this.runWasm(args.wasmPath, args.directory, args.timeout);
• src/core/mcp-shared.js:544-617 (helper)

  Helper function used by runWasm to execute the 'onyx run' command process, handling spawn, timeout, and output capture.
  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 }); } }); }); }