# missioflow-handoff-mcp

Serveur MCP local + web UI pour la coordination async entre les deux sessions Claude qui travaillent sur **missioflow-app** (backend PHP) et **missioflow-SuperAdmin** (panel Next.js). Remplace progressivement le markdown handoff `~/projects/missioflow-handoff.md`.

## Pourquoi

Le markdown handoff a fonctionné jusqu'à ~50 KB injectés par tour. Au-delà, on perd en signal :
- numérotation des Q dérive (Q8 promis ailleurs, repris pour autre chose)
- statut (open / answered / closed) implicite, à déduire à la lecture
- pas de query — il faut grep le fichier
- pas d'archivage propre, le fichier grossit linéairement

Ce serveur expose une API structurée stockée en SQLite, avec 6 outils MCP et un board kanban web pour visualiser.

## Architecture

```
┌────────────────────┐      stdio JSON-RPC      ┌──────────────────────┐
│ Claude (panel)     ├──────────────────────────┤ server.mjs           │
│   MCP_SESSION_ID   │                          │   (per-session pid)  │
│   = "panel"        │      ┌───────────────────┤                      │
└────────────────────┘      │                   └──────────┬───────────┘
                            │                              │ node:sqlite
┌────────────────────┐      │                              ▼
│ Claude (app)       ├──────┘                   ┌──────────────────────┐
│   MCP_SESSION_ID   │                          │ data/handoff.sqlite  │
│   = "app"          │                          │  (WAL mode)          │
└────────────────────┘                          └──────────┬───────────┘
                                                           │ read-only
                                                ┌──────────▼───────────┐
                                                │ web.mjs              │
                                                │ http://127.0.0.1:7878│
                                                └──────────────────────┘
```

Chaque session Claude lance son propre processus `server.mjs` (stdio MCP). Le SQLite en mode WAL gère les accès concurrents. Le web UI est un process séparé qui lit la même DB.

## Installation

```bash
cd ~/projects/missioflow-handoff-mcp
npm install
```

Une seule dépendance directe : `@modelcontextprotocol/sdk` (paquet officiel Anthropic). Aucune dépendance native de SQLite — utilise `node:sqlite` builtin (Node 22+).

## Configuration côté projets

Dans `~/projects/missioflow-app/.mcp.json` :

```json
{
  "mcpServers": {
    "missioflow-handoff": {
      "command": "node",
      "args": ["/home/taaazzz/projects/missioflow-handoff-mcp/src/server.mjs"],
      "env": {
        "MCP_SESSION_ID": "app"
      }
    }
  }
}
```

Dans `~/projects/missioflow-SuperAdmin/.mcp.json` :

```json
{
  "mcpServers": {
    "missioflow-handoff": {
      "command": "node",
      "args": ["/home/taaazzz/projects/missioflow-handoff-mcp/src/server.mjs"],
      "env": {
        "MCP_SESSION_ID": "panel"
      }
    }
  }
}
```

Au prochain démarrage de chaque session Claude (ou après `/mcp` pour rechargement), les 6 outils `mf_*` apparaîtront comme des tools natifs.

## Outils MCP exposés

| Outil | Rôle |
|---|---|
| `mf_ask(to, subject, body)` | Poser une question à l'autre session. |
| `mf_inbox(status?, limit?)` | Lister les questions adressées à ma session. |
| `mf_answer(message_id, body)` | Répondre à une question (passe son statut à `answered`). |
| `mf_close(message_id)` | Fermer une question sans réponse (obsolète, déjà résolue ailleurs). |
| `mf_history(subject_contains?, from_session?, to_session?, status?, limit?)` | Recherche dans tout l'historique. |
| `mf_thread(message_id)` | Récupérer un fil complet (question + toutes ses réponses). |

## Web UI

```bash
npm run web
# → http://localhost:7878
```

Board kanban à 3 colonnes (Open / Answered / Closed), auto-refresh toutes les 5 secondes, montre les threads avec leurs réponses inlinées. Lit le SQLite en read-only — peut tourner en parallèle des sessions Claude.

Variables d'env optionnelles :
- `MCP_HANDOFF_WEB_PORT` (défaut 7878)
- `MCP_HANDOFF_WEB_HOST` (défaut 127.0.0.1)
- `MCP_HANDOFF_DB` (défaut `data/handoff.sqlite`) — partagé avec `server.mjs`

## Tests

```bash
MCP_HANDOFF_DB=/tmp/smoke.sqlite npm run smoke
```

Smoke test bout-en-bout (ask → inbox → answer → thread → close → history).

## Cohabitation avec le markdown handoff legacy

Le fichier `~/projects/missioflow-handoff.md` reste en place comme archive des questions Q4-Q8 et des décisions actées avant le passage MCP. Les hooks `Stop` + `UserPromptSubmit` côté chaque projet continuent d'injecter ce markdown jusqu'à ce qu'on décide de les retirer (probablement après quelques jours d'usage MCP réussi).

À terme, les hooks seront simplifiés : juste un appel à `mf_inbox` pour signaler les questions ouvertes, plutôt que d'injecter le markdown complet.

## Limites v0.1

- Pas d'auth sur le web UI (bind sur 127.0.0.1 uniquement).
- Pas de pagination dans l'UI (les threads s'accumulent).
- Pas de fil de discussion multi-niveaux (une question peut avoir plusieurs réponses, mais une réponse ne peut pas être commentée).
- Pas de migration depuis le markdown legacy — l'historique Q4-Q8 reste seulement en .md.

À considérer pour v0.2 : auth basique sur le web UI, recherche/filtre dans l'UI, export en markdown pour archivage.