Metadata-Version: 2.4
Name: docsite-ingest-mcp
Version: 1.0
Summary: Scrape documentation websites, index in Chroma, expose retrieval through MCP
Author-email: Valentin JOURNET <valentin.journet@talan.com>
License: MIT
Project-URL: Homepage, https://github.com/talan-digital-factory/docsite-ingest-mcp
Project-URL: Repository, https://github.com/talan-digital-factory/docsite-ingest-mcp
Project-URL: Issues, https://github.com/talan-digital-factory/docsite-ingest-mcp/issues
Project-URL: Documentation, https://github.com/talan-digital-factory/docsite-ingest-mcp#readme
Keywords: mcp,documentation,vector-search,rag,chromadb,web-scraper
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Classifier: Topic :: Internet :: WWW/HTTP
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: beautifulsoup4>=4.12.3
Requires-Dist: chromadb>=0.5.5
Requires-Dist: ddgs>=9.14.4
Requires-Dist: httpx>=0.27.0
Requires-Dist: lxml>=5.2.2
Requires-Dist: mcp>=1.10.1
Requires-Dist: sentence-transformers>=3.0.1
Provides-Extra: dev
Requires-Dist: pytest>=7.0; extra == "dev"
Requires-Dist: black>=23.0; extra == "dev"
Requires-Dist: ruff>=0.1.0; extra == "dev"
Requires-Dist: mypy>=1.0; extra == "dev"
Dynamic: license-file

# Deploiement Utilisateur - docsite-ingest-mcp

Ce guide est pense pour un utilisateur qui veut:

- installer l outil via pip
- le brancher comme serveur MCP dans son projet
- ingester une documentation sans config complexe
- utiliser la recherche de documentation depuis son assistant

## 1) Prerequis

- Python 3.11+
- pip
- un client MCP (Claude Desktop, VS Code MCP, etc.)

## 2) Installation via pip

Installez le package dans votre environnement projet (venv recommande):

```bash
pip install docsite-ingest-mcp
```

Verifiez l installation:

```bash
python -m docsite_ingest_mcp --help
```

## 3) Lancer le serveur MCP localement

```bash
python -m docsite_ingest_mcp serve
```

Le serveur expose les tools MCP suivants:

- list_indexed_doc_sites()
- search_documentation(query, top_k=5, site_id=None, topic=None)
- suggest_documentation_urls(topic, max_results=5)
- ingest(url, incremental=True, max_pages=1200, delay=0.2)
- ingest_and_register_topic(topic, url, incremental=True, max_pages=1200, delay=0.2)
- ingest_status(job_id)
- wait_for_ingest_completion(job_id, poll_interval_seconds=2.0, timeout_seconds=600.0)

## 4) Workflow recommande (nouveau)

### Cas A - l utilisateur fournit deja une URL de doc

1. Appeler ingest_and_register_topic(topic, url).
2. Suivre le job avec une des deux options:
  - polling: ingest_status(job_id) pour afficher la progression (progress_percent, phase, visited_urls, pages_kept, queued_urls)
  - attente bloquante: wait_for_ingest_completion(job_id) pour etre notifie quand le job finit
3. Rechercher ensuite avec search_documentation(..., topic=...).

### Cas B - l utilisateur ne fournit pas d URL

1. Appeler suggest_documentation_urls(topic).
2. Proposer les suggestions a l utilisateur.
3. Une fois l URL validee, appeler ingest_and_register_topic(topic, url).
4. Suivre le job via ingest_status(job_id) ou wait_for_ingest_completion(job_id).

## 5) Garde-fous integres (important)

- Les suggestions web visent des pages de depart de documentation (pas des roots generiques quand une meilleure page est detectable).
- ingest valide l URL avant mise en file:
  - si la cible retourne HTTP 404, le serveur repond avec un payload explicite
  - le message demande une URL de premiere page de doc (exemple: .../docs/intro)
- ingest_and_register_topic reutilise ingest:
  - si URL invalide (404), la route topic -> site nest pas enregistree
  - le payload inclut route_registered=false

## 6) Integrer le MCP dans votre projet

Exemple de configuration MCP (format type mcpServers):

```json
{
  "mcpServers": {
    "docsite-ingest-mcp": {
      "command": "python",
      "args": ["-m", "docsite_ingest_mcp", "serve"],
      "cwd": "C:/path/to/your/project"
    }
  }
}
```

Recommandation:

- utilisez le Python du venv du projet plutot que le Python systeme
- gardez un chemin absolu stable pour command/cwd

Exemple Windows (venv):

```json
{
  "mcpServers": {
    "docsite-ingest-mcp": {
      "command": "C:/path/to/your/project/.venv/Scripts/python.exe",
      "args": ["-m", "docsite_ingest_mcp", "serve"],
      "cwd": "C:/path/to/your/project"
    }
  }
}
```

## 7) Auth Hugging Face (optionnel)

Si votre environnement exige un token HF pour le modele d embedding:

```bash
# Windows PowerShell
$env:HF_TOKEN = "hf_xxx"

# Linux/macOS
export HF_TOKEN="hf_xxx"
```

Variables reconnues:

- HUGGINGFACE_HUB_TOKEN
- HF_TOKEN
- HUGGINGFACE_TOKEN

## 8) Verification rapide

1. Demarrer le serveur.
2. Dans le client MCP, appeler list_indexed_doc_sites().
3. Si vide, lancer ingest_and_register_topic(topic, url).
4. Poller ingest_status(job_id).
  - ou appeler wait_for_ingest_completion(job_id) pour un retour final direct
5. Rejouer search_documentation(query, topic=...).

## 9) Depannage

### La commande ne fonctionne pas

```bash
pip install --upgrade docsite-ingest-mcp
python -m docsite_ingest_mcp --help
```

### Le MCP ne voit pas le module

Cause frequente: le client utilise un autre Python que celui du venv projet.

Solution: configurez command avec le chemin absolu vers .venv/Scripts/python.exe (Windows) ou .venv/bin/python (Linux/macOS).

### Ingestion refusee avec invalid_start_url

Votre URL ne pointe pas vers une page valide de documentation (404).

Solution: utilisez une URL de premiere page de doc (exemple: /docs/intro), ou passez par suggest_documentation_urls(topic).

## 10) Liens utiles

- Guide developpeur: DEVELOPMENT.md
- Vue d ensemble: README.md
