Colin Maudry
1034 lines
35 KiB
Markdown
1034 lines
35 KiB
Markdown
# Tools MCP colibre (scope A de #111) — Implementation Plan
|
|
|
|
> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking.
|
|
|
|
**Goal:** Exposer 4 fonctions métier des DECP comme _tools_ MCP via le décorateur `@mcp_enabled` de Dash, sans authentification (le gate abonnement = scope B, séparé).
|
|
|
|
**Architecture:** Un package `src/mcp/` fin. `tools.py` contient les 4 fonctions décorées (surface MCP + tracking, aucun SQL) ; `queries.py` porte la logique données en réutilisant la couche existante (`src/db.py`, `src/api/filters.py`, `src/utils/search.py`) ; `serialization.py` convertit le Polars en JSON propre. Le serveur MCP est activé dans `src/app.py` via `enable_mcp` + `configure_mcp_server` qui coupe l'exposition des callbacks/layout/pages : seules les 4 fonctions sont exposées.
|
|
|
|
**Tech Stack:** Python 3, Dash 4.4 (`dash.mcp`), Polars, DuckDB, httpx (tracking Matomo), pytest.
|
|
|
|
## Global Constraints
|
|
|
|
- Imports internes toujours préfixés `src.` (ex. `from src.db import ...`), jamais `db` ou `utils`.
|
|
- Périmètre = **scope A uniquement**. Aucune authentification, aucun gate abonnement dans ce plan.
|
|
- Sorties des tools = structures **JSON-sérialisables** : dates en ISO 8601 (`YYYY-MM-DD`), valeurs manquantes en `None`, montants numériques.
|
|
- Le serveur MCP n'expose **que** les fonctions `@mcp_enabled` (couper `include_callbacks/layout/pages/clientside`).
|
|
- Activation par variable d'env `DASH_MCP_ENABLED` (`"true"` pour activer), **off par défaut**. Ne pas activer en prod tant que le scope B n'est pas livré.
|
|
- Colonnes réelles de la table `decp` : `uid`, `objet`, `montant`, `dateNotification`, `codeCPV`, `acheteur_id`, `acheteur_nom`, `acheteur_departement_code`, `acheteur_departement_nom`, `acheteur_commune_nom`, `titulaire_id`, `titulaire_nom`, `titulaire_departement_nom`, `titulaire_commune_nom`. **Pas de colonne `annee`** → dériver l'année via `date_part('year', "dateNotification")`. **Pas de libellé CPV** dans les données.
|
|
- Avant chaque commit, le hook `pre-commit` (ruff + prettier) s'exécute et peut reformater : si des fichiers sont modifiés par le hook, refaire `git add` puis `git commit`.
|
|
- Lancer les tests avec `uv run pytest`. Chaque tâche ne lance QUE son fichier de test ; la suite complète (`uv run pytest` sans chemin) uniquement à la dernière tâche.
|
|
|
|
## File Structure
|
|
|
|
- Create: `src/mcp/__init__.py` — package vide.
|
|
- Create: `src/mcp/serialization.py` — `to_json_records(df) -> list[dict]`.
|
|
- Create: `src/mcp/queries.py` — `search_organisations`, `search_marches`, `build_where_args`, `compute_org_stats`, `_org_identite`.
|
|
- Create: `src/mcp/tools.py` — les 4 fonctions `@mcp_enabled`.
|
|
- Modify: `src/utils/tracking.py` — ajouter `track_mcp_tool`.
|
|
- Modify: `src/utils/search.py` — ajouter le paramètre `track: bool = True` à `search_org`.
|
|
- Modify: `src/app.py` — activer le serveur MCP (constructeur + `configure_mcp_server` + import des tools).
|
|
- Modify: `.template.env` — documenter `DASH_MCP_ENABLED`.
|
|
- Create: `tests/mcp/__init__.py`, `tests/mcp/test_serialization.py`, `tests/mcp/test_tracking.py`, `tests/mcp/test_queries.py`, `tests/mcp/test_tools.py`.
|
|
|
|
Le harness de test racine (`tests/conftest.py`) écrit `tests/test.parquet` (1 ligne : `acheteur_id="123"`, `acheteur_nom="ACHETEUR 1"`, `titulaire_id="345"`, `titulaire_nom="TITULAIRE 1"`, `montant=10`, `codeCPV="71600000"`, `dateNotification=2025-01-01`, `acheteur_departement_code="75"`, `objet="Objet test"`) et construit une base DuckDB de test isolée à l'import du conftest. Les tests sous `tests/mcp/` en héritent automatiquement.
|
|
|
|
---
|
|
|
|
### Task 1: `serialization.py` — conversion Polars → JSON
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/mcp/__init__.py`
|
|
- Create: `src/mcp/serialization.py`
|
|
- Test: `tests/mcp/__init__.py`, `tests/mcp/test_serialization.py`
|
|
|
|
**Interfaces:**
|
|
|
|
- Produces: `to_json_records(df: pl.DataFrame) -> list[dict[str, Any]]` — convertit chaque ligne en dict JSON-sérialisable ; `datetime.date`/`datetime.datetime` → chaîne ISO, `None` préservé.
|
|
|
|
- [ ] **Step 1: Créer le package et le fichier de test**
|
|
|
|
Créer `src/mcp/__init__.py` (vide) et `tests/mcp/__init__.py` (vide), puis écrire le test :
|
|
|
|
```python
|
|
# tests/mcp/test_serialization.py
|
|
import datetime
|
|
|
|
import polars as pl
|
|
|
|
from src.mcp.serialization import to_json_records
|
|
|
|
|
|
def test_dates_become_iso_strings():
|
|
df = pl.DataFrame({"d": [datetime.date(2025, 1, 1)], "n": [10]})
|
|
assert to_json_records(df) == [{"d": "2025-01-01", "n": 10}]
|
|
|
|
|
|
def test_none_is_preserved():
|
|
df = pl.DataFrame({"nom": [None], "x": [3]})
|
|
assert to_json_records(df) == [{"nom": None, "x": 3}]
|
|
|
|
|
|
def test_strings_and_numbers_untouched():
|
|
df = pl.DataFrame({"s": ["abc"], "f": [1.5]})
|
|
assert to_json_records(df) == [{"s": "abc", "f": 1.5}]
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test → échec**
|
|
|
|
Run: `uv run pytest tests/mcp/test_serialization.py -v`
|
|
Expected: FAIL — `ModuleNotFoundError: No module named 'src.mcp.serialization'`
|
|
|
|
- [ ] **Step 3: Implémenter `serialization.py`**
|
|
|
|
```python
|
|
# src/mcp/serialization.py
|
|
import datetime
|
|
from typing import Any
|
|
|
|
import polars as pl
|
|
|
|
|
|
def to_json_records(df: pl.DataFrame) -> list[dict[str, Any]]:
|
|
"""Convertit un DataFrame Polars en liste de dicts JSON-sérialisables.
|
|
|
|
Les dates/datetimes deviennent des chaînes ISO 8601 ; les valeurs nulles
|
|
restent None. Utilisé par tous les tools MCP pour produire une sortie propre.
|
|
"""
|
|
return [
|
|
{key: _jsonify(value) for key, value in row.items()}
|
|
for row in df.to_dicts()
|
|
]
|
|
|
|
|
|
def _jsonify(value: Any) -> Any:
|
|
if isinstance(value, (datetime.date, datetime.datetime)):
|
|
return value.isoformat()
|
|
return value
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer le test → succès**
|
|
|
|
Run: `uv run pytest tests/mcp/test_serialization.py -v`
|
|
Expected: PASS (3 tests)
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/mcp/__init__.py src/mcp/serialization.py tests/mcp/__init__.py tests/mcp/test_serialization.py
|
|
git commit -m "feat(mcp): sérialisation Polars -> JSON pour les tools MCP"
|
|
```
|
|
|
|
(Si le hook reformate, refaire `git add` puis `git commit`.)
|
|
|
|
---
|
|
|
|
### Task 2: `track_mcp_tool` — tracking Matomo des appels MCP
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/utils/tracking.py`
|
|
- Test: `tests/mcp/test_tracking.py`
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: le module `src.utils.tracking` (constante `DEVELOPMENT`, `post` de httpx).
|
|
- Produces: `track_mcp_tool(tool_name: str, query: str | None = None) -> None` — best-effort, n'émet qu'en prod (`not DEVELOPMENT` et `MATOMO_DOMAIN` défini) ; envoie `action_name="MCP / <tool>"`, `dimension1=<tool>`, et `search=<query>` si fourni.
|
|
|
|
- [ ] **Step 1: Écrire le test**
|
|
|
|
```python
|
|
# tests/mcp/test_tracking.py
|
|
import src.utils.tracking as tracking
|
|
|
|
|
|
def test_track_mcp_tool_sends_action_and_dimension(monkeypatch):
|
|
captured = {}
|
|
|
|
def fake_post(url, params):
|
|
captured["url"] = url
|
|
captured["params"] = params
|
|
|
|
class _R:
|
|
def raise_for_status(self):
|
|
pass
|
|
|
|
return _R()
|
|
|
|
monkeypatch.setattr(tracking, "DEVELOPMENT", False)
|
|
monkeypatch.setattr(tracking, "post", fake_post)
|
|
monkeypatch.setenv("MATOMO_DOMAIN", "matomo.example")
|
|
monkeypatch.setenv("MATOMO_ID_SITE", "1")
|
|
|
|
tracking.track_mcp_tool("rechercher_marches", query="informatique")
|
|
|
|
assert captured["params"]["action_name"] == "MCP / rechercher_marches"
|
|
assert captured["params"]["dimension1"] == "rechercher_marches"
|
|
assert captured["params"]["search"] == "informatique"
|
|
|
|
|
|
def test_track_mcp_tool_noop_in_development(monkeypatch):
|
|
called = False
|
|
|
|
def fake_post(url, params):
|
|
nonlocal called
|
|
called = True
|
|
|
|
monkeypatch.setattr(tracking, "DEVELOPMENT", True)
|
|
monkeypatch.setattr(tracking, "post", fake_post)
|
|
monkeypatch.setenv("MATOMO_DOMAIN", "matomo.example")
|
|
|
|
tracking.track_mcp_tool("stats_acheteur")
|
|
|
|
assert called is False
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test → échec**
|
|
|
|
Run: `uv run pytest tests/mcp/test_tracking.py -v`
|
|
Expected: FAIL — `AttributeError: module 'src.utils.tracking' has no attribute 'track_mcp_tool'`
|
|
|
|
- [ ] **Step 3: Ajouter `track_mcp_tool` à `src/utils/tracking.py`**
|
|
|
|
Ajouter à la fin du fichier (les imports `os`, `uuid`, `localtime`, `post`, `DEVELOPMENT` sont déjà présents en tête) :
|
|
|
|
```python
|
|
def track_mcp_tool(tool_name: str, query: str | None = None) -> None:
|
|
"""Enregistre un appel d'outil MCP dans Matomo (best-effort, prod uniquement).
|
|
|
|
`action_name="MCP / <tool>"`, `dimension1=<tool>`. Si l'outil porte une
|
|
requête texte, elle est envoyée en `search`. Nécessite un Custom Dimension
|
|
slot 1 (scope Action) configuré côté Matomo — sinon `dimension1` est ignoré.
|
|
Ne lève jamais : une panne Matomo ne doit pas casser l'appel du tool.
|
|
"""
|
|
if DEVELOPMENT or not os.getenv("MATOMO_DOMAIN"):
|
|
return
|
|
params = {
|
|
"idsite": os.getenv("MATOMO_ID_SITE"),
|
|
"url": "https://colibre.fr/_mcp",
|
|
"rec": "1",
|
|
"action_name": f"MCP / {tool_name}",
|
|
"dimension1": tool_name,
|
|
"rand": uuid.uuid4().hex,
|
|
"apiv": "1",
|
|
"h": localtime().tm_hour,
|
|
"m": localtime().tm_min,
|
|
"s": localtime().tm_sec,
|
|
"token_auth": os.getenv("MATOMO_TOKEN"),
|
|
}
|
|
if query:
|
|
params["search"] = query
|
|
params["search_cat"] = "mcp"
|
|
try:
|
|
post(url=f"https://{os.getenv('MATOMO_DOMAIN')}/matomo.php", params=params)
|
|
except Exception:
|
|
pass
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer le test → succès**
|
|
|
|
Run: `uv run pytest tests/mcp/test_tracking.py -v`
|
|
Expected: PASS (2 tests)
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/utils/tracking.py tests/mcp/test_tracking.py
|
|
git commit -m "feat(mcp): helper track_mcp_tool pour tracer les appels MCP dans Matomo"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 3: `search_org` — paramètre `track` optionnel
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/utils/search.py`
|
|
- Test: `tests/mcp/test_queries.py` (créé ici, complété aux tâches suivantes)
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `search_org(dff, query, org_type)` existant.
|
|
- Produces: `search_org(dff, query, org_type, track: bool = True)` — quand `track=False`, ne déclenche pas `track_search(...)`. Comportement inchangé par défaut.
|
|
|
|
- [ ] **Step 1: Écrire le test**
|
|
|
|
```python
|
|
# tests/mcp/test_queries.py
|
|
import src.utils.search as search_mod
|
|
from src.utils.data import DF_ACHETEURS
|
|
from src.utils.search import search_org
|
|
|
|
|
|
def test_search_org_track_false_skips_track_search(monkeypatch):
|
|
calls = []
|
|
monkeypatch.setattr(
|
|
search_mod, "track_search", lambda q, c: calls.append((q, c))
|
|
)
|
|
|
|
search_org(DF_ACHETEURS, "ACHETEUR", "acheteur", track=False)
|
|
|
|
assert calls == []
|
|
|
|
|
|
def test_search_org_track_true_calls_track_search(monkeypatch):
|
|
calls = []
|
|
monkeypatch.setattr(
|
|
search_mod, "track_search", lambda q, c: calls.append((q, c))
|
|
)
|
|
|
|
search_org(DF_ACHETEURS, "ACHETEUR", "acheteur", track=True)
|
|
|
|
assert calls == [("ACHETEUR", "home_page_search")]
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test → échec**
|
|
|
|
Run: `uv run pytest tests/mcp/test_queries.py -v`
|
|
Expected: FAIL — `TypeError: search_org() got an unexpected keyword argument 'track'`
|
|
|
|
- [ ] **Step 3: Ajouter le paramètre `track`**
|
|
|
|
Dans `src/utils/search.py`, modifier la signature et le corps :
|
|
|
|
```python
|
|
def search_org(
|
|
dff: pl.DataFrame, query: str, org_type: str, track: bool = True
|
|
) -> pl.DataFrame:
|
|
```
|
|
|
|
et remplacer :
|
|
|
|
```python
|
|
# Enregistrement des recherche dans Matomo
|
|
track_search(query, "home_page_search")
|
|
```
|
|
|
|
par :
|
|
|
|
```python
|
|
# Enregistrement des recherche dans Matomo
|
|
if track:
|
|
track_search(query, "home_page_search")
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer le test → succès**
|
|
|
|
Run: `uv run pytest tests/mcp/test_queries.py -v`
|
|
Expected: PASS (2 tests)
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/utils/search.py tests/mcp/test_queries.py
|
|
git commit -m "feat(mcp): search_org accepte track=False pour ne pas polluer Matomo"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 4: `queries.py` — `search_organisations`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/mcp/queries.py`
|
|
- Test: `tests/mcp/test_queries.py` (ajout)
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `search_org(dff, query, org_type, track=False)` (Task 3), `DF_ACHETEURS`/`DF_TITULAIRES` de `src.utils.data`, `to_json_records` (Task 1).
|
|
- Produces: `search_organisations(query: str, org_type: str = "acheteur", limite: int = 20) -> list[dict]` — retourne `[{"id", "nom", "departement"}]`. Lève `ValueError` si `org_type` invalide. Aussi : constantes `PAGE_SIZE = 50`, `TOP_N = 10`, `ORG_FRAMES`.
|
|
|
|
- [ ] **Step 1: Écrire le test (ajouter à `tests/mcp/test_queries.py`)**
|
|
|
|
```python
|
|
import pytest
|
|
|
|
from src.mcp.queries import search_organisations
|
|
|
|
|
|
def test_search_organisations_finds_known_acheteur():
|
|
result = search_organisations("ACHETEUR", "acheteur")
|
|
assert any(r["id"] == "123" for r in result)
|
|
first = next(r for r in result if r["id"] == "123")
|
|
assert set(first.keys()) == {"id", "nom", "departement"}
|
|
|
|
|
|
def test_search_organisations_invalid_type_raises():
|
|
with pytest.raises(ValueError):
|
|
search_organisations("x", "autre")
|
|
|
|
|
|
def test_search_organisations_respects_limite():
|
|
result = search_organisations("ACHETEUR", "acheteur", limite=1)
|
|
assert len(result) <= 1
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test → échec**
|
|
|
|
Run: `uv run pytest tests/mcp/test_queries.py -v`
|
|
Expected: FAIL — `ModuleNotFoundError: No module named 'src.mcp.queries'`
|
|
|
|
- [ ] **Step 3: Créer `src/mcp/queries.py` avec `search_organisations`**
|
|
|
|
```python
|
|
# src/mcp/queries.py
|
|
from src.mcp.serialization import to_json_records # noqa: F401 (utilisé aux tâches suivantes)
|
|
from src.utils.data import DF_ACHETEURS, DF_TITULAIRES
|
|
from src.utils.search import search_org
|
|
|
|
PAGE_SIZE = 50
|
|
TOP_N = 10
|
|
ORG_FRAMES = {"acheteur": DF_ACHETEURS, "titulaire": DF_TITULAIRES}
|
|
|
|
|
|
def search_organisations(
|
|
query: str, org_type: str = "acheteur", limite: int = 20
|
|
) -> list[dict]:
|
|
"""Recherche des organisations par nom, résout un nom -> id."""
|
|
if org_type not in ORG_FRAMES:
|
|
raise ValueError(
|
|
f"type invalide: {org_type!r} (attendu 'acheteur' ou 'titulaire')"
|
|
)
|
|
df = search_org(ORG_FRAMES[org_type], query, org_type, track=False).head(limite)
|
|
return [
|
|
{
|
|
"id": r[f"{org_type}_id"],
|
|
"nom": r[f"{org_type}_nom"],
|
|
"departement": r.get("Département"),
|
|
}
|
|
for r in df.to_dicts()
|
|
]
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer le test → succès**
|
|
|
|
Run: `uv run pytest tests/mcp/test_queries.py -v`
|
|
Expected: PASS (5 tests au total dans ce fichier)
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/mcp/queries.py tests/mcp/test_queries.py
|
|
git commit -m "feat(mcp): tool search_organisations (résolution nom -> id)"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 5: `queries.py` — `build_where_args` + `search_marches`
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/mcp/queries.py`
|
|
- Test: `tests/mcp/test_queries.py` (ajout)
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `build_where(args, schema)` et `FilterError` de `src.api.filters` ; `query_marches`, `count_marches`, `schema` de `src.db` ; `to_json_records` (Task 1) ; `PAGE_SIZE` (Task 4).
|
|
- Produces:
|
|
|
|
- `build_where_args(named: dict, filtres_avances: dict | None) -> list[tuple[str, str]]` — traduit paramètres nommés + filtres avancés en tuples `("col__op", "valeur")`.
|
|
- `search_marches(*, acheteur_id=None, titulaire_id=None, cpv=None, objet_contient=None, montant_min=None, montant_max=None, date_min=None, date_max=None, departement=None, page=1, filtres_avances=None) -> dict` — retourne `{"meta": {"page", "page_size", "total"}, "marches": [...]}` ou `{"error": ..., "champ": ...}` sur `FilterError`.
|
|
|
|
- [ ] **Step 1: Écrire le test (ajouter à `tests/mcp/test_queries.py`)**
|
|
|
|
```python
|
|
from src.mcp.queries import build_where_args, search_marches
|
|
|
|
|
|
def test_build_where_args_named_params():
|
|
args = build_where_args(
|
|
{"acheteur_id": "123", "montant_min": 5, "objet_contient": "test"}, None
|
|
)
|
|
assert ("acheteur_id__exact", "123") in args
|
|
assert ("montant__greater", "5") in args
|
|
assert ("objet__contains", "test") in args
|
|
|
|
|
|
def test_build_where_args_merges_filtres_avances():
|
|
args = build_where_args(
|
|
{"acheteur_id": "123"}, {"titulaire_departement_code__exact": "35"}
|
|
)
|
|
assert ("acheteur_id__exact", "123") in args
|
|
assert ("titulaire_departement_code__exact", "35") in args
|
|
|
|
|
|
def test_search_marches_returns_meta_and_rows():
|
|
result = search_marches(acheteur_id="123")
|
|
assert result["meta"]["total"] >= 1
|
|
assert result["meta"]["page"] == 1
|
|
assert result["meta"]["page_size"] == 50
|
|
assert any(m["acheteur_id"] == "123" for m in result["marches"])
|
|
# dates sérialisées en ISO
|
|
assert result["marches"][0]["dateNotification"] == "2025-01-01"
|
|
|
|
|
|
def test_search_marches_no_match_is_empty():
|
|
result = search_marches(acheteur_id="inconnu-xyz")
|
|
assert result["meta"]["total"] == 0
|
|
assert result["marches"] == []
|
|
|
|
|
|
def test_search_marches_bad_filter_returns_error():
|
|
result = search_marches(filtres_avances={"colonne_bidon__exact": "x"})
|
|
assert "error" in result
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test → échec**
|
|
|
|
Run: `uv run pytest tests/mcp/test_queries.py -v`
|
|
Expected: FAIL — `ImportError: cannot import name 'build_where_args'`
|
|
|
|
- [ ] **Step 3: Étendre `src/mcp/queries.py`**
|
|
|
|
Remplacer la ligne d'import `to_json_records` (marquée `noqa`) par les imports réels et ajouter le code. Nouvel en-tête d'imports en haut du fichier :
|
|
|
|
```python
|
|
from src.api.filters import FilterError, build_where
|
|
from src.db import count_marches, query_marches
|
|
from src.db import schema as duckdb_schema
|
|
from src.mcp.serialization import to_json_records
|
|
from src.utils.data import DF_ACHETEURS, DF_TITULAIRES
|
|
from src.utils.search import search_org
|
|
```
|
|
|
|
Ajouter après les constantes :
|
|
|
|
```python
|
|
# Colonnes renvoyées par rechercher_marches (sortie ciblée, pas SELECT *).
|
|
MARCHES_COLUMNS = [
|
|
"uid",
|
|
"objet",
|
|
"montant",
|
|
"dateNotification",
|
|
"codeCPV",
|
|
"acheteur_id",
|
|
"acheteur_nom",
|
|
"acheteur_departement_code",
|
|
"titulaire_id",
|
|
"titulaire_nom",
|
|
]
|
|
|
|
# (param nommé, colonne decp, opérateur du moteur de filtres API).
|
|
# `greater` = >=, `less` = <=, `contains` = LIKE %v%, `exact` = =.
|
|
_NAMED_FILTERS = [
|
|
("acheteur_id", "acheteur_id", "exact"),
|
|
("titulaire_id", "titulaire_id", "exact"),
|
|
("cpv", "codeCPV", "contains"),
|
|
("objet_contient", "objet", "contains"),
|
|
("montant_min", "montant", "greater"),
|
|
("montant_max", "montant", "less"),
|
|
("date_min", "dateNotification", "greater"),
|
|
("date_max", "dateNotification", "less"),
|
|
("departement", "acheteur_departement_code", "exact"),
|
|
]
|
|
|
|
|
|
def build_where_args(
|
|
named: dict, filtres_avances: dict | None
|
|
) -> list[tuple[str, str]]:
|
|
"""Traduit les paramètres nommés + filtres avancés en tuples (col__op, valeur)."""
|
|
args: list[tuple[str, str]] = []
|
|
for param, col, op in _NAMED_FILTERS:
|
|
value = named.get(param)
|
|
if value is not None:
|
|
args.append((f"{col}__{op}", str(value)))
|
|
if filtres_avances:
|
|
for key, value in filtres_avances.items():
|
|
args.append((key, str(value)))
|
|
return args
|
|
|
|
|
|
def search_marches(
|
|
*,
|
|
acheteur_id: str | None = None,
|
|
titulaire_id: str | None = None,
|
|
cpv: str | None = None,
|
|
objet_contient: str | None = None,
|
|
montant_min: float | None = None,
|
|
montant_max: float | None = None,
|
|
date_min: str | None = None,
|
|
date_max: str | None = None,
|
|
departement: str | None = None,
|
|
page: int = 1,
|
|
filtres_avances: dict | None = None,
|
|
) -> dict:
|
|
"""Recherche paginée de marchés. Même sémantique de filtres que l'API REST."""
|
|
named = {
|
|
"acheteur_id": acheteur_id,
|
|
"titulaire_id": titulaire_id,
|
|
"cpv": cpv,
|
|
"objet_contient": objet_contient,
|
|
"montant_min": montant_min,
|
|
"montant_max": montant_max,
|
|
"date_min": date_min,
|
|
"date_max": date_max,
|
|
"departement": departement,
|
|
}
|
|
args = build_where_args(named, filtres_avances)
|
|
try:
|
|
where_sql, params, order_sql = build_where(args, duckdb_schema)
|
|
except FilterError as e:
|
|
return {"error": str(e), "champ": e.field}
|
|
|
|
page = max(1, int(page))
|
|
offset = (page - 1) * PAGE_SIZE
|
|
order_by = order_sql or '"dateNotification" DESC, "uid" DESC'
|
|
df = query_marches(
|
|
where_sql,
|
|
params,
|
|
columns=MARCHES_COLUMNS,
|
|
order_by=order_by,
|
|
limit=PAGE_SIZE,
|
|
offset=offset,
|
|
)
|
|
total = count_marches(where_sql, params)
|
|
return {
|
|
"meta": {"page": page, "page_size": PAGE_SIZE, "total": total},
|
|
"marches": to_json_records(df),
|
|
}
|
|
```
|
|
|
|
Supprimer l'ancienne ligne `from src.mcp.serialization import to_json_records # noqa: F401` et l'ancien bloc d'imports partiel de la Task 4 (remplacés par l'en-tête ci-dessus).
|
|
|
|
- [ ] **Step 4: Lancer le test → succès**
|
|
|
|
Run: `uv run pytest tests/mcp/test_queries.py -v`
|
|
Expected: PASS (10 tests au total dans ce fichier)
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/mcp/queries.py tests/mcp/test_queries.py
|
|
git commit -m "feat(mcp): tool rechercher_marches (filtres hybrides + pagination)"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 6: `queries.py` — `compute_org_stats`
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/mcp/queries.py`
|
|
- Test: `tests/mcp/test_queries.py` (ajout)
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `aggregate_marches`, `query_marches` de `src.db` ; `to_json_records` (Task 1) ; `TOP_N` (Task 4).
|
|
- Produces: `compute_org_stats(org_type: str, org_id: str) -> dict` — retourne `{"identite", "nb_marches", "montant_total", "repartition_annuelle", "top_<contrepartie>s", "top_cpv"}`. Contrepartie = `titulaire` si `org_type="acheteur"`, sinon `acheteur`. `nb_marches=0` et listes vides si id inconnu (pas d'exception). Aussi `_org_identite(org_type, org_id) -> dict`.
|
|
|
|
- [ ] **Step 1: Écrire le test (ajouter à `tests/mcp/test_queries.py`)**
|
|
|
|
```python
|
|
from src.mcp.queries import compute_org_stats
|
|
|
|
|
|
def test_compute_org_stats_acheteur_known():
|
|
stats = compute_org_stats("acheteur", "123")
|
|
assert stats["nb_marches"] >= 1
|
|
assert stats["montant_total"] == 10
|
|
assert stats["identite"]["id"] == "123"
|
|
assert stats["identite"]["nom"] == "ACHETEUR 1"
|
|
assert "top_titulaires" in stats
|
|
assert "top_cpv" in stats
|
|
# répartition annuelle dérivée de dateNotification (2025)
|
|
annees = [row["annee"] for row in stats["repartition_annuelle"]]
|
|
assert 2025 in annees
|
|
|
|
|
|
def test_compute_org_stats_titulaire_known():
|
|
stats = compute_org_stats("titulaire", "345")
|
|
assert stats["nb_marches"] >= 1
|
|
assert "top_acheteurs" in stats
|
|
|
|
|
|
def test_compute_org_stats_unknown_is_empty():
|
|
stats = compute_org_stats("acheteur", "inconnu-xyz")
|
|
assert stats["nb_marches"] == 0
|
|
assert stats["montant_total"] == 0
|
|
assert stats["repartition_annuelle"] == []
|
|
assert stats["top_titulaires"] == []
|
|
assert stats["top_cpv"] == []
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test → échec**
|
|
|
|
Run: `uv run pytest tests/mcp/test_queries.py -v`
|
|
Expected: FAIL — `ImportError: cannot import name 'compute_org_stats'`
|
|
|
|
- [ ] **Step 3: Étendre `src/mcp/queries.py`**
|
|
|
|
Ajouter `aggregate_marches` à l'import de `src.db` :
|
|
|
|
```python
|
|
from src.db import aggregate_marches, count_marches, query_marches
|
|
```
|
|
|
|
Ajouter les fonctions :
|
|
|
|
```python
|
|
def _org_identite(org_type: str, org_id: str) -> dict:
|
|
df = query_marches(
|
|
where_sql=f'"{org_type}_id" = ?',
|
|
params=[org_id],
|
|
columns=[
|
|
f"{org_type}_id",
|
|
f"{org_type}_nom",
|
|
f"{org_type}_departement_nom",
|
|
f"{org_type}_commune_nom",
|
|
],
|
|
limit=1,
|
|
)
|
|
if df.height == 0:
|
|
return {"id": org_id, "nom": None, "departement": None, "commune": None}
|
|
r = df.row(0, named=True)
|
|
return {
|
|
"id": org_id,
|
|
"nom": r[f"{org_type}_nom"],
|
|
"departement": r[f"{org_type}_departement_nom"],
|
|
"commune": r[f"{org_type}_commune_nom"],
|
|
}
|
|
|
|
|
|
def compute_org_stats(org_type: str, org_id: str) -> dict:
|
|
"""Statistiques agrégées d'un acheteur ou titulaire."""
|
|
if org_type not in ORG_FRAMES:
|
|
raise ValueError(
|
|
f"type invalide: {org_type!r} (attendu 'acheteur' ou 'titulaire')"
|
|
)
|
|
other = "titulaire" if org_type == "acheteur" else "acheteur"
|
|
where_sql = f'"{org_type}_id" = ?'
|
|
params = [org_id]
|
|
identite = _org_identite(org_type, org_id)
|
|
|
|
totals = aggregate_marches(
|
|
select_sql='COUNT("uid") AS nb, COALESCE(SUM("montant"), 0) AS montant_total',
|
|
where_sql=where_sql,
|
|
params=params,
|
|
)
|
|
nb = int(totals["nb"][0])
|
|
if nb == 0:
|
|
return {
|
|
"identite": identite,
|
|
"nb_marches": 0,
|
|
"montant_total": 0,
|
|
"repartition_annuelle": [],
|
|
f"top_{other}s": [],
|
|
"top_cpv": [],
|
|
}
|
|
|
|
annuelle = aggregate_marches(
|
|
select_sql=(
|
|
'CAST(date_part(\'year\', "dateNotification") AS INTEGER) AS annee, '
|
|
'COUNT("uid") AS nb_marches, '
|
|
'COALESCE(SUM("montant"), 0) AS montant_total'
|
|
),
|
|
where_sql=where_sql,
|
|
params=params,
|
|
group_by='date_part(\'year\', "dateNotification")',
|
|
order_by="annee",
|
|
)
|
|
top_other = aggregate_marches(
|
|
select_sql=(
|
|
f'"{other}_id" AS id, any_value("{other}_nom") AS nom, '
|
|
'COUNT("uid") AS nb_marches, '
|
|
'COALESCE(SUM("montant"), 0) AS montant_total'
|
|
),
|
|
where_sql=where_sql,
|
|
params=params,
|
|
group_by=f'"{other}_id"',
|
|
order_by="nb_marches DESC",
|
|
limit=TOP_N,
|
|
)
|
|
top_cpv = aggregate_marches(
|
|
select_sql='"codeCPV" AS cpv, COUNT("uid") AS nb_marches',
|
|
where_sql=where_sql,
|
|
params=params,
|
|
group_by='"codeCPV"',
|
|
order_by="nb_marches DESC",
|
|
limit=TOP_N,
|
|
)
|
|
return {
|
|
"identite": identite,
|
|
"nb_marches": nb,
|
|
"montant_total": float(totals["montant_total"][0]),
|
|
"repartition_annuelle": to_json_records(annuelle),
|
|
f"top_{other}s": to_json_records(top_other),
|
|
"top_cpv": to_json_records(top_cpv),
|
|
}
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer le test → succès**
|
|
|
|
Run: `uv run pytest tests/mcp/test_queries.py -v`
|
|
Expected: PASS (13 tests au total dans ce fichier)
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/mcp/queries.py tests/mcp/test_queries.py
|
|
git commit -m "feat(mcp): tools stats_acheteur / stats_titulaire (agrégations)"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 7: `tools.py` — les 4 fonctions `@mcp_enabled`
|
|
|
|
**Files:**
|
|
|
|
- Create: `src/mcp/tools.py`
|
|
- Test: `tests/mcp/test_tools.py`
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `queries.search_organisations`, `queries.search_marches`, `queries.compute_org_stats` ; `track_mcp_tool` (Task 2) ; `mcp_enabled` de `dash.mcp`.
|
|
- Produces: 4 fonctions décorées `rechercher_organisations`, `stats_acheteur`, `stats_titulaire`, `rechercher_marches`, importables et appelables directement.
|
|
|
|
- [ ] **Step 1: Écrire le test**
|
|
|
|
```python
|
|
# tests/mcp/test_tools.py
|
|
from src.mcp import tools
|
|
|
|
|
|
def test_all_four_tools_are_callable():
|
|
for name in (
|
|
"rechercher_organisations",
|
|
"stats_acheteur",
|
|
"stats_titulaire",
|
|
"rechercher_marches",
|
|
):
|
|
assert callable(getattr(tools, name))
|
|
|
|
|
|
def test_rechercher_organisations_returns_list():
|
|
result = tools.rechercher_organisations("ACHETEUR", "acheteur")
|
|
assert isinstance(result, list)
|
|
assert any(r["id"] == "123" for r in result)
|
|
|
|
|
|
def test_rechercher_marches_returns_meta():
|
|
result = tools.rechercher_marches(acheteur_id="123")
|
|
assert result["meta"]["total"] >= 1
|
|
|
|
|
|
def test_stats_acheteur_returns_stats():
|
|
result = tools.stats_acheteur("123")
|
|
assert result["nb_marches"] >= 1
|
|
assert result["identite"]["id"] == "123"
|
|
|
|
|
|
def test_stats_titulaire_returns_stats():
|
|
result = tools.stats_titulaire("345")
|
|
assert result["nb_marches"] >= 1
|
|
```
|
|
|
|
- [ ] **Step 2: Lancer le test → échec**
|
|
|
|
Run: `uv run pytest tests/mcp/test_tools.py -v`
|
|
Expected: FAIL — `ModuleNotFoundError: No module named 'src.mcp.tools'`
|
|
|
|
- [ ] **Step 3: Créer `src/mcp/tools.py`**
|
|
|
|
```python
|
|
# src/mcp/tools.py
|
|
from dash.mcp import mcp_enabled
|
|
|
|
from src.mcp import queries
|
|
from src.utils.tracking import track_mcp_tool
|
|
|
|
|
|
@mcp_enabled(name="rechercher_organisations", expose_docstring=True)
|
|
def rechercher_organisations(
|
|
query: str, type: str = "acheteur", limite: int = 20 # noqa: A002
|
|
) -> list[dict]:
|
|
"""Recherche des acheteurs ou titulaires publics par nom.
|
|
|
|
Utiliser en premier pour résoudre un nom d'organisation vers son
|
|
identifiant, à passer ensuite à stats_acheteur / stats_titulaire.
|
|
|
|
query: texte libre (nom d'organisation).
|
|
type: "acheteur" ou "titulaire".
|
|
Retourne une liste de {id, nom, departement}.
|
|
"""
|
|
track_mcp_tool("rechercher_organisations", query=query)
|
|
return queries.search_organisations(query, type, limite)
|
|
|
|
|
|
@mcp_enabled(name="stats_acheteur", expose_docstring=True)
|
|
def stats_acheteur(acheteur_id: str) -> dict:
|
|
"""Statistiques agrégées d'un acheteur public (par identifiant).
|
|
|
|
Retourne nombre de marchés, montant total, répartition annuelle,
|
|
principaux titulaires et principaux codes CPV.
|
|
"""
|
|
track_mcp_tool("stats_acheteur")
|
|
return queries.compute_org_stats("acheteur", acheteur_id)
|
|
|
|
|
|
@mcp_enabled(name="stats_titulaire", expose_docstring=True)
|
|
def stats_titulaire(titulaire_id: str) -> dict:
|
|
"""Statistiques agrégées d'un titulaire (entreprise) par identifiant.
|
|
|
|
Retourne nombre de marchés remportés, montant total, répartition
|
|
annuelle, principaux acheteurs et principaux codes CPV.
|
|
"""
|
|
track_mcp_tool("stats_titulaire")
|
|
return queries.compute_org_stats("titulaire", titulaire_id)
|
|
|
|
|
|
@mcp_enabled(name="rechercher_marches", expose_docstring=True)
|
|
def rechercher_marches(
|
|
acheteur_id: str | None = None,
|
|
titulaire_id: str | None = None,
|
|
cpv: str | None = None,
|
|
objet_contient: str | None = None,
|
|
montant_min: float | None = None,
|
|
montant_max: float | None = None,
|
|
date_min: str | None = None,
|
|
date_max: str | None = None,
|
|
departement: str | None = None,
|
|
page: int = 1,
|
|
filtres_avances: dict | None = None,
|
|
) -> dict:
|
|
"""Recherche paginée de marchés publics (DECP).
|
|
|
|
Filtres nommés : acheteur_id, titulaire_id, cpv (code CPV, correspondance
|
|
partielle), objet_contient (texte de l'objet), montant_min, montant_max,
|
|
date_min / date_max (format YYYY-MM-DD, sur dateNotification),
|
|
departement (code département de l'acheteur).
|
|
filtres_avances : dict optionnel {"colonne__operateur": valeur} pour les
|
|
besoins pointus (mêmes colonnes/opérateurs que l'API REST colibre).
|
|
page : numéro de page (50 résultats par page).
|
|
Retourne {meta: {page, page_size, total}, marches: [...]}.
|
|
"""
|
|
track_mcp_tool("rechercher_marches", query=objet_contient)
|
|
return queries.search_marches(
|
|
acheteur_id=acheteur_id,
|
|
titulaire_id=titulaire_id,
|
|
cpv=cpv,
|
|
objet_contient=objet_contient,
|
|
montant_min=montant_min,
|
|
montant_max=montant_max,
|
|
date_min=date_min,
|
|
date_max=date_max,
|
|
departement=departement,
|
|
page=page,
|
|
filtres_avances=filtres_avances,
|
|
)
|
|
```
|
|
|
|
- [ ] **Step 4: Lancer le test → succès**
|
|
|
|
Run: `uv run pytest tests/mcp/test_tools.py -v`
|
|
Expected: PASS (5 tests)
|
|
|
|
- [ ] **Step 5: Commit**
|
|
|
|
```bash
|
|
git add src/mcp/tools.py tests/mcp/test_tools.py
|
|
git commit -m "feat(mcp): expose les 4 fonctions métier via @mcp_enabled"
|
|
```
|
|
|
|
---
|
|
|
|
### Task 8: Activation du serveur MCP dans l'app + doc env
|
|
|
|
**Files:**
|
|
|
|
- Modify: `src/app.py`
|
|
- Modify: `.template.env`
|
|
- Test: vérification manuelle (import) + suite complète.
|
|
|
|
**Interfaces:**
|
|
|
|
- Consumes: `src.mcp.tools` (Task 7), `enable_mcp`/`configure_mcp_server` de Dash.
|
|
- Produces: serveur MCP monté sur `/_mcp` quand `DASH_MCP_ENABLED=true`, exposant uniquement les 4 tools.
|
|
|
|
- [ ] **Step 1: Ajouter le paramètre `enable_mcp` au constructeur `Dash`**
|
|
|
|
Dans `src/app.py`, juste avant `app: Dash = Dash(` (vers la ligne 78), ajouter :
|
|
|
|
```python
|
|
_mcp_enabled = os.getenv("DASH_MCP_ENABLED") == "true"
|
|
```
|
|
|
|
Puis, dans l'appel `Dash(...)`, ajouter le paramètre (après `compress=True,`) :
|
|
|
|
```python
|
|
enable_mcp=_mcp_enabled,
|
|
```
|
|
|
|
- [ ] **Step 2: Monter les tools après l'init de l'app**
|
|
|
|
Toujours dans `src/app.py`, juste après la ligne `init_api(app.server)`, ajouter :
|
|
|
|
```python
|
|
# Serveur MCP (issue #111, scope A) : n'expose QUE les fonctions @mcp_enabled,
|
|
# jamais les callbacks/layout/pages d'UI. Activé via DASH_MCP_ENABLED=true.
|
|
if _mcp_enabled:
|
|
from dash.mcp import configure_mcp_server # noqa: E402
|
|
|
|
configure_mcp_server(
|
|
include_layout=False,
|
|
include_callbacks=False,
|
|
include_pages=False,
|
|
include_clientside_callbacks=False,
|
|
)
|
|
import src.mcp.tools # noqa: E402,F401 # l'import enregistre les @mcp_enabled
|
|
```
|
|
|
|
- [ ] **Step 3: Documenter la variable dans `.template.env`**
|
|
|
|
Ajouter à `.template.env` :
|
|
|
|
```bash
|
|
# Serveur MCP (issue #111). Laisser à false tant que l'authentification
|
|
# (OAuth + gate abonnement, scope B) n'est pas en place : sinon le serveur MCP
|
|
# est ouvert sans contrôle d'accès. Prérequis Matomo pour le tracking des appels :
|
|
# créer un Custom Dimension slot 1 (scope Action).
|
|
DASH_MCP_ENABLED=false
|
|
```
|
|
|
|
- [ ] **Step 4: Vérifier l'import des tools (hors app complète)**
|
|
|
|
Run: `uv run python -c "import src.mcp.tools; print('ok', [f for f in ('rechercher_organisations','stats_acheteur','stats_titulaire','rechercher_marches')])"`
|
|
Expected: affiche `ok [...]` sans erreur d'import.
|
|
|
|
- [ ] **Step 5: Lancer la suite de tests MCP complète**
|
|
|
|
Run: `uv run pytest tests/mcp/ -v`
|
|
Expected: PASS (tous les tests des tâches 1-7).
|
|
|
|
- [ ] **Step 6: Lancer la suite complète (dernière tâche du plan)**
|
|
|
|
Run: `uv run pytest`
|
|
Expected: PASS (aucune régression ; les tests Selenium nécessitent Chrome).
|
|
|
|
- [ ] **Step 7: Commit**
|
|
|
|
```bash
|
|
git add src/app.py .template.env
|
|
git commit -m "feat(mcp): activer le serveur MCP via DASH_MCP_ENABLED (scope A #111)"
|
|
```
|
|
|
|
---
|
|
|
|
## Vérification manuelle de bout en bout (optionnelle, après Task 8)
|
|
|
|
Pour tester le serveur MCP réel avec un vrai client :
|
|
|
|
```bash
|
|
DASH_MCP_ENABLED=true DATA_FILE_PARQUET_PATH=tests/test.parquet uv run run.py
|
|
# dans un autre terminal / client MCP :
|
|
claude mcp add colibre-local --transport http --scope user http://127.0.0.1:8050/_mcp
|
|
```
|
|
|
|
Puis demander à l'agent d'appeler `rechercher_marches` / `stats_acheteur`. Confirmer que seuls les 4 tools sont visibles (aucun callback d'UI).
|
|
|
|
## Self-Review (effectuée)
|
|
|
|
- **Couverture spec** : sérialisation (T1), tracking Matomo `action_name="MCP"`+`dimension1` (T2), non-pollution de `track_search` (T3), les 4 tools `rechercher_organisations` (T4) / `rechercher_marches` hybride (T5) / `stats_acheteur`+`stats_titulaire` (T6), surface réduite via `configure_mcp_server` + gating `DASH_MCP_ENABLED` off par défaut (T8), doc env + prérequis Matomo (T8). ✎ Écarts assumés vs spec, dus aux données réelles : pas de libellé CPV (`top_cpv` = `{cpv, nb_marches}`) ; `search_organisations` renvoie `{id, nom, departement}` sans `commune` (colonne absente de la sortie de `search_org`) — l'identité complète (avec commune) reste fournie par `stats_*` via `_org_identite`. Arborescence affinée : logique données regroupée dans `queries.py` (au lieu de `stats.py` seul) pour garder `tools.py` sans SQL.
|
|
- **Placeholders** : aucun TODO/TBD ; tout le code est fourni.
|
|
- **Cohérence des types** : `search_marches` / `compute_org_stats` / `search_organisations` référencés en T7 avec les signatures définies en T4-T6 ; `to_json_records`, `track_mcp_tool`, `search_org(track=…)` cohérents entre tâches ; contrepartie `top_<other>s` cohérente entre T6 (définition) et T7 (docstrings).
|