Mad Cp

MadCP - Modern AI-Driven Code Platform

Piattaforma modulare e agnostica per lo sviluppo software moderno

Documentazione • Quick Start • Architettura • API • Contributing

📋 Indice

• Introduzione
• Caratteristiche Principali
• Architettura
• Quick Start
• Installazione
• Configurazione
• Utilizzo
• API Reference
• Plugin System
• Deployment
• Sviluppo
• Testing
• Documentazione
• Contributing
• Roadmap
• License

🎯 Introduzione

MadCP (Modern AI-Driven Code Platform) è un server MCP avanzato progettato per supportare team di sviluppo con strumenti intelligenti di analisi del codebase, ricerca semantica, generazione automatica di patch e pianificazione assistita da AI.

Scopo

Il server MCP offre una piattaforma modulare e agnostica che:

• 🔍 Analizza il codebase in profondità (parsing, AST, dipendenze, metriche)
• 🧠 Comprende il codice tramite embeddings e ricerca semantica
• 🔧 Suggerisce fix, refactor e genera diff pronti per PR
• 📊 Pianifica automaticamente issue e task basandosi sull'analisi del repository
• 🔌 Si estende tramite un sistema di plugin modulari
• 🌐 Si integra facilmente in qualsiasi workflow (locale, LAN, cloud)

Perché MadCP?

• Riduzione Costi Token: Tecniche avanzate di caching, RAG e retrieval riducono drasticamente il consumo di token LLM
• Multi-linguaggio: Supporto estensibile per Python, JavaScript, TypeScript, Go, Java, Rust e altri
• Developer-Friendly: Web UI completa per configurazione e manutenzione
• Production-Ready: Architettura a microservizi scalabile, con supporto Docker e Kubernetes
• Sicuro: OAuth2/OIDC, RBAC, TLS integrati di default

✨ Caratteristiche Principali

Core Features

🔍 Code Analysis

• Parsing Multi-linguaggio: Tree-sitter per AST accurati
• Dependency Graph: Analisi completa delle dipendenze
• Code Metrics: Complessità ciclomatica, LOC, code smells
• Pattern Detection: Individuazione automatica di anti-pattern

🧠 Semantic Search

• Vector Embeddings: Rappresentazione semantica di codice e documentazione
• Similarity Search: Ricerca per somiglianza concettuale
• Context Retrieval: RAG ottimizzato per domande tecniche
• Smart Chunking: Strategie intelligenti per segmentazione del codice

🔧 AI Assistance

• Fix Suggestions: Suggerimenti automatici per bug e code smell
• Refactoring: Proposte di refactoring basate su best practices
• Diff Generation: Generazione di patch pronte per PR
• Code Review: Assistenza automatica nella code review

📊 Planning & Automation

• Repository Analysis: Analisi completa del progetto
• Issue Generation: Creazione automatica di issue da TODO e problemi
• Task Breakdown: Suddivisione intelligente di task complessi
• Project Insights: Dashboard con metriche e KPI di progetto

🔌 Plugin System

• Modulare: Architettura plugin-based estendibile
• Sandboxed: Esecuzione sicura dei plugin
• Hot Reload: Caricamento dinamico senza restart
• Plugin Registry: Repository centralizzato di plugin

🌐 Web UI

• Dashboard Intuitiva: Interfaccia user-friendly per tutte le funzionalità
• Configuration Management: Gestione configurazioni tramite UI
• Real-time Updates: WebSocket per aggiornamenti in tempo reale
• Analytics: Visualizzazione metriche e statistiche

Non-Functional Features

• ⚡ Alta Performance: Architettura asincrona e caching intelligente
• 📈 Scalabilità: Microservizi scalabili orizzontalmente
• 🔒 Sicurezza: OAuth2, JWT, RBAC, TLS
• 📊 Observability: Prometheus, Grafana, OpenTelemetry
• 🐳 Portabilità: Docker, Kubernetes, bare-metal
• 🛠️ Configurabilità: YAML, environment variables, UI

🏗️ Architettura

MadCP utilizza un'architettura a microservizi per garantire scalabilità, manutenibilità e resilienza.

┌─────────────────────────────────────────────────────────┐
│                  API Gateway (Nginx)                     │
│         Load Balancing • Rate Limiting • TLS             │
└──────────────────────┬──────────────────────────────────┘
                       │
        ┌──────────────┼──────────────┐
        │              │              │
┌───────▼──────┐ ┌────▼─────┐ ┌──────▼───────┐
│ Auth Service │ │Core API  │ │  Web UI      │
│  (Keycloak)  │ │ (FastAPI)│ │ (Next.js)    │
└──────────────┘ └────┬─────┘ └──────────────┘
                      │
        ┌─────────────┼─────────────────┐
        │             │                 │
┌───────▼────────┐ ┌─▼──────────┐ ┌────▼──────────┐
│ Code Analysis  │ │ Embedding  │ │ Planning      │
│   Service      │ │  Service   │ │  Service      │
│ (AST, Parse)   │ │ (Vectors)  │ │ (AI Planning) │
└────────┬───────┘ └─────┬──────┘ └───────┬───────┘
         │               │                 │
┌────────▼───────────────▼─────────────────▼───────┐
│            Plugin Manager Service                 │
│         (Dynamic Plugin Loading)                  │
└────────┬──────────────────────────────────────────┘
         │
┌────────▼──────────────────────────────────────────┐
│                  Data Layer                       │
│  PostgreSQL  │  Qdrant  │  Redis  │  S3/MinIO    │
└───────────────────────────────────────────────────┘

Componenti Principali

Per dettagli completi, vedi Documentazione Architettura.

🚀 Quick Start

Opzione 1: Portainer (Più Facile) 🎯

Hai già Portainer? Deploy con interfaccia web in 5 minuti!

➡️ Vai alla Guida Portainer

Portainer rende il deployment semplicissimo con un'interfaccia grafica - niente command line necessaria!

Opzione 2: Docker Compose (Command Line)

Prerequisiti

• Docker 24.0+ e Docker Compose 2.20+
• Python 3.11+ (per sviluppo locale)
• Node.js 18+ (per Web UI)
• Almeno 4GB RAM disponibili

Installazione Rapida (Docker)

# 1. Clone del repository
git clone https://github.com/yayoboy/MadCP.git
cd MadCP

# 2. Copia il file di configurazione
cp .env.example .env

# 3. Modifica le variabili d'ambiente (opzionale)
nano .env

# 4. Avvia tutti i servizi
docker-compose up -d

# 5. Verifica lo stato dei servizi
docker-compose ps

# 6. Accedi alla Web UI
# http://localhost:3000

Verifica Installazione

# Health check del Core API
curl http://localhost:8000/health

# Verifica servizi
curl http://localhost:8000/api/v1/status

Output atteso:

{
  "status": "healthy",
  "version": "1.0.0",
  "services": {
    "database": "connected",
    "redis": "connected",
    "vector_db": "connected"
  }
}

📦 Installazione

Opzione 1: Docker Compose (Raccomandato)

Vedi Quick Start.

Opzione 2: Installazione Manuale

Backend

# 1. Setup Python environment
cd services/core-api
python -m venv venv
source venv/bin/activate  # Windows: venv\Scripts\activate

# 2. Installa dipendenze
pip install -r requirements.txt

# 3. Setup database
alembic upgrade head

# 4. Avvia il server
uvicorn app.main:app --reload --host 0.0.0.0 --port 8000

Frontend

# 1. Installa dipendenze
cd web-ui
npm install

# 2. Configura environment
cp .env.example .env.local

# 3. Avvia dev server
npm run dev

Database e Redis

# PostgreSQL
docker run -d \
  --name madcp-postgres \
  -e POSTGRES_PASSWORD=madcp_password \
  -e POSTGRES_DB=madcp \
  -p 5432:5432 \
  postgres:15-alpine

# Redis
docker run -d \
  --name madcp-redis \
  -p 6379:6379 \
  redis:7-alpine

# Qdrant (Vector DB)
docker run -d \
  --name madcp-qdrant \
  -p 6333:6333 \
  qdrant/qdrant

Opzione 3: Kubernetes

# 1. Setup namespace
kubectl create namespace madcp

# 2. Deploy con Helm
helm install madcp ./infrastructure/helm/madcp \
  --namespace madcp \
  --values infrastructure/helm/madcp/values-production.yaml

# 3. Verifica deployment
kubectl get pods -n madcp

Vedi Deployment Guide per dettagli completi.

⚙️ Configurazione

File di Configurazione

MadCP supporta configurazione tramite:

1. File YAML: config/default.yaml, config/production.yaml
2. Environment Variables: .env
3. Web UI: Interfaccia di configurazione

Configurazione Base

# config/default.yaml
app:
  name: "MadCP"
  version: "1.0.0"
  environment: "development"
  debug: true

api:
  host: "0.0.0.0"
  port: 8000
  cors_origins:
    - "http://localhost:3000"
  rate_limit: "100/minute"

database:
  url: "postgresql://madcp:password@localhost:5432/madcp"
  pool_size: 10
  max_overflow: 20

redis:
  url: "redis://localhost:6379/0"
  password: null
  max_connections: 50

vector_db:
  provider: "qdrant"
  url: "http://localhost:6333"
  collection_name: "madcp_embeddings"

llm:
  provider: "openai"  # openai, anthropic, local
  api_key: "${OPENAI_API_KEY}"
  model: "gpt-4-turbo-preview"
  max_tokens: 4096
  temperature: 0.7

embeddings:
  provider: "openai"
  model: "text-embedding-3-small"
  dimensions: 1536
  batch_size: 100

plugins:
  enabled: true
  directory: "./plugins"
  auto_reload: true

security:
  oauth2_enabled: true
  jwt_secret: "${JWT_SECRET}"
  jwt_algorithm: "HS256"
  access_token_expire_minutes: 30

observability:
  prometheus_enabled: true
  grafana_enabled: true
  tracing_enabled: true
  log_level: "INFO"

Environment Variables

# .env.example

# Application
APP_ENV=development
DEBUG=true

# Database
POSTGRES_HOST=localhost
POSTGRES_PORT=5432
POSTGRES_DB=madcp
POSTGRES_USER=madcp
POSTGRES_PASSWORD=madcp_secure_password

# Redis
REDIS_HOST=localhost
REDIS_PORT=6379
REDIS_PASSWORD=

# Vector Database
QDRANT_HOST=localhost
QDRANT_PORT=6333

# LLM Providers
OPENAI_API_KEY=sk-your-key-here
ANTHROPIC_API_KEY=your-key-here

# Security
JWT_SECRET=your-super-secret-jwt-key-change-this
OAUTH2_CLIENT_ID=
OAUTH2_CLIENT_SECRET=

# Web UI
NEXT_PUBLIC_API_URL=http://localhost:8000

# Observability
PROMETHEUS_PORT=9090
GRAFANA_PORT=3001

💻 Utilizzo

Via API REST

import requests

# 1. Analizza un repository
response = requests.post(
    "http://localhost:8000/api/v1/analysis/repository",
    json={
        "repository_url": "https://github.com/username/repo",
        "branch": "main",
        "languages": ["python", "javascript"]
    }
)
analysis_id = response.json()["id"]

# 2. Ottieni risultati analisi
results = requests.get(
    f"http://localhost:8000/api/v1/analysis/{analysis_id}"
).json()

# 3. Ricerca semantica
search_results = requests.post(
    "http://localhost:8000/api/v1/search/semantic",
    json={
        "query": "function for database connection pooling",
        "repository_id": results["repository_id"],
        "limit": 10
    }
).json()

# 4. Genera fix per un bug
fix = requests.post(
    "http://localhost:8000/api/v1/assist/fix",
    json={
        "file_path": "src/database.py",
        "issue_description": "Memory leak in connection pool",
        "context": search_results
    }
).json()

Via Web UI

1. Dashboard: Panoramica di tutti i repository analizzati
2. Analyze: Carica e analizza un nuovo repository
3. Search: Ricerca semantica nel codebase
4. Assist: Richiedi fix, refactor o code review
5. Plan: Genera issue e task automaticamente
6. Plugins: Gestisci plugin installati
7. Settings: Configurazione e preferenze

Via CLI (Coming Soon)

# Analizza repository locale
madcp analyze ./my-project

# Ricerca semantica
madcp search "authentication middleware"

# Genera fix
madcp fix --file src/auth.py --issue "SQL injection vulnerability"

📚 API Reference

Endpoints Principali

Analysis API

Search API

Assist API

Planning API

Documentazione API completa: API Reference

OpenAPI/Swagger UI: http://localhost:8000/docs

🔌 Plugin System

Struttura Plugin

# plugins/python/my_plugin.py

from madcp.plugin import Plugin, PluginMetadata

class MyPlugin(Plugin):
    metadata = PluginMetadata(
        name="my-plugin",
        version="1.0.0",
        description="Plugin example",
        author="Your Name",
        dependencies=["tree-sitter-python"]
    )

    def on_load(self):
        """Chiamato quando il plugin viene caricato"""
        self.logger.info("Plugin loaded")

    def analyze_code(self, code: str, language: str):
        """Analisi custom del codice"""
        # Your logic here
        return {"analysis": "result"}

    def on_unload(self):
        """Cleanup quando plugin viene scaricato"""
        pass

Plugin Disponibili

Vedi Plugin Directory per lista completa.

🚢 Deployment

Portainer (Raccomandato) 🎯

Deploy con 1 click tramite interfaccia web!

Portainer rende il deployment di MadCP estremamente semplice e user-friendly:

Quick Deploy

1. Apri Portainer: http://your-server:9000
2. Vai su Stacks → Add Stack
3. Nome: madcp
4. Metodo:

- Repository: https://github.com/yayoboy/MadCP (file: portainer-stack.yml) - Oppure Web Editor: Copia/incolla il contenuto di portainer-stack.yml

1. Configura variabili (nell'interfaccia Portainer):

   POSTGRES_PASSWORD=your-secure-password
   JWT_SECRET_KEY=generate-a-long-secret-key-32-chars-min
   OPENAI_API_KEY=sk-your-openai-key

1. Deploy the stack ✅

Deploy da Template

Usa il template pre-configurato per un setup ancora più rapido:

1. Importa portainer-template.json in Portainer
2. Vai su App Templates → MadCP
3. Clicca Deploy
4. Compila i parametri richiesti
5. Deploy! 🚀

Vantaggi Portainer

• ✅ Interfaccia visuale - No command line necessaria
• ✅ Gestione facile - Start/Stop/Restart con un click
• ✅ Monitoring integrato - Logs, stats, health checks in UI
• ✅ Updates semplici - Aggiornamento immagini con un click
• ✅ Multi-ambiente - Gestisci dev, staging, prod da un'unica UI

📖 Guida completa: Deployment con Portainer

Docker Compose (Development)

docker-compose up -d

Docker Compose (Production)

docker-compose -f docker-compose.prod.yml up -d

Kubernetes + Helm

helm install madcp ./infrastructure/helm/madcp \
  --namespace madcp \
  --values values-production.yaml

Cloud Providers

• AWS: AWS Deployment Guide
• GCP: GCP Deployment Guide
• Azure: Azure Deployment Guide

🛠️ Sviluppo

Setup Ambiente di Sviluppo

# 1. Clone repository
git clone https://github.com/yayoboy/MadCP.git
cd MadCP

# 2. Setup pre-commit hooks
pip install pre-commit
pre-commit install

# 3. Avvia ambiente dev
docker-compose -f docker-compose.dev.yml up -d

# 4. Installa dipendenze
cd services/core-api
pip install -r requirements-dev.txt

# 5. Run tests
pytest

Struttura del Codice

services/core-api/
├── app/
│   ├── __init__.py
│   ├── main.py              # Entry point FastAPI
│   ├── config.py            # Configurazione
│   ├── api/                 # Endpoints API
│   │   ├── v1/
│   │   │   ├── analysis.py
│   │   │   ├── search.py
│   │   │   ├── assist.py
│   │   │   └── planning.py
│   ├── core/                # Business logic
│   ├── models/              # Database models
│   ├── schemas/             # Pydantic schemas
│   ├── services/            # Service layer
│   ├── utils/               # Utilities
│   └── db/                  # Database utilities
├── tests/
├── alembic/                 # DB migrations
├── requirements.txt
└── Dockerfile

Code Style

• Python: Black, isort, flake8, mypy
• JavaScript: ESLint, Prettier
• Commit: Conventional Commits

# Format code
black .
isort .

# Lint
flake8 .
mypy .

# Test
pytest --cov

🧪 Testing

Unit Tests

# Python
pytest tests/unit

# JavaScript
npm run test:unit

Integration Tests

pytest tests/integration

E2E Tests

pytest tests/e2e

Performance Tests

locust -f tests/performance/locustfile.py

Coverage

pytest --cov --cov-report=html

📖 Documentazione

• Architecture - Architettura dettagliata
• API Reference - Documentazione API completa
• Plugin Development - Guida sviluppo plugin
• Deployment - Guide deployment
• Configuration - Riferimento configurazione
• Troubleshooting - Risoluzione problemi
• Security - Best practices sicurezza
• Performance - Ottimizzazione performance

🤝 Contributing

Contributi benvenuti! Vedi CONTRIBUTING.md per linee guida.

Process

1. Fork del repository
2. Crea feature branch (git checkout -b feature/amazing-feature)
3. Commit delle modifiche (git commit -m 'Add amazing feature')
4. Push al branch (git push origin feature/amazing-feature)
5. Apri una Pull Request

Code of Conduct

Vedi CODE_OF_CONDUCT.md.

🗺️ Roadmap

v1.0.0 (Q2 2024) - Foundation ✅

• [x] Core API architecture
• [x] Code analysis service
• [x] Embedding service
• [x] Basic Web UI
• [x] Docker support

v1.1.0 (Q3 2024) - Enhancement

• [ ] Advanced plugin system
• [ ] GitHub/GitLab integration
• [ ] Advanced planning features
• [ ] Performance optimization
• [ ] Comprehensive documentation

v1.2.0 (Q4 2024) - Production Ready

• [ ] Kubernetes support
• [ ] Multi-tenancy
• [ ] Advanced security features
• [ ] Analytics dashboard
• [ ] CLI tool

v2.0.0 (Q1 2025) - Enterprise

• [ ] Enterprise features
• [ ] SaaS offering
• [ ] Advanced AI models
• [ ] Custom model training
• [ ] Enterprise support

📄 License

Questo progetto è rilasciato sotto licenza MIT. Vedi LICENSE per dettagli.

👥 Team

• Lead Developer: @yayoboy

🙏 Acknowledgments

• FastAPI - Framework web moderno
• LangChain - Framework LLM
• Tree-sitter - Parser multi-linguaggio
• Qdrant - Vector database

📞 Supporto

• Issues:
• Discussions:
• Email: support@madcp.dev

Made with ❤️ by the MadCP Team

⬆ Torna all'inizio