Tools & SDK

Brightsy AI provides comprehensive tooling for developers, including a powerful CLI, TypeScript SDK, MCP server integration, and specialized tools for content management, AI interactions, and platform automation.

Command Line Interface (CLI)

The Brightsy CLI (@brightsy/cli) is a comprehensive command-line tool for platform interaction.

For detailed information, see the CLI documentation.

BrightsyClient SDK

The BrightsyClient TypeScript/JavaScript SDK provides programmatic access to the full Brightsy platform.

Installation

npm install @brightsy/client

Basic Usage

import { BrightsyClient } from '@brightsy/client';

const client = new BrightsyClient({
  api_key: 'bsy_...',
  account_id: 'account-uuid'
});

// CMA - Content Management API (draft content)
const records = await client.cma.recordType('blog-post').get();

// CDA - Content Delivery API (published content)
const published = await client.cda.recordType('blog-post').get();

// CPA - Content Preview API (draft preview)
const preview = await client.cpa.recordType('blog-post').get();

Core Features

• Multi-API Support: CMA (draft), CDA (published), CPA (preview)
• TypeScript Types: Full type safety and IntelliSense
• OAuth Integration: Automatic token refresh
• Streaming Support: Real-time chat completions
• File Management: Upload/download with signed URLs
• Error Handling: Comprehensive error types and recovery

Content Management

// Create record
const post = await client.cma.recordType('blog-post').create({
  title: { en: 'Hello World', de: 'Hallo Welt' },
  slug: 'hello-world',
  content: '# Welcome to my blog...'
});

// Update with relationships
await client.cma.recordType('blog-post').update(post.id, {
  author: 'author-uuid', // has-one relationship
  tags: ['javascript', 'react'] // array field
});

// Query with filters
const filtered = await client.cma.recordType('blog-post')
  .where('status', 'eq', 'published')
  .where('author.name', 'like', 'John')
  .orderBy('created_at', 'desc')
  .limit(10)
  .get();

AI & Agent Integration

// List available agents
const agents = await client.agents().list();

// Chat with agent
const response = await client.agent('agent-id').chat({
  message: 'Help me debug this code',
  system_context: 'You are a senior developer'
});

// Direct model completion
const completion = await client.models.complete({
  model: 'claude_sonnet_4_5',
  messages: [{ role: 'user', content: 'Explain React hooks' }],
  mode: 'ask' // ask, plan, agent, or debug
});

File Operations

// Upload file
const upload = await client.files().upload('image.jpg', imageBuffer);

// Get signed URL for secure access
const signedUrl = await client.files().getSignedUrl('path/to/file.jpg');

// List files
const files = await client.files().list('documents/');

Automation & Integration

// Webhooks
const webhooks = await client.webhooks().list();
const webhook = await client.webhooks().create({
  name: 'Order Notifications',
  url: 'https://api.example.com/webhook',
  events: ['record.created']
});

// Scenarios
const scenarios = await client.scenarios().list();
await client.scenarios().trigger('scenario-id', { orderId: '123' });

// API Keys
const keys = await client.apikeys().create({
  name: 'Frontend App',
  permissions: {
    cms: {
      'blog-post': { read: true, create: true },
      'product': { read: true }
    }
  }
});

File Management System

Brightsy provides a comprehensive file management system with secure storage, access controls, and AI-powered organization.

Features & Capabilities

• Hierarchical Storage: Organize files in unlimited folder structures
• Search & Discovery: Full-text search across file names and content
• Access Control: Permission-based file access (public/private)
• Signed URLs: Secure temporary access links
• AI Integration: Agents can manage and analyze files
• Version History: Track file changes and rollbacks
• CDN Integration: Global content delivery for performance

File Operations

// SDK usage
const files = await client.files().list('documents/');
const upload = await client.files().upload('report.pdf', fileBuffer);
const signedUrl = await client.files().getSignedUrl('private/document.pdf');

// CLI usage
brightsy files list --path documents/
brightsy files upload report.pdf --folder documents/
brightsy files delete old-report.pdf

MCP Tools for Files

When using Brightsy Desktop or standalone MCP server:

• local_read_file: Read project files (no auth required)
• local_write_file: Write to project files
• local_list_files: Browse project directory structure
• local_search_files: Search file contents with regex
• local_grep: Advanced text search with patterns

Best Practices

• Organization: Use consistent folder naming (e.g., images/, documents/, assets/)
• Naming: Use descriptive, URL-safe filenames
• Access Control: Store sensitive files privately, public assets openly
• File Types: Leverage Brightsy's support for all common formats
• Cleanup: Regularly remove unused files to manage storage costs
• Backup: Important files are automatically backed up with version history

Visual Page Builder & Components

Brightsy's visual page builder enables no-code website creation with drag-and-drop components and AI assistance.

Features & Capabilities

• Component Libraries: Pre-built and custom React components
• Visual Editor: Puck-based drag-and-drop page builder
• Theme System: CSS variables and design tokens
• AI Assistance: LLM-powered page building and component suggestions
• Responsive Design: Mobile-first, cross-device compatibility
• Multi-page Sites: Complete website management
• Component Marketplace: Shared libraries and templates

Component Development

// Create custom components
import { BrightsyComponentConfig } from '@brightsy/component-dev-kit';

export const Button = ({ text, href, variant = 'primary' }) => (
  <a href={href} className={`btn btn-${variant}`}>
    {text}
  </a>
);

export const buttonConfig: BrightsyComponentConfig = {
  label: 'Button',
  category: 'Interactive',
  fields: {
    text: { type: 'text', label: 'Button Text' },
    href: { type: 'text', label: 'Link URL' },
    variant: {
      type: 'radio',
      label: 'Style',
      options: [
        { label: 'Primary', value: 'primary' },
        { label: 'Secondary', value: 'secondary' },
      ],
    },
  },
  defaultProps: {
    text: 'Click me',
    href: '#',
    variant: 'primary',
  },
};

Theme Integration

Components automatically adapt to site themes using CSS variables:

.my-component {
  background: var(--color-surface, #ffffff);
  color: var(--color-text, #1f2937);
  border-radius: var(--border-radius-md, 0.375rem);
  padding: var(--spacing-lg, 1.5rem);
}

CLI Integration

# Create component library
brightsy create my-components

# Connect to site
brightsy connect

# Develop locally
npm run dev
brightsy push --dev

# Deploy to production
npm run build
brightsy push

Best Practices

• Component Naming: Use clear, descriptive component names
• Prop Types: Define comprehensive prop schemas for the page builder
• Accessibility: Ensure components meet WCAG guidelines
• Performance: Optimize components for fast loading
• Reusability: Design components for multiple use cases
• Documentation: Include LLM instructions for AI-assisted building

Automation & Integration

Brightsy provides powerful automation capabilities through scenarios, webhooks, and API integrations.

Scenarios (Workflow Automation)

// Create automation scenario
const scenario = await client.scenarios().create({
  name: 'Welcome Email',
  description: 'Send welcome email to new users',
  trigger_type: 'record_create',
  trigger_config: {
    record_type: 'users'
  },
  agent_id: 'email-agent-id',
  actions: [{
    type: 'send_email',
    config: {
      template: 'welcome',
      recipient_field: 'email'
    }
  }]
});

// Trigger manually
await client.scenarios().trigger(scenario.id, {
  userId: '123',
  email: 'user@example.com'
});

Webhooks (Event-Driven Integration)

// Create webhook
const webhook = await client.webhooks().create({
  name: 'Order Processing',
  url: 'https://api.example.com/webhooks/orders',
  secret: 'webhook-secret',
  events: ['record.created', 'record.updated']
});

// CLI alternative
brightsy webhooks create "Order Webhook" "https://api.example.com/webhooks" --events "record.created"

Scheduled Tasks

// Create cron-based schedule
const schedule = await client.schedules().create({
  name: 'Daily Report',
  cron_expression: '0 9 * * *', // 9 AM daily
  timezone: 'America/New_York',
  scenario_id: 'report-scenario-id'
});

API Keys & Permissions

// Create scoped API key
const apiKey = await client.apikeys().create({
  name: 'E-commerce Integration',
  permissions: {
    cms: {
      'product': { read: true, create: true, update: true },
      'order': { read: true, create: true },
      'user': { read: true }
    },
    files: { read: true, create: true },
    scenarios: { read: true, trigger: true }
  }
});

External API Integration

While Brightsy focuses on internal automation, you can integrate with external services:

// Using the SDK for external APIs
const externalData = await fetch('https://api.stripe.com/v1/charges', {
  headers: { 'Authorization': `Bearer ${process.env.STRIPE_SECRET_KEY}` }
});

// Process and store in Brightsy
await client.cma.recordType('payments').create({
  stripe_id: externalData.id,
  amount: externalData.amount,
  status: externalData.status
});

Best Practices

• Event-Driven Architecture: Use webhooks for real-time integrations
• Idempotent Operations: Design scenarios to handle duplicate triggers
• Error Handling: Implement retry logic for failed operations
• Monitoring: Set up alerts for failed automations
• Security: Use scoped API keys with minimal permissions
• Testing: Test scenarios with sample data before production use

AI Models & Direct Access

Brightsy provides direct access to leading AI models without requiring agent setup.

Available Models

Direct Model Usage

// SDK - Direct completion
const response = await client.models.complete({
  model: 'claude_sonnet_4_5',
  messages: [
    { role: 'user', content: 'Explain React hooks in simple terms' }
  ],
  mode: 'ask', // ask, plan, agent, or debug
  temperature: 0.7,
  max_tokens: 1000
});

// With tools
const withTools = await client.models.complete({
  model: 'claude_sonnet_4_5',
  messages: [{ role: 'user', content: 'What\'s the weather in Paris?' }],
  tools: [{
    type: 'function',
    function: {
      name: 'get_weather',
      description: 'Get current weather',
      parameters: {
        type: 'object',
        properties: { location: { type: 'string' } }
      }
    }
  }]
});

// Streaming
await client.models.complete({
  model: 'gemini_3_flash_preview',
  messages: [{ role: 'user', content: 'Write a story' }],
  stream: true,
  onChunk: (chunk) => process.stdout.write(chunk)
});

CLI Usage

# List available models
brightsy models

# Direct completion
brightsy chat --model claude_sonnet_4_5 "Explain quantum computing"

# Interactive model selection
brightsy chat
# Choose "Direct Model Completion" then select model

Model Capabilities

• Tools: Function calling and tool use
• Vision: Image analysis and understanding
• Reasoning: Extended thinking and planning
• Streaming: Real-time response generation
• Multilingual: Support for multiple languages

When to Use Direct Models vs Agents

Best Practices

• Model Selection: Choose based on task requirements and cost
• Context Limits: Be aware of token limits for long conversations
• Cost Optimization: Use appropriate model size for task complexity
• Caching: Implement caching for repeated queries when possible
• Rate Limits: Respect API rate limits (varies by model)
• Error Handling: Implement fallback models for reliability

MCP Servers & AI Integration

Brightsy provides comprehensive Model Context Protocol (MCP) integration for seamless AI tool connectivity.

MCP Integration Options

1. Brightsy Desktop (Recommended)

// Cursor configuration
{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-desktop-mcp"
    }
  }
}

Features:

• 60+ tools including filesystem, terminal, and full Brightsy platform
• Local development workspace access
• Automatic authentication from Desktop app
• Zero configuration setup

2. Standalone MCP Server

// Cursor configuration
{
  "mcpServers": {
    "brightsy": {
      "command": "brightsy-mcp",
      "env": {
        "BRIGHTSY_ALLOWED_DIRS": "/workspace"
      }
    }
  }
}

Features:

• NPM package @brightsy/mcp-server
• Local tools (filesystem, terminal, CLI discovery)
• OAuth authentication to Brightsy platform
• Customizable environment variables

3. Web MCP Server

// For remote access
{
  "mcpServers": {
    "brightsy": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.brightsy.ai/mcp"]
    }
  }
}

MCP Tool Categories

Local Development Tools (No Auth Required)

• local_read_file, local_write_file: File operations
• local_list_files, local_search_files: Directory browsing
• local_run_command: Terminal command execution
• discover_cli_tools: Find npm scripts and build tools

Cloud Platform Tools (Auth Required)

• Agent Management: list_agents, chat (multi-turn conversations)
• Direct AI: list_models, complete (model gateway)
• Content Management: Full CRUD for records and schemas
• Sites & Pages: Visual page builder management
• Files: Storage with signed URLs
• Automation: Scenarios, schedules, webhooks
• API Keys: Permission management

MCP in AI Applications

// Example: Cursor/Claude Desktop integration
// Tools automatically appear in AI assistant interface
// No additional configuration needed beyond MCP setup

// Example conversation:
// User: "List my Brightsy agents"
// AI: [calls list_agents tool] → "You have 3 agents: Customer Support, Data Analysis, Content Writer"

// User: "Create a blog post about React 19"
// AI: [calls create_record tool] → "Created blog post with ID: post-123"

CLI + MCP Integration

The CLI and MCP servers share authentication and can be used interchangeably:

# CLI for scripting
brightsy records list blog-post --status published

# MCP for AI-assisted workflows
# AI tools call the same underlying APIs through MCP protocol

Best Practices

• Choose Right MCP: Desktop for full access, Standalone for custom setups
• Security: MCP respects Brightsy's permission system
• Performance: Local tools are faster than cloud roundtrips
• Authentication: OAuth tokens are shared across MCP and CLI
• Tool Discovery: MCP provides self-documenting tool descriptions
• Error Handling: MCP tools return structured error information
• Rate Limits: Respects Brightsy API limits (100 req/min, 1000 req/hour)