Samurai MCP Super Server

A comprehensive Model Context Protocol (MCP) super server with plugin architecture, secure vault integration, and real-time web dashboard.

🚀 Features

Core Features

- Plugin-Based Architecture: Modular MCP instances for different services (SMS via Twilio, etc.) - LLM Provider Management: Support for multiple LLM providers with API key management - Secure Vault Integration: Industry-standard API key storage and encryption - Real-time Web Dashboard: Live monitoring and management interface - Rate Limiting & Throttling: Per-provider and per-plugin request control - Comprehensive Logging: Request/response analytics with queryable history

Advanced Features

- Plugin Marketplace: Community-contributed plugins - A/B Testing Framework: Different LLM configuration testing - Cost Tracking: Budgeting per user/organization - Response Caching: API cost reduction through intelligent caching - Plugin Sandboxing: Security isolation for plugins - Metrics & Observability: Prometheus/Grafana integration

Developer Experience

- Plugin SDK/CLI: Easy plugin development tools - Hot-reloading: Development-time plugin reloading - OpenAPI Documentation: Auto-generated API docs - Testing Framework: Mock services for plugin testing

📁 Project Structure

├── README.md
├── go.mod
├── go.sum
├── samurai.go                 # Development CLI tool
├── docker-compose.yml         # Database services
├── .env.example              # Environment template
├── backend/
│   ├── cmd/
│   │   └── server/
│   │       └── main.go       # Application entry point
│   └── internal/
│       ├── api/
│       │   ├── handlers/     # HTTP request handlers
│       │   ├── middleware/   # HTTP middleware
│       │   └── routes/       # Route definitions
│       ├── config/           # Configuration management
│       ├── database/         # Database connection & models
│       └── utils/            # Utilities (logging, etc.)
├── config/
│   └── development.json      # Development configuration
├── logs/                     # Application logs
├── bin/                      # Compiled binaries
└── data/                     # Database data

🛠️ Prerequisites

- Go 1.21+: Download Go
- Docker Desktop: Download Docker
- Git: Download Git

⚡ Quick Start

1. Clone Repository

git clone https://github.com/exprays/samurai
cd exprays-samurai

2. Setup Development Environment

go run samurai.go setup

This will: - Create necessary directories - Copy .env.example to .env - Download Go dependencies - Pull required Docker images

3. Start Development Environment

go run samurai.go dev

This will: - Start PostgreSQL database - Start the backend server - Display service URLs and status

4. Verify Installation

go run samurai.go status

🔧 Development Commands

| Command | Description |
|---------|-------------|
| go run samurai.go dev | Start full development environment |
| go run samurai.go setup | Setup development environment |
| go run samurai.go build | Build the application |
| go run samurai.go test | Run all tests |
| go run samurai.go status | Show service status |
| go run samurai.go logs | Show service logs |
| go run samurai.go stop | Stop all services |
| go run samurai.go clean | Clean build artifacts |

🌐 Service Endpoints

| Service | URL | Description |
|---------|-----|-------------|
| Health Check | http://localhost:8080/health | Service health status |
| Ready Check | http://localhost:8080/health/ready | Database readiness |
| API Base | http://localhost:8080/api/v1 | REST API endpoints |
| Database | localhost:5432 | PostgreSQL database |

📊 Logging

The application uses structured logging with separate log files:

- Application Logs: logs/app.log - Main application events
- Access Logs: logs/access.log - HTTP request/response logs
- Database Logs: logs/database.log - Database queries and operations

Log Configuration

Logs are configured via environment variables: - LOG_LEVEL: debug, info, warn, error (default: info) - LOG_FORMAT: json, console (default: json)

🔒 Environment Configuration

Copy .env.example to .env and configure:

```env