whats-mcp 0.1.0

package/.dockerignore

@@ -0,0 +1,12 @@
+.agent/
+AGENTS.md
+CLAUDE.md
+GEMINI.md
+COPILOT.md
+VIBE.md
+.git/
+node_modules/
+coverage/
+.env
+deploy/.env
+auth/

package/.gitlab-ci.yml

@@ -0,0 +1,54 @@
+stages:
+  - validate
+  - deploy
+
+validate_project:
+  stage: validate
+  image: node:22-bookworm-slim
+  script:
+    - npm ci
+    - npm test -- --runInBand
+    - node -e "const { loadConfig } = require('./src/config'); const cfg = loadConfig(); if (cfg.server.name !== 'whats-mcp') throw new Error('Unexpected package metadata wiring'); console.log('whats-mcp config smoke test OK');"
+
+deploy_homelab:
+  stage: deploy
+  tags:
+    - homelab
+  variables:
+    GIT_CLEAN_FLAGS: none
+  only:
+    - main
+  needs:
+    - validate_project
+  script:
+    - echo "🚀 Deploying whats-mcp to the homelab..."
+    - cd deploy
+    - echo "WHATSAPP_STATE_DIR=/data/state" > .env
+    - echo "WHATSAPP_LOG_LEVEL=error" >> .env
+    - echo "WHATSAPP_PRINT_QR=false" >> .env
+    - echo "WHATS_MCP_HTTP_HOST=0.0.0.0" >> .env
+    - echo "WHATS_MCP_HTTP_PORT=8092" >> .env
+    - echo "WHATS_MCP_HTTP_MCP_PATH=/mcp" >> .env
+    - echo "WHATS_MCP_ADMIN_ENV_FILE=/data/whats-admin.env" >> .env
+    - echo "WHATS_MCP_PUBLIC_BASE_URL=https://whats.kpihx-labs.com" >> .env
+    - echo "WHATS_MCP_FALLBACK_BASE_URL=https://whats.homelab" >> .env
+    - echo "TELEGRAM_WHATS_HOMELAB_TOKEN=$TELEGRAM_WHATS_HOMELAB_TOKEN" >> .env
+    - echo "TELEGRAM_CHAT_IDS=$TELEGRAM_CHAT_IDS" >> .env
+    - docker compose -p whats-mcp config -q
+    - docker rm -f whats-mcp || true
+    - docker compose -p whats-mcp up -d --build --remove-orphans
+    - |
+      for attempt in $(seq 1 20); do
+        status="$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}starting{{end}}' whats-mcp 2>/dev/null || true)"
+        if [ "$status" = "healthy" ]; then
+          break
+        fi
+        if [ "$status" = "unhealthy" ]; then
+          docker logs --tail 200 whats-mcp
+          exit 1
+        fi
+        sleep 3
+      done
+    - docker inspect --format '{{.State.Health.Status}}' whats-mcp | grep -qx healthy
+    - docker exec whats-mcp node -e "fetch('http://127.0.0.1:8092/health').then((r) => { if (!r.ok) process.exit(1); }).catch(() => process.exit(1))"
+    - docker image prune -f

package/CHANGELOG.md

@@ -0,0 +1,38 @@
+# Changelog
+
+All notable changes to **whats-mcp** will be documented in this file.
+
+## [Unreleased]
+
+### Changed
+
+- **Project rename finalized** — the public package and operator surface now consistently use `whats-mcp` / `whats-admin`.
+- **Package metadata normalized** — server name and version now come from `package.json` instead of being duplicated in `config.json`.
+- **Runtime artifact naming cleaned** — pid/log filenames now use the final `whats-mcp.*` naming.
+
+### Added
+
+- **Shared MCP server builder** — `src/server.js` now centralizes stdio and HTTP server construction.
+- **Dual transport entrypoint** — `src/main.js` now supports both `serve` and `serve-http`.
+- **HTTP operator surface** — `src/http_app.js` now exposes `/health`, `/admin/status`, `/admin/help`, and streamable MCP over `/mcp`.
+- **Shared admin helpers** — `src/admin/service.js` now centralizes status/help/log summaries for CLI, HTTP, and Telegram.
+- **Telegram admin bridge** — `src/admin/telegram.js` adds the first homelab operator bridge for `/start`, `/help`, `/status`, `/health`, `/urls`, `/logs`, and `/restart`.
+- **Deployment bundle** — `.dockerignore`, `Dockerfile`, `deploy/docker-compose.yml`, `deploy/docker-compose.override.example.yml`, `src/.env.example`, and `.gitlab-ci.yml`.
+- **HTTP admin tests** — `tests/http_app.test.js` validates the new handler surface.
+- **Admin logging parity** — shared admin logging now records Telegram commands, replies, and errors into the common admin log file.
+- **Package-internal env loading** — `src/.env` is loaded automatically before runtime environment overrides.
+- **Deploy health probes fixed** — Docker Compose and GitLab now use Node-native fetch probes instead of assuming `curl` exists inside the image.
+- **Container operator binaries exposed** — the image now installs `whats-mcp` and `whats-admin` on `PATH` so `docker exec ... whats-admin ...` works directly.
+- **Admin reconnect path clarified** — CLI and Telegram now expose a `reconnect` operator action, and pairing code login accepts phone formats like `+33605957785`.
+- **Remote pairing flow added** — HTTP and Telegram admin now expose first-connection / re-pair actions through `POST /admin/pair-code` and `/pair_code <phone>`, backed by the shared `whats-admin login --code --phone ... --force` flow.
+- **Compose project isolation** — whats-mcp deploys now pin the Compose project name to `whats-mcp`, preventing sibling MCP stacks deployed from other `deploy/` directories from being treated as orphans and removed.
+- **Reconnect semantics fixed** — `/reconnect`, `POST /admin/reconnect`, and `whats-admin server reconnect` now trigger a live WhatsApp socket reconnect instead of restarting the container, preventing Telegram command replay loops caused by poll offset resets. `/restart` remains the explicit full-process restart path.
+- **Deploy migration hardened** — the homelab deploy now reuses the existing `deploy_whats_mcp_data` volume and removes any stale `whats-mcp` container before `docker compose up`, preserving the paired WhatsApp session while migrating to the isolated Compose project name.
+
+## [0.1.0]
+
+### Added
+
+- Initial WhatsApp MCP server based on Baileys
+- Persistent local store and analytics
+- Tool catalog covering messaging, chats, contacts, groups, profile, channels, labels, utilities, and intent-first overview flows

package/README.md

@@ -0,0 +1,205 @@
+# whats-mcp
+
+Comprehensive **WhatsApp MCP server** powered by Baileys, with intent-first read surfaces and dual transport support:
+
+- local `stdio` for direct MCP clients
+- remote `streamable-http` for homelab deployment
+- operator surfaces over CLI, HTTP, and Telegram
+
+## Features
+
+- **64 MCP tools** for messaging, chats, contacts, groups, profile, channels, labels, analytics, watchlists, and intent-first overview flows
+- **Intent-first tools** already built into the surface:
+  - `whatsup`
+  - `find_messages`
+  - `daily_digest`
+  - `manage_watchlist`
+- **Persistent auth + local analytics store**
+- **Dual transport**:
+  - `whats-mcp serve`
+  - `whats-mcp serve-http`
+- **Operator surfaces**:
+  - `whats-admin`
+  - `/health`
+  - `/admin/status`
+  - `/admin/help`
+  - `POST /admin/reconnect`
+  - `POST /admin/pair-code`
+  - Telegram admin bridge when configured
+
+## Package Layout
+
+```text
+src/
+├── admin/
+│   ├── service.js      # shared operator summaries and runtime status helpers
+│   └── telegram.js     # Telegram command bridge
+├── tools/              # MCP tool catalog
+├── connection.js       # Baileys lifecycle and reconnect logic
+├── config.js           # config.json + env overrides + package metadata
+├── helpers.js          # shared WhatsApp helper functions
+├── http_app.js         # HTTP transport + /health + /admin/*
+├── main.js             # transport entrypoint (stdio + HTTP)
+├── server.js           # shared MCP server construction
+└── store.js            # local cache, analytics index, watchlists
+```
+
+## Installation
+
+```bash
+npm install
+```
+
+Commands exposed:
+
+```bash
+whats-mcp
+whats-admin
+```
+
+## Local Usage
+
+### Stdio MCP
+
+```bash
+whats-mcp serve
+```
+
+### HTTP MCP
+
+```bash
+whats-mcp serve-http
+```
+
+Default HTTP surface:
+
+- MCP: `/mcp`
+- Health: `/health`
+- Admin status: `/admin/status`
+- Admin help: `/admin/help`
+- Admin reconnect: `POST /admin/reconnect`
+- Admin pair-code: `POST /admin/pair-code`
+
+Default URLs:
+
+- Primary: `https://whats.kpihx-labs.com`
+- Fallback: `https://whats.homelab`
+
+## Configuration
+
+The project uses:
+
+- `config.json` for non-sensitive runtime settings
+- `src/.env.example` for deploy/runtime environment variables
+
+Relevant environment variables:
+
+| Variable | Purpose |
+|---|---|
+| `WHATSAPP_STATE_DIR` | Persistent Baileys auth + local store path |
+| `WHATSAPP_LOG_LEVEL` | Runtime log level |
+| `WHATS_MCP_HTTP_HOST` | HTTP bind host |
+| `WHATS_MCP_HTTP_PORT` | HTTP bind port |
+| `WHATS_MCP_HTTP_MCP_PATH` | MCP HTTP path |
+| `WHATS_MCP_PUBLIC_BASE_URL` | Primary trusted route |
+| `WHATS_MCP_FALLBACK_BASE_URL` | Fallback route |
+| `TELEGRAM_WHATS_HOMELAB_TOKEN` | Optional Telegram admin bot token |
+| `TELEGRAM_CHAT_IDS` | Optional comma-separated Telegram admin allowlist |
+
+## CLI Admin
+
+Shared operator summary:
+
+```bash
+whats-admin guide
+```
+
+Main commands:
+
+```text
+whats-admin status
+whats-admin guide
+whats-admin login [--code] [--phone N] [--force]
+whats-admin logout [-f]
+whats-admin server status|stop|restart|reconnect|pid|test
+whats-admin config show|edit|reset|path
+whats-admin logs show|tail|clean|path
+```
+
+Container usage:
+
+```bash
+docker exec -it whats-mcp whats-admin status
+docker exec -it whats-mcp whats-admin login
+docker exec -it whats-mcp whats-admin login --code --phone +33605957785
+curl -fsS -X POST https://whats.kpihx-labs.com/admin/pair-code -H 'content-type: application/json' -d '{"phone":"33605957785"}'
+curl -fsS -X POST https://whats.kpihx-labs.com/admin/reconnect
+docker exec -it whats-mcp whats-admin server reconnect
+```
+
+Reconnect semantics:
+
+- `reconnect` performs an in-process WhatsApp socket reconnect and keeps the HTTP server plus Telegram poller alive.
+- `restart` restarts the container process and should be reserved for full service restarts, not routine session refreshes.
+
+## Telegram Admin
+
+When both variables are configured:
+
+- `TELEGRAM_WHATS_HOMELAB_TOKEN`
+- `TELEGRAM_CHAT_IDS`
+
+the HTTP service auto-starts a Telegram admin poller.
+
+Current commands:
+
+```text
+/start
+/help
+/status
+/health
+/urls
+/logs [lines]
+/pair_code <phone>
+/reconnect
+/restart
+```
+
+## Docker / Homelab Deployment
+
+Deployment bundle:
+
+- `Dockerfile`
+- `deploy/docker-compose.yml`
+- `deploy/docker-compose.override.example.yml`
+- `.dockerignore`
+- `.gitlab-ci.yml`
+- `src/.env.example`
+
+Typical local dry-run:
+
+```bash
+cd deploy
+cp ../src/.env.example .env
+docker compose config -q
+docker compose up --build
+```
+
+The deployment stores persistent WhatsApp state under `/data/state` inside the container volume, so redeploys do not wipe the linked session.
+
+## Validation
+
+Current baseline:
+
+```bash
+npm test -- --runInBand
+```
+
+This validates:
+
+- config loading
+- helpers
+- store behavior
+- tool registry and handlers
+- HTTP admin handler surface
+- Telegram admin dispatch and runtime status

package/TODO.md

@@ -0,0 +1,6 @@
+# TODO
+
+- [ ] Split the current large Node modules into smaller domains where it materially improves maintainability without harming testability.
+- [ ] Add integration tests for `serve-http` end-to-end MCP initialize / tools/list / tools/call flows.
+- [ ] Add deployment smoke checks for the containerized HTTP transport on the homelab.
+- [ ] Open the GitHub and GitLab remotes for this new repository once the migration is stable.

package/config.json

@@ -0,0 +1,19 @@
+{
+  "server": {
+    "state_directory": "~/.mcps/whatsapp"
+  },
+  "connection": {
+    "print_qr_in_terminal": true,
+    "reconnect_interval_ms": 3000,
+    "max_reconnect_attempts": 10,
+    "mark_online_on_connect": false
+  },
+  "store": {
+    "max_messages_per_chat": 5000,
+    "max_chats": 1000
+  },
+  "logging": {
+    "level": "error"
+  },
+  "watchlists": {}
+}

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "whats-mcp",
+  "version": "0.1.0",
+  "description": "MCP server for WhatsApp — intent-first messaging, chat management, analytics, and operator surfaces over stdio and HTTP.",
+  "main": "src/main.js",
+  "bin": {
+    "whats-mcp": "src/main.js",
+    "whats-admin": "src/admin.js"
+  },
+  "scripts": {
+    "start": "node src/main.js serve",
+    "serve:http": "node src/main.js serve-http",
+    "admin": "node src/admin.js",
+    "login": "node src/admin.js login",
+    "login:code": "node src/admin.js login --code",
+    "test": "node --experimental-vm-modules node_modules/.bin/jest --coverage",
+    "test:watch": "node --experimental-vm-modules node_modules/.bin/jest --watch",
+    "stop": "node src/admin.js server stop",
+    "status": "node src/admin.js status"
+  },
+  "keywords": [
+    "whatsapp",
+    "mcp",
+    "model-context-protocol",
+    "baileys",
+    "messaging",
+    "automation"
+  ],
+  "author": "Ivann KAMDEM <kapoivha@gmail.com>",
+  "license": "MIT",
+  "type": "commonjs",
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@whiskeysockets/baileys": "^7.0.0-rc.9",
+    "commander": "^13.1.0",
+    "express": "^5.2.1",
+    "pino": "^10.3.1",
+    "qrcode-terminal": "^0.12.0"
+  },
+  "devDependencies": {
+    "jest": "^29.0.0"
+  }
+}

package/src/.env.example

@@ -0,0 +1,21 @@
+# HTTP transport
+WHATS_MCP_HTTP_HOST=0.0.0.0
+WHATS_MCP_HTTP_PORT=8092
+WHATS_MCP_HTTP_MCP_PATH=/mcp
+WHATS_MCP_PUBLIC_BASE_URL=https://whats.kpihx-labs.com
+WHATS_MCP_FALLBACK_BASE_URL=https://whats.homelab
+WHATS_MCP_ADMIN_ENV_FILE=/data/whats-admin.env
+
+# WhatsApp runtime
+WHATSAPP_STATE_DIR=/data/state
+WHATSAPP_LOG_LEVEL=error
+WHATSAPP_MAX_RECONNECT=10
+WHATSAPP_PRINT_QR=false
+WHATSAPP_SYNC_FULL_HISTORY=true
+WHATSAPP_REFRESH_APP_STATE=true
+WHATSAPP_PERSIST_STORE=true
+WHATSAPP_MAX_MESSAGES_PER_CHAT=5000
+
+# Optional Telegram admin bridge
+TELEGRAM_WHATS_HOMELAB_TOKEN=
+TELEGRAM_CHAT_IDS=