@inwinkdev/data-mcp

Serveur MCP Data inwink — accès lecture seule aux données d'événements inwink, pour répondre à des questions de statistiques en langage naturel.

Contrairement au MCP DevTools (qui aide à développer des extensions), ce serveur ne génère pas de code : il expose dynamiquement les endpoints de lecture d'inwink pour que vous puissiez demander, par exemple :

• « Combien d'exposants sur mon événement Tech Summit ? »
• « Combien de visiteurs VIP sont venus le 12 juin sur l'événement X ? »
• « Liste les 20 derniers inscrits de l'événement Y. »

🔒 Lecture seule. Aucune opération d'écriture (create / edit / delete / import) n'est exposée. Seuls query, count et la découverte de schéma sont disponibles.

Installation

npm install
npm run build

Authentification

L'accès aux données nécessite une authentification OAuth2 (PKCE) auprès d'inwink. Deux options :

1. En ligne de commande (une fois) :

   npm run login          # ouvre le navigateur
   npm run login -- --force   # force une reconnexion

   Le token est chiffré et stocké dans ~/.config/inwink-data-mcp/auth.json. Il est rafraîchi automatiquement.

2. Via l'outil MCP inwink_login directement depuis l'assistant.

Outils exposés

| Outil | Rôle | |---|---| | inwink_login | Authentification OAuth PKCE (ouvre le navigateur). | | inwink_find_event | Résout un événement par son nom → eventId + customerId, cross-customer (aucun customerId requis). | | inwink_count | Compte des entités correspondant à un filtre → un entier. | | inwink_query | Liste des entités (filtres, projection, tri, pagination). | | inwink_aggregate | GROUP BY + comptage côté MCP (répartitions par jour, statut, catégorie…). | | inwink_describe | Découvre dynamiquement les entités et leurs champs (dont champs custom), avec filtrage search/fieldType/maxFields. |

Workflow type pour une question de stats

1. inwink_find_event avec name="Tech Summit" → récupère le eventId.
2. (optionnel) inwink_describe pour connaître les champs disponibles.
3. inwink_count ou inwink_query avec api="eventapi", shardId=<eventId>, entity="exhibitor" (ou person, session…).

Entités fréquentes (eventapi)

| Entité | Contenu | |---|---| | person | Participants / visiteurs (inscrits, présents, VIP via kinds, check-in…) | | exhibitor | Exposants | | session | Sessions / conférences | | order | Commandes |

Format des filtres (JSON Query inwink, type MongoDB)

// Exposants : pas de filtre
{}

// Visiteurs VIP
{ "kinds": { "$any": { "$eq": "VIP" } } }

// Présents (check-in effectué) après une date
{ "$and": [ { "hasAttended": true }, { "checkinDate": { "$gte": "2024-06-12T00:00:00Z" } } ] }

Opérateurs : $eq, $neq, $gt/$gte/$lt/$lte, $and/$or/$not, $text.$contains, $any/$all (collections), opérateurs de date ($utcNow, $days…). L'égalité est implicite : { "status": "Active" } ≡ { "status": { "$eq": "Active" } }.

Répartitions / GROUP BY (inwink_aggregate)

inwink n'a pas d'agrégation native. inwink_aggregate pagine les données filtrées côté MCP (projection réduite au seul champ groupé, dédup par id) et compte, sans rapatrier les lignes dans la conversation.

// Exposants ajoutés par jour
{ "api": "eventapi", "shardId": "<eventId>", "entity": "exhibitor",
  "groupBy": "creationDate", "dateBucket": "day" }

// Participants par catégorie (champ multivalué → chaque valeur comptée)
{ "api": "eventapi", "shardId": "<eventId>", "entity": "person", "groupBy": "kinds" }

Un plafond maxRecords (défaut 50 000) protège des très gros volumes ; complete: false dans la réponse signale un résultat partiel.

Configuration dans un client MCP

Exemple pour Claude Desktop / VS Code (mcp.json) :

{
  "mcpServers": {
    "inwink-data": {
      "command": "node",
      "args": ["C:/Users/FlorentSANTIN/Sources/MCP Data/dist/index.js"]
    }
  }
}

Variables d'environnement (optionnel)

| Variable | Défaut | |---|---| | INWINK_EVENT_API_URL | https://api-event.inwink.com | | INWINK_CUSTOMER_API_URL | https://api-customer.inwink.com | | INWINK_BACKOFFICE_URL | https://my.inwink.com | | INWINK_DISCOVERY_URL | https://openapi.inwink.com | | INWINK_AUTHORITY | https://auth.inwink.com/inwink | | INWINK_CLIENT_ID | inwink-extensions | | INWINK_SCOPE | openid profile offline_access |

Architecture

src/
  config.ts            Configuration (URLs, OAuth) — surchargée par env
  index.ts             Point d'entrée MCP (stdio) — enregistre les outils
  login-cli.ts         CLI `npm run login`
  inwink-client.ts     Client HTTP lecture seule (query / count / discovery)
  tools.ts             Définition des 5 outils MCP
  auth/
    oidc.ts            Découverte OIDC + helpers PKCE
    oauth-flow.ts      Flux Authorization Code + PKCE (navigateur)
    token-store.ts     Stockage chiffré des tokens (~/.config)
    token-manager.ts   Récupération / refresh silencieux du token

#� �M�C�P�-�i�n�w�i�n�k�-�D�a�t�a� � �