Telaria MCP — Catalogue d'outils

Ce document définit les conventions et le catalogue des outils Telaria MCP.

V1 en production (v0.1.3) : 3 outils lecture seule — list_docs, read_doc, search_docs. Les outils de génération et d'audit sont en réserve V2+. Schémas JSON autorités : ia-mcp.md §9.

1. Principes MCP pour les tools

Exigences minimales :

Les tools sont listés via tools/list et appelés via tools/call.
Chaque tool expose un inputSchema JSON Schema.
Les résultats peuvent être du texte, des images, des ressources ou des messages.
Les actions sensibles requièrent un humain dans la boucle.

Source : https://modelcontextprotocol.io/specification/2025-11-25/server/tools

2. Conventions Codexia

Conventions :

Noms en minuscules, séparés par des underscores (audit_rgaa, build_toc).
Descriptions orientées action, sans jargon inutile.
Un tool = une intention claire et testable.
Toutes les sorties sont structurées et auditables.

3. Fiche standard d'un tool

Champs recommandés :

name : identifiant stable.
title : titre humain.
description : objectif et limites.
inputSchema : JSON Schema minimal.
outputSchema : format de sortie attendu.
risks : risques fonctionnels ou de conformité.
humanInTheLoop : booléen et conditions.

3.1 Schémas JSON - gabarits

3.1.1 Schéma d'entrée générique (inputSchema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "context": {
      "type": "string",
      "description": "Contexte court et ciblé."
    }
  },
  "required": ["context"],
  "additionalProperties": false
}

3.1.2 Schéma de sortie générique (outputSchema)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["ok", "warning", "error"] },
    "summary": { "type": "string" },
    "items": {
      "type": "array",
      "items": { "type": "object" }
    }
  },
  "required": ["status", "summary"],
  "additionalProperties": false
}

3.1.3 Schéma `audit_rgaa` (exemple)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "html": { "type": "string" },
    "scope": { "type": "string", "enum": ["page", "component"] }
  },
  "required": ["html"],
  "additionalProperties": false
}

3.1.4 Schéma de sortie `audit_rgaa` (exemple)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["ok", "warning", "error"] },
    "summary": { "type": "string" },
    "issues": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "criterion": { "type": "string" },
          "severity": { "type": "string", "enum": ["minor", "major", "critical"] },
          "message": { "type": "string" },
          "location": { "type": "string" }
        },
        "required": ["criterion", "severity", "message"],
        "additionalProperties": false
      }
    }
  },
  "required": ["status", "summary"],
  "additionalProperties": false
}

3.1.5 Schéma `build_toc` (exemple)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "markdown": { "type": "string" },
    "maxDepth": { "type": "integer", "minimum": 1, "maximum": 6 }
  },
  "required": ["markdown"],
  "additionalProperties": false
}

3.1.6 Schéma de sortie `build_toc` (exemple)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["ok", "warning", "error"] },
    "toc": { "type": "string" },
    "items": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "title": { "type": "string" },
          "level": { "type": "integer", "minimum": 1, "maximum": 6 },
          "anchor": { "type": "string" }
        },
        "required": ["title", "level"],
        "additionalProperties": false
      }
    }
  },
  "required": ["status", "toc"],
  "additionalProperties": false
}

3.1.7 Schéma `draft_readme_basic` (réserve V2+, déclassé de V1)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "projectName": { "type": "string" },
    "shortDescription": { "type": "string" },
    "stack": { "type": "array", "items": { "type": "string" } },
    "installSteps": { "type": "array", "items": { "type": "string" } },
    "usage": { "type": "string" },
    "license": { "type": "string" }
  },
  "required": ["projectName", "shortDescription", "installSteps", "usage", "license"],
  "additionalProperties": false
}

3.1.8 Schéma de sortie `draft_readme_basic` (réserve V2+)

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["ok", "warning", "error"] },
    "readme": { "type": "string" },
    "sections": {
      "type": "array",
      "items": { "type": "string" }
    }
  },
  "required": ["status", "readme"],
  "additionalProperties": false
}

3.2 Schémas JSON - conventions

Conventions :

Toujours définir additionalProperties à false.
Utiliser des enums quand le choix est fermé.
Documenter la taille maximale des champs dans description.
Prévoir des schémas de sortie stables et versionnés.

4. Catalogue

4.0 Outils V1 — en production

Trois outils lecture seule, adossés au cœur RAG (L0). Schémas complets ci-dessous.

`search_docs` — recherche sémantique (outil ancre V1)

// entrée
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": { "type": "string", "description": "Question en langage naturel." },
    "k": { "type": "integer", "minimum": 1, "maximum": 20, "default": 5 }
  },
  "required": ["query"],
  "additionalProperties": false
}
// sortie
{
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["ok", "warning", "error"] },
    "hits": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path":    { "type": "string" },
          "section": { "type": "string" },
          "score":   { "type": "number" },
          "excerpt": { "type": "string" }
        },
        "required": ["path", "score", "excerpt"],
        "additionalProperties": false
      }
    }
  },
  "required": ["status", "hits"],
  "additionalProperties": false
}

`list_docs` — liste des documents indexés

// entrée
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "prefix": { "type": "string", "description": "Filtre optionnel sur préfixe de chemin (ex. 'specs/')." },
    "limit":  { "type": "integer", "minimum": 1, "maximum": 500, "default": 200 }
  },
  "additionalProperties": false
}
// sortie
{
  "type": "object",
  "properties": {
    "status": { "type": "string", "enum": ["ok", "warning", "error"] },
    "documents": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "path":  { "type": "string" },
          "title": { "type": "string" }
        },
        "required": ["path", "title"],
        "additionalProperties": false
      }
    },
    "truncated": { "type": "boolean", "description": "true si tronqué à limit." }
  },
  "required": ["status", "documents", "truncated"],
  "additionalProperties": false
}

`read_doc` — contenu Markdown brut d'un document

// entrée
{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "path": { "type": "string", "description": "Chemin relatif à la racine du projet (ex. 'specs/ia-coeur.md')." }
  },
  "required": ["path"],
  "additionalProperties": false
}
// sortie — Markdown brut (UTF-8), aucune normalisation côté serveur
{
  "type": "object",
  "properties": {
    "status":  { "type": "string", "enum": ["ok", "warning", "error"] },
    "path":    { "type": "string" },
    "title":   { "type": "string" },
    "content": { "type": "string", "description": "Markdown brut tel que stocké." },
    "metadata": {
      "type": "object",
      "properties": {
        "mtime":        { "type": "string", "format": "date-time" },
        "content_hash": { "type": "string" },
        "size_bytes":   { "type": "integer", "minimum": 0 }
      },
      "required": ["mtime", "content_hash", "size_bytes"],
      "additionalProperties": false
    }
  },
  "required": ["status", "path", "title", "content", "metadata"],
  "additionalProperties": false
}

4.1 Réserve V2+ — Conformité et qualité

audit_rgaa : analyse RGAA sur un extrait HTML.
audit_wcag : vérification WCAG 2.2 sur un extrait HTML.
check_opquast : contrôle de règles Opquast sur une page.
gdpr_risk_scan : détection de données personnelles ou sensibles.
doc_quality_report : rapport de qualité documentaire (lisibilité, structure, cohérence).

4.2 Structuration documentaire

build_toc : génération d'une table des matières.
crosslink_docs : liens croisés internes.
tagging_topics : indexation thématique.
normalize_headings : harmonisation des niveaux de titres.
extract_glossary_terms : extraction de termes pour glossaire.

4.3 Assistance rédactionnelle

draft_user_doc : production d'une documentation utilisateur.
vade_mecum_tech : fiche technique structurée.
doc_security_theme : documentation thématique sécurité.
release_notes : notes de version lisibles.
support_faq : FAQ support et dépannage.

4.4 Gouvernance et suivi

coverage_matrix : matrice de couverture doc / exigences.
risk_register_update : mise à jour des risques documentaires.
accessibility_checklist : checklist RGAA / WCAG par livrable.

5. Évolution du catalogue

Processus recommandé :

Tout nouveau tool est décrit, testé et validé.
Les outils critiques exigent validation humaine systématique.
Les changements de schéma sont versionnés.