docsite-ingest-mcp 0.1.0

Scrape documentation websites, index in Chroma, expose retrieval through MCP

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)

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

pip install docsite-ingest-mcp

Installation avec dépendances de développement

pip install -e ".[dev]"

Vérifier l'installation

docsite-ingest-mcp --help

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

Utilisation

1) Ingestion complete (scrape + index)

python -m docsite_ingest_mcp ingest --reset

Pour un site unique parametrable:

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:

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

Mode incremental:

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:

{
  "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

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.

{
  "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

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:

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

[distutils]
index-servers = pypi

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

Puis uploadez simplement:

twine upload dist/*

Test sur TestPyPI d'abord (recommandé):

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:

python -m docsite_ingest_mcp --help

Pour afficher les arguments de chaque sous-commande:

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