redteamsfr/thot repository overview

⁠Thot — documentation Markdown par MCP et HTTP

Thot indexe un dossier de fichiers Markdown et le rend consultable par des agents IA (serveur MCP, transport Streamable HTTP) et par une API HTTP. Une console web est incluse. Chaque passage renvoyé porte son chemin, ses lignes source et une référence à une version figée de l'index : un agent peut citer ses sources, et on peut les vérifier.

Cinq outils MCP en lecture seule : search_docs (recherche plein texte BM25), find_pattern (chaîne exacte), list_docs, get_outline et read_doc.

• Tags : latest (plus haute version publiée), X.Y.Z (version précise, par exemple 0.4.0)
• Plateformes : linux/amd64, linux/arm64 (Mac Apple Silicon en natif)

⁠Essayer en une commande, sans rien monter

L'image embarque un corpus d'exemple — cinq pages de la documentation GitLab — et, faute de token fourni, le profil d'essai en génère un par droit et les écrit dans ses journaux.

docker run -d --name thot -p 127.0.0.1:8218:8218 \
  --read-only --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --cap-drop ALL --security-opt no-new-privileges:true \
  -e THOT_PROFILE=local-test \
  -e THOT_DOCS_DIR=/opt/thot/corpus-exemple \
  redteamsfr/thot:latest
docker logs thot   # le bloc « MODE MAQUETTE » donne les tokens

Ouvrez http://127.0.0.1:8218/⁠ et collez le token docs:read.

C'est un mode de démonstration, pas un déploiement. Les tokens changent à chaque démarrage, disparaissent avec le conteneur, et le token d'administration est lisible par quiconque lit les journaux. L'index est jetable : sans THOT_DATA_DIR, il vit dans /tmp et ne survit pas à l'arrêt. Pour tout le reste, fournissez vos secrets : il suffit qu'une des deux variables THOT_DEV_TOKEN_FILE et THOT_ADMIN_TOKEN_FILE soit posée pour que Thot exige l'autre plutôt que de générer quoi que ce soit. Le profil production ne génère jamais rien.

Le corpus d'exemple vit sur /opt/thot/corpus-exemple ; il n'est servi que si THOT_DOCS_DIR le désigne, jamais par défaut. Ce sont des pages de GitLab Inc. sous CC BY-SA 4.0⁠, adaptées ; l'attribution complète est dans l'image, sur /opt/thot/ATTRIBUTION.md.

⁠Démarrage avec votre dossier Markdown

Le dossier de documentation se monte en lecture seule sur /docs. L'index vit dans un volume séparé, sur /var/lib/thot.

1. Créez deux tokens, un de consultation et un d'administration :

(umask 077 && mkdir -p secrets \
  && openssl rand -hex 32 > secrets/read-token \
  && openssl rand -hex 32 > secrets/admin-token)

1. Lancez Thot en remplaçant /chemin/vers/vos-docs par votre dossier :

docker run -d --name thot -p 127.0.0.1:8218:8218 \
  --read-only --tmpfs /tmp:rw,noexec,nosuid,size=64m \
  --cap-drop ALL --security-opt no-new-privileges:true \
  -e THOT_PROFILE=local-test \
  -e THOT_DEV_TOKEN_FILE=/run/secrets/read-token \
  -e THOT_ADMIN_TOKEN_FILE=/run/secrets/admin-token \
  -e THOT_DOCS_DIR=/docs \
  -e THOT_DATA_DIR=/var/lib/thot \
  -v "$PWD/secrets:/run/secrets:ro" \
  -v /chemin/vers/vos-docs:/docs:ro \
  -v thot-index:/var/lib/thot \
  redteamsfr/thot:latest

1. Utilisez-le :

• Console : http://127.0.0.1:8218/⁠, avec le contenu de secrets/read-token.
• MCP : URL http://127.0.0.1:8218/mcp/, transport Streamable HTTP, en-tête Authorization: Bearer <read-token>.
• Prise en compte des modifications : l'index ne suit pas le dossier en continu. Après avoir modifié vos fichiers, relancez l'indexation depuis le panneau Administration de la console, ou avec :

curl -X POST -H "Authorization: Bearer $(cat secrets/admin-token)" \
  http://127.0.0.1:8218/api/v1/admin/reindex

Si l'indexation échoue, la version précédente reste servie.

⁠Bon à savoir

• Frontmatter facultatif. Une page sans frontmatter est indexée. Si vous en mettez un, id (unique dans le dossier) et title sont obligatoires ; description porte le résumé — summary en reste un alias hérité, lu seulement quand description manque — et tags est facultatif. Les autres champs sont conservés et rendus tels quels. Un id dupliqué ou un champ invalide bloque la nouvelle indexation, et la précédente reste servie.
• L'index veut son volume. Sans THOT_DATA_DIR, le profil local-test écrit un index jetable sous /tmp et le dit au démarrage ; le profil production exige la variable et refuse de démarrer sans elle.
• Linux et droits des fichiers. Le service tourne sous l'UID 10001 et doit pouvoir lire les tokens : sudo chown 10001:10001 secrets/*. Sur Mac (Docker Desktop, Colima), le partage de fichiers s'en charge, mais le dossier doit être partagé avec la VM (par défaut, votre dossier personnel).
• Un seul conteneur par volume d'index.
• Sondes : /health/live (processus actif) et /health/ready (un index valide est servi).
• Profil obligatoire : sans THOT_PROFILE, l'image refuse de démarrer.
• Édition désactivée par défaut. La console ne peut écrire que si vous l'activez explicitement : THOT_EDITING_ENABLED=true, un troisième token distinct sur THOT_WRITE_TOKEN_FILE, et /docs monté en écriture.

⁠Profil production

Le profil local-test, ses tokens statiques et sa génération de tokens servent aux essais. Pour une instance partagée, derrière un accès HTTPS, utilisez des JWT RS256 émis par votre fournisseur d'identité (scopes docs:read, docs:write et docs:admin) :

THOT_PROFILE=production
THOT_DOCS_DIR=/docs
THOT_DATA_DIR=/var/lib/thot
THOT_JWT_PUBLIC_KEY_FILE=/run/secrets/public-key.pem
THOT_JWT_ISSUER=https://votre-fournisseur-identite
THOT_JWT_AUDIENCE=thot

Dans ce profil, aucun token n'est généré ni affiché, et THOT_DATA_DIR est obligatoire.