Metadata-Version: 2.4
Name: docsite-ingest-mcp
Version: 1.0.2
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 (uv recommande)

### Option A - installation globale avec uv (recommande)

```bash
uv tool install docsite-ingest-mcp
doc-ingest --help
```

Pour afficher le dossier d'installation des executables:

```bash
uv tool dir
```

Si la commande n'est pas visible, ajoutez ce dossier a votre `PATH`.

### Option B - installation projet avec uv

```bash
uv venv
uv pip install -e .
```

### Option C - installation via pip (fallback)

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

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

Pour installer la commande dans `~/.local/bin` (Linux/macOS):

```bash
python -m pip install --user docsite-ingest-mcp
export PATH="$HOME/.local/bin:$PATH"
doc-ingest --help
```

Important:

- Le package ne peut pas forcer le repertoire d'installation des executables.
- C'est `pip` (et son mode `--user`/venv/systeme) qui decide la destination.
- Si `doc-ingest` n'est pas trouve, verifiez que le dossier cible est dans votre `PATH`.

Verifiez l installation:

```bash
python -m docsite_ingest_mcp --help
doc-ingest --help
```

L'installation pip expose aussi une commande alias `doc-ingest` (en plus de `docsite-ingest-mcp`).
L'installation via `uv tool install` expose egalement ces deux commandes.

### Installer les skills/prompts client `/doc-ingest`

Apres installation, executez une fois:

```bash
doc-ingest install --target all
```

Emplacements par defaut utilises:

- Claude: `~/.claude/skills/doc-ingest` (`SKILL.md`, `SYSTEM_PROMPT.txt`)
- Copilot: `~/.copilot/instructions` (`doc-ingest.instructions.md`)
- GPT: `~/.doc-ingest/gpt` (`SYSTEM_PROMPT.txt`)
- Gemini: `~/.doc-ingest/gemini` (`SYSTEM_PROMPT.txt`)

Vous pouvez forcer un dossier de sortie explicite:

```bash
doc-ingest install --target gpt --output-dir ./out/prompts
```

Important: uv/pip ne peuvent pas executer un hook post-install universel pour configurer les clients LLM. Cette commande doit etre lancee manuellement une fois apres installation.

La commande `doc-ingest install` ecrit aussi des fichiers de configuration MCP client avec le Python et le `cwd` detectes automatiquement:

- Claude: `MCP_SERVER.json`
- Copilot: `doc-ingest.mcp.json`
- GPT/Gemini: `MCP_SERVER.json`

Par defaut, la config MCP generee utilise l'executable installe `doc-ingest` (par exemple dans `~/.local/bin` ou le dossier `Scripts`) avec `serve` comme argument. Le `cwd` par defaut est le dossier de cet executable.

Vous pouvez imposer les valeurs de config MCP:

```bash
doc-ingest install --target all --python-executable "C:/path/to/python.exe" --mcp-cwd "C:/path/to/project"
```

## 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

Option UX: l utilisateur peut taper `/doc-ingest <url>` dans le chat si son client mappe ce slash command vers le tool `ingest`.

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 choisie, appeler ingest(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

### 6.1 Mapping explicite de la commande client `/doc-ingest`

Point cle: le slash command est gere par le client. Le serveur expose le tool MCP `ingest` pour demarrer l'ingestion.

Important: l'installation pip ne peut pas enregistrer automatiquement `/doc-ingest` pour tous les LLM. Le mapping slash doit etre configure client par client (Claude, GitHub Copilot, GPT, Gemini, etc.).

Vous devez configurer le client pour transformer:

- `/doc-ingest <url>` -> `ingest(url="<url>")`

Comportement recommande cote client:

1. Appeler `ingest(url=...)`.
2. Recuperer le `job_id` et suivre avec `ingest_status` ou `wait_for_ingest_completion`.

### 6.2 Test rapide de la commande `/doc-ingest`

Une fois la regle client en place, validez ces cas:

1. URL directe:
  - `/doc-ingest https://playwright.dev/docs/intro`
  - attendu: retour avec `job_id`
2. URL invalide:
  - `/doc-ingest https://playwright.dev/docs`
  - attendu: `invalid_start_url` avec message explicite et suggestion potentielle
3. Suivi:
  - appeler `ingest_status(job_id)` puis eventuellement `wait_for_ingest_completion(job_id)`
  - attendu: progression puis statut final

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"
    }
  }
}
```

Configuration avec MCP_SYSTEM_PROMPT (recommande):

Important:

- MCP_SYSTEM_PROMPT est une variable d environnement transmise au processus MCP.
- Cette variable ne force pas a elle seule la politique d orchestration du client IA.
- Pour imposer MCP-first, configurez aussi les instructions du profil assistant dans votre client IA et desactivez les connecteurs concurrents (ex: Context7) pour ce profil/workspace.

```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",
      "env": {
        "HF_TOKEN": "hf_xxx",
        "MCP_SYSTEM_PROMPT": "HARD RULES: 1) docsite-ingest-mcp is the ONLY allowed connector for project documentation retrieval while available. 2) NEVER call Context7 (or any other doc connector) before attempting docsite-ingest-mcp. 3) For any project/API/config/troubleshooting/version question, always execute this sequence first: list_indexed_doc_sites(); search_documentation(query, topic=..., site_id=... when known). 4) Slash mapping rule: when user writes /doc-ingest <url>, call ingest(url=<url>) immediately. 5) If user asks to add a new documentation source without /doc-ingest: require explicit URL; if missing, call suggest_documentation_urls(topic), present candidates, get confirmation, then call ingest_and_register_topic(topic, url). 6) After ingestion starts, either (A) poll ingest_status(job_id) to show progress_percent/phase, or (B) call wait_for_ingest_completion(job_id) and notify user on completion. 7) If MCP has no relevant result, report that clearly and ask user whether to fallback to Context7; do not fallback automatically. 8) Final answers must cite source URLs returned by search_documentation."
      }
    }
  }
}
```

Conseils de personnalisation:

- Adaptez le texte du prompt a vos produits cibles en conservant la regle MCP-first.
- Gardez la regle de mapping explicite `/doc-ingest <url>` -> `ingest(url=<url>)`.
- Gardez le workflow explicite list_indexed_doc_sites -> search_documentation -> ingest_status.
- Remplacez C:/path/to/your/project par le chemin absolu reel de votre environnement.

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
