ragifix-mcp

Servidor MCP (Model Context Protocol, transporte Streamable HTTP) que expone una base ragifix a un cliente de chat compatible (búsqueda, adición, eliminación, listado de documentos).

Sumario

• Instalación vía Docker

• Instalación vía paquete .deb

• Instalación en entorno de desarrollo

• Configuración para pegar en el cliente de chat

• Herramientas expuestas

• Acceso remoto

Related MCP server: docrag

Instalación vía 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: por defecto (server.host: 127.0.0.1), el servidor debe seguir siendo alcanzable en local en la máquina que aloja también ragifix y el cliente de chat.

Verificar que el servicio se está ejecutando (se espera 401 sin token — es la señal de que el servidor responde):

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

Instalación vía paquete .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

La instalación (postinst) crea un entorno virtual de Python en /opt/ragifix-mcp/venv e instala allí las dependencias desde PyPI (ligero: mcp, httpx, starlette, uvicorn, pydantic — se requiere acceso a la red en el momento de apt install, el servicio queda luego sin conexión).

El paquete crea un usuario de sistema dedicado, /etc/ragifix-mcp/config.yaml y ragifix-mcp.env (a partir de los ejemplos), y una unidad 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

Instalación en entorno de desarrollo

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

Configuración para pegar en el cliente de chat

Una vez iniciado el servidor, declarar un servidor MCP remoto (transporte HTTP) en la configuración del cliente, con el formato estándar actual:

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

Reemplazar <RAGIFIX_MCP_TOKEN> por el valor configurado en ragifix-mcp.env (o RAGIFIX_MCP_TOKEN en desarrollo), y la URL por la dirección real del servidor si es diferente de 127.0.0.1:8422.

Algunos clientes más antiguos todavía no saben conectarse directamente a un servidor HTTP remoto y solo aceptan un comando local (command/args); en ese caso, usar un puente como mcp-remote:

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

Consulte la documentación del cliente de chat utilizado para saber dónde pegar esta configuración (archivo de configuración MCP o interfaz de gestión de conectores/servidores MCP).

Herramientas expuestas

Acceso remoto

Por defecto (server.host: 127.0.0.1), el servidor solo es alcanzable desde la máquina local — algo adecuado para un cliente de chat que se ejecuta en la misma máquina (p. ej.: Claude Desktop en local).

Para un cliente de chat remoto, son necesarios dos cambios:

1. server.host en config.yaml: cambiar a 0.0.0.0 (todas las interfaces) o a la IP de la interfaz de red correspondiente. Se registra una advertencia al inicio mientras host no sea local, para recordar este punto.

2. TLS: este servidor no termina TLS por sí mismo. Colocar un reverse-proxy (nginx, Caddy, Traefik...) delante, que gestione el certificado y retransmita internamente hacia http://127.0.0.1:<port>/mcp. Ejemplo mínimo con Caddy:

   mcp.exemple.fr {
       reverse_proxy 127.0.0.1:8422
   }

   La url declarada en el lado del cliente de chat pasa entonces a ser https://mcp.exemple.fr/mcp.

El token dedicado (RAGIFIX_MCP_TOKEN) sigue siendo la protección a nivel de aplicación en ambos casos — el TLS protege el transporte, el token protege el acceso.