# marketlens-llm-mcp

![Python 3.11](https://img.shields.io/badge/python-3.11-blue.svg)
![License](https://img.shields.io/badge/license-MIT-green.svg)
![Docker](https://img.shields.io/badge/docker-enabled-blue.svg)
![LangChain](https://img.shields.io/badge/framework-LangChain-orange.svg)

DeepSeek LLM semantic enrichment pipeline exposed via a FastMCP Model Context Protocol server. Performs sentiment analysis, category mapping, and attribute extraction on raw product data.

## Architecture
This microservice is part of the MarketLens AI Platform. It is designed to be decoupled from the scraping layer, communicating via standardized schemas and file-based or artifact-based storage.

- **Enricher Agent**: Uses LangChain and DeepSeek to process raw product data into enriched metadata.
- **MCP Server**: Provides a Model Context Protocol interface to expose product intelligence tools.

## MCP Tools Exposed
- `get_top_products(limit: int)`: Returns the top ranked products.
- `get_cluster_summary(cluster_id: int)`: Provides aggregate metrics for specific product clusters.

## Quick Start
1. Clone the repository.
2. Install dependencies:
   ```bash
   pip install -r requirements.txt
   ```
3. Set your environment variables (see `.env.example`).
4. Run the enrichment pipeline:
   ```bash
   PYTHONPATH=. python llm_agents/main.py
   ```
5. Start the MCP server:
   ```bash
   PYTHONPATH=. python llm_agents/mcp_server.py
   ```

## Environment Variables
- `DEEPSEEK_API_KEY`: Required for LLM enrichment.
- `TOP_PRODUCTS_PATH`: (Optional) Override path for the ranked products dataset.
- `MCP_TRANSPORT`: (Optional) `stdio` (default) or `sse`.

## Docker Usage
Build the image:
```bash
docker build -t marketlens-llm-mcp .
```
Run the container:
```bash
docker run -e DEEPSEEK_API_KEY=your_key marketlens-llm-mcp
```

## Part of the MarketLens AI Platform
This service integrates with the wider MarketLens ecosystem:
1. **Scraping** (Source)
2. **Enrichment** (This service)
3. **ML Pipeline** (Training & Ranking)
4. **Dashboard** (UI)

---
**Author:** Yassine Kamouss — FST Tanger, LSI 2, 2025/2026