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.
# 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
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.
# 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
Use Direct Models When
Use Agents When
Simple one-off completions
Need persistent personality
Testing different models
Want built-in tools
Custom tool definitions
Want conversation memory
Maximum control
Want pre-configured behavior
Raw model capabilities
Want simplified interface
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.
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