BRAINS OS - version MCP

A modern, serverless operating system for AI systems and agents, built with SST, React, and TypeScript. This project provides a robust framework for managing Large Language Models (LLMs) and specialized AI agents through the MCP (Model Control Protocol) with a unified command system and shared operating template.

Overview

Brains MCP is designed to:

• Manage and orchestrate AI workflows through a visual interface
• Provide a unified command system for AI operations
• Enable secure, scalable deployment of AI subminds
• Support comprehensive prompt management and benchmarking
• Maintain strict data ownership and audit capabilities

Key Features

Current Version

• Visual flow editor for AI workflow design
• Unified command system for AI operations
• Secure authentication and authorization
• Real-time workflow execution
• Comprehensive audit logging

Coming Soon

• Advanced prompt library with benchmarking capabilities
• MCP (Model Control Protocol) client/server implementation
• Enhanced state management and persistence
• Extended model support and integration
• Advanced templating system

Architecture

The system is built on modern cloud-native technologies:

• Frontend: React with TypeScript and Flow-based UI
• Backend: AWS Lambda functions
• Authentication: AWS Cognito
• Database: DynamoDB
• Infrastructure: SST (Serverless Stack)

Getting Started

Prerequisites

• Node.js (v16 or later)
• AWS account with configured credentials
• Git

Installation

1. Clone the repository:

   git clone [repository-url]
   cd brains-mcp
   

2. Install dependencies:

   npm install
   

3. Start the development server:

   npx sst dev
   

Test Environment Setup

1. Create your test environment file:

   cp .env.test.example .env.test
   chmod 600 .env.test  # Set secure file permissions
   

2. Configure your test environment by editing .env.test:

   # API Configuration
   API_STAGE=dev
   API_VERSION=latest
   API_BASE_URL=https://dev-api.yoururl-in-aws-route53.com
   
   # AWS Cognito Authentication (Required)
   COGNITO_USERNAME=your_test_username@example.com
   COGNITO_PASSWORD=your_test_password
   USER_POOL_ID=us-east-1_xxxxxx
   APP_CLIENT_ID=xxxxxxxxxxxxxxxxxx
   COGNITO_REGION=us-east-1
   IDENTITY_POOL_ID=us-east-1:xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx
   API_GATEWAY_REGION=us-east-1
   

3. Verify your test setup:

   # Run a basic test to verify configuration
   ./packages/brainsOS/test_scripts/mcp/test_tools.sh
   

Security Notes

• Never commit .env.test to version control
• Keep test credentials secure and rotate them regularly
• Ensure .env.test has correct permissions (600)
• Review test scripts for any hardcoded sensitive data
• Use separate test credentials from production

Test Script Organization

packages/brainsOS/test_scripts/
├── mcp/                    # MCP-specific test scripts
├── resources/             # Resource API test scripts
├── services/             # Service API test scripts
└── test_utils.sh         # Common test utilities

Running Tests

1. Individual test scripts:

   # Run specific test suite
   ./packages/brainsOS/test_scripts/mcp/test_tools.sh
   
   # Run with specific starting point
   ./packages/brainsOS/test_scripts/mcp/test_tools.sh -5  # Start from step 5
   

2. Interactive features:

   • Press [Enter] to continue to next test
   • Press [R] to retry the last command
   • Press [Q] to quit the test suite

3. Reviewing results:

   • ✅ indicates passed tests
   • ❌ indicates failed tests
   • ⚠️ indicates warnings or important notices

Troubleshooting

1. Permission Issues:

   # Reset file permissions
   chmod 600 .env.test
   chmod 755 packages/brainsOS/test_scripts/*.sh
   

2. Authentication Errors:

   • Verify Cognito credentials in .env.test
   • Check API endpoint configuration
   • Ensure AWS region settings are correct

3. Common Issues:

   • Token expiration: Scripts handle this automatically
   • Rate limiting: Built-in delays prevent API throttling
   • Missing environment variables: Validation will catch these

Project Structure

brains-mcp/
├── packages/
│   ├── frontend/           # React-based flow editor
│   │   ├── src/
│   │   │   ├── components/
│   │   │   ├── nodes/
│   │   │   └── core/
│   │   └── ...
│   └── brainsOS/          # Core backend system
│       ├── commands/      # Command implementations
│       ├── core/         # Core services
│       ├── functions/    # API functions
│       └── utils/        # Shared utilities
├── infra/                # Infrastructure code
└── sst.config.ts        # SST configuration

Development

Local Development

npx sst dev

Deployment

npx sst deploy --stage <stage>

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

[License Type] - See LICENSE file for details