# MCP Integration — Guida BALDART per i consumer

Questo documento spiega **quando** un agent/skill BALDART deve appoggiarsi a un Model Context Protocol (MCP) server, **quali** MCP sono raccomandati per i casi d'uso più comuni, e **come** dichiarare la dipendenza MCP nel body dell'agent in modo che il consumer sappia subito cosa configurare.

> **Scope di questa release**: convenzione testuale, **zero nuove chiavi config** in `baldart.config.yml`. Le chiavi `mcp.*` (es. `mcp.required: []` / `mcp.optional: []`) entreranno solo se e quando una skill concreta dovrà gatearne il comportamento, in una release dedicata con propagazione end-to-end completa (regola di [schema-change propagation](../docs/PROJECT-CONFIGURATION.md)).

---

## 1. Quando usare un MCP

Tre opzioni per integrare un sistema esterno in un agent BALDART. Scegli il più semplice che risolve il problema:

| Opzione | Quando ha senso | Costi/limiti |
|---|---|---|
| **MCP server** | Il sistema è **bidirezionale**, ha molte operazioni discrete (search, get, mutate), serve a **molti agent diversi**, o richiede **stato di sessione** (browser, DB). | Setup nel consumer (configurazione MCP), dipendenza esplicita, esposizione dei dati al modello. |
| **Script CLI / Bash** | È un'azione **one-shot** o **idempotente** (build, test, git, lint, deploy), output testuale ben definito, niente stato di sessione. | Niente — è la baseline. Preferibile quando funziona. |
| **API call diretta (fetch/curl)** | Serve **un'unica chiamata** verso un endpoint REST/GraphQL pubblico o autenticato via env var, **non serve a più agent**. | Risposta opaca al framework (non recuperabile per altri agent), parsing manuale, niente cache strutturata. |

**Regola pratica**: se la stessa integrazione tornerà utile a **2+ agent o skill**, è un MCP. Se è un'esecuzione una-tantum da una singola skill, è uno script CLI o un fetch.

---

## 2. Catalogo MCP raccomandati per i casi d'uso comuni

Non è un'imposizione: BALDART non installa MCP, non li valida, non li richiede. È una lista curata di MCP che hanno senso nei deployment dove BALDART è già in uso.

### Browser automation
- **Playwright MCP** (`@modelcontextprotocol/server-playwright`) — usato da [bug](../.claude/skills/bug/SKILL.md) e [webapp-testing](../.claude/skills/webapp-testing/SKILL.md) per cattura visiva, network, console.

### Code knowledge graph (Graphify)
- **Graphify** (`pipx install graphifyy` → CLI `graphify` + MCP server `graphify-mcp`) — code knowledge graph (tree-sitter, locale/offline, Leiden nativo). Gatato da `features.has_code_graph`. Usato da [codebase-architect](../.claude/agents/codebase-architect.md) e dalle skill di esplorazione per query **strutturali/relazionali** (`graphify query`/`path`/`explain`/`affected`), e dal layer wiki (`wiki-curator`, `/capture`, routine `doc-graph-align`) che si alimenta del `GRAPH_REPORT.md` nativo. **CLI-first** (sempre disponibile post-install); l'MCP `graphify-mcp` è opt-in (`graph.register_mcp`, best-effort `claude mcp add`). Fallback: degrada a LSP→Grep→Git. Vedi [code-graph-protocol.md](../agents/code-graph-protocol.md) e [CODE-GRAPH-LAYER.md](CODE-GRAPH-LAYER.md).

### Database
- **Firebase MCP** (`@modelcontextprotocol/server-firebase` — già integrato come plugin BALDART quando `stack.database.primary` è Firestore) — ispezione documenti, query collection, transazioni.
- **Postgres MCP** (`@modelcontextprotocol/server-postgres`) — per stack SQL.

### Issue tracker / project management
- **GitHub MCP** (`@modelcontextprotocol/server-github`) o **`gh` CLI** — issue triage, PR review, gist creation. Per BALDART consigliamo `gh` (è una CLI già universale), MCP solo se servono molte mutazioni in pipeline.
- **Linear MCP**, **Jira MCP** — disponibili nella registry ufficiale Anthropic per chi usa quei ticketing system.

### Design tool
- **Figma MCP** — usato da agent di design / UI per estrarre token, screenshot, asset.

### Observability
- **Sentry MCP** — già disponibile in BALDART come [sentry plugin](../../CLAUDE.md). Per analisi error → root cause.

### Communication
- **Slack MCP**, **Gmail MCP** — disponibili nel marketplace MCP. Usali solo se l'agent deve davvero comunicare verso umani (es. post-mortem auto-pubblicato).

**Anti-pattern**: NON installare MCP "perché esistono". Ogni MCP aggiunge tool al system prompt del modello, consuma context, e crea dipendenze infrastrutturali nel consumer. Il pattern BALDART è "tanti agent specializzati, pochi MCP universalmente utili".

---

## 3. La convenzione `## MCP dependencies` (per author di agent/skill BALDART)

Ogni agent o skill BALDART che usa MCP deve dichiararlo esplicitamente nel body, in una sezione dedicata. Questo permette:
- al **consumer** di sapere cosa configurare (e cosa succede se non lo configura);
- al `baldart doctor` futuro di leggere queste sezioni e verificare gli MCP `required`;
- ad altri agent di sapere se invocare questo agent è "free" o richiede setup.

### Struttura

Subito dopo la sezione `## Project Context` (o, in mancanza, subito dopo il frontmatter e l'intro):

```markdown
## MCP dependencies

**Required** (skill/agent rifiuta o degrada visibilmente senza questi MCP):
- `mcp__<server>__<tool>` — cosa serve, perché.

**Optional** (l'agent ne approfitta se disponibile, ma ha un fallback):
- `mcp__<server>__<tool>` — cosa offre in più, qual è il fallback.

**None** (per skill senza MCP — utile dichiararlo esplicitamente):
- This skill uses no MCP servers. <breve nota se rilevante>
```

### Regole

1. **Sii specifico**: cita il prefisso del tool (`mcp__playwright__browser_navigate`), non il "concetto" (`Playwright MCP`). Aiuta il consumer a fare grep.
2. **Required vs Optional**: required = la skill non può completare il proprio task senza il MCP (o degrada gravemente). Optional = la skill ha un fallback funzionante.
3. **Fallback espliciti**: per ogni `Optional`, descrivi il fallback in una frase ("se MCP unavailable, usa `rg` su `docs/` per trovare pattern noti").
4. **Niente nuovo schema in `baldart.config.yml`**: non aggiungere `mcp.required` o `mcp.optional` nel config — è solo convenzione testuale finché non c'è una skill che ha bisogno di gatearne il comportamento a runtime.
5. **Aggiorna la dichiarazione quando la dipendenza cambia**: se rimuovi un MCP dall'agent, rimuovi la riga; se aggiungi un fallback Grep e l'MCP diventa optional, sposta la riga.

### Esempi nel framework corrente

Vedi le seguenti dichiarazioni per pattern di riferimento:
- [framework/.claude/agents/codebase-architect.md](../.claude/agents/codebase-architect.md) — `## MCP dependencies` con Graphify (code graph) + LSP-related optional.
- [framework/.claude/skills/bug/SKILL.md](../.claude/skills/bug/SKILL.md) — Playwright required per UI bug, Firestore optional.
- [framework/.claude/skills/playwright-skill/SKILL.md](../.claude/skills/playwright-skill/SKILL.md) — esempio di sezione "None" (la skill usa Playwright Test CLI, non MCP).

---

## 4. FAQ per il consumer

**D: BALDART installa gli MCP per me?**
R: No. BALDART distribuisce agent e skill che eventualmente li **usano**. L'installazione e configurazione MCP è responsabilità del consumer (di solito via `.mcp.json` o `.claude/settings.json`). Vedi la [documentazione Claude Code](https://docs.claude.com) per il setup MCP.

**D: Cosa succede se invoco un agent che richiede un MCP non configurato?**
R: Dipende da come l'agent è stato scritto. Gli agent BALDART che seguono il pattern raccomandato fanno **graceful degrade** (riportano il missing MCP e provano un fallback documentato). Quelli che dichiarano un MCP come **Required** dovrebbero rifiutare visibilmente di proseguire — ma oggi BALDART non enforza questa policy in modo automatico. Il `baldart doctor` futuro potrà controllarla.

**D: Posso aggiungere un MCP custom non nella lista del § 2?**
R: Sì, e se diventa utile a più agent valuta una PR upstream a BALDART per aggiungerlo al catalogo. Vedi [MAINTAINING.md](../../MAINTAINING.md) per il workflow di contribuzione.

**D: La mia organizzazione ha un sistema interno (ticketing, docs, monitoring) — devo per forza esporlo via MCP?**
R: Non per forza. Se l'integrazione serve a **uno** script una tantum, una semplice fetch è meglio. Se serve a 2+ agent BALDART o se vuoi che gli agent possano "scoprire" dati senza che tu glieli passi manualmente, allora vale la pena un MCP custom.

---

## 5. Cosa cambia per BALDART nelle prossime release

Roadmap (vedi piano [gap-analysis vs. large codebases](../../.claude/plans/voglio-che-studi-questo-fluttering-nova.md)):

- **Adesso** (questa release): convenzione testuale `## MCP dependencies`, doc + 3 agent/skill aggiornati come reference.
- **Prossima release MINOR** (se serve): introduzione di una skill che richiede gating runtime su MCP → in quella release sarà propagata la chiave `mcp.required/optional` end-to-end (template + configure + doctor + CHANGELOG), seguendo la regola di schema-change propagation.
- **Routine `mcp-check`** (opzionale, T-level): controllo settimanale che ogni MCP `Required` dichiarato nel framework abbia un endpoint sano nel consumer.

Finché la chiave config non esiste, la convenzione testuale **è** il contratto.
