Onyx Documentation MCP Server

Instructions

Implementation Reference

• src/core/mcp-shared.js:377-425 (handler)

  The core handler function for the 'build_onyx_code' tool. It writes the provided Onyx code to a file in the specified directory, executes 'onyx build' command, captures output and errors, and returns formatted results.
  async buildOnyxCode(code, filename = 'main.onyx', directory = '.', timeout = 30) { const toolMessage = `Building Onyx code using "onyx build" in directory: ${directory}`; try { // Resolve the target directory const targetDir = path.resolve(directory); // Check if directory exists try { await fs.access(targetDir); } catch (error) { throw new Error(`Directory does not exist: ${targetDir}`); } // Write the code to the specified file in target directory const filePath = path.join(targetDir, filename); await fs.writeFile(filePath, code, 'utf8'); // Build the Onyx code in target directory const result = await this.executeOnyxCommand(['build', filename], timeout, targetDir); // Format the response with build results const response = { success: result.success, exitCode: result.exitCode, stdout: result.stdout, stderr: result.stderr, executionTime: result.executionTime, command: `onyx build ${filename}`, filename: filename, codeLength: code.length, workingDirectory: targetDir }; return this.formatResponse(JSON.stringify(response, null, 2), toolMessage); } catch (error) { const errorResponse = { success: false, error: error.message, command: `onyx build ${filename}`, filename: filename, codeLength: code.length, workingDirectory: directory }; return this.formatResponse(JSON.stringify(errorResponse, null, 2), toolMessage); } }
• src/core/mcp-shared.js:147-160 (schema)

  The input schema and metadata definition for the 'build_onyx_code' tool, including name, description, and parameter specifications. This is part of the TOOL_DEFINITIONS array used for tool registration.
  { name: 'build_onyx_code', description: 'Build Onyx code file using "onyx build" in a specified directory', inputSchema: { type: 'object', properties: { code: { type: 'string', description: 'Onyx code to build' }, filename: { type: 'string', description: 'Filename for the Onyx file', default: 'main.onyx' }, directory: { type: 'string', description: 'Directory to build in (defaults to current working directory)', default: '.' }, timeout: { type: 'number', description: 'Build timeout in seconds', default: 30 } }, required: ['code'] } },
• src/core/mcp-shared.js:651-652 (registration)

  The dispatch/registration point in the executeTool switch statement that routes calls to the buildOnyxCode handler function.
  case 'build_onyx_code': return await this.buildOnyxCode(args.code, args.filename, args.directory, args.timeout);
• src/core/mcp-shared.js:543-617 (helper)

  Helper function used by the build_onyx_code handler to spawn and manage the 'onyx' process, handling stdout/stderr capture, timeouts, and errors.
  // 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 }); } }); }); }