omnara 1.0.0

Omnara Agent Dashboard MCP Server

Omnara - Agent Dashboard

A unified interface for monitoring and interacting with multiple AI agents.

Overview

Omnara provides a web dashboard where users can:

• Monitor multiple AI agents (Claude Code, GitHub Copilot, Cursor, Codex, etc.)
• See real-time progress of agent tasks
• Answer questions from agents when they need guidance
• Send feedback and additional instructions to active agents
• View history of completed tasks and interactions
• Manage API keys for secure agent authentication

Architecture

• MCP Server: Agents connect here to log progress and ask questions
• Backend API: FastAPI service providing data to frontend
• Frontend: React app with clean UI for non-technical users
• Database: PostgreSQL for persistent storage

graph TB
    subgraph "AI Agents"
        A1["Claude Code"]
        A2["GitHub Copilot"]
        A3["Cursor"]
        A4["Other Agents"]
    end
    
    subgraph "Agent Dashboard System"
        subgraph "Services"
            MCP["MCP Server<br/>Port 8080<br/>FastMCP + HTTP/SSE"]
            Backend["Backend API<br/>Port 8000<br/>FastAPI + REST"]
            Frontend["Frontend<br/>Port 3000<br/>React + Vite"]
        end
        
        subgraph "Data Layer"
            DB["PostgreSQL<br/>Port 5432<br/>Shared Database"]
        end
    end
    
    subgraph "Users"
        U1["Web Users"]
    end
    
    A1 -.->|"MCP Protocol<br/>log_step() + feedback<br/>ask_question()<br/>end_session()"| MCP
    A2 -.->|"MCP Protocol<br/>log_step() + feedback<br/>ask_question()<br/>end_session()"| MCP
    A3 -.->|"MCP Protocol<br/>log_step() + feedback<br/>ask_question()<br/>end_session()"| MCP
    A4 -.->|"MCP Protocol<br/>log_step() + feedback<br/>ask_question()<br/>end_session()"| MCP
    
    MCP <-->|"SQLAlchemy ORM<br/>Shared Models"| DB
    Backend <-->|"SQLAlchemy ORM<br/>Shared Models"| DB
    
    Frontend <-->|"REST API<br/>JSON"| Backend
    U1 <-->|"HTTP/Browser"| Frontend
    
    classDef agent fill:#e1f5fe
    classDef service fill:#f3e5f5
    classDef data fill:#e8f5e8
    classDef user fill:#fff3e0
    
    class A1,A2,A3,A4 agent
    class MCP,Backend,Frontend service
    class DB data
    class U1 user

Quick Start

Prerequisites

• Docker and Docker Compose
• OR: Python 3.12+, Node.js 18+, PostgreSQL
• Supabase account (for authentication)

Initial Setup (First Time Only)

The frontend is maintained as a separate git repository. After cloning this repository, initialize the frontend submodule:

# Initialize and update all submodules (including frontend)
git submodule update --init --recursive

# Alternative: Only initialize the frontend submodule
git submodule update --init frontend

For new team members: Always run the submodule command after cloning this repository to populate the frontend/ folder.

Authentication Setup

1. Create a Supabase project at https://supabase.com
2. Enable Google OAuth provider in Authentication settings (optional)
3. Generate RSA keys for API key signing:

   python scripts/generate_jwt_keys.py
   

4. Create .env file with required variables (see Environment Variables section)

Running with Docker (Recommended)

# Start all services with one command
docker compose up

# Services will be available at:
# - Frontend: http://localhost:3000
# - Backend API: http://localhost:8000
# - MCP Server: http://localhost:8080
# - PostgreSQL: localhost:5432

Manual Installation

# Generate JWT keys (if not done already)
python scripts/generate_jwt_keys.py

# Backend setup
cd mcp_server
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows
pip install -r requirements.txt

cd ../backend
python -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Frontend setup
cd ../frontend
npm install
# Create .env with your configuration
# Copy the template below and save as .env
# Edit .env with your actual values

# Initialize database
python -m shared.database.init_db

# Development tools (optional)
pip install -r requirements-dev.txt

# Set up pre-commit hooks (recommended)
make pre-commit-install

Manual Running

# Terminal 1: MCP Server
cd mcp_server
python -m server

# Terminal 2: Backend API
cd backend
python -m main

# Terminal 3: Frontend
cd frontend
npm run dev

Project Structure

• mcp_server/ - MCP server for agent communication
• backend/ - FastAPI backend serving the web app
• frontend/ - React frontend with shadcn/ui (git submodule)
• shared/ - Shared code between services
• scripts/ - Development scripts for linting and formatting
• CLAUDE.md - System design documentation
• pyproject.toml - Python project configuration and tool settings
• pyrightconfig.json - Pyright type checker configuration

Development

Working with the Frontend Submodule

The frontend/ folder is a git submodule pointing to the omnara-frontend repository.

# Check submodule status
git submodule status

# Update frontend to latest from remote
cd frontend
git pull origin main
cd ..
git add frontend
git commit -m "Update frontend submodule to latest"

# Switch frontend to a specific branch/commit
cd frontend
git checkout main  # or any branch/commit
cd ..
git add frontend
git commit -m "Update frontend submodule reference"

# If frontend folder is empty after pulling changes
git submodule update --init --recursive

Important Notes:

• The frontend/ folder contains a reference to a specific commit in the omnara-frontend repo
• To update frontend code, work directly in the omnara-frontend repository
• After updating the submodule reference, commit the change in this main repository
• Never commit files directly inside frontend/ - they belong to the submodule

Code Quality Tools

This project uses ruff for linting/formatting and pyright for type checking, with pre-commit hooks to ensure code quality.

# Install development dependencies and set up pre-commit
make pre-commit-install

# Pre-commit hooks will automatically run on git commit
# To manually run pre-commit on all files:
make pre-commit-run

# Manual code quality commands:
make lint               # Run all checks (linting + type checking)
make format             # Auto-format code
make ruff-check         # Just ruff linting
make ruff-format-check  # Just format checking
make typecheck          # Just type checking

Pre-commit Hooks

Pre-commit hooks automatically run before each commit to ensure code quality:

• Ruff linting - Automatically fixes common issues
• Ruff formatting - Ensures consistent code style
• Pyright type checking - Catches type errors
• General checks - Removes trailing whitespace, fixes end-of-file issues

If pre-commit hooks fail, the commit is blocked until issues are resolved.

Python Version

The project uses Python 3.12. All Docker images and virtual environments should use this version.

Environment Variables

Backend (.env)

# Database
DATABASE_URL=postgresql://user:password@localhost:5432/agent_dashboard

# Supabase (for web auth)
SUPABASE_URL=https://your-project.supabase.co
SUPABASE_ANON_KEY=your-anon-key

# JWT Keys (generate with scripts/generate_jwt_keys.py)
JWT_PRIVATE_KEY='-----BEGIN RSA PRIVATE KEY-----\n...\n-----END RSA PRIVATE KEY-----'
JWT_PUBLIC_KEY='-----BEGIN PUBLIC KEY-----\n...\n-----END PUBLIC KEY-----'

# Optional
API_PORT=8000
MCP_SERVER_PORT=8080

Frontend (.env.local)

VITE_SUPABASE_URL=https://your-project.supabase.co
VITE_SUPABASE_ANON_KEY=your-anon-key
VITE_API_URL=http://localhost:8000

For Agents

Getting Started

1. Sign up at http://localhost:3000
2. Navigate to API Keys section in dashboard
3. Create a new API key
4. Configure your MCP client with the API key

MCP Client Configuration

{
  "mcpServers": {
    "omnara": {
      "type": "sse",
      "url": "http://127.0.0.1:8080/sse",
      "headers": {
        "Authorization": "Bearer TOKEN"
      }
    }
  }
}

Replace TOKEN with the API key you generated from the dashboard.

Available Tools

• log_step - Log your current high-level task and receive user feedback
• ask_question - Ask the user for guidance (non-blocking)
• end_session - Mark the agent session as completed

All tools require authentication via the API key. The log_step tool returns any user feedback submitted since the last step, allowing agents to incorporate user instructions and corrections in real-time. The end_session tool should be called after the user confirms task completion to properly close the session.