Basic

Un serveur MCP (Model Context Protocol) avec une interface React, exposant des outils, ressources et prompts autour des utilisateurs GitHub, de la météo et d'un système d'étude de documents (PMP).

Structure du projet

basic-mcp/
├── server/
│   ├── main.ts            # Point d'entrée — transport stdio
│   ├── server-http.ts     # Point d'entrée — transport HTTP (Streamable HTTP)
│   └── src/
│       ├── application/   # Cas d'usage (GetGitHubUser, GetWeather)
│       ├── domain/        # Entités et ports (interfaces)
│       ├── infrastructure/
│       │   ├── ocr/
│       │   │   ├── tesseractWorker.ts   # Worker Tesseract singleton (cache local)
│       │   └── └── imagePreprocessor.ts # Pipeline Sharp (gris → upscale → normalize → sharpen → binarize)
│       │   ├── repositories/    # Appels APIs externes
│       │   ├── search/
│       │   │   └── bm25Engine.ts    # Moteur BM25 (TypeScript pur, zéro dépendance)
│       │   └── vision/
│       │       └── githubVisionService.ts # GPT-4o Vision (fallback optionnel)
│       └── interface/
│           ├── chat/      # Route /chat (Ollama + outils via MCP in-process)
│           └── mcp/
│               ├── tools/     # Outils MCP
│               ├── resources/ # Ressources MCP
│               └── prompts/   # Prompts MCP
├── client/
│   └── src/
│       ├── application/hooks/  # useMcpTool, useMcpResource, useMcpPrompt, useChat
│       ├── domain/             # Entités côté client
│       ├── infrastructure/mcp/ # Adaptateur MCP client (HTTP)
│       └── presentation/       # Composants React
└── output/
    └── document-index.json     # Index BM25 du document (généré par extract-document-index)

Prérequis

• Node.js >= 18
• npm >= 9
• Ollama avec le modèle llama3.2 pour le chat local

ollama pull llama3.2

Installation

npm install
cd client && npm install

Variables d'environnement

Créez un fichier .env à la racine du projet :

# Optionnel — fallback GPT-4o Vision si confiance OCR < 40%
# Sans ce token, l'extraction est 100% locale (Tesseract + Sharp)
GITHUB_TOKEN=ghp_xxxxxxxxxxxxxxxxxxxx

# Optionnel — langue OCR Tesseract (défaut : fra)
OCR_LANGUAGE=fra

# Optionnel — modèle Ollama pour le chat et generate-quiz (défaut : llama3.2)
OLLAMA_MODEL=llama3.2

# Optionnel — chemin vers le dossier de chapitres à indexer
DOCUMENT_BASE_PATH=./Management_de_project_Logiciels

Sans GITHUB_TOKEN, tout le projet fonctionne 100% hors ligne :

• OCR via Tesseract + prétraitement Sharp
• Chat et quiz via Ollama local
• Recherche documentaire via BM25

Démarrage

Serveur seul (stdio)

npm run start

Serveur HTTP (port 3001)

npm run start:http

Serveur HTTP + Interface React

npm run start:ui

L'interface est accessible sur http://localhost:5173.
Le serveur MCP HTTP écoute sur http://localhost:3001/mcp.
Le endpoint de chat est disponible sur http://localhost:3001/chat.

Outils MCP disponibles

Outils généraux

Outil	Paramètres	Description
ping-server	message	Vérifie que le serveur répond
get-github-user	username	Retourne les infos d'un utilisateur GitHub
get-weather	city ou latitude + longitude	Retourne la météo actuelle (Open-Meteo, sans clé API)
read-log-file	filename, lastLines (optionnel)	Lit un fichier .log du dossier logs/

Outils document / étude PMP

Outil	Paramètres	Description
extract-document-index	chapters, force	Extrait le texte des images via Tesseract + Sharp (local). Fallback GPT-4o Vision si confiance OCR < 40% et GITHUB_TOKEN présent
ask-document	question, chapter, pmpFocus	Recherche les passages pertinents via BM25 puis synthèse via Ollama (fallback GPT-4o). Mode BM25 pur si aucun LLM disponible
generate-quiz	chapter, count, domain	Génère des QCM style examen PMP via Ollama (fallback GPT-4o)
generate-document-pdf	chapters, mode, filename	Génère un PDF du document (images, texte ou mixte)

Ressources MCP disponibles

URI	Description
github://users/{username}	Profil GitHub d'un utilisateur
weather://forecast/{latitude},{longitude}	Météo pour des coordonnées GPS
weather://city/{city}	Météo pour une ville
logs://{filename}	Contenu brut d'un fichier .log
document://chapters	Liste des chapitres disponibles dans l'index

Prompts MCP disponibles

Prompt	Paramètres	Description
analyze-weather	city, language (fr/en)	Analyse la météo d'une ville avec conseils pratiques
compare-weather	city1, city2	Compare la météo entre deux villes
summarize-github-user	username	Rédige une biographie professionnelle à partir du profil GitHub

Architecture

Le projet suit les principes de la Clean Architecture :

• Domain — entités et interfaces de ports (aucune dépendance externe)
• Application — cas d'usage orchestrant la logique métier
• Infrastructure — implémentations des ports : repositories, OCR, vision, moteur BM25
• Interface — exposition via MCP (tools, resources, prompts) et via REST (/chat)

Chat et MCP : intégration in-process

Le endpoint /chat ne duplique pas les outils MCP. Il crée un client MCP connecté au serveur en mémoire via InMemoryTransport, découvre dynamiquement tous les outils enregistrés et les expose au LLM (Ollama llama3.2) via le Vercel AI SDK :

/chat request
    └─► mcpClient.listTools()       ← tous les outils MCP automatiquement
    └─► streamText(ollama, tools)   ← le LLM choisit et appelle les outils
    └─► mcpClient.callTool(...)     ← exécution via MCP in-process

Pipeline OCR local (Tesseract + Sharp)

L'extraction de texte est entièrement locale. imagePreprocessor.ts applique une chaîne de transformations mathématiques avant de passer l'image à Tesseract :

Image originale
    │
    ├─ 1. Niveaux de gris      Y = 0.299·R + 0.587·G + 0.114·B
    ├─ 2. Upscale ×2           si largeur < 1800px (interpolation Lanczos 3)
    ├─ 3. Normalize             étire l'histogramme → [0, 255]
    ├─ 4. Unsharp Mask          renforce les bords des caractères (σ=1.5)
    ├─ 5. Binarisation          seuil 128 → noir/blanc pur
    └─ Buffer PNG → Tesseract

Si la confiance Tesseract est < 40% et que GITHUB_TOKEN est présent, GPT-4o Vision prend le relais pour cette page uniquement.

Moteur de recherche BM25

ask-document utilise un moteur BM25 implémenté en TypeScript pur (zéro dépendance) :

$$\text{score}(q, d) = \sum_{t \in q} \log\frac{N - n_t + 0.5}{n_t + 0.5} \times \frac{f(t,d) \cdot (k_1+1)}{f(t,d) + k_1 \cdot \left(1 - b + b \cdot \frac{|d|}{\text{avgdl}}\right)}$$

Avec $k_1 = 1.5$ et $b = 0.75$. Cela permet de retrouver les 5 passages les plus pertinents avant de les envoyer au LLM, réduisant la consommation de tokens de 5 à 10×.

Dépendances externes et niveau d'autonomie

Composant	Sans clé API	Avec GITHUB_TOKEN
OCR / indexation	Tesseract local	Tesseract + fallback GPT-4o Vision
Chat (/chat)	Ollama local	Ollama local
ask-document	BM25 + Ollama	BM25 + Ollama (fallback GPT-4o)
generate-quiz	Ollama local	Ollama local (fallback GPT-4o)
Météo / GitHub	APIs publiques (sans clé)	idem

APIs externes utilisées

API	Usage	Clé requise
GitHub REST API	Profils utilisateurs	Non
Open-Meteo Forecast	Données météo	Non
Open-Meteo Geocoding	Ville → coordonnées	Non
GitHub Models (GPT-4o)	Fallback vision OCR uniquement	Optionnel (GITHUB_TOKEN)