Server MCP

Server Model Context Protocol per Mapfolio - Consente agli assistenti IA di interagire con i dati di Mapfolio

Panoramica

Il Server MCP Mapfolio è un server Model Context Protocol (MCP) che consente agli assistenti IA e ad altri client compatibili MCP di interagire con i dati e le operazioni di Mapfolio. Fornisce accesso programmatico a aziende, progetti, utenti, profili LinkedIn e funzioni amministrative.

Cos'è MCP?

Model Context Protocol (MCP) è un protocollo aperto che consente agli assistenti IA di accedere in modo sicuro a fonti di dati e strumenti esterni. I server MCP espongono capacità tramite un'interfaccia standardizzata, consentendo agli assistenti IA di:

  • Interrogare e recuperare dati
  • Eseguire operazioni
  • Accedere a risorse
  • Integrarsi con sistemi esterni

Funzionalità

Il Server MCP Mapfolio fornisce funzionalità complete:

Dati Aziendali

  • Cercare aziende con filtri avanzati
  • Ottenere dettagli aziendali per ID
  • Recuperare aziende per cantone e lettera iniziale
  • Ottenere aziende casuali per campionamento
  • Accedere alle statistiche di visite aziendali

Gestione Progetti

  • Creare e gestire progetti
  • Elencare e filtrare progetti utente
  • Aggiornare dettagli progetto
  • Eliminare progetti
  • Aggiungere e rimuovere aziende dai progetti

Profili Utente

  • Ottenere informazioni profilo utente
  • Aggiornare impostazioni profilo
  • Elencare progetti utente
  • Gestire chiavi API

Integrazione LinkedIn

  • Ottenere dati profilo LinkedIn
  • Cercare profili LinkedIn
  • Accedere alle informazioni di connessione
  • Visualizzare cronologia versioni profilo
  • Ottenere dati aziendali LinkedIn

Operazioni Amministrative

  • Elencare tutti gli utenti (solo admin)
  • Creare nuovi utenti (solo admin)
  • Gestire chiavi API (solo admin)
  • Accedere alle statistiche dashboard admin

Statistiche

  • Ottenere statistiche aziendali aggregate
  • Visualizzare conteggi a livello di cantone
  • Accedere a conteggi basati su lettere
  • Ottenere statistiche combinazioni due lettere

Installazione

Prerequisiti

  • Node.js >= 20.0.0
  • npm >= 10.0.0
  • Accesso all'istanza Supabase Mapfolio

Configurazione

  1. Installare dipendenze:
cd mcp-server
npm install
  1. Configurare variabili d'ambiente:
cp .env.example .env

Modificare .env e configurare:

# URL API Mapfolio (predefinito: https://mapfolio.app)
MAPFOLIO_API_URL=https://mapfolio.app

# Tipo trasporto: 'stdio' (predefinito) o 'http' per accesso remoto
MCP_TRANSPORT=stdio

# Porta HTTP (usata solo quando MCP_TRANSPORT=http)
MCP_HTTP_PORT=3001

# Opzionale: Autenticazione predefinita (può essere fornita via contesto MCP o intestazioni HTTP)
MAPFOLIO_API_KEY=mapf_your_api_key_here
MAPFOLIO_JWT_TOKEN=your-jwt-token-here
  1. Compilare il server:
npm run build

Utilizzo

Eseguire il Server

Sviluppo Locale (trasporto stdio)

Il server MCP utilizza il trasporto stdio per impostazione predefinita (protocollo MCP standard):

npm start

Per sviluppo con ricaricamento automatico:

npm run dev

Trasporto HTTP (per accesso remoto)

Per eseguire il server con trasporto HTTP per test locali:

MCP_TRANSPORT=http MCP_HTTP_PORT=3001 npm start

Questo avvia un server HTTP sulla porta 3001 che accetta richieste JSON-RPC 2.0 tramite HTTP POST.

Deployment Vercel (Accesso Remoto)

Il server MCP è automaticamente disponibile via HTTP quando distribuito su Vercel:

  • Endpoint: https://your-app.vercel.app/api/mcp
  • Protocollo: JSON-RPC 2.0 tramite HTTP POST
  • Autenticazione: Tramite intestazione X-API-Key o intestazione Authorization: Bearer <token>

Esempio richiesta:

curl -X POST https://your-app.vercel.app/api/mcp \
  -H "Content-Type: application/json" \
  -H "X-API-Key: mapf_your_api_key" \
  -d '{
    "jsonrpc": "2.0",
    "method": "tools/list",
    "id": 1
  }'

Configurazione Client MCP

Claude Desktop

Deployment locale:

{
  "mcpServers": {
    "mapfolio": {
      "command": "node",
      "args": ["/path/to/mapfolio/mcp-server/dist/index.js"],
      "env": {
        "MAPFOLIO_API_URL": "https://mapfolio.app",
        "MAPFOLIO_API_KEY": "mapf_your_api_key_here"
      }
    }
  }
}

Cursor

Configurare tramite impostazioni MCP:

  • Comando: node
  • Args: ["/path/to/mapfolio/mcp-server/dist/index.js"]
  • Variabili d'ambiente:
    • MAPFOLIO_API_URL: https://mapfolio.app
    • MAPFOLIO_API_KEY: La tua chiave API (opzionale)

Autenticazione

Il server supporta due metodi di autenticazione:

Autenticazione Chiave API

Le chiavi API sono prefissate con mapf_ e possono:

  • Essere impostate tramite variabile d'ambiente MAPFOLIO_API_KEY
  • Essere passate per richiesta tramite parametro apiKey nelle chiamate strumento

Autenticazione Token JWT

I token JWT Supabase possono:

  • Essere impostati tramite variabile d'ambiente MAPFOLIO_JWT_TOKEN
  • Essere passati per richiesta tramite parametro jwtToken nelle chiamate strumento

Priorità Autenticazione

  1. Trasporto HTTP: Le intestazioni (X-API-Key o Authorization) hanno priorità
  2. Credenziali per richiesta (apiKey o jwtToken negli argomenti strumento)
  3. Variabili d'ambiente (MAPFOLIO_API_KEY o MAPFOLIO_JWT_TOKEN)

Autenticazione Trasporto HTTP

Quando si utilizza l'endpoint HTTP (/api/mcp), l'autenticazione è fornita tramite intestazioni HTTP:

  • Chiave API: X-API-Key: mapf_your_api_key
  • Token JWT: Authorization: Bearer your_jwt_token

Strumenti Disponibili

Il server fornisce 30+ strumenti in 6 categorie:

Strumenti Aziende

  • search_companies - Cercare con filtri
  • get_company - Ottenere azienda per ID
  • get_companies_by_canton_letter - Ottenere per cantone e lettera
  • get_random_companies - Ottenere campioni casuali
  • get_company_visits - Ottenere statistiche visite

Strumenti Progetti

  • create_project - Creare nuovo progetto
  • list_projects - Elencare progetti utente
  • get_project - Ottenere dettagli progetto
  • update_project - Aggiornare progetto
  • delete_project - Eliminare progetto
  • add_companies_to_project - Aggiungere aziende
  • remove_companies_from_project - Rimuovere aziende

Strumenti Utente

  • get_user_profile - Ottenere profilo
  • update_user_profile - Aggiornare profilo
  • get_user_projects - Elencare progetti
  • get_user_api_keys - Elencare chiavi API

Strumenti LinkedIn

  • get_linkedin_profile - Ottenere profilo
  • search_linkedin_profiles - Cercare profili
  • get_linkedin_connections - Ottenere connessioni
  • get_linkedin_profile_versions - Ottenere cronologia versioni
  • get_linkedin_companies - Ottenere dati aziendali

Strumenti Admin (Solo Admin)

  • list_all_users - Elencare tutti gli utenti
  • create_user - Creare utente
  • get_user_details - Ottenere dettagli utente
  • list_api_keys - Elencare tutte le chiavi API
  • create_api_key - Creare chiave API
  • revoke_api_key - Revocare chiave API
  • get_admin_stats - Ottenere statistiche admin

Strumenti Statistiche

  • get_company_stats - Ottenere statistiche aggregate
  • get_canton_counts - Ottenere conteggi cantoni
  • get_letter_counts - Ottenere conteggi lettere
  • get_two_letter_counts - Ottenere conteggi due lettere

Risorse

Il server fornisce accesso basato su risorse:

  • mapfolio://company/{id} - Dati azienda
  • mapfolio://project/{id} - Dati progetto
  • mapfolio://user/{id} - Profilo utente
  • mapfolio://linkedin-profile/{id} - Profilo LinkedIn

Le risorse possono includere autenticazione tramite parametri query:

  • mapfolio://company/{id}?apiKey=mapf_...
  • mapfolio://company/{id}?jwtToken=...

Esempio di Utilizzo

Cercare Aziende

{
  "tool": "search_companies",
  "arguments": {
    "query": "technology",
    "cantons": ["ZH", "BE"],
    "page": 1,
    "limit": 20
  }
}

Creare Progetto

{
  "tool": "create_project",
  "arguments": {
    "name": "Tech Companies Zurich",
    "searchType": "company",
    "searchQuery": "technology",
    "isPublic": false
  }
}

Ottenere Dettagli Azienda

{
  "tool": "get_company",
  "arguments": {
    "companyId": "company-uuid-here"
  }
}

Gestione Errori

Tutti gli strumenti restituiscono errori in un formato coerente:

{
  "error": "Messaggio di errore"
}

Scenari di errore comuni:

  • 401 Non Autorizzato: Autenticazione non valida o mancante
  • 403 Vietato: Permessi insufficienti
  • 404 Non Trovato: Risorsa non trovata
  • 500 Errore Interno del Server: Errore lato server

Architettura Solo API

Il server MCP utilizza richieste HTTP a mapfolio.app invece di accesso diretto al database. Ciò significa:

  • ✅ Nessuna credenziale Supabase necessaria - Funziona solo con URL API e chiave API
  • ✅ Deployment Vercel facile - Distribuire come funzione serverless
  • ✅ Sicuro - Tutte le richieste passano attraverso l'API Mapfolio con autenticazione
  • ✅ Scalabile - Beneficia della limitazione della velocità e della cache dell'API Mapfolio

Attualmente Disponibile via API

  • ✅ Ricerca e recupero aziende
  • ✅ Statistiche aziendali (conteggi cantoni, conteggi lettere)
  • ✅ Aziende casuali
  • ✅ Visite aziendali

In Arrivo (Richiede Endpoint API)

  • ⏳ Gestione progetti (creare, elencare, aggiornare, eliminare)
  • ⏳ Gestione profili utente
  • ⏳ Accesso profili LinkedIn
  • ⏳ Operazioni amministrative

Queste funzionalità restituiranno messaggi di errore utili fino a quando gli endpoint API non saranno creati.

Considerazioni di Sicurezza

  1. Chiavi API: Archiviare in modo sicuro, non committare mai nel controllo versione
  2. Token JWT: I token scadono, gestire l'aggiornamento appropriatamente
  3. Limitazione Velocità API: Rispetta i limiti di velocità dell'API Mapfolio
  4. Solo HTTPS: Utilizzare sempre HTTPS per richieste API
  5. Operazioni Admin: Richiedono autenticazione admin esplicita (quando gli endpoint sono disponibili)

Sviluppo

Verifica Tipo

npm run type-check

Compilazione

npm run build

Modalità Sviluppo

npm run dev

Documentazione

Per documentazione completa, consultare il README Server MCP.

Supporto

Per problemi o domande:

Licenza

MIT