book-recommender

# 📘 Book Recommender

📝 Description

This project builds a Book Recommendation System powered by Generative AI and the Model Context Protocol (MCP).
It uses real data from the Goodreads dataset (via Kaggle) and combines Python-based data processing with an AI agent capable of understanding user prompts, translating genres, and recommending books based on genre, page count, and ratings.

The project was developed collaboratively to practice version control, team workflows, and AI tool integration in a real-world Data Science scenario.

Related MCP server: goodreads-mcp

⚙️ Technologies and Tools Used

• Python 3.11

• pandas – data manipulation

• numpy – numerical operations

• tqdm – progress tracking

• OpenAI API – language model for the AI agent

• LangGraph – for building the ReAct-style reasoning agent

• MCP (Model Context Protocol) – connects the AI agent to external tools

• Jupyter Notebook – exploratory data analysis and prototyping

💻 How to Run the Project

Step-by-step instructions to run it locally:

# Clone the repository
git clone https://github.com/nalugomesv/book-recommender.git

# Enter the project folder
cd book-recommender

# (Optional) Create a virtual environment
python -m venv .venv
.\.venv\Scripts\activate    # Windows
# or
source .venv/bin/activate   # Linux/Mac

# Install dependencies
pip install -r requirements.txt

# Run the core script
python -m src.buscador --genero "romance" --paginas 120

# Or search by title
python -m src.buscador --titulo "Dune"

🧩 Project Structure

.

├── src/

│ ├── buscador.py # Core search functions (genre, pages, title)

│ └── server_mcp.py # Local MCP server exposing tools to the AI agente

├── notebooks/ # Exploratory and test notebooks

├── data/ # Dataset (not versioned)

├── outputs/ # Generated artifacts (ignored)

├── .env.example # Environment variable example

├── requirements.txt # Dependencies

└── README.md # Project documentation

👥 Collaborators

⦁ Ana Luiza Gomes Vieira (@nalugomesv) ⦁ Arthur Mendes Fernandes (@thuplex)

🎯 Future Improvements

• Add more filtering options (author, publication year, etc.)

• Integrate external MCP APIs (HTTP/SSE)

• Add evaluation metrics (Precision@K, MAP)

• Improve LLM reasoning prompts for more accurate recommendations

📄 License

This project is licensed under the MIT License.

🧠 Acknowledgments

This project was inspired by the PrograMaria – Data & Generative AI Sprint,
specifically the Workshop on Predictive Query Models (MCP) and Book Recommendation System using Generative AI.