KFabric MCP Server

KFabric

KFabric est une plateforme Python-first de fabrication de corpus documentaires. Le projet vise un problème très concret : aider à construire un corpus traçable, pondéré et réutilisable à partir de sources hétérogènes, avant même de brancher un assistant RAG conversationnel.

Au lieu de passer directement du web au chat, KFabric se concentre d'abord sur la qualité du matériau documentaire :

• découverte de documents candidats
• collecte et normalisation
• scoring et décision documentaire
• récupération de fragments utiles dans des documents rejetés
• consolidation et synthèse
• préparation d'artefacts indexables pour des usages RAG futurs

Pourquoi KFabric

Dans beaucoup de pipelines RAG, la vraie faiblesse n'est pas le modèle mais le corpus. KFabric part de l'idée inverse :

• un bon corpus vaut mieux qu'une mauvaise conversation bien emballée
• les documents faibles contiennent parfois des signaux utiles à sauver
• la traçabilité et la prudence documentaire doivent exister dès le MVP
• un serveur MCP et une API REST doivent exposer exactement le même coeur métier

Ce que fait le MVP

Le MVP actuel couvre déjà un flux bout en bout :

1. créer une requête documentaire
2. découvrir des documents candidats
3. collecter et parser un document
4. attribuer un score global et des sous-scores
5. accepter, rejeter, ou rejeter avec récupération partielle
6. consolider les fragments sauvés
7. générer une synthèse documentaire prudente
8. construire un corpus final
9. préparer un artefact d'indexation

Points forts

• API REST FastAPI pour piloter le pipeline corpus
• serveur MCP natif en Python
• workers Celery pour les traitements longs
• UI légère en Jinja2, HTMX et Alpine.js
• modèles SQLAlchemy 2 et migration Alembic initiale
• mode sécurisé activé par défaut
• approche corpus-first avant chat RAG complet

Architecture

Le projet est structuré comme un monolithe modulaire Python :

• `kfabric/api` : routes REST, dépendances, sérialisation
• `kfabric/mcp` : tools, resources, prompts, serveur MCP
• `kfabric/domain` : contrats métier et enums
• `kfabric/services` : scoring, salvage, déduplication, synthèse, corpus
• `kfabric/infra` : base de données, observabilité, persistance
• `kfabric/workers` : tâches Celery
• `kfabric/web` : interface serveur rendue
• `migrations` : migration initiale
• `tests` : tests API, MCP et logique métier

Stack technique

• Python 3.12
• FastAPI
• Pydantic v2
• SQLAlchemy 2 + Alembic
• Celery + Redis + RabbitMQ
• PostgreSQL prêt pour la production
• MCP Python SDK
• Jinja2 + HTMX + Alpine.js

Démarrage rapide

Installation minimale :

python3.12 -m venv .venv
source .venv/bin/activate
pip install setuptools wheel
pip install -e ".[dev]" --no-build-isolation
cp .env.example .env
uvicorn kfabric.api.app:app --reload

Si tu veux aussi les dépendances plus lourdes liées aux connecteurs et à la préparation RAG étendue :

pip install -e ".[dev,extended]" --no-build-isolation

L'application démarre ensuite sur :

• UI : http://127.0.0.1:8000/
• API : http://127.0.0.1:8000/docs

Commandes utiles via `Makefile` :

make install-extended
make test
make run-api
make stack-up

Async broker-only

Les traitements asynchrones de KFabric fonctionnent maintenant en mode broker-only :

• les routes et boutons async doivent être dispatchés via Celery
• RabbitMQ et Redis doivent être disponibles
• le worker KFabric doit être lancé
• il n'existe plus de fallback local en thread si le broker ne répond pas

Variables recommandées dans `.env.example` :

KFABRIC_PREFER_CELERY_TASKS=true
KFABRIC_CELERY_ALWAYS_EAGER=false

Dans docker-compose.yml, les services KFabric utilisent toujours les hôtes internes postgres, redis, rabbitmq et qdrant, même si ton fichier .env contient des URLs localhost pour un lancement hors Docker.

En environnement de test, KFABRIC_CELERY_ALWAYS_EAGER=true reste utile pour exécuter les tâches immédiatement sans broker externe.

Exploitation V1

KFabric dispose maintenant d'un mode d'exploitation local plus stable :

• docker-compose.yml avec migrations, healthchecks et volume de stockage
• Makefile pour les commandes courantes
• readiness détaillée sur /api/v1/readiness
• mode async broker-only avec worker Celery dédié

Le runbook dédié est disponible dans `docs/v1-runbook.md`.

Sécurité et accès

KFabric peut fonctionner sans authentification en local, mais dès qu'une clé API est configurée via `KFABRIC_API_KEY`, l'accès est protégé :

• l'API REST accepte X-API-Key ou Authorization: Bearer ...
• l'interface web demande