manager-api

Maascamp/manager-api

3.2

If you are the rightful owner of manager-api and would like to certify it and/or have it hosted online, please leave a comment on the right or send an email to henry@mcphub.com.

The Manager Assistant Application is an intelligent assistant designed to help engineering leaders gain insights into their organizations by integrating multiple data sources and leveraging LLM capabilities.

Tools
3
Resources
0
Prompts
0

Manager Assistant Application

An intelligent assistant application that helps engineering leaders answer questions about their organizations by leveraging LLM capabilities with access to organizational data through Google Workspace, Atlassian, and Slack APIs.

🎯 Overview

The Manager Assistant Application provides natural language querying capabilities across multiple organizational data sources, enabling managers to get comprehensive insights about their teams, projects, and organizational context. The system uses an MCP (Model Context Protocol) server architecture to provide secure, tool-based access to organizational data sources.

Key Features

  • πŸ” Multi-source Data Integration: Google Workspace (Cloud Search, Gmail, Google Apps), Atlassian (Jira, Confluence), Slack, Workday
  • πŸ” Secure Credential Management: Encrypted storage and management of API keys and tokens
  • πŸ€– LLM Flexibility: Support for multiple LLM providers with easy configuration switching
  • ⚑ Context Management: Intelligent context selection and optimization for large datasets
  • 🎯 Quality Assurance: LLM-as-judge evaluation system for answer refinement
  • πŸ’¬ Natural Language Interface: Conversational query processing and response generation

πŸ—οΈ Architecture

The application follows a modular architecture designed for extensibility and security:

β”Œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”
β”‚                    Manager Assistant Application                β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Frontend Interface (Web/CLI)                                  β”‚
β”‚  β”œβ”€ Query Input & Processing                                   β”‚
β”‚  β”œβ”€ Response Display & Interaction                             β”‚
β”‚  └─ Configuration Management                                   β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Core Application Layer                                        β”‚
β”‚  β”œβ”€ LLM Integration (Configurable Provider)                    β”‚
β”‚  β”œβ”€ Query Processing & Intent Recognition                      β”‚
β”‚  β”œβ”€ Context Management & Optimization                          β”‚
β”‚  β”œβ”€ Response Generation & Refinement                           β”‚
β”‚  └─ LLM-as-Judge Evaluation System                             β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Context Management System                                      β”‚
β”‚  β”œβ”€ Intelligent Context Selection & Filtering                 β”‚
β”‚  β”œβ”€ Multi-Level Content Summarization                         β”‚
β”‚  β”œβ”€ Context Window Optimization                               β”‚
β”‚  β”œβ”€ Semantic Chunking & Compression                           β”‚
β”‚  └─ Context Caching & Indexing                               β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  MCP Server Layer                                              β”‚
β”‚  β”œβ”€ Google Workspace Tools (Cloud Search, Gmail, Apps)        β”‚
β”‚  β”œβ”€ Atlassian Tools (Jira, Confluence)                       β”‚
β”‚  β”œβ”€ Slack Tools (Messages, Channels, Users)                   β”‚
β”‚  └─ Tool Orchestration & Response Aggregation                 β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  Security & Credential Management                              β”‚
β”‚  β”œβ”€ Encrypted Credential Storage                               β”‚
β”‚  β”œβ”€ OAuth2/API Key Management                                 β”‚
β”‚  β”œβ”€ Permission Mapping & Access Control                        β”‚
β”‚  └─ Audit Logging & Security Monitoring                       β”‚
β”œβ”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€
β”‚  External APIs                                                 β”‚
β”‚  β”œβ”€ Google Workspace APIs                                     β”‚
β”‚  β”œβ”€ Atlassian Cloud APIs                                      β”‚
β”‚  └─ Slack Web API                                             β”‚
β””β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”€β”˜

πŸš€ Quick Start

Prerequisites

  • Python 3.11+ (required)
  • Node.js 18+ (for frontend development)
  • PostgreSQL 13+
  • Redis 6+
  • OpenTelemetry-compatible observability backend (Jaeger, Prometheus, etc.)
  • Access to required APIs (Google Workspace, Atlassian, Slack)

Installation

Quick Setup (Recommended)
# Clone the repository
git clone https://github.com/Maascamp/manager-api.git
cd manager-api

# Run automated setup
./setup.sh

# Update configuration
# Edit .env with your API keys and configuration

# Start development environment
make dev
Manual Setup
  1. Clone the repository

    git clone https://github.com/Maascamp/manager-api.git
    cd manager-api
    
  2. Set up Python virtual environment

    # Create virtual environment
    python3 -m venv venv
    
    # Activate virtual environment
    # On macOS/Linux:
    source venv/bin/activate
    # On Windows:
    # venv\Scripts\activate
    
    # Upgrade pip
    pip install --upgrade pip
    
  3. Install dependencies

    # Python backend (required)
    pip install -r requirements.txt
    
    # Frontend dependencies
    cd frontend
    npm install
    cd ..
    
  4. Configure environment

    cp env.example .env
    # Edit .env with your configuration
    
  5. Initialize database

    python -m alembic upgrade head
    
  6. Start the application

    # Start backend
    python -m uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload
    
    # In another terminal, start frontend
    cd frontend
    npm run dev
    

πŸ“‹ Configuration

LLM Provider Setup

Configure your preferred LLM provider in the environment variables:

# OpenAI
OPENAI_API_KEY=your_openai_key
OPENAI_MODEL=gpt-4

# Anthropic
ANTHROPIC_API_KEY=your_anthropic_key
ANTHROPIC_MODEL=claude-3-opus

# Google
GOOGLE_API_KEY=your_google_key
GOOGLE_MODEL=gemini-pro

API Credentials

Set up credentials for each data source:

# Google Workspace
GOOGLE_CLIENT_ID=your_client_id
GOOGLE_CLIENT_SECRET=your_client_secret
GOOGLE_SERVICE_ACCOUNT_KEY=path_to_service_account.json

# Atlassian
ATLASSIAN_API_TOKEN=your_api_token
ATLASSIAN_BASE_URL=https://your-domain.atlassian.net

# Slack
SLACK_BOT_TOKEN=xoxb-your-bot-token
SLACK_APP_TOKEN=xapp-your-app-token

# OpenTelemetry Configuration (Required)
OTEL_SERVICE_NAME=manager-assistant
OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces
OTEL_EXPORTER_PROMETHEUS_ENDPOINT=http://localhost:9090/metrics
OTEL_LOG_LEVEL=INFO

πŸ”§ Development

Project Structure

mgr-api/
β”œβ”€β”€ src/
β”‚   β”œβ”€β”€ core/                    # Core application logic
β”‚   β”‚   β”œβ”€β”€ llm/                # LLM integration
β”‚   β”‚   β”œβ”€β”€ context/            # Context management
β”‚   β”‚   └── evaluation/         # LLM-as-judge system
β”‚   β”œβ”€β”€ mcp_server/             # MCP server implementation
β”‚   β”‚   β”œβ”€β”€ tools/              # API tool implementations
β”‚   β”‚   └── registry/           # Tool registry
β”‚   β”œβ”€β”€ security/               # Security and credential management
β”‚   β”œβ”€β”€ api/                    # REST API endpoints
β”‚   └── observability/          # OpenTelemetry instrumentation
β”œβ”€β”€ frontend/                    # Web interface
β”œβ”€β”€ cli/                        # Command-line interface
β”œβ”€β”€ tests/                      # Test suite
β”œβ”€β”€ docs/                       # Documentation
└── scripts/                    # Utility scripts

Frontend Technology Stack

The frontend is built with modern React technologies:

  • React 18+: Latest React with hooks and concurrent features
  • TypeScript: Type safety and better developer experience
  • Vite: Fast build tool and development server
  • Tailwind CSS: Utility-first CSS framework for styling
  • Zustand: Lightweight state management
  • TanStack Query: Data fetching and caching
  • Shadcn/ui: Modern, accessible UI components
  • Radix UI: Accessible component primitives

Development Setup

  1. Install development dependencies

    # Backend
    pip install -r requirements-dev.txt
    
    # Frontend
    cd frontend
    npm install
    
  2. Run tests

    # Backend tests
    pytest
    
    # Frontend tests
    cd frontend
    npm test
    
  3. Start development servers

    # Backend (terminal 1)
    python manage.py runserver --debug
    
    # Frontend (terminal 2)
    cd frontend
    npm run dev
    

Adding New Data Sources

The MCP server architecture makes it easy to add new data sources:

  1. Create a new tool class in src/mcp_server/tools/
  2. Implement the tool interface with authentication and data access
  3. Register the tool in the tool registry
  4. Update documentation with new capabilities

Example:

class NewDataSourceTool(BaseTool):
    def __init__(self, credentials):
        self.credentials = credentials
    
    def search(self, query, filters=None):
        # Implement data source search
        pass
    
    def get_details(self, item_id):
        # Implement item detail retrieval
        pass

πŸ”’ Security

Credential Management

  • All credentials are encrypted using AES-256
  • Credentials are stored in a secure vault with access controls
  • Automatic credential rotation and renewal
  • Audit logging for all credential access

Data Protection

  • Data minimization: Only access necessary data for queries
  • Configurable data retention policies
  • User consent and data anonymization options
  • Compliance with GDPR, SOC 2, and industry standards

Network Security

  • End-to-end encryption for all communications
  • Network isolation with VPC and firewall configuration
  • API rate limiting and DDoS protection
  • Real-time security monitoring and alerting

πŸ“Š Monitoring & Observability

OpenTelemetry Instrumentation (Required)

The application uses exclusively OpenTelemetry for all observability needs:

Tracing
  • Distributed Tracing: All API calls, LLM requests, and MCP operations are traced
  • Custom Spans: Business logic and LLM operations have custom spans
  • Context Propagation: Trace context maintained across async operations
  • Exporters: Jaeger, Zipkin, or other OTel-compatible backends
Metrics
  • Custom Metrics: Query performance, LLM token usage, system health
  • Prometheus Export: Metrics exported to Prometheus-compatible backends
  • Business Metrics: Query success rates, response times, cost tracking
  • System Metrics: CPU, memory, database performance
Logging
  • Structured Logging: JSON format with OpenTelemetry correlation IDs
  • Log Correlation: Logs linked to traces and metrics
  • Security Events: Audit trail for all operations
  • Performance Tracking: Request/response timing and error tracking

Setup OpenTelemetry

  1. Install OpenTelemetry packages

    pip install opentelemetry-api opentelemetry-sdk opentelemetry-instrumentation-fastapi
    pip install opentelemetry-exporter-jaeger opentelemetry-exporter-prometheus
    
  2. Configure exporters

    # Jaeger for tracing
    OTEL_EXPORTER_JAEGER_ENDPOINT=http://localhost:14268/api/traces
    
    # Prometheus for metrics
    OTEL_EXPORTER_PROMETHEUS_ENDPOINT=http://localhost:9090/metrics
    
  3. Start observability backends

    # Start Jaeger
    docker run -d -p 16686:16686 -p 14268:14268 jaegertracing/all-in-one
    
    # Start Prometheus
    docker run -d -p 9090:9090 prom/prometheus
    

πŸ§ͺ Testing

Test Categories

  • Unit Tests: Individual component testing
  • Integration Tests: API and service integration
  • Security Tests: Penetration testing and vulnerability assessment
  • Performance Tests: Load testing and optimization
  • End-to-End Tests: Complete user workflow testing

Running Tests

# Run all tests
pytest

# Run specific test categories
pytest tests/unit/
pytest tests/integration/
pytest tests/security/

# Run with coverage
pytest --cov=src --cov-report=html

πŸ“š Documentation

  • : Detailed technical specification
  • : REST API reference
  • : Guidelines for LLM agents working on this project
  • : Production deployment instructions
  • : Security best practices and compliance

🀝 Contributing

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

Development Guidelines

  • Follow the coding standards defined in the project
  • Write comprehensive tests for new features
  • Update documentation for any changes
  • Ensure security best practices are followed
  • Maintain backward compatibility when possible

πŸ“„ License

This project is licensed under the MIT License - see the file for details.

πŸ†˜ Support

  • Issues: Report bugs and request features via GitHub Issues
  • Discussions: Join community discussions in GitHub Discussions
  • Security: Report security vulnerabilities privately via security@company.com
  • Documentation: Check the docs/ directory for detailed guides

πŸ—ΊοΈ Roadmap

Current Milestones

  • Milestone 1: Core Foundation βœ…
  • Milestone 2: Google Workspace Integration πŸ”„
  • Milestone 3: Atlassian Integration πŸ“‹
  • Milestone 4: Slack Integration πŸ“‹
  • Milestone 5: Multi-Source Intelligence & Context Management πŸ“‹
  • Milestone 6: LLM-as-Judge Quality System πŸ“‹
  • Milestone 7: User Interface πŸ“‹
  • Milestone 8: Security & Production Readiness πŸ“‹

Future Enhancements

  • Additional data source integrations
  • Advanced analytics and reporting
  • Mobile application
  • Team collaboration features
  • Advanced security features

Status: 🚧 In Development
Version: 0.1.0
Last Updated: 2024-12-19