CTC4-AZEBAL

HyunjunGil/CTC4-AZEBAL

3.2

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

AZEBAL is an intelligent MCP server designed to streamline Azure error debugging and analysis directly within your IDE.

Tools
2
Resources
0
Prompts
0

AZEBAL - Azure Error Analysis & BreALdown

Python Version FastMCP

AZEBAL is an intelligent MCP (Model Context Protocol) server that provides real-time Azure error debugging and analysis directly within your IDE. It integrates with AI agents to analyze Azure-related errors comprehensively by examining user permissions, source code, and real-time Azure resource status.

🎯 Overview

AZEBAL transforms fragmented Azure debugging approaches into a systematic, AI-powered solution that:

  • Authenticates users via Azure CLI access tokens (Phase 1 Complete ✅)
  • Analyzes Azure errors by combining source code context with real-time resource status (Phase 2 - Planned)
  • Provides actionable debugging insights and solutions directly in your IDE (Phase 2 - Planned)
  • Reduces development time spent on Azure-related troubleshooting

🏗️ Architecture

This project follows a monolithic architecture for rapid MVP development:

  • FastMCP Server: Single entry point for IDE AI agent communication
  • Authentication Module: Azure CLI token-based authentication (Phase 1 Complete ✅)
  • JWT Service: AZEBAL-specific JWT token management (Phase 1 Complete ✅)
  • LLM Engine: Core error analysis using Azure OpenAI (Phase 2 - Planned)
  • Azure API Client: Real-time Azure resource queries (Phase 2 - Planned)
  • Session Management: Redis-based user session storage (Phase 2 - Planned)

📁 Project Structure

azebal/
├── .vscode/                # VSCode configuration
├── docs/                   # Project documentation
│   ├── architecture/       # Detailed architecture docs
│   ├── prd/               # Product Requirements Document
│   └── stories/           # User stories
├── scripts/               # Build and deployment scripts
├── src/                   # Source code
│   ├── __init__.py
│   ├── main.py           # MCP server entry point
│   ├── tools/            # MCP tool definitions
│   │   ├── greeting.py   # Test greeting tool
│   │   └── login.py      # Azure CLI login tool (Phase 1 Complete ✅)
│   ├── core/             # Core business logic
│   │   ├── auth.py       # Azure authentication service (Phase 1 Complete ✅)
│   │   ├── jwt_service.py # JWT token management (Phase 1 Complete ✅)
│   │   ├── config.py     # Configuration management (Phase 1 Complete ✅)
│   │   └── engine.py     # LLM analysis engine (Phase 2 - Planned)
│   ├── services/         # External service integrations
│   │   └── azure_client.py
│   └── utils/            # Utility functions
├── tests/                # Test suite
│   ├── unit/             # Unit tests (>80% coverage target)
│   ├── integration/      # Integration tests
│   ├── e2e/              # End-to-end tests
│   └── fixtures/         # Test data and fixtures
├── requirements.txt      # Python dependencies
├── requirements-dev.txt  # Development dependencies
├── environment.yml       # Conda environment specification
├── environment.template  # Environment variables template
├── pytest.ini           # Pytest configuration
└── README.md

🚀 Quick Start

Prerequisites

  • Python 3.11+
  • Conda (for environment management)
  • Azure CLI (for authentication - Phase 1)
  • Azure Account with appropriate permissions (Phase 1)
  • Redis Server (for session storage - Phase 2)

Installation

  1. Clone the repository

    git clone <repository-url>
cd AZEBAL

  2. Set up Python environment

    # Create conda environment
conda env create -f environment.yml
conda activate azebal

# Or if environment already exists
conda activate azebal
pip install -r requirements.txt

  3. Configure environment

    cp environment.template .env
# Edit .env with your Azure subscription ID and JWT secret key

  4. Set up Azure CLI authentication

    # Login to Azure CLI
az login

# Get your access token (for testing)
az account get-access-token

  5. Run the MCP server

    # Activate conda environment
conda activate azebal

# Run with stdio transport (default)
python run_mcp_server.py

# Or run with SSE/Streamable-HTTP transport
python run_mcp_server_sse.py

Development Setup

  1. Install development dependencies

    conda activate azebal
pip install -r requirements-dev.txt

  2. Run tests

    # Run all tests
pytest

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

# Run specific test categories
pytest -m unit      # Unit tests only
pytest -m integration  # Integration tests only

  3. Code formatting and linting

    # Format code
black src/ tests/

# Check linting
flake8 src/ tests/

# Type checking
mypy src/

🔧 Configuration

Environment Variables

Key configuration variables (see environment.template for complete list):

# Azure Configuration (Phase 1)
AZURE_SUBSCRIPTION_ID=your-azure-subscription-id

# JWT Configuration (Phase 1)
JWT_SECRET_KEY=your-secret-key-change-in-production
JWT_ALGORITHM=HS256
JWT_EXPIRATION_HOURS=24

# Redis Configuration (Phase 2 - Future)
REDIS_HOST=localhost
REDIS_PORT=6379

Azure CLI Setup

  1. Install Azure CLI:

    # Ubuntu/Debian
curl -sL https://aka.ms/InstallAzureCLIDeb | sudo bash

# macOS (using Homebrew)
brew install azure-cli

# Windows (using PowerShell)
Invoke-WebRequest -Uri https://aka.ms/installazurecliwindows -OutFile .\AzureCLI.msi; Start-Process msiexec.exe -Wait -ArgumentList '/I AzureCLI.msi /quiet'

  2. Login to Azure:

    az login

  3. Check Available Subscriptions:

    # List all available subscriptions
az account list --output table

# Show current subscription
az account show

# Get subscription ID only
az account show --query id --output tsv

  4. Set Your Subscription (if needed):

    # Set by subscription ID
az account set --subscription "your-subscription-id"

# Set by subscription name
az account set --subscription "Your Subscription Name"

  5. Get Access Token:

    # Get access token for current subscription
az account get-access-token

# Get access token for specific resource
az account get-access-token --resource https://management.azure.com/

Quick Reference: Azure CLI Commands

# Authentication & Account Management
az login                                    # Login to Azure
az logout                                   # Logout from Azure
az account show                             # Show current account info
az account list --output table             # List all subscriptions
az account set --subscription "sub-id"     # Switch subscription

# Access Tokens
az account get-access-token                # Get access token
az account get-access-token --query expiresOn  # Check token expiration

# Subscription Information
az account show --query "{Name:name, Id:id, State:state, TenantId:tenantId}"
az account show --query id --output tsv    # Get subscription ID only
az account show --query name --output tsv  # Get subscription name only

# Troubleshooting
az --version                               # Check Azure CLI version
az account list --all                      # List all subscriptions (including disabled)
az role assignment list --assignee $(az account show --query user.name --output tsv)

🎮 Usage

AZEBAL supports two distinct transport methods for different use cases. Choose the method that best fits your needs:

📡 Transport Methods

1. stdio Transport (Recommended for IDE Integration)

Best for: Cursor IDE, VSCode, and other IDE integrations Communication: Direct process communication Setup: Simple command-based configuration

2. HTTP Transport (Recommended for Web/Production)

Best for: Web applications, Docker deployments, production environments Communication: HTTP with streamable transport Setup: URL-based configuration

🔌 stdio Transport Setup

Step 1: Start the stdio Server

# Activate conda environment
conda activate azebal

# Navigate to AZEBAL directory
cd /path/to/your/AZEBAL

# Start stdio server
python run_mcp_server.py

Step 2: Configure Cursor IDE

  1. Open Cursor MCP configuration file:

    • macOS/Linux: ~/.cursor/mcp.json
    • Windows: %APPDATA%\Cursor\mcp.json

  2. Add stdio configuration:

    {
  "mcpServers": {
    "azebal": {
      "command": "python",
      "args": ["/path/to/your/AZEBAL/run_mcp_server.py"],
      "cwd": "/path/to/your/AZEBAL"
    }
  }
}

    Important: Replace /path/to/your/AZEBAL with your actual absolute path

Step 3: Test stdio Connection

  1. Restart Cursor IDE
  2. Open any file in Cursor
  3. Start a chat with the AI assistant
  4. Test the connection: 
    Can you use the greeting tool from AZEBAL?

Expected Result: The AI should return "hello" from the greeting function

Step 4: Verify stdio Setup

# Test server creation manually
python -c "from src.server import create_mcp_server; server = create_mcp_server(); print('✅ stdio Server OK')"

# Check if server runs without errors
python run_mcp_server.py
# (Should start and wait for input, press Ctrl+C to stop)

🌐 HTTP Transport Setup

Step 1: Start the HTTP Server

# Activate conda environment
conda activate azebal

# Navigate to AZEBAL directory
cd /path/to/your/AZEBAL

# Start HTTP server
python run_mcp_server_sse.py

Server will start on: http://localhost:8000/sse/

Step 2: Configure Cursor IDE (HTTP Mode)

  1. Open Cursor MCP configuration file:

    • macOS/Linux: ~/.cursor/mcp.json
    • Windows: %APPDATA%\Cursor\mcp.json

  2. Add HTTP configuration:

    {
  "mcpServers": {
    "azebal": {
      "type": "http",
      "url": "http://localhost:8000/sse/",
      "headers": {}
    }
  }
}

Step 3: Test HTTP Connection

  1. Restart Cursor IDE
  2. Open any file in Cursor
  3. Start a chat with the AI assistant
  4. Test the connection: 
    Can you use the greeting tool from AZEBAL?

Expected Result: The AI should return "hello" from the greeting function

Step 4: Verify HTTP Setup

# Test MCP endpoint directly
curl -X POST http://localhost:8000/sse/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'

# Test greeting tool
curl -X POST http://localhost:8000/sse/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "greeting", "arguments": {}}}'

Expected Results:

  • Initialize call should return server capabilities
  • Greeting tool call should return "hello"

🐳 Docker Deployment (HTTP Transport Only)

Quick Start with Docker

# Build Docker image
docker build -t azebal-mcp:latest .

# Run container with HTTP transport
docker run -d --name azebal-mcp-server \
  -p 8000:8000 \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_PORT=8000 \
  --restart unless-stopped \
  azebal-mcp:latest

# Verify container is running
docker ps --filter name=azebal-mcp-server

# Check logs
docker logs azebal-mcp-server

Using Docker Compose (Recommended)

# Start with docker-compose
docker-compose up -d

# Check status
docker-compose ps

# View logs
docker-compose logs -f azebal-mcp

# Stop services
docker-compose down

Test Docker Deployment

# Test MCP endpoint
curl -X POST http://localhost:8000/sse/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'

# Test greeting tool
curl -X POST http://localhost:8000/sse/ \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc": "2.0", "id": 2, "method": "tools/call", "params": {"name": "greeting", "arguments": {}}}'

🛠️ Available Tools

Phase 1 Tools (Complete ✅)

  • greeting: A test tool that returns "hello" (for testing connectivity)
  • login: Authenticate user with Azure CLI access token and get AZEBAL JWT
Login Tool Usage Example
# 1. Get Azure access token
az account get-access-token

# 2. Use the token with AZEBAL login tool
# (This would be called through your IDE MCP client)

Login Tool Response:

{
  "success": true,
  "message": "Login successful",
  "azebal_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9...",
  "user_info": {
    "object_id": "12345678-1234-1234-1234-123456789012",
    "user_principal_name": "user@company.com",
    "tenant_id": "87654321-4321-4321-4321-210987654321",
    "display_name": "John Doe",
    "email": "user@company.com"
  }
}

Phase 2 Tools (Planned)

  • debug_error: Comprehensive Azure error analysis and debugging

🔧 Troubleshooting

stdio Transport Issues

  1. Verify Python Environment:

    conda activate azebal
cd /path/to/AZEBAL
python run_mcp_server.py

  2. Check File Paths:

    • Ensure absolute paths in mcp.json
    • Use forward slashes on Windows
    • Verify cwd points to correct directory

  3. Test Server Creation:

    python -c "from src.server import create_mcp_server; server = create_mcp_server(); print('✅ Server OK')"

HTTP Transport Issues

  1. Verify Server is Running:

    # Check if port 8000 is in use
lsof -i :8000  # macOS/Linux
netstat -an | findstr :8000  # Windows

  2. Test HTTP Endpoint:

    curl -X POST http://localhost:8000/sse/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2024-11-05", "capabilities": {}, "clientInfo": {"name": "test-client", "version": "1.0.0"}}}'

  3. Check Server Logs:

    # For local server
python run_mcp_server_sse.py

# For Docker
docker logs azebal-mcp-server

Azure CLI Issues

  1. Check Azure CLI Installation:

    # Verify Azure CLI is installed
az --version

# Check if logged in
az account show

  2. Subscription Issues:

    # List all available subscriptions
az account list --output table

# Check current subscription
az account show --query "{Name:name, Id:id, State:state}"

# Switch subscription if needed
az account set --subscription "your-subscription-id"

  3. Access Token Issues:

    # Get fresh access token
az account get-access-token

# Check token expiration
az account get-access-token --query expiresOn

# Re-login if token is expired
az login

  4. Permission Issues:

    # Check your role assignments
az role assignment list --assignee $(az account show --query user.name --output tsv)

# Check if you have access to Azure Resource Manager
az account get-access-token --resource https://management.azure.com/

Cursor IDE Issues

  1. Verify Configuration:

    # Check mcp.json exists and is valid JSON
cat ~/.cursor/mcp.json  # macOS/Linux
type %APPDATA%\Cursor\mcp.json  # Windows

  2. Check Cursor Logs:

    • Open Cursor Developer Tools (Cmd+Shift+I on macOS, Ctrl+Shift+I on Windows/Linux)
    • Look for MCP-related error messages in the console

  3. Restart Cursor:

    • Close Cursor completely
    • Restart Cursor IDE
    • Test connection again

Docker Issues

# Check container status
docker ps -a --filter name=azebal-mcp-server

# View container logs
docker logs azebal-mcp-server

# Check container health
docker inspect azebal-mcp-server | grep -A 5 "Health"

# Restart container
docker restart azebal-mcp-server

# Remove and recreate container
docker stop azebal-mcp-server && docker rm azebal-mcp-server
docker run -d --name azebal-mcp-server -p 8000:8000 azebal-mcp:latest

🧪 Testing

The project follows a test pyramid approach:

  • Unit Tests: Fast, isolated component tests (>80% coverage)
  • Integration Tests: Component interaction verification
  • E2E Tests: Complete workflow testing
# Run test suite with coverage
pytest --cov=src --cov-report=term-missing

# Run specific test types
pytest tests/unit/          # Unit tests
pytest tests/integration/   # Integration tests  
pytest tests/e2e/          # End-to-end tests

📚 Documentation

  • - Complete project requirements and scope
  • - Detailed technical architecture
  • - Individual architecture components

🛠️ Development

Code Standards

  • Style: Black formatting, Flake8 linting
  • Type Hints: 100% type annotation coverage required
  • Testing: Pytest with >80% coverage for core logic
  • Documentation: Comprehensive docstrings and README updates

Epic Development Plan

Epic 1: Azure CLI Token-based Authentication (Complete ✅)

  • ✅ Implement Azure CLI access token authentication
  • ✅ Create AZEBAL JWT token management
  • ✅ Validate Azure API connectivity
  • ✅ Establish secure user session foundation

Epic 2: Real-time Error Analysis Engine Implementation (In Progress)

  • 🔄 Develop comprehensive error analysis capabilities
  • 🔄 Integrate Azure resource status queries
  • 🔄 Implement LLM-powered solution generation
  • 🔄 Add Redis session management

🤝 Contributing

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

Ensure all tests pass and code follows the established standards before submitting.

📄 License

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

🙋 Support

For questions or support:

  • Check the
  • Review
  • Create a if needed

Built with ❤️ using the BMad methodology for AI-driven development