whats-mcp 0.1.0 → 0.2.0

package/.gitlab-ci.yml

@@ -2,13 +2,38 @@ stages:
   - validate
   - deploy
 
+variables:
+  DOCKER_DRIVER: overlay2
+
 validate_project:
   stage: validate
   image: node:22-bookworm-slim
+  variables:
+    GIT_CLEAN_FLAGS: none
   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');"
+    - |
+      if command -v npm >/dev/null 2>&1; then
+        apt-get update -qq && apt-get install -y --no-install-recommends git
+        git config --global url."https://github.com/".insteadOf "git@github.com:"
+        npm install
+        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');"
+      elif command -v docker >/dev/null 2>&1; then
+        docker run --rm \
+          -v "$CI_PROJECT_DIR:/work" \
+          -w /work \
+          node:22-bookworm-slim \
+          sh -c '
+            apt-get update -qq && apt-get install -y --no-install-recommends git &&
+            git config --global url."https://github.com/".insteadOf "git@github.com:" &&
+            npm install &&
+            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\");"
+          '
+      else
+        echo "Neither npm nor docker is available on this runner."
+        exit 1
+      fi
 
 deploy_homelab:
   stage: deploy
@@ -21,7 +46,7 @@ deploy_homelab:
   needs:
     - validate_project
   script:
-    - echo "🚀 Deploying whats-mcp to the homelab..."
+    - echo "Deploying whats-mcp to the homelab..."
     - cd deploy
     - echo "WHATSAPP_STATE_DIR=/data/state" > .env
     - echo "WHATSAPP_LOG_LEVEL=error" >> .env
@@ -50,5 +75,5 @@ deploy_homelab:
         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 exec whats-mcp bun -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

@@ -4,6 +4,12 @@ All notable changes to **whats-mcp** will be documented in this file.
 
 ## [Unreleased]
 
+## [0.2.0]
+
+### Added
+- **Local Media Cache Tooling** — `download_media` now saves extracted Baileys buffers to local disk (`$HOME/.cache/whats_media/`) and returns the paths instead of flooding the MCP context with multi-megabyte Base64 strings.
+- **`cleanup_media` tool** — added a new utility tool to clear the local media cache directory and free up space safely.
+
 ### Changed
 
 - **Project rename finalized** — the public package and operator surface now consistently use `whats-mcp` / `whats-admin`.

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 KAMDEM Ivann (KπX)
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/Makefile

@@ -0,0 +1,44 @@
+.DEFAULT_GOAL := help
+ZSH_LOGIN     := zsh -lc
+
+help:  ## Show available targets
+	@grep -E '^[a-zA-Z_-]+:.*?##' $(MAKEFILE_LIST) | \
+	  awk 'BEGIN {FS = ":.*?## "}; {printf "  %-15s %s\n", $$1, $$2}'
+
+# ── Dev ──────────────────────────────────────────────────────────────────────
+
+install:  ## Install dependencies
+	@bun install
+
+test:  ## Run tests
+	@bun test
+
+# ── Build & Publish ───────────────────────────────────────────────────────────
+
+build:  ## Bundle with bun
+	@bun run build
+
+publish: build  ## Publish to npm (requires NPM_TOKEN via bw-env)
+	@$(ZSH_LOGIN) 'if ! env | grep -q "^NPM_TOKEN="; then \
+		echo "NPM_TOKEN missing — run bw-env first"; exit 1; fi; \
+	bun publish'
+
+release: test build publish push  ## Full release: test → build → publish → push
+
+# ── Git ───────────────────────────────────────────────────────────────────────
+
+push:  ## Push current branch to all remotes (github + gitlab)
+	@branch="$$(git branch --show-current)"; \
+	for remote in $$(git remote); do \
+		echo "==> pushing $$branch to $$remote"; \
+		git push "$$remote" "$$branch"; \
+	done
+
+push-tags:  ## Push all tags to all remotes
+	@for remote in $$(git remote); do git push "$$remote" --tags; done
+
+status:  ## git status --short
+	@git status --short
+
+log:  ## Last 10 commits oneline
+	@git log --oneline -10

package/README.md

@@ -1,5 +1,9 @@
 # whats-mcp
 
+[![npm](https://img.shields.io/npm/v/whats-mcp)](https://www.npmjs.com/package/whats-mcp)
+[![Node](https://img.shields.io/node/v/whats-mcp)](https://www.npmjs.com/package/whats-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
+
 Comprehensive **WhatsApp MCP server** powered by Baileys, with intent-first read surfaces and dual transport support:
 
 - local `stdio` for direct MCP clients
@@ -47,7 +51,11 @@ src/
 ## Installation
 
 ```bash
-npm install
+# recommended — installs globally as a standalone tool
+npm install -g whats-mcp
+
+# or via npx (no install)
+npx whats-mcp
 ```
 
 Commands exposed:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "whats-mcp",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "MCP server for WhatsApp — intent-first messaging, chat management, analytics, and operator surfaces over stdio and HTTP.",
   "main": "src/main.js",
   "bin": {
@@ -8,15 +8,16 @@
     "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"
+    "start": "bun src/main.js serve",
+    "serve:http": "bun src/main.js serve-http",
+    "admin": "bun src/admin.js",
+    "login": "bun src/admin.js login",
+    "login:code": "bun src/admin.js login --code",
+    "build": "echo 'No build required'",
+    "test": "jest --coverage",
+    "test:watch": "jest --watch",
+    "stop": "bun src/admin.js server stop",
+    "status": "bun src/admin.js status"
   },
   "keywords": [
     "whatsapp",
@@ -30,6 +31,7 @@
   "license": "MIT",
   "type": "commonjs",
   "engines": {
+    "bun": ">=1.0.0",
     "node": ">=18.0.0"
   },
   "dependencies": {

package/src/tools/utils.js

@@ -2,7 +2,7 @@
  * whats-mcp — Utility tools (6 tools).
  *
  * connection_status, whatsapp_guide, send_presence,
- * read_messages, search_messages, download_media,
+ * read_messages, search_messages, download_media, cleanup_media,
  * analytics_overview, analytics_top_chats, analytics_chat_insights,
  * analytics_timeline, analytics_search
  */
@@ -240,7 +240,7 @@ module.exports = [
       name: "download_media",
       description:
         "Download media (image, video, audio, document, sticker) from a message." +
-        " Returns the media as base64-encoded data." +
+        " Returns the local file path where the media was saved ($HOME/.cache/whats_media/)." +
         " The message must be in the local store.",
       inputSchema: {
         type: "object",
@@ -291,17 +291,80 @@ module.exports = [
 
       // Use Baileys downloadMediaMessage
       const { downloadMediaMessage } = require("@whiskeysockets/baileys");
-      const buffer = await downloadMediaMessage(msg, "buffer", {});
-      const base64 = buffer.toString("base64");
+      let buffer;
+      try {
+        buffer = await downloadMediaMessage(msg, "buffer", {});
+      } catch (err) {
+        return errResult(`Failed to download media: ${err.message}`);
+      }
+
+      const os = require("os");
+      const fs = require("fs");
+      const path = require("path");
+
+      const cacheDir = path.join(os.homedir(), ".cache", "whats_media");
+      if (!fs.existsSync(cacheDir)) {
+        fs.mkdirSync(cacheDir, { recursive: true });
+      }
+
+      let fileName = mediaMsg.fileName || mediaMsg.title || `${message_id}.${mediaType}`;
+      fileName = fileName.replace(/[^a-zA-Z0-9.\-_]/g, "_");
+      
+      let ext = path.extname(fileName);
+      if (!ext && mediaMsg.mimetype) {
+        const mimeExt = mediaMsg.mimetype.split("/")[1]?.split(";")[0];
+        if (mimeExt) fileName += `.${mimeExt}`;
+      }
+
+      const filePath = path.join(cacheDir, fileName);
+      fs.writeFileSync(filePath, buffer);
 
       return okResult({
         message_id,
         media_type: mediaType,
         mimetype: mediaMsg.mimetype || null,
-        filename: mediaMsg.fileName || null,
-        file_length: mediaMsg.fileLength ? Number(mediaMsg.fileLength) : buffer.length,
-        base64_length: base64.length,
-        data: base64,
+        filename: fileName,
+        file_length: buffer.length,
+        saved_to: filePath,
+      });
+    },
+  },
+
+  // 7. cleanup_media
+  {
+    definition: {
+      name: "cleanup_media",
+      description: "Clear the local WhatsApp media cache directory ($HOME/.cache/whats_media/).",
+      inputSchema: { type: "object", properties: {} },
+    },
+    handler: async () => {
+      const os = require("os");
+      const fs = require("fs");
+      const path = require("path");
+      
+      const cacheDir = path.join(os.homedir(), ".cache", "whats_media");
+      if (!fs.existsSync(cacheDir)) {
+        return okResult({ status: "skipped", message: "Cache directory does not exist." });
+      }
+      
+      let count = 0;
+      let bytesFreed = 0;
+      const files = fs.readdirSync(cacheDir);
+      for (const file of files) {
+        const filePath = path.join(cacheDir, file);
+        const stats = fs.statSync(filePath);
+        if (stats.isFile()) {
+            bytesFreed += stats.size;
+            fs.unlinkSync(filePath);
+            count++;
+        }
+      }
+      
+      return okResult({
+        status: "cleaned",
+        files_deleted: count,
+        bytes_freed: bytesFreed,
+        cache_dir: cacheDir
       });
     },
   },
@@ -313,7 +376,7 @@ function _guessCategory(name) {
   if (/channel|newsletter/.test(name)) return "channels";
   if (/label/.test(name)) return "labels";
   if (/^analytics_|^daily_digest/.test(name)) return "analytics";
-  if (/^connection_status$|^whatsapp_guide$|^send_presence$|^read_messages$|^search_messages$|^download_media$/.test(name)) {
+  if (/^connection_status$|^whatsapp_guide$|^send_presence$|^read_messages$|^search_messages$|^download_media$|^cleanup_media$/.test(name)) {
     return "utilities";
   }
   if (/^send_|^edit_|^delete_|^forward_|^batch_/.test(name)) return "messaging";