Onyx Documentation MCP Server

Instructions

Implementation Reference

• src/core/mcp-shared.js:329-374 (handler)

  Main handler function that writes Onyx code to a temporary file, executes it using 'onyx run', captures stdout/stderr/exit code, handles timeouts and cleanup, and formats the response.
  async runOnyxCode(code, filename = 'temp.onyx', timeout = 10) { const toolMessage = `Executing Onyx code to test and validate functionality`; try { // Create a temporary directory for code execution const tempDir = path.join(this.dataDir, 'temp'); await fs.mkdir(tempDir, { recursive: true }); // Write the code to a temporary file const filePath = path.join(tempDir, filename); await fs.writeFile(filePath, code, 'utf8'); // Execute the Onyx code const result = await this.executeOnyxFile(filePath, timeout); // Clean up the temporary file try { await fs.unlink(filePath); } catch (cleanupError) { // Ignore cleanup errors } // Format the response with execution results const response = { success: result.success, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, executionTime: result.executionTime, filename: filename, codeLength: code.length }; return this.formatResponse(JSON.stringify(response, null, 2), toolMessage); } catch (error) { const errorResponse = { success: false, error: error.message, filename: filename, codeLength: code.length }; return this.formatResponse(JSON.stringify(errorResponse, null, 2), toolMessage); } }
• src/core/mcp-shared.js:122-133 (schema)

  Schema definition including name, description, and input schema (parameters: code (required), filename, timeout) for the run_onyx_code tool.
  name: 'run_onyx_code', description: 'Execute Onyx code and return the output/errors for testing and debugging', inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'Onyx code to execute' }, filename: { type: 'string', description: 'Optional filename (defaults to temp.onyx)', default: 'temp.onyx' }, timeout: { type: 'number', description: 'Execution timeout in seconds', default: 10 } }, required: ['code'] } },
• src/core/mcp-shared.js:645-646 (registration)

  Registration in the tool dispatcher switch statement that maps the 'run_onyx_code' tool name to the runOnyxCode handler method.
  case 'run_onyx_code': return await this.runOnyxCode(args.code, args.filename, args.timeout);
• src/core/mcp-shared.js:471-541 (helper)

  Supporting helper function specifically for executing Onyx files via child_process.spawn('onyx', ['run', filePath]), handling output collection, timeouts, and errors.
  async executeOnyxFile(filePath, timeoutSeconds = 10) { return new Promise((resolve) => { const startTime = Date.now(); let stdout = ''; let stderr = ''; let finished = false; // Try to run with 'onyx run' first const child = spawn('onyx', ['run', filePath], { stdio: ['pipe', 'pipe', 'pipe'], cwd: path.dirname(filePath) }); // Set up timeout const timer = setTimeout(() => { if (!finished) { finished = true; child.kill('SIGTERM'); resolve({ success: false, exitCode: -1, stdout: stdout, stderr: stderr + '\n[TIMEOUT] Execution 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 }); } }); }); }