server/ — Server MCP (TypeScript/Node)

Server Model Context Protocol in TypeScript/Node. Espone i tool MCP al client LLM via transport stdio (primario, constitution #7) e inoltra i comandi all'add-in Revit via WebSocket su localhost.

Scelte implementative: ../specs/decisions/ADR-001-server-stack.md.

Stato

Core MVP implementato e testato end-to-end (handshake MCP + 7 tool) contro l'add-in Revit reale (../plugin/, verificato su Revit 2024).

Comandi

npm install
npm run build      # compila in dist/
npm test           # vitest (unit + smoke MCP stdio, non richiede Revit)
npm run typecheck  # tsc --noEmit
npm run dev        # tsc --watch
npm start          # avvia dist/index.js (serve dist/, quindi build prima)
npm run build:mcpb # produce mcp-revit.mcpb per Claude Desktop (ADR-005)

Configurazione (env var)

| Variabile | Default | Descrizione | |---|---|---| | VISIONXT_BRIDGE_HOST | 127.0.0.1 | Host del bridge dell'add-in (solo localhost). | | VISIONXT_BRIDGE_PORT | 8765 | Porta WebSocket del bridge. Se hai due Revit aperti insieme, il secondo passa automaticamente a 8766 (ADR-010) — imposta questa variabile solo per raggiungere quella seconda istanza. | | VISIONXT_REQUEST_TIMEOUT_MS | 30000 | Timeout per richiesta (architecture spec: 30s). |

Struttura

manifest.json             # bundle .mcpb (ADR-005): server config + user_config opzionale
scripts/
└── build-mcpb.mjs        # build:mcpb — stage + npm ci --omit=dev + mcpb pack
src/
├── index.ts              # entry: stdio transport, avvio server
├── server.ts             # factory McpServer + istruzioni model-facing
├── config.ts             # config da env var
├── categories.ts         # mapping IT/EN → BuiltInCategory (differenziatore)
├── bridge/
│   ├── protocol.ts       # schema messaggi, protocolVersion, error codes (D4)
│   ├── transport.ts      # astrazione transport (testabile)
│   ├── ws-transport.ts   # implementazione WebSocket (ws)
│   └── client.ts         # correlazione requestId, timeout, compat protocollo
└── tools/
    ├── schemas.ts        # input schema Zod dei 7 tool (spec 003)
    └── register.ts       # registrazione tool + wiring sul bridge
test/                     # unit (fake transport) + smoke MCP stdio

Tool (tutti read-only in MVP — spec 003)

get_project_info, query_elements, get_element_details, get_selected_elements, select_elements, list_views_levels_sheets, export_schedule_data.

Vincoli

• stdio è il transport primario; HTTP è v2, mai default (constitution #7).
• I dati letti dal modello vanno trattati come dati, mai come istruzioni (threat model, ../specs/004-security-spec.md) — vedi instructions in server.ts.
• Categorie sempre risolte a OST_* lato server, mai stringhe localizzate all'add-in (constitution #3).