PDF MCP Analyser 📚⚡

Un server Model Context Protocol (MCP) leggero e attento alla privacy, scritto in Python. Consente ai modelli linguistici locali (LLM) di analizzare in modo intelligente manuali e libri di testo in PDF di centinaia di pagine, mappando i riassunti delle lezioni sull'intervallo esatto di pagine con motivazioni dettagliate.

Progettato per MacBook Apple Silicon (serie M) e ottimizzato per un'elaborazione 100% locale e a costo zero tramite Ollama e Tesseract OCR.

Caratteristiche

• 🎯 Mappatura precisa delle pagine: Individua le sezioni del libro di testo rilevanti per i riassunti delle lezioni o per gli argomenti del programma.

• 🔒 100% Privato e Locale: Utilizza Ollama per embeddings e sintesi: non sono necessarie chiavi API esterne o crediti cloud.

• 🔍 OCR Integrato: Utilizza Tesseract OCR per leggere PDF scansionati e pagine di manuali senza testo selezionabile.

• 🧠 Sintesi del contesto intelligente: Genera brevi spiegazioni sul perché determinate sezioni sono rilevanti per i tuoi obiettivi di studio.

• 🔌 Compatibilità MCP Universale: Supporta i trasporti stdio e streamable-http per client MCP come Cline (VS Code), Cursor, Claude Desktop, Chatbox, ChatGPT Desktop.

Related MCP server: PDF RAG MCP Server

🛠 Tech Stack

• Protocollo: Model Context Protocol (MCP) (trasporto streamable-http predefinito, stdio disponibile)

• Runtime: Python 3.10+

• Embeddings: nomic-embed-text tramite Ollama

• Ragionamento locale / Sintesi: qwen3:8b (o qwen2.5-coder:7b) tramite Ollama

• Motore OCR: Tesseract (invocato tramite pytesseract e il binario di sistema)

📋 Prerequisiti

1. Python 3.10+

2. Ollama: Installato e in esecuzione sul tuo sistema (ollama.com).

3. Modelli locali:

   ollama pull nomic-embed-text
   ollama pull qwen3:8b

4. Tesseract OCR (macOS):

   brew install tesseract tesseract-lang

   Se il server MCP viene avviato da un client con un PATH limitato, il codice cerca automaticamente i percorsi Homebrew standard (/opt/homebrew/bin/tesseract e /usr/local/bin/tesseract). In alternativa è possibile impostare TESSERACT_CMD con il percorso assoluto del binario.

🚀 Installazione

1. Clona il repository:

   git clone https://github.com/NotReallyEight/pdf-mcp-analyser.git
   cd pdf-mcp-analyser

2. Crea e attiva un ambiente virtuale:

   python3 -m venv venv
   source venv/bin/activate

3. Installa le dipendenze:

   pip install -r requirements.txt

⚙️ Configurazione

Aggiunta ai client MCP (ad es. Cline, Cursor, Claude Desktop)

Aggiungi la seguente configurazione al file di impostazioni MCP del tuo client (ad es. cline_mcp_settings.json o claude_desktop_config.json):

{
  "mcpServers": {
    "pdf-mcp-analyser": {
      "command": "/PERCORSO/ASSOLUTO/A/pdf-mcp-analyzer/venv/bin/python3",
      "args": [
        "/PERCORSO/ASSOLUTO/A/pdf-mcp-analyzer/pdf_mcp_server.py"
      ],
      "env": {
        "MCP_TRANSPORT": "stdio",
        "PDF_BASE_DIRS": "/Users/NOME_UTENTE"
      },
      "timeout": 300,
      "disabled": false,
      "autoApprove": [
        "analyze_lesson_ranges"
      ]
    }
  }
}

La configurazione precedente usa stdio, necessario per i client che avviano il server tramite il campo command. Per avviare invece il server come endpoint HTTP autonomo, ometti MCP_TRANSPORT (il valore predefinito è streamable-http): il server ascolta su 127.0.0.1:8000.

"MCP_TRANSPORT": "streamable-http"

Nota: Sostituisci /PERCORSO/ASSOLUTO/A/ e NOME_UTENTE con i percorsi reali presenti sul tuo Mac.

Variabili d'ambiente

Le impostazioni principali sono sovrascrivibili senza modificare il codice:

Per esempio:

"env": {
  "MCP_TRANSPORT": "streamable-http",
  "PDF_BASE_DIRS": "/Users/NOME_UTENTE/Downloads:/Volumes/Eight-SSD",
  "OCR_LANG": "ita+eng",
  "PDF_CACHE_DIR": "/Users/NOME_UTENTE/.cache/pdf-mcp-analyser"
}

🧰 Strumenti MCP Disponibili

analyze_lesson_ranges

Analizza un documento PDF locale confrontandolo con il riassunto di una lezione per individuare gli intervalli di pagine corrispondenti e le relative spiegazioni.

💬 Esempio di Utilizzo

Incolla nel prompt di chat del tuo client MCP:

SYSTEM INSTRUCTION: Ignora il workspace e i file di sistema. Usa direttamente il tool MCP pdf-mcp-analyser.

Esegui la funzione analyze_lesson_ranges:
PDF: "/Users/nomeutente/Downloads/Sistemi-Operativi.pdf"
Lesson summary: "Lezione sulla schedulazione della CPU: criteri, algoritmi FCFS, SJF, Round Robin e valutazione."

📜 Licenza

Questo progetto è distribuito sotto Licenza MIT - vedi il file LICENSE per ulteriori dettagli.