> ## Documentation Index
> Fetch the complete documentation index at: https://void-2d69096f.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# SmartPDF-MCP Overview

> Professional Document Extraction and autonomous tool for AI Agents.

A high-performance tool that transforms messy PDF documents into clean, usable data. We evolved this from a standard FastAPI web server into a fully autonomous Model Context Protocol (MCP) tool for AI Agents.

> [!NOTE]
>
> **Cost Optimization & API Utilization:** Currently, we do not use bulk uploading to send massive folders of PDFs to the AI at once. To protect our API utilization limits and prevent high compute costs, the MCP server uses local Python scripts to pre-scan and filter documents (e.g., searching for the keyword "Java") *before* triggering the Gemini API for deep extraction.

## 🚀 The Architecture Journey

Here is how the project evolved from a basic web server into an autonomous AI tool.

**1. Part 1: The API Gateway (The Menu)**

We built a professional API foundation using **FastAPI**.

* **The Result:** An interactive dashboard (Swagger UI) that allows anyone to upload files securely.
* **Real-World Value:** Created a bridge that lets the internet "talk" to our Python code.

**2. Part 2: The Extraction Engine (The Kitchen)**

We integrated **PyMuPDF (fitz)** to "rip open" PDFs and pull out the data.

* **The Result:** Successfully processed real-world resumes, instantly extracting raw text like names, skills (Java, MySQL, Spring Boot), and contact info.
* **Real-World Value:** This replaces hours of manual data entry with a 1-second automated pipeline.

**3. Part 3: The AI Brain (The Head Chef)**

We connected our data extraction pipeline to Google's **Gemini 2.5 Flash** AI model using the new `google-genai` SDK.

* **The Result:** The AI reads the extracted text, understands the context, and intelligently identifies the candidate's exact Name, Role, Phone Number, and Technical Skills.
* **Real-World Value:** We bridge the gap between backend code and modern AI. We aren't just reading data anymore; we are *understanding* it.

**4. Part 4: The Bento Box (Structured JSON)**

We forced the AI to stop returning conversational paragraphs and start returning strict, database-ready JSON using **Pydantic**.

* **The Result:** The AI now outputs a perfect dictionary (e.g., `{"full_name": "Dinesh Thandapani", "top_5_technical_skills": ["Java"]}`).
* **Real-World Value:** This is enterprise-grade engineering. Frontend websites and SQL databases cannot read paragraphs; they require strict JSON.

**5. Part 5: The MCP Server (The Autonomous Drive-Thru)**

We converted the core engine into an **MCP Server**, allowing autonomous AI agents to use this pipeline as a digital tool.

* **The Result:** We built an intelligent `find_candidates_by_skill` search engine.
* **Real-World Value:** AI agents (like Claude Desktop) can now use this pipeline autonomously to find the exact candidates they need, saving massive amounts of API compute costs by filtering locally first.

***

## 📖 Simple Coding Dictionary

If you are looking at the codebase, here is a quick translation guide for the core technologies used in this project.

> **Core Backend**
>
> * **`async def` (The Multitasker):** Imagine a chef. A normal function stares at boiling water and does nothing else. `async def` allows the chef to chop onions while the water heats up. It makes the server lightning fast.
> * **`await` (The Bookmark):** This tells the code: "Pause here until the file is fully downloaded, then resume exactly where you left off."
> * **`fitz` (The Translator):** The internal name for PyMuPDF. It’s the "brain" that knows how to read PDF formatting and turn it into simple text.

> **AI & Data Structure**
>
> * **`genai.Client` (The Waiter):** This is our secure connection to Google. It uses our API key to prove we are allowed in, and it carries our raw data to the AI model.
> * **`Pydantic / BaseModel` (The Bento Box Maker):** A strict template builder. We use it to tell the AI: *"You MUST put the name in this exact compartment, and the skills in this exact list."*
> * **`response_mime_type` (The To-Go Box Rule):** By setting this to `application/json`, we forbid the AI from talking in plain English paragraphs and force it to use computer-friendly JSON.

> **MCP & Automation**
>
> * **`FastMCP` (The Food Truck):** We packed up our kitchen so we can take it directly to the AI agents. It replaces the traditional FastAPI restaurant building.
> * **`@mcp.tool()` (The Menu Item):** A label we put on our Python function that tells AI agents, "Hey! You are allowed to order this specific action."
> * **`os` & `glob` (The Pantry Searchlights):** Built-in Python tools that allow our code to instantly scan a massive folder and find every single PDF ingredient before we start cooking.

***

## 🛠️ Tech Stack

> **Python 3.12+**
>
> The core programming language powering the backend.

> **MCP**
>
> The open standard for AI Agent tool integration.

> **Google GenAI SDK**
>
> Connecting our server to the Gemini 2.5 Flash model.

> **PyMuPDF & Pydantic**
>
> High-speed PDF manipulation and strict data validation.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.