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