dguiducci/skald-connectors
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
dedd09d7c7d50a89184a51e3b6a946268b3203fe
skald-connectors/SKALD.md
T

8.8 KiB
Raw Blame History

Skald Connectors Marketplace

Updated: 2026-07-16

Cos'è

Il marketplace è il catalogo dei connector testati per Skald. Ogni connector è un adattatore che permette a Skald di interfacciarsi con un servizio esterno (API, email, calendario, ricerca, messaggistica, ecc.).

Due tipi di connector:

  • mcp_remote — un MCP server già hosted, accessibile via URL (es. Tavily).
  • mcp_local — script Python/Node da eseguire lato client (es. Gmail, Google Calendar).

Struttura directory

connectors/
├── connectors.json          ← INDICE (radice di fiducia unica)
├── index.html               ← Catalogo UI (legge connectors.json via fetch)
├── gmail/                   ← Un connector per cartella
│   ├── connector.json       ← Configurazione tecnica
│   ├── gmail_mcp_server.py  ← Script MCP
│   ├── gmail_oauth_setup.py ← Script setup OAuth
│   ├── requirements.txt     ← Dipendenze Python
│   ├── icon_sm.svg          ← Icona piccola (48×48)
│   └── icon_lg.svg          ← Icona grande (es. preview)
└── tavily/
    ├── connector.json
    ├── icon_sm.png
    └── icon_lg.png

Schema — connectors.json (root)

Questo è l'unico punto di fiducia. Contiene type, scope e gli sha256 dei file di ogni connector. Non ha hash di sé stesso — in futuro potrà essere firmato digitalmente.

{
  "version": 1,
  "connectors": [
    {
      "id": "gmail",
      "name": "Gmail",
      "type": "mcp_local",
      "scope": "user",
      "icon_small": "gmail/icon_sm.svg",
      "icon_large": "gmail/icon_lg.svg",
      "user_description": "Read, send, and manage Gmail emails via OAuth...",
      "requires": ["OAUTH", "PYTHON"],
      "tags": ["email", "mcp", "local", "google"],
      "folder": "gmail",
      "files": [
        {"path": "gmail_mcp_server.py",  "sha256": "a50d4da9621f7a4b092f...", "size": 46772},
        {"path": "gmail_oauth_setup.py", "sha256": "e488acb289c43a3e6d54...", "size": 3627},
        {"path": "icon_lg.svg",          "sha256": "93c8d9c8dae96f0206e5...", "size": 254},
        {"path": "icon_sm.svg",          "sha256": "029d7f5d81de6cf2b17b...", "size": 251},
        {"path": "requirements.txt",     "sha256": "3f659cc5e5f0543f1326...", "size": 82}
      ]
    }
  ]
}

Campi dell'indice

Campo Obbligatorio Descrizione
id ✅ Identificatore unico (kebab-case)
name ✅ Nome visualizzato
type ✅ mcp_remote o mcp_local
scope ✅ global o user
icon_small ✅ Path relativo dalla root del marketplace
icon_large ✅ Path relativo dalla root del marketplace
user_description ✅ Descrizione breve per la UI
requires ✅ Array di enum requisiti
tags ✅ Array di tag per filtraggio
folder ✅ Nome della cartella del connector
files ✅ Array di file con sha256 (NO self-hash)

Schema — connector.json (per cartella)

Configurazione tecnica per l'attivazione del connector.

{
  "id": "gmail",
  "name": "Gmail",
  "version": "1.0.0",
  "type": "mcp_local",
  "scope": "user",
  "launch_command": "python3 gmail_mcp_server.py",
  "transport": "stdio",
  "requires": ["OAUTH", "PYTHON"],
  "tags": ["email", "mcp", "local", "google"],
  "dependencies": [
    "google-api-python-client>=2.150.0",
    "google-auth>=2.35.0",
    "google-auth-oauthlib>=1.2.0"
  ],
  "setup_instructions": [
    "Install dependencies: pip install -r requirements.txt",
    "Create secrets/google_oauth_client.json with {\"client_id\": \"...\", \"client_secret\": \"...\"}",
    "Run: python3 gmail_oauth_setup.py (opens browser for OAuth)",
    "Set GMAIL_CREDS_PATH env var or place token at secrets/gmail_creds.json"
  ],
  "docs": [
    {
      "lang": "en",
      "description": "Full description for human users...",
      "llm_short_description": "One-line description for LLM context..."
    }
  ],
  "auth": {
    "type": "oauth2",
    "provider": "google",
    "scopes": [
      "https://www.googleapis.com/auth/gmail.modify",
      "https://www.googleapis.com/auth/gmail.labels"
    ]
  },
  "mcp_config": {
    "command": "python3",
    "args": ["gmail_mcp_server.py"],
    "env": {
      "GMAIL_CREDS_PATH": "{secrets}/gmail_creds.json"
    }
  },
  "homepage": "https://mail.google.com",
  "icon_small": "icon_sm.svg",
  "icon_large": "icon_lg.svg"
}

Campi del connector.json

Campo Obbligatorio Descrizione
id ✅ Identificatore unico (match con folder name)
name ✅ Nome visualizzato
version ✅ SemVer
type ✅ mcp_remote o mcp_local
scope ✅ global o user
requires ✅ Array di enum requisiti
tags ✅ Array di tag
auth ✅ Oggetto configurazione autenticazione
docs ✅ Array di documentazione multilingua
icon_small ✅ Nome file icona nella cartella locale
icon_large ✅ Nome file icona nella cartella locale
launch_command solo mcp_local Comando per avviare il server MCP
transport solo mcp_local stdio (default)
dependencies consigliato Dipendenze Python/Node
setup_instructions consigliato Passi per configurare il connector
mcp_config solo mcp_local Configurazione per l'MCP client
homepage opzionale URL del servizio

Enum riservati

type (tipo di connector)

Valore Descrizione Esempi
mcp_remote Server MCP hosted, accessibile via URL Tavily, Weather
mcp_local Script da eseguire localmente Gmail, Google Calendar, WhatsApp
script Script standalone (non MCP) (futuro)

scope (ambito di configurazione)

Valore Descrizione Esempi
global Una singola istanza/config per tutto il sistema Tavily, Weather, Google Trends
user Ogni utente ha la propria istanza/autenticazione Gmail, WhatsApp, Google Calendar

requires (prerequisiti)

Valore Descrizione
API_KEY Richiede una chiave API da configurare
OAUTH Richiede autenticazione OAuth (Google, ecc.)
DOCKER Richiede Docker Engine
NODE Richiede Node.js runtime
PYTHON Richiede Python 3
SECRETS_DIR Richiede file di credenziali in secrets/

Campo auth

Struttura che descrive come il connector gestisce l'autenticazione:

// API key in query string
{"type": "api_key", "delivery": "query",  "param": "tavilyApiKey"}

// API key in header
{"type": "api_key", "delivery": "header", "param": "X-API-Key"}

// OAuth2
{"type": "oauth2",  "provider": "google", "scopes": ["...", "..."]}

// Nessuna autenticazione
{"type": "none"}

Convenzioni icone

  • Formato: SVG per icone vettoriali (meglio per retina/zoom), PNG per raster
  • Nome: icon_sm.{svg|png} (small, ~48×48px), icon_lg.{svg|png} (large, ~96×96px)
  • Path: relativo alla cartella del connector
  • Nell'indice la path è {folder}/{filename} (es. gmail/icon_sm.svg)

Integrità file (sha256)

  • Gli hash sha256 sono solo in connectors.json (l'indice)
  • connector.json non contiene hash di sé stesso — è il file manifesto
  • L'indice è l'unica radice di fiducia; in futuro si può firmare digitalmente solo l'indice
  • Sui file locali, per calcolare/aggiornare gli hash: 
    python3 -c "import hashlib; print(hashlib.sha256(open('file.py','rb').read()).hexdigest())"

Workflow locale

  1. Lavora su file nella cartella connectors/
  2. Modifica connectors.json, connector.json, script, icone
  3. Prima del deploy aggiorna gli sha256 in connectors.json: 
    python3 scripts/update_hashes.py
  4. Fai l'upload sul server con rsync: 
    rsync -avz --delete connectors/ dguiducci@skald-server:/var/www/connectors.skaldagent.net/
  5. Verifica su https://connectors.skaldagent.net/

Deploy su server remoto

Il server remoto è:

  • Host: skald-home-server (192.168.1.100 / 145.40.169.107)
  • User: dguiducci
  • Path: /var/www/connectors.skaldagent.net/
  • Proprietario: caddy:caddy
  • Sudo: richiesto per scrivere in /var/www/

Comando di deploy (da eseguire con sudo o con rsync):

# Sync se il server permette rsync via SSH
rsync -avz --delete ./connectors/ dguiducci@skald-server:/var/www/connectors.skaldagent.net/

Dopo il deploy, verificare i permessi:

sudo chown -R caddy:caddy /var/www/connectors.skaldagent.net/
sudo find /var/www/connectors.skaldagent.net/ -type f -exec chmod 644 {} \;

Connector attuali

ID Nome Tipo Scope
tavily Tavily mcp_remote global
gmail Gmail mcp_local user
Reference in New Issue View Git Blame Copy Permalink