Initial commit: marketplace structure with connectors.json and index.html

2026-07-16 18:49:01 +01:00
commit dedd09d7c7
13 changed files with 1872 additions and 0 deletions
@@ -0,0 +1,262 @@
+# 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.
+
+```json
+{
+  "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.
+
+```json
+{
+  "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:
+
+```json
+// 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:
+  ```bash
+  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`:
+   ```bash
+   python3 scripts/update_hashes.py
+   ```
+4. Fai l'upload sul server con rsync:
+   ```bash
+   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):
+
+```bash
+# 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:
+```bash
+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` |