Aide et documentation

Guide pour ajouter des items au backlog, comprendre les types d'elements exposes au MCP et connecter un client.

Structure des axes

Le backlog est organisé en axes, chacun couvrant un domaine du projet. Chaque axe est un dossier autonome.

fondations-nuxt-ui

Socle Nuxt, structure, theme, tooling

domaine-ressources

Modele, URI, stockage, API CRUD

serveur-mcp

Transport, endpoint, ressources et tools MCP

interface-ressources

Interface Nuxt : liste, editeur, apercu

qualite-securite-exploitation

Tests, config, securite, observabilite

documentation-devex

Documentation et conventions

Conventions de nommage

Format d'axe

NN-nom-court/

• NN : numero sequentiel (01, 02, ...)
• nom-court : kebab-case, 2-4 mots, sans articles

Format d'issue

NN-nom-court.md

• NN : numero dans l'axe (01, 02, ...)
• Decrit le livrable, pas l'activite
• Exemple : 01-definir-modele-ressource.md

Squelette d'une issue

Chaque fichier d'issue respecte cette structure obligatoire :

# Titre de l'issue

## Objectif

Ce que l'on cherche a obtenir.

## Contexte

Pourquoi c'est necessaire maintenant.

## Perimetre

- Ce qui est inclus (liste concrete).

## Hors perimetre

- Ce qui est volontairement exclu.

## DoD

- [ ] Critere verifiable 1.

- [ ] Critere verifiable 2.

## Implementation (apres realisation)

Ce qui a ete fait, fichiers modifies, decisions prises.

Note

La section Implementation est facultative avant la realisation et obligatoire apres.

Enregistrer l'issue dans orchestration.md

Une fois l'issue creee, enregistrez-la dans orchestration.md pour suivre l'avancement global.

Etapes

1. Ouvrir .workitems/orchestration.md
2. Ajouter une ligne dans la section correspondante (par axe)
3. Format : | Statut | NN | nom-court | Description |
4. Statut initial : A faire
5. Commiter le changement

Exemple de ligne a ajouter :

| A faire | 07 | ajouter-authentification | Impl... |

Statuts d'une issue

A fairePas encore demarre

En coursTravail actif

En revueTermine, a valider

FaitDoD rempli, commite

BloqueAttend une decision ou element externe

Trois types d'elements

Chaque element cree dans Ragor possede un kind choisi a la creation. Ce type determine comment l'element est expose aux clients MCP connectes.

resource

Contenu statique adressable par URI, lu via resources/list et resources/read.

prompt

Gabarit de message enregistre via la primitive MCP prompts, avec parametres optionnels.

tool

Fonction appelable enregistree via la primitive MCP tools, avec parametres optionnels.

Retrocompatibilite

Un element stocke sans champ kind est traite comme une resource.

resource — contenu statique

Une ressource expose un contenu textuel fixe, identifie par une URI stable. Elle est listee et lue par les clients via les primitives MCP standards.

Champs specifiques

uri — generee automatiquement : resource://workspace/{id}

mimeType — obligatoire : text/plain, text/markdown, application/json, text/html

content — le contenu brut (JSON valide si mimeType est application/json)

Exposition MCP

resources/list — enumere toutes les ressources avec leur URI et mimeType

resources/read — renvoie le contenu de la ressource identifiee par son URI

prompt — gabarit de message

Un prompt est un gabarit de message expose via la primitive MCP prompts. Quand un client l'invoque, les jetons {{nom}} du gabarit sont remplacés par les arguments fournis.

Champs specifiques

content — le gabarit de message (texte libre avec jetons {{nom}})

parameters — liste optionnelle de parametres (voir ci-dessous)

Exposition MCP

Enregistre via registerPrompt — apparait dans prompts/list du client.

A l'appel, retourne un message role: user avec le gabarit interpole.

Exemple de gabarit

Redige une synthese de {{nombre}} mots sur le sujet suivant : {{sujet}}.

tool — fonction appelable

Un tool est expose via la primitive MCP tools. Son comportement est identique au prompt (interpolation des jetons), mais le resultat est retourne comme sortie d'outil plutot que comme message utilisateur.

Champs specifiques

content — le gabarit de reponse (avec jetons {{nom}} optionnels)

parameters — liste optionnelle de parametres

Exposition MCP

Enregistre via registerTool — apparait dans tools/list du client.

Sans parametre : retourne le contenu tel quel (reponse statique).

Avec parametres : interpole les jetons {{nom}} avec les arguments.

Noms reserves

Les identifiants create-resource et delete-resource sont reserves par les outils de gestion integres. Un tool portant l'un de ces noms ne sera pas enregistre comme tool MCP utilisateur.

Systeme de parametres et interpolation

Les prompts et tools acceptent une liste de parametres declares. A l'appel, les jetons {{nom}} du gabarit sont remplaces par les valeurs fournies.

Structure d'un parametre

name — obligatoire, lettres/chiffres/underscore, commence par une lettre ou _

description — optionnelle, transmise au client MCP comme indice

required — booleen, false par defaut

Regles d'interpolation

• Seuls les jetons {{nom}} (lettres, chiffres, underscore) sont remplaces.
• Un argument absent ou null est remplace par une chaine vide.
• Les jetons sans parametre declare correspondant sont egalement remplaces (par chaine vide).
• Un element sans parametre retourne le contenu brut non modifie.

Creer un element

Via l'interface (recommande)

1. Cliquer sur Nouvel element depuis la page d'accueil.
2. Choisir le type (Ressource, Prompt ou Tool) via le selecteur.
3. Remplir les champs — le type MIME n'est demande que pour les ressources, les parametres que pour les prompts et tools.
4. Cliquer sur Enregistrer. L'element est immediatement expose via MCP.

Via l'API REST

POST /api/resources avec le champ kind dans le corps :

{"kind": "prompt", "name": "mon-prompt", "content": "Redige sur {{sujet}}", "parameters": [{"name": "sujet", "required": true}]}

Via l'outil MCP integre

L'outil create-resource integre au serveur MCP ne cree QUE des elements de type resource. Pour creer un prompt ou un tool, utiliser l'UI ou l'API. L'outil delete-resource supprime n'importe quel element (resource, prompt ou tool) par son id.

URL MCP locale

L'endpoint MCP local est disponible a cette adresse :

https://ragor.frnx.dev/mcp

Connexion en une commande (Claude Code)

claude mcp add --transport http ragor https://ragor.frnx.dev/mcp

Configuration Claude Desktop

Pour connecter Claude Desktop au serveur MCP, utilisez cette configuration (fichier ~/.claude/claude_desktop_config.json) :

Sans token d'authentification

{
  "mcpServers": {
    "ragor": {
      "type": "http",
      "url": "https://ragor.frnx.dev/mcp"
    }
  }
}

Avec token d'authentification

{
  "mcpServers": {
    "ragor": {
      "type": "http",
      "url": "https://ragor.frnx.dev/mcp",
      "headers": {
        "Authorization": "Bearer <votre-token>"
      }
    }
  }
}

Important

Cette configuration suppose que le serveur MCP est disponible a https://ragor.frnx.dev/mcp

Tester la connexion

Pour verifier que le serveur MCP repond, lancez cette commande dans le terminal :

curl -s -D - -X POST https://ragor.frnx.dev/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'

Une reponse 200 avec un en-tete Mcp-Session-Id indique que le serveur MCP repond.

Limitations connues (MVP)

Sessions en memoire

Les ressources sont persistees dans data/resources.json, mais les sessions MCP sont en memoire : redemarrer le serveur force les clients a se reconnecter.

Pas d'OAuth

L'authentification se limite a un token Bearer statique (optionnel). Les connecteurs web qui imposent OAuth ne sont pas encore supportes nativement.

HTTP en local

Le serveur ecoute en HTTP sur localhost. Pour Claude.ai ou ChatGPT, exposer une URL publique HTTPS via un tunnel (cloudflared, ngrok).

Clients supportes

Teste avec Claude Code et Claude Desktop (Streamable HTTP). Le CORS est active, donc les clients navigateur fonctionnent une fois l'URL exposee en HTTPS.

Authentification (optionnel)

Si vous avez defini une variable d'environnement NUXT_API_TOKEN, les modifications (POST, PUT, DELETE) requierent un token Bearer ; les appels API utilisateur peuvent aussi utiliser ce token :

curl -s -X POST https://ragor.frnx.dev/mcp \
  -H "Authorization: Bearer <votre-token>" \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"curl","version":"1.0"}}}'