Metadata-Version: 2.4
Name: docsite-ingest-mcp
Version: 0.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: 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

# Website Docs MCP

Agent Python pour:

- Scraper une ou plusieurs documentations a partir d'URLs parametrables
- La stocker dans une base vectorielle locale (Chroma)
- Exposer une recherche documentaire multi-site via un serveur MCP (transport `stdio`)

## Prerequis

- Python 3.11+
- Acces reseau aux documentations à indexer

## Installation

### Installation simple (depuis le repository)

```bash
# Cloner le repo
git clone https://github.com/talan-digital-factory/docsite-ingest-mcp.git
cd docsite-ingest-mcp

# Créer et activer un venv
python -m venv .venv
.venv\Scripts\activate  # Windows
# source .venv/bin/activate  # Linux/macOS

# Installer en mode développement
pip install -e .
```

### Installation depuis PyPI (quand publié)

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

### Installation avec dépendances de développement

```bash
pip install -e ".[dev]"
```

### Vérifier l'installation

```bash
docsite-ingest-mcp --help
```

Si la commande n'est pas reconnue, assurez-vous que le venv est activé.

## Utilisation

### 1) Ingestion complete (scrape + index)

```bash
python -m docsite_ingest_mcp ingest --reset
```

Pour un site unique parametrable:

```bash
python -m docsite_ingest_mcp ingest --site-id haystack --site-name "Haystack" --start-url "https://docs.haystack.deepset.ai/docs/intro" --allowed-host docs.haystack.deepset.ai --allowed-path-prefix /docs/ --incremental
```

Pour plusieurs sites avec une config:

```bash
python -m docsite_ingest_mcp ingest --sites-config sites.json --incremental
```

Mode incremental:

```bash
python -m docsite_ingest_mcp ingest --incremental
```

Ce mode recrawl la documentation, compare le hash de contenu de chaque page avec l'etat precedent, puis:

- reindexe uniquement les pages modifiees
- supprime du vector store les pages disparues
- ignore les pages inchangees

Options utiles:

- `--max-pages 1500`
- `--delay 0.3`
- `--chunk-size 1200 --chunk-overlap 200`
- `--incremental`

Les donnees sont ecrites dans:

- `data/raw/<site_id>.jsonl`
- `data/raw/<site_id>.state.json`
- `data/chroma/`

## Fichier sites.json

Exemple:

```json
{
  "sites": [
    {
      "site_id": "haystack",
      "site_name": "Haystack",
      "start_url": "https://docs.haystack.deepset.ai/docs/intro",
      "allowed_host": "docs.haystack.deepset.ai",
      "allowed_path_prefix": "/docs/"
    },
    {
      "site_id": "example",
      "site_name": "Example Docs",
      "start_url": "https://example.com/docs/getting-started",
      "allowed_host": "example.com",
      "allowed_path_prefix": "/docs/"
    }
  ]
}
```

Chaque site est indexe avec ses metadonnees `site_id` et `site_name`, ce qui permet a un agent d'interroger explicitement la bonne documentation.

## Chunking semantique

Le decoupage est base sur les sections de la documentation:

- extraction des sections a partir des titres `h1` a `h6`
- prefixage de chaque chunk par le titre de page et le titre de section
- sous-decoupage par taille uniquement a l'interieur d'une section

Ce decoupage ameliore la pertinence pour les requetes ciblees sur un composant, une etape de pipeline ou une option de configuration.

### 2) Lancer le serveur MCP

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

Tool expose:

- `list_indexed_doc_sites()`
- `search_documentation(query: str, top_k: int = 5, site_id: str | None = None)`

Le tool de recherche retourne les extraits les plus pertinents avec identite du site, section, URL source et score de pertinence. Le parametre `site_id` permet a un agent de restreindre la recherche a la bonne documentation.

## Exemple de config MCP (client)

Le client MCP doit pointer vers le Python du virtual environment (et non le Python systeme) pour que le module `docsite_ingest_mcp` soit trouve.

```json
{
  "mcpServers": {
    "docsite-ingest-mcp": {
      "command": "c:/Users/$user$/Workspace/docsite-ingest-mcp/.venv/Scripts/python.exe",
      "args": ["-m", "docsite_ingest_mcp", "serve"],
      "cwd": "c:/Users/$user$/Workspace/docsite-ingest-mcp"
    }
  }
}
```

Remplacez `$user$` par votre nom d'utilisateur Windows. L'utilisation du chemin absolu vers `.venv/Scripts/python.exe` evite d'avoir a activer le venv manuellement.

## Packaging et Distribution

### Construire le package

```bash
pip install build
python -m build --sdist --wheel
```

Les fichiers `.whl` et `.tar.gz` sont générés dans `dist/`.

### Publier sur PyPI

**Prérequis:**
- Compte PyPI créé sur https://pypi.org/account/register/
- Token d'authentification généré dans **Account settings → API tokens**

**Étapes de publication:**

```bash
# 1. Nettoyer les anciens builds
rm -r build dist *.egg-info

# 2. Builder la distribution
python -m build --sdist --wheel

# 3. Vérifier les fichiers (optionnel mais recommandé)
pip install twine
twine check dist/*

# 4. Upload sur PyPI (remplacer YOUR_TOKEN par votre token)
twine upload dist/* -u __token__ -p "pypi-YOUR_TOKEN"
```

**Alternative : Configuration .pypirc**

Créez `~/.pypirc` (ou `%APPDATA%\pip\pip.ini` sur Windows):

```ini
[distutils]
index-servers = pypi

[pypi]
repository = https://upload.pypi.org/legacy/
username = __token__
password = pypi-YOUR_TOKEN_HERE
```

Puis uploadez simplement:
```bash
twine upload dist/*
```

**Test sur TestPyPI d'abord (recommandé):**

```bash
twine upload --repository testpypi dist/* -u __token__ -p "pypi-YOUR_TOKEN"
pip install -i https://test.pypi.org/simple/ --pre docsite-ingest-mcp
```

**Vérifier après publication:**

- PyPI: https://pypi.org/project/docsite-ingest-mcp/
- Installation: `pip install docsite-ingest-mcp`

### Métadonnées du package

Le package inclut :
- **console script** : `docsite-ingest-mcp` (accessible directement depuis le terminal après installation)
- **entry point** : `docsite_ingest_mcp.__main__:main`
- **dépendances optionnelles** : `pip install -e ".[dev]"` pour développement (pytest, black, ruff, mypy)
- **classifiers PyPI** : facilite la découverte sur PyPI

## Architecture et Packaging

### Structure src-layout

Le projet utilise la structure moderne `src-layout` pour éviter les conflits d'imports :

```
docsite-ingest-mcp/
├── src/
│   └── docsite_ingest_mcp/  (le package)
│       ├── __init__.py
│       ├── __main__.py       (CLI entry point)
│       ├── config.py
│       ├── mcp_server.py     (MCP tools)
│       ├── scraper.py
│       ├── indexer.py
│       └── sites.py
├── pyproject.toml            (PEP 621)
└── README.md
```

### Avantages

- ✅ CLI directe : `docsite-ingest-mcp ingest --help`
- ✅ Facilement packageable pour PyPI
- ✅ Dépendances déclarées explicitement
- ✅ Compatible avec `pip install -e .` pour développement

Pour lister les commandes disponibles:

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

Pour afficher les arguments de chaque sous-commande:

```bash
python -m docsite_ingest_mcp scrape --help
python -m docsite_ingest_mcp index --help
python -m docsite_ingest_mcp ingest --help
python -m docsite_ingest_mcp serve --help
```

Localisation par defaut de `--sites-config`:

- `sites.json` a la racine du projet

## Agent de test (Copilot)

Agent recommande pour valider l'application de bout en bout:

- `dev-python-validation`

Role de cet agent:

- lire le code
- compiler/lancer le projet
- demander l'URL de la documentation cible et l'identite du site
- scraper et verifier les donnees stockees
- verifier que la recherche MCP exposee fonctionne correctement

Usage (dans Copilot Chat):

- lancer un sous-agent avec le nom exact `dev-python-validation`
- decrire le site a tester (site_id + URL de documentation)
- demander une validation end-to-end de l'ingestion et de la recherche MCP
