dcl-mcp — il MCP del DataCivicLab

Server MCP unico per partecipare all'ecosistema del Lab: contesto org-wide, GitHub Discussions e query read-only sui dati pubblici.

pip install "lab-connectors[mcp,duckdb] @ git+https://github.com/dataciviclab/lab-connectors.git"
pip install "dcl-mcp @ git+https://github.com/dataciviclab/dcl-mcp.git"

Cosa espone

Un solo server, nome dataciviclab — 15 tool in tre famiglie:

Flusso tipico (onboarding)

find("rifiuti urbani")            # scopri dataset/analisi/repo
  → explore("ispra_ru_base")      # card: description, anni, colonne,
                                  # clean_rows, marts, gcs_path, query_hint
  → gcs_query(slug=…, sql=…)      # SELECT o WITH…SELECT su `_data`,
                                  # layer=mart per le tabelle mart
  → find(…, include_github=true)  # issue/PR aperte + discussioni open del tema
  → github_get_discussion / _comments
  → github_list_discussion_categories → github_create_discussion

Routing tra MCP del Lab

• dcl-mcp (questo) — org-wide: dove cerco, cosa è successo, come partecipo, dati pubblicati

• toolkit — repo locale: pipeline, contratti, SQL su raw/clean/mart del workspace

• source-observatory — scouting fonti e inventory

Related MCP server: MCPipe Toolchain

Configurazione

{
  "mcpServers": {
    "dataciviclab": {
      "command": "dcl-mcp"
    }
  }
}

Note di design

• Context legge da remoto gli artefatti prodotti dalla CI di agent-context-builder sul branch context (raw.githubusercontent, cache TTL 120s). Nessuna checkout locale richiesta. explore sulle card dataset espone anche description, periodo (year_min/year_max), clean_rows, lista marts (da mart_refs), colonne compatte (name/type/role), gcs_path e query_hint pronto.

• clean_rows è il conteggio dell'ultimo snapshot clean pubblicato dal producer: non è garantito sia la serie completa. Per numeri citabili usa query_hint (count(*)) via gcs_query.

• GCS è read-only: solo bucket dataciviclab-clean e dataciviclab-mart, una sola istruzione per chiamata (SELECT o WITH…SELECT, niente DML/PRAGMA), limite 500 righe (clamp dichiarato). La query deve referenziare la tabella _data (view sul parquet). Per i mart usa layer=mart e lo slug dataset__table (in marts/ marts_hint della card, o dal registry del repo produttore).

• Ref tipizzati: in caso di collisione di slug (es. repo e analysis con lo stesso nome) explore("analysis:slug") forza il tipo; senza prefisso l'ordine è dataset → repo → domain → source → analysis.

• I nomi dei tool sono contratti cross-repo (skill, docs, config utente): non vanno cambiati senza migrazione.

Sviluppo

pip install -e ".[dev]"
pytest tests/ -q -m "not smoke"
ruff check src/ tests/
mypy src/dcl_mcp/

Storia: questo server nasce dalla migrazione di dataciviclab-context (ACB) e github-discussions (lab-connectors) + il nuovo gcs_query, modellato su tre passate di audit con agenti newcomer. Il builder degli artefatti resta in ACB; le librerie condivise in lab-connectors.

Licenza

MIT — vedi LICENSE.