
mcp
com.vuntum/mcp
Sourced, dated data on consumer robots and physical AI: specs, prices, availability, evidence.
Documentation
Vuntum MCP server
Français
Serveur Model Context Protocol de Vuntum, le média et la base de données française sur les robots grand public et l'IA physique : humanoïdes, robots chiens, robots de maison et de service. Chaque valeur renvoyée est datée et rattachée à une source, avec son niveau de preuve.
Ce dépôt contient :
- le code source du serveur (dossier
server/), sous licence MIT ; - la description publique du serveur (
server.json,glama.json) et des exemples de clients (examples/).
L'outil est libre, pas la base
| Licence | Dans ce dépôt ? | |
|---|---|---|
| Code (serveur, exemples, schéma SQL) | MIT | Oui |
| Données Vuntum (fiches, prix, sources) | CC BY-NC 4.0 | Non |
Les données de Vuntum ne sont pas copiées ici. Le fichier server/sql/seed.sql ne contient que
trois robots fictifs (« Demo Robot A », « Demo Robot B », « Demo Robot C »), avec des sources
sur example.com. Ils servent seulement à lancer le serveur chez soi.
Licence des données servies par vuntum.com : CC BY-NC 4.0 pour les versions publiées depuis le
24 octobre 2026 (versions plus anciennes : CC BY 4.0). Attribution obligatoire : reprendre le champ
attribution de la réponse, avec le lien de la fiche. Détail :
docs/LEGAL_AND_ATTRIBUTION.md.
Utiliser le serveur public (rien à installer)
Le serveur public reste ouvert à tous : https://vuntum.com/mcp (Streamable HTTP), sans clé ni
compte. Dans Claude Code :
claude mcp add --transport http vuntum https://vuntum.com/mcp
Autres clients (claude.ai, Claude Desktop, ChatGPT, Cursor, VS Code) :
docs/INSTALLATION.md. Pour vérifier qu'il répond, à la racine du dépôt :
npm install && npm run check (sortie attendue : OK: 20 tools, all read-only, get_robot answers with sourced data.).
- Gratuit : 100 appels d'outils par jour et par adresse IP, puis erreur HTTP 429.
initializeettools/listne comptent jamais. - Attribution obligatoire : chaque réponse porte un champ
attributionà reprendre avec les données. - Usage commercial : accès pro sur demande, vuntum.com/fr/api-mcp#acces-pro.
- Lecture seule : 20 outils, tous annotés
readOnlyHint: true. - Textes en français par défaut, en anglais avec
locale: "en". 50 résultats au plus par appel. - Nom dans le registre MCP officiel :
com.vuntum/mcp.
Ce que le code montre
Le code de server/src est celui qui tourne sur vuntum.com, sans les données.
- Quota par adresse, sur
tools/callseulement (access.ts). Une adresse a droit à 100 appels d'outils par jour (jour UTC). Les autres messages du protocole (initialize,tools/list) ne comptent jamais : un annuaire qui vérifie que le serveur répond ne reçoit jamais d'erreur 429. Une adresse IPv6 compte pour son préfixe /64 entier. Les annuaires MCP connus et les connecteurs des assistants IA ont un quota partagé plus haut (2 000 par jour). Un connecteur d'assistant n'y a droit que si son adresse figure dans la liste officielle publiée par son éditeur (net/robot-ranges.ts) : écrire « ChatGPT-User » dans un en-tête ne suffit pas. - Accès pro par clé hachée en SHA-256 (
data/api-keys.ts). La clé arrive parAuthorization: Bearer vtm_...ouX-Vuntum-Key. La base ne garde que son empreinte SHA-256, lue par une fonction SQL : le rôle du serveur ne voit jamais la table des clés. Une clé inconnue ou révoquée reçoit une erreur 403, jamais un retour discret à l'accès gratuit. Le résultat est gardé une minute en mémoire. Les journaux n'écrivent quevtm_et les huit caractères qui suivent. - Attribution et licence dans chaque réponse (
terms.ts). Chaque réponse commence parattribution(la phrase à citer, avec le lien de la fiche) etlicense(CC BY-NC 4.0 sans clé, licence commerciale avec une clé pro). Un test vérifie que chaque outil passe par là. - Garde HTTP (
http-guard.ts,server-http.ts). POST seulement, corps limité à 64 Kio, un seul message JSON-RPC par requête, limite par minute et par adresse. Les en-têtesX-Real-IPetX-Forwarded-Forne sont crus que s'ils viennent d'un proxy (boucle locale ou réseau privé) (net/client-ip.ts). Le serveur est sans état : un serveur MCP neuf par requête. - Arrêt propre (
graceful-shutdown.ts). Sur SIGTERM, le serveur répond encore 5 secondes avecConnection: close, puis cesse d'écouter, puis laisse finir les requêtes en cours (12 secondes au plus). Un redémarrage ne coupe aucune requête. - Lecture seule à chaque étage. Les outils passent par une interface de lecture
(
data/reader.ts). Son adaptateur PostgreSQL (data/sql-reader.ts) ne lit que des relationspublic_*, avec un rôle en lecture seule (sql/readonly-role.sql).
Lancer le serveur chez soi
Prérequis : Node.js 20 ou plus récent ; Docker pour la base de démonstration.
En HTTP, avec Docker Compose (PostgreSQL + données fictives + serveur) :
git clone https://github.com/RAAAAAGEEEEE/vuntum-mcp
cd vuntum-mcp/server
docker compose up -d --build
curl http://127.0.0.1:3001/health
Le serveur répond sur http://127.0.0.1:3001/mcp. Les mots de passe de docker-compose.yml ne
servent qu'à cette démonstration locale : la base n'écoute que sur 127.0.0.1.
En stdio (le client lance le serveur lui-même), avec la base de Docker Compose :
cd vuntum-mcp/server
npm ci
npm run build
DATABASE_URL=postgres://vuntum_mcp_ro:local-demo-readonly-only@127.0.0.1:5432/vuntum node dist/server-stdio.js
Brancher un client : configurations prêtes pour Claude Desktop, Claude Code et Cursor dans
examples/local/. Avec Claude Code, en HTTP :
claude mcp add --transport http vuntum-local http://127.0.0.1:3001/mcp
Tests (sans Docker : une base PostgreSQL en mémoire, PGlite, charge le schéma et les données fictives) :
cd server
npm ci && npm test && npm run build
Variables d'environnement : DATABASE_URL (obligatoire, rôle en lecture seule),
VUNTUM_PUBLIC_URL (https://vuntum.com par défaut, base des liens), MCP_HOST (127.0.0.1
par défaut), MCP_PORT (3001 par défaut), LOG_LEVEL (info par défaut). Aucune n'a de mot
de passe par défaut.
Avec vos propres données : créez les tables de server/sql/schema.sql
(ou des vues de même forme sur votre modèle), puis le rôle de
server/sql/readonly-role.sql. Pour une clé pro de test, insérez
dans api_key l'empreinte SHA-256 (en hexadécimal) d'une clé faite de vtm_ suivi de
43 caractères base64url. Ne stockez jamais la clé elle-même.
Documentation
Architecture · Installation · Usage et outils · Limites · Sécurité · Contribuer · Changements (documents en anglais).
Contact : contact@vuntum.com, ou une issue dans ce dépôt. Une erreur dans les données se signale par e-mail, avec l'adresse de la fiche.
English
Model Context Protocol server of Vuntum, the French media outlet and database about consumer robots and physical AI: humanoids, robot dogs, home and service robots. Every value it returns is dated and tied to a source, with its level of evidence.
This repository holds:
- the source code of the server (folder
server/), under the MIT license; - the public description of the server (
server.json,glama.json) and client examples (examples/).
The tool is open source, the database is not
| License | In this repository? | |
|---|---|---|
| Code (server, examples, SQL schema) | MIT | Yes |
| Vuntum data (robot sheets, prices, sources) | CC BY-NC 4.0 | No |
The Vuntum data is not copied here. server/sql/seed.sql only holds three fictitious robots
("Demo Robot A", "Demo Robot B", "Demo Robot C"), with sources on example.com. They are only there
so that you can run the server on your own machine.
License of the data served by vuntum.com: CC BY-NC 4.0 for the versions published since
24 October 2026 (earlier versions: CC BY 4.0). Attribution is mandatory: reproduce the
attribution field of the response, with the link to the robot sheet. Detail:
docs/LEGAL_AND_ATTRIBUTION.md.
Use the public server (nothing to install)
The public server stays open to everyone: https://vuntum.com/mcp (Streamable HTTP), no key, no
account. In Claude Code:
claude mcp add --transport http vuntum https://vuntum.com/mcp
Other clients (claude.ai, Claude Desktop, ChatGPT, Cursor, VS Code):
docs/INSTALLATION.md. To check that it answers, at the root of the
repository: npm install && npm run check (expected output: OK: 20 tools, all read-only, get_robot answers with sourced data.).
- Free: 100 tool calls per day per IP address, then HTTP 429.
initializeandtools/listnever count. - Attribution is mandatory: every response carries an
attributionfield to reproduce with the data. - Commercial use: pro access on request, vuntum.com/fr/api-mcp#acces-pro.
- Read-only: 20 tools, all annotated
readOnlyHint: true. - Texts in French by default, in English with
locale: "en". At most 50 results per call. - Name in the official MCP registry:
com.vuntum/mcp.
What the code shows
The code in server/src is the code that runs on vuntum.com, without the data.
- Quota per address, on
tools/callonly (access.ts). An address gets 100 tool calls per day (UTC day). The other protocol messages (initialize,tools/list) never count, so a directory that checks that the server is up never gets a 429. An IPv6 address counts for its whole /64 prefix. Known MCP directories and the connectors of AI assistants get a higher shared quota (2,000 a day). An assistant's connector only gets it when its address is in the official list published by its operator (net/robot-ranges.ts): writing "ChatGPT-User" in a header is not enough. - Pro access by a key hashed with SHA-256 (
data/api-keys.ts). The key comes inAuthorization: Bearer vtm_...orX-Vuntum-Key. The database only keeps its SHA-256 digest, read through an SQL function: the server's role never sees the key table. An unknown or revoked key gets a 403, never a silent fall back to the free access. The result is cached for one minute in memory. The logs only writevtm_and the eight characters after it. - Attribution and license in every answer (
terms.ts). Every answer starts withattribution(the sentence to quote, with the link to the robot sheet) andlicense(CC BY-NC 4.0 without a key, commercial license with a pro key). A test checks that every tool goes through it. - HTTP guard (
http-guard.ts,server-http.ts). POST only, body limited to 64 KiB, one JSON-RPC message per request, a per-minute limit per address. TheX-Real-IPandX-Forwarded-Forheaders are only believed when they come from a proxy (loopback or private network) (net/client-ip.ts). The server is stateless: a fresh MCP server for each request. - Graceful shutdown (
graceful-shutdown.ts). On SIGTERM, the server keeps answering for 5 seconds withConnection: close, then stops listening, then lets the requests in progress finish (12 seconds at most). A restart cuts no request. - Read-only at every level. The tools go through a read interface
(
data/reader.ts). Its PostgreSQL adapter (data/sql-reader.ts) only readspublic_*relations, with a read-only role (sql/readonly-role.sql).
Run the server on your machine
Prerequisites: Node.js 20 or later; Docker for the demo database.
Over HTTP, with Docker Compose (PostgreSQL + fictitious data + server):
git clone https://github.com/RAAAAAGEEEEE/vuntum-mcp
cd vuntum-mcp/server
docker compose up -d --build
curl http://127.0.0.1:3001/health
The server answers on http://127.0.0.1:3001/mcp. The passwords in docker-compose.yml are only
for this local demo: the database only listens on 127.0.0.1.
Over stdio (the client starts the server itself), with the Docker Compose database:
cd vuntum-mcp/server
npm ci
npm run build
DATABASE_URL=postgres://vuntum_mcp_ro:local-demo-readonly-only@127.0.0.1:5432/vuntum node dist/server-stdio.js
Connect a client: ready configurations for Claude Desktop, Claude Code and Cursor in
examples/local/. With Claude Code, over HTTP:
claude mcp add --transport http vuntum-local http://127.0.0.1:3001/mcp
Tests (no Docker: an in-memory PostgreSQL, PGlite, loads the schema and the fictitious data):
cd server
npm ci && npm test && npm run build
Environment variables: DATABASE_URL (required, a read-only role), VUNTUM_PUBLIC_URL
(https://vuntum.com by default, base of the links), MCP_HOST (127.0.0.1 by default),
MCP_PORT (3001 by default), LOG_LEVEL (info by default). None has a default password.
With your own data: create the tables of server/sql/schema.sql (or
views of the same shape over your own model), then the role of
server/sql/readonly-role.sql. For a test pro key, insert into
api_key the SHA-256 digest (in hexadecimal) of a key made of vtm_ followed by 43 base64url
characters. Never store the key itself.
Documentation
Architecture · Installation · Usage and tools · Limitations · Security · Contributing · Changelog.
Contact: contact@vuntum.com, or an issue in this repository. Report an error in the data by e-mail, with the address of the robot sheet.
No installation packages available.