Onyx Documentation MCP Server

Instructions

Implementation Reference

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

  Main handler function that implements the 'run_onyx_code' tool logic: writes Onyx code to temp file, executes with 'onyx run', captures stdout/stderr/execution time, handles timeout and errors, formats MCP 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:124-132 (schema)

  Input schema definition for the 'run_onyx_code' tool, specifying parameters: code (required string), filename (optional string), timeout (optional number).

  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:121-133 (registration)

  Tool registration in TOOL_DEFINITIONS array, including name, description, and input schema.

  {
    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)

  Dispatcher switch case in executeTool method that routes 'run_onyx_code' calls to the runOnyxCode handler.

  case 'run_onyx_code':
    return await this.runOnyxCode(args.code, args.filename, args.timeout);

• src/core/mcp-shared.js:471-541 (helper)

  Helper function executeOnyxFile used by runOnyxCode to spawn 'onyx run' process, handle stdout/stderr, timeout, errors, and resolve with execution results.

  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
          });
        }
      });
    });
  }