# MCP Servers Workspace

Repository per server MCP locali (Node.js/TypeScript), skill operative e tooling di supporto.
Questo README e' la guida principale di installazione, configurazione e bootstrap.

## 1) Contenuto repository

Server MCP inclusi:
- `cf-node`
- `docs-node`
- `git-node`
- `linter-node`
- `mantis-node`
- `office-node`
- `playwright-node`
- `projectfs-node`
- `sql-node`

Supporto operativo:
- `skills/`
- `docs/` (governance, milestone completate, backlog)
- `setup.ps1` / `setup.sh` (bootstrap dipendenze + build)
- `genera_mcp_json.ps1` / `genera_mcp_json.sh` (generatori config MCP)

Riferimenti permanenti:
- `AGENTS.md`
- `docs/mcp-skills-agents-development-guide.md`

## 2) Prerequisiti

Minimi:
- Node.js **LTS 24.x** installato (target standard di questo workspace)
- npm disponibile
- Git installato (raccomandato per `git-node`)

Verifica:

```bash
node -v
npm -v
```

Windows:
- usare path assoluto a `node.exe` nelle config client e' piu robusto
- esempio tipico: `C:\Program Files\nodejs\node.exe`

### 2.1) Verifica e gestione versione Node.js (Windows + Ubuntu)

L'obiettivo e' avere `node` in versione `24.x` (LTS) sia in locale sia in ambienti remoti.

Controllo versione attuale:

```bash
node -v
npm -v
```

Output atteso per Node:
- `v24.x.y` (qualsiasi patch `x.y`)

Se vedi `v22.x` o altra major, aggiorna come sotto.

#### Windows (winget)

Verifica pacchetto disponibile:

```powershell
winget search OpenJS.NodeJS.LTS
```

Installazione/upgrade LTS:

```powershell
winget install --id OpenJS.NodeJS.LTS -e --source winget
```

Reinstall pulita (disinstalla + reinstalla LTS):

```powershell
winget uninstall --id OpenJS.NodeJS.LTS -e
winget install --id OpenJS.NodeJS.LTS -e --source winget
```

Verifica percorso risolto:

```powershell
Get-Command node | Select-Object Source, Version, Name
```

Nota:
- dopo upgrade/reinstall, chiudi e riapri terminale/IDE prima di rieseguire `node -v`.

#### Ubuntu

Per avere Node 24 LTS in modo affidabile usa repository NodeSource.

Rimozione versioni distro precedenti (opzionale ma consigliata in caso di mismatch):

```bash
sudo apt remove -y nodejs npm
sudo apt autoremove -y
```

Installazione Node 24 LTS:

```bash
sudo apt update
sudo apt install -y ca-certificates curl gnupg
curl -fsSL https://deb.nodesource.com/setup_24.x | sudo -E bash -
sudo apt install -y nodejs
```

Verifica finale:

```bash
node -v
npm -v
which node
```

Nota:
- se usi VS Code Remote/WSL/SSH, esegui questi comandi **nel sistema remoto** dove girano i server MCP.

## 3) Setup rapido (workspace)

Gli script setup lavorano sulle cartelle di primo livello con `package.json`.

Cosa fanno:
- `npm install` (o `npm ci` se richiesto e lockfile presente)
- `npm run build --if-present` (se build non disabilitata)
- opzionale install browser Playwright (`chromium`)
- opzionale `npm audit fix` (solo opt-in)

Cosa NON fanno:
- non aggiornano npm globalmente
- non eseguono `npm audit fix` di default

### Windows PowerShell

```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1
```

Opzioni:

```powershell
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -UseCI
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -SkipBuild
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -ContinueOnError
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -InstallPlaywright
powershell -ExecutionPolicy Bypass -File .\setup.ps1 -AuditFix
```

### Linux / macOS

```bash
chmod +x setup.sh
./setup.sh
```

Opzioni:

```bash
./setup.sh --ci
./setup.sh --skip-build
./setup.sh --continue-on-error
./setup.sh --install-playwright
./setup.sh --audit-fix
```

## 4) Generazione config MCP (script)

I due script `genera_mcp_json` producono file separati per client:
- `settings.codex.toml` (Codex)
- `settings.vscode.mcp.json` (VS Code/Copilot)
- `settings.claude.json` (Claude Desktop)

Opzionalmente possono generare anche i file legacy:
- `settings.json`
- `settings.toml`

### PowerShell

```powershell
powershell -ExecutionPolicy Bypass -File .\genera_mcp_json.ps1
```

Opzioni principali:

```powershell
powershell -ExecutionPolicy Bypass -File .\genera_mcp_json.ps1 -RootDir D:\mcp-servers
powershell -ExecutionPolicy Bypass -File .\genera_mcp_json.ps1 -NodePath "C:\Program Files\nodejs\node.exe"
powershell -ExecutionPolicy Bypass -File .\genera_mcp_json.ps1 -UseNodeFromPath
powershell -ExecutionPolicy Bypass -File .\genera_mcp_json.ps1 -WriteLegacySettings
```

### Bash

```bash
./genera_mcp_json.sh --root /path/to/mcp-servers
./genera_mcp_json.sh --node-path /usr/bin/node
./genera_mcp_json.sh --use-node-alias
./genera_mcp_json.sh --write-legacy
```

## 5) Configurazione client MCP

Mappa file di configurazione:
- Codex: `%USERPROFILE%\\.codex\\config.toml`
- VS Code/Copilot: comando `MCP: Open User Configuration` (oppure `.vscode/mcp.json`)
- Claude Desktop: `%APPDATA%\\Claude\\claude_desktop_config.json`

### 4.1 Codex (`config.toml`)

Esempio base:

```toml
model = "gpt-5.4"
model_reasoning_effort = "high"

[windows]
sandbox = "elevated"

[features]
multi_agent = true

[mcp_servers.git-mcp-server]
command = 'C:\Program Files\nodejs\node.exe'
args = ['D:\mcp-servers\git-node\index.js']
enabled = true

[mcp_servers.docs-mcp-server]
command = 'C:\Program Files\nodejs\node.exe'
args = ['D:\mcp-servers\docs-node\index.js']
enabled = true

[mcp_servers.linter-mcp-server]
command = 'C:\Program Files\nodejs\node.exe'
args = ['D:\mcp-servers\linter-node\dist\index.js']
enabled = true
```

Verifica:

```powershell
codex mcp list
```

Se sandbox non parte:
- verificare blocchi duplicati nel TOML
- fallback temporaneo: `[windows] sandbox = "unelevated"`

### 4.2 VS Code / Copilot (`mcp.json`)

Esempio:

```json
{
  "servers": {
    "git-mcp-server": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["D:\\mcp-servers\\git-node\\index.js"]
    },
    "docs-mcp-server": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["D:\\mcp-servers\\docs-node\\index.js"]
    },
    "playwright-mcp-server": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["D:\\mcp-servers\\playwright-node\\index.js"],
      "env": {
        "ALLOWED_URLS": "localhost,127.0.0.1",
        "BLOCK_MEDIA": "false"
      }
    }
  }
}
```

Verifica:
- `MCP: List Servers`
- in Agent mode verificare disponibilita tool

### 4.3 Claude Desktop (`claude_desktop_config.json`)

Esempio:

```json
{
  "mcpServers": {
    "git-mcp-server": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["D:\\mcp-servers\\git-node\\index.js"]
    },
    "docs-mcp-server": {
      "command": "C:\\Program Files\\nodejs\\node.exe",
      "args": ["D:\\mcp-servers\\docs-node\\index.js"]
    }
  }
}
```

Dopo modifica:
- chiudere e riaprire completamente Claude Desktop

## 6) Note per server specifici

### `cf-node`

Per il bridge ColdFusion non basta avviare `cf-node`.
Serve pubblicare i file in `cf-node/mcp_tool` e configurare mapping:
- Logical Path: `/mcp_tool`
- Directory Path: cartella deploy reale in ColdFusion

`CF_BRIDGE_URL` va nel `.env` del progetto target.

### `linter-node`

Usare sempre `dist/index.js` nella configurazione MCP.
Variabili comuni:
- `CFLINT_JAR`
- `JAVA_BIN`

### `projectfs-node`

E' read-only e vincolato a roots consentite.
Variabili bootstrap tipiche:
- `PROJECTFS_ALLOWED_ROOTS`
- `PROJECTFS_CONFIG`

Precedenza env:
- se un tool riceve `project_path`, il `.env` del progetto target deve poter sovrascrivere il bootstrap launcher.

### `sql-node`

Legge credenziali DB dal `.env` del progetto target (`project_path`).
Supporta anche tunnel SSH (es. `SSH_HOST`, `SSH_PORT`, `SSH_USER`, `SSH_KEY_PATH`).

### `playwright-node`

Variabili launcher utili:
- `ALLOWED_URLS`
- `BLOCK_MEDIA`

Primo avvio: installare browser Chromium (script setup opzionale con flag dedicato).

### `docs-node`

Indicizza Markdown in SQLite (FTS5).
Uso tipico:
- scan (`scan_file` / `scan_folder`)
- ricerca (`search`)
- lettura documento (`read_document`)

### `office-node`

Supporta Word/Excel/PDF.
Per operazioni di write/export, payload include `save_path` e riferimenti artifact compatibili.

## 7) Variabili `.env` principali

Valori tipicamente usati (a seconda dei server attivi):
- DB: `DB_TYPE`, `DB_SERVER`, `DB_PORT`, `DB_NAME`, `DB_USER`, `DB_PASSWORD`
- Mantis: `MANTIS_URL`, `MANTIS_TOKEN`, `MANTIS_PROJECT_ID`
- Linter: `CFLINT_JAR`, `JAVA_BIN`, `CFLINT_CONFIG`
- ProjectFS: `PROJECTFS_ALLOWED_ROOTS`, `PROJECTFS_CONFIG`, `PROJECTFS_MAX_FILE_BYTES`, `PROJECTFS_MAX_DEPTH`

Regola importante:
- le variabili di dominio vanno lette dal progetto esterno target passato al tool (tipicamente `project_path`), non dal repo MCP corrente.

### `MANTIS_TOKEN` come variabile utente (opzionale)

Se vuoi tenere il token fuori dal `.env` condiviso, puoi impostarlo nell'ambiente utente/processo che avvia i server MCP.
Quando `mantis-node` legge anche un `.env` nel progetto target (`project_path`), quel valore ha precedenza.

Linux/macOS (sessione corrente):

```bash
export MANTIS_TOKEN="il_tuo_token"
```

Linux/macOS (persistente):

```bash
echo 'export MANTIS_TOKEN="il_tuo_token"' >> ~/.bashrc
source ~/.bashrc
```

Windows PowerShell (sessione corrente):

```powershell
$env:MANTIS_TOKEN = "il_tuo_token"
```

Windows PowerShell (persistente utente):

```powershell
[System.Environment]::SetEnvironmentVariable("MANTIS_TOKEN", "il_tuo_token", "User")
```

Windows cmd (persistente utente):

```cmd
setx MANTIS_TOKEN "il_tuo_token"
```

Dopo l'impostazione persistente, riavvia terminale/editor/client MCP.

## 8) VS Code Remote (Linux/WSL/SSH)

Se i server girano in remoto:
- installare Node nel sistema remoto
- clonare il repo nel filesystem remoto
- eseguire setup nel remoto (`./setup.sh`)
- usare path Linux assoluti nelle config MCP (`/home/.../mcp-servers/...`)

## 9) Troubleshooting rapido

- Server assente nel client:
  - file configurazione errato
  - JSON/TOML invalido
- Server non avvia:
  - `node` non raggiungibile
  - path script sbagliato
- Tool senza credenziali:
  - `.env` non presente nel progetto target
- Solo alcuni server partono:
  - testare manualmente `node <path>/index.js`
- Playwright fallisce al primo avvio:
  - installare browser Chromium

## 10) Done minimo su modifiche MCP/skill

Una modifica e' chiusa quando:
- comportamento richiesto implementato
- compatibilita legacy preservata (salvo richiesta contraria)
- smoke/schema check eseguiti
- documentazione aggiornata
- se cambia codice server MCP, ricordare riavvio server nei client