What is Serverless Mcp

serverless-mcp is a modern, serverless operating system designed for managing AI systems and agents. It leverages SST, React, and TypeScript to provide a robust framework for orchestrating Large Language Models (LLMs) and specialized AI agents through the Model Control Protocol (MCP).

Use cases

Use cases for serverless-mcp include developing and managing AI applications, conducting prompt management and benchmarking, deploying AI subminds securely, and maintaining data ownership with audit capabilities.

How to use

To use serverless-mcp, clone the repository from GitHub, install the necessary dependencies using npm, and start the development server with the command ‘npx sst dev’. Ensure you have Node.js, an AWS account, and Git installed beforehand.

Key features

Key features of serverless-mcp include a visual flow editor for designing AI workflows, a unified command system for AI operations, secure authentication and authorization, real-time workflow execution, and comprehensive audit logging.

Where to use

serverless-mcp is suitable for various fields including AI development, machine learning operations, and any domain requiring orchestration of AI workflows and management of large language models.

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)
   [email protected]
   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