freelance-dashboard/docs/MCP_VBA_GUIDE.md

Freelance Dashboard - Guide MCP VBA

Comment utiliser VBA MCP Server pour construire ce projet Excel.

Prerequis

1. VBA MCP Server v0.6.0+ installe
2. Microsoft Excel installe
3. "Trust access to VBA project object model" active dans Excel

Outils MCP Disponibles

Pour Excel

Outil	Usage dans ce projet
get_worksheet_data	Lire donnees des feuilles
set_worksheet_data	Ecrire donnees et formules
list_excel_tables	Lister les Excel Tables
create_excel_table	Creer tables structurees
insert_rows	Ajouter lignes
delete_rows	Supprimer lignes
inject_vba	Injecter macros optionnelles
validate_vba	Valider syntaxe VBA
run_macro	Executer macros
open_in_office	Ouvrir Excel visible

---

Etape 1: Creer le Fichier Excel

Manuel: Ouvrir Excel > Nouveau classeur > Enregistrer comme FreelanceDashboard.xlsx

Emplacement: C:\Users\alexi\Documents\projects\freelance-dashboard\templates\FreelanceDashboard.xlsx

Creer les onglets

Renommer/creer les feuilles:

1. Dashboard
2. Data_Clients
3. Data_Temps
4. Data_Revenus
5. Config

---

Etape 2: Creer les Tables de Donnees

Data_Clients

Utilise set_worksheet_data pour ecrire les donnees:

# En-tetes + donnees
data = [
    ["ClientID", "Nom", "Secteur", "DateDebut"],
    ["CLI001", "Acme Corporation", "Tech", "15/01/2024"],
    ["CLI002", "Tech Solutions", "Tech", "01/03/2024"],
    ["CLI003", "Marketing Pro", "Marketing", "10/06/2024"],
    ["CLI004", "E-Shop Plus", "E-commerce", "22/09/2024"],
    ["CLI005", "Finance Group", "Finance", "05/11/2024"],
]
set_worksheet_data("FreelanceDashboard.xlsx", "Data_Clients", data)

Puis creer la table structuree:

create_excel_table("FreelanceDashboard.xlsx", "Data_Clients", "A1:D6", "tbl_Clients", has_headers=True)

Data_Temps

data = [
    ["Date", "ClientID", "Projet", "Heures", "Description"],
    ["02/01/2025", "CLI001", "Site Web", 3.5, "Maquettes"],
    ["02/01/2025", "CLI002", "API Backend", 6.0, "Endpoints"],
    ["03/01/2025", "CLI001", "Site Web", 4.0, "Integration"],
    ["03/01/2025", "CLI003", "Campagne SEO", 2.5, "Audit"],
    ["06/01/2025", "CLI002", "API Backend", 7.0, "Tests"],
    ["06/01/2025", "CLI004", "Boutique", 5.0, "Setup"],
    ["07/01/2025", "CLI001", "Maintenance", 1.5, "Updates"],
    ["08/01/2025", "CLI003", "Campagne SEO", 3.0, "Keywords"],
    ["08/01/2025", "CLI005", "Dashboard", 4.5, "Design"],
    ["09/01/2025", "CLI002", "App Mobile", 6.5, "Screens"],
]
set_worksheet_data("FreelanceDashboard.xlsx", "Data_Temps", data)
create_excel_table("FreelanceDashboard.xlsx", "Data_Temps", "A1:E11", "tbl_Temps", has_headers=True)

Data_Revenus

data = [
    ["Date", "ClientID", "Montant", "Type"],
    ["15/01/2025", "CLI001", 2500, "Facture"],
    ["20/01/2025", "CLI002", 4200, "Facture"],
    ["25/01/2025", "CLI003", 1800, "Facture"],
    ["28/01/2025", "CLI001", 1000, "Acompte"],
    ["31/01/2025", "CLI004", 3500, "Facture"],
    ["05/02/2025", "CLI002", 2800, "Facture"],
    ["10/02/2025", "CLI005", 1500, "Acompte"],
]
set_worksheet_data("FreelanceDashboard.xlsx", "Data_Revenus", data)
create_excel_table("FreelanceDashboard.xlsx", "Data_Revenus", "A1:D8", "tbl_Revenus", has_headers=True)

---

Etape 3: Creer la Configuration

data = [
    ["Parametre", "Valeur"],
    ["AnneeCourante", 2025],
    ["TauxHoraireDefaut", 75],
    ["DevisePrincipale", "EUR"],
    ["ObjectifMensuel", 10000],
    ["ObjectifHeures", 140],
]
set_worksheet_data("FreelanceDashboard.xlsx", "Config", data)

---

Etape 4: Ecrire les Formules KPIs

Sur l'onglet Dashboard, ecrire les formules:

kpis = [
    ["KPI", "Valeur", "Formule"],
    ["CA Total", "=SUM(tbl_Revenus[Montant])", ""],
    ["Heures Totales", "=SUM(tbl_Temps[Heures])", ""],
    ["Taux Horaire Moyen", "=B2/B3", ""],
    ["Nb Clients", "=COUNTA(tbl_Clients[ClientID])", ""],
]
set_worksheet_data("FreelanceDashboard.xlsx", "Dashboard", kpis, start_cell="A1")

---

Etape 5: VBA Optionnel (Refresh)

Injecter une macro pour rafraichir les donnees:

code = '''
Sub RefreshDashboard()
    ' Rafraichit toutes les connexions et TCD
    Application.CalculateFull

    Dim ws As Worksheet
    For Each ws In ThisWorkbook.Worksheets
        Dim pt As PivotTable
        For Each pt In ws.PivotTables
            pt.RefreshTable
        Next pt
    Next ws

    MsgBox "Dashboard actualise!", vbInformation
End Sub

Sub AutoRefresh()
    ' Appele a l'ouverture du classeur
    RefreshDashboard
End Sub
'''

validate_vba(code, file_type="excel")
inject_vba("FreelanceDashboard.xlsm", "mod_Refresh", code)

---

Commandes Frequentes

Lire les donnees

get_worksheet_data("FreelanceDashboard.xlsx", "Data_Temps")

Ajouter une entree de temps

# Lire donnees existantes, ajouter ligne, reecrire
# Ou utiliser insert_rows
insert_rows("FreelanceDashboard.xlsx", "Data_Temps", position=12, count=1)
set_worksheet_data("FreelanceDashboard.xlsx", "Data_Temps",
    [["10/01/2025", "CLI001", "Nouveau", 2.5, "Test"]],
    start_cell="A12")

Lister les tables

list_excel_tables("FreelanceDashboard.xlsx")

Ouvrir Excel visible

open_in_office("FreelanceDashboard.xlsx")

Executer macro refresh

run_macro("FreelanceDashboard.xlsm", "RefreshDashboard")

---

Ce qui doit etre fait dans Excel UI

Element	Raison
Tableaux Croises Dynamiques	Interface complexe
Graphiques	Design visuel precis
Slicers	Connexion aux TCD
Mise en forme conditionnelle	Regles visuelles
Layout Dashboard	Positionnement precis

---

Workflow Complet

1. Creer fichier Excel vide      → Manuel
2. set_worksheet_data            → Donnees clients
3. set_worksheet_data            → Donnees temps
4. set_worksheet_data            → Donnees revenus
5. create_excel_table (x3)       → Tables structurees
6. set_worksheet_data            → Config
7. set_worksheet_data            → Formules KPIs
8. Creer TCD                     → Excel UI
9. Creer graphiques              → Excel UI
10. Design dashboard             → Excel UI
11. inject_vba                   → Macro refresh (optionnel)

---

Fichiers de Reference

Fichier	Contenu
DATA_MODEL.md	Schema tables + donnees demo
FORMULAS.md	Toutes les formules Excel
PLAN.md	Layout, couleurs, phases