ragifix-mcp

Serveur MCP (Model Context Protocol, transport Streamable HTTP) qui expose une base ragifix à un client de chat compatible (recherche, ajout, suppression, listing de documents).

Sommaire

• Installation via Docker

• Installation via paquet .deb

• Installation en environnement de développement

• Configuration à coller dans le client de chat

• Outils exposés

• Accès distant

Related MCP server: docrag

Installation via Docker

git clone <url-du-dépôt> ragifix-mcp && cd ragifix-mcp

cp config.example.yaml config.yaml              # puis l'adapter
cp deploy/ragifix-mcp.env.example ragifix-mcp.env # puis renseigner les secrets

docker build -f deploy/docker/Dockerfile -t ragifix-mcp .

docker run -d \
  --name ragifix-mcp \
  --network host \
  --env-file ragifix-mcp.env \
  -v "$(pwd)/config.yaml:/etc/ragifix/config.yaml:ro" \
  ragifix-mcp

--network host : par défaut (server.host: 127.0.0.1), le serveur doit rester joignable en local sur la machine qui héberge aussi ragifix et le client de chat.

Vérifier que le service tourne (401 attendu sans token — c'est le signe que le serveur répond) :

curl -s -o /dev/null -w "%{http_code}\n" http://127.0.0.1:8422/mcp \
  -X POST -H "Content-Type: application/json" -d '{}'

Installation via paquet .deb

git clone <url-du-dépôt> ragifix-mcp && cd ragifix-mcp

sudo apt-get install -y devscripts debhelper python3-venv python3-pip
dpkg-buildpackage -us -uc -b

sudo apt install -y ../ragifix-mcp_0.1.0-1_all.deb

L'installation (postinst) construit un environnement virtuel Python dans /opt/ragifix-mcp/venv et y installe les dépendances depuis PyPI (léger : mcp, httpx, starlette, uvicorn, pydantic — accès réseau requis au moment de apt install, service ensuite hors-ligne).

Le paquet crée un utilisateur système dédié, /etc/ragifix-mcp/config.yaml et ragifix-mcp.env (depuis les exemples), et une unité systemd ragifix-mcp.service.

sudo nano /etc/ragifix-mcp/config.yaml
sudo nano /etc/ragifix-mcp/ragifix-mcp.env
sudo systemctl enable --now ragifix-mcp
journalctl -u ragifix-mcp -f

sudo apt remove ragifix-mcp    # conserve la config
sudo apt purge ragifix-mcp     # supprime tout

Installation en environnement de développement

git clone <url-du-dépôt> ragifix-mcp && cd ragifix-mcp

python3 -m venv venv
source venv/bin/activate
pip install -e .

cp config.example.yaml config.yaml   # reste à côté du code, hors /etc

export RAGIFIX_MCP_TOKEN=dev-mcp-token
export RAGIFIX_API_TOKEN=dev-token    # le token de l'API ragifix visée

ragifix-mcp --config ./config.yaml

Configuration à coller dans le client de chat

Une fois le serveur démarré, déclarer un serveur MCP distant (transport HTTP) dans la configuration du client, au format standard actuel :

{
  "mcpServers": {
    "ragifix": {
      "url": "http://127.0.0.1:8422/mcp",
      "headers": {
        "Authorization": "Bearer <RAGIFIX_MCP_TOKEN>"
      }
    }
  }
}

Remplacer <RAGIFIX_MCP_TOKEN> par la valeur configurée dans ragifix-mcp.env (ou RAGIFIX_MCP_TOKEN en développement), et l'URL par l'adresse réelle du serveur si différente de 127.0.0.1:8422.

Certains clients plus anciens ne savent pas encore se connecter directement à un serveur HTTP distant et n'acceptent qu'une commande locale (command/args) ; dans ce cas, passer par un pont comme mcp-remote :

{
  "mcpServers": {
    "ragifix": {
      "command": "npx",
      "args": [
        "-y", "mcp-remote",
        "http://127.0.0.1:8422/mcp",
        "--header", "Authorization: Bearer <RAGIFIX_MCP_TOKEN>"
      ]
    }
  }
}

Se référer à la documentation du client de chat utilisé pour savoir où coller cette configuration (fichier de config MCP, ou interface de gestion des connecteurs/serveurs MCP).

Outils exposés

Accès distant

Par défaut (server.host: 127.0.0.1), le serveur n'est joignable que depuis la machine locale — adapté à un client de chat qui tourne sur la même machine (ex: Claude Desktop en local).

Pour un client de chat distant, deux changements sont nécessaires :

1. server.host dans config.yaml : passer à 0.0.0.0 (toutes les interfaces) ou à l'IP de l'interface réseau concernée. Un avertissement est loggué au démarrage tant que host n'est pas local, pour rappeler ce point.

2. TLS : ce serveur ne termine pas lui-même de TLS. Placer un reverse-proxy (nginx, Caddy, Traefik...) devant, qui gère le certificat et relaie vers http://127.0.0.1:<port>/mcp en interne. Exemple minimal avec Caddy :

   mcp.exemple.fr {
       reverse_proxy 127.0.0.1:8422
   }

   Le url déclaré côté client de chat devient alors https://mcp.exemple.fr/mcp.

Le token dédié (RAGIFIX_MCP_TOKEN) reste la protection applicative dans les deux cas — le TLS protège le transport, le token protège l'accès.