neuron-mcp-server 1.1.0 → 1.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Neuron (https://neuron.ng)
+
+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/README.md

@@ -1,193 +1,190 @@
 # Neuron MCP Server
 
-Exposes the Neuron WhatsApp platform as MCP tools (bots, conversations, broadcasts, approvals, and more). Each tool proxies to the Neuron REST API (`NEURON_API_URL`, default `https://api.neuron.ng/api/v1`).
+> WhatsApp automation platform with 300+ MCP tools for AI-powered chatbots, broadcasts, campaigns, and more.
 
-## Connect
+[![npm version](https://img.shields.io/npm/v/neuron-mcp-server)](https://www.npmjs.com/package/neuron-mcp-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![smithery badge](https://smithery.ai/badge/rsh/neuron)](https://smithery.ai/servers/rsh/neuron)
 
-- **Remote (Claude.ai / hosted clients):** `https://mcp.neuron.ng/mcp` (Streamable HTTP).
-- **Local (Claude Code / IDE, stdio):** run `node dist/index.js` (or `npm run dev`). Configure with `MCP_TRANSPORT=stdio` (default).
+## What is Neuron?
 
-## Auth
+[Neuron](https://neuron.ng) is an AI-powered WhatsApp automation platform. This MCP server exposes **300+ tools** that let AI coding assistants — Claude Code, Cursor, Windsurf, and other MCP-compatible clients — manage your entire WhatsApp business programmatically.
 
-Two token types are used:
+Build chatbots, send broadcasts, manage contacts, create campaigns, publish newsletters, and more — all through natural language with your AI assistant.
 
-- **Session token** — most tools use the org-level token from `neuron_login` (or `NEURON_AUTH_TOKEN` / smithery `authToken`).
-- **Bot API key (`nrn_`)** — the `neuron_bot_api_*` and `neuron_*_approval` tools take an explicit `apiKey` argument per call. Create one in the dashboard under your bot's API keys.
+## Quick Start
 
----
+### Option 1: Remote Server (Recommended — zero install)
 
-## Approvals — human-in-the-loop sign-off
+Add to your MCP client config:
 
-Ask a human to approve or reject an action over WhatsApp and get the decision back. The recipient replies `approve` / `reject` / `reject: <reason>` (or quotes the message). Use it to gate refunds, deploys, spend, publishing, or an agent's own tool use.
+```json
+{
+  "mcpServers": {
+    "neuron": {
+      "type": "url",
+      "url": "https://mcp.neuron.ng/mcp"
+    }
+  }
+}
+```
 
-**Tools** (all take `apiKey`, a bot API key with the `nrn_` prefix):
+No installation required. Works immediately with any MCP client that supports Streamable HTTP.
 
-| Tool | Purpose |
-|---|---|
-| `neuron_request_approval` | Create a request and send the WhatsApp prompt |
-| `neuron_get_approval` | Fetch one approval; `waitSeconds` (1–60) long-polls until it resolves |
-| `neuron_list_approvals` | List approvals, filter by `status` |
-| `neuron_respond_approval` | Approve/reject programmatically — decide via MCP instead of WhatsApp |
-| `neuron_cancel_approval` | Cancel a still-pending request |
+### Option 2: Local Server (via npm)
 
-An operator can resolve an approval from either side — a WhatsApp reply **or** `neuron_respond_approval`. Whichever lands first wins (exactly-once); the later one returns a "already resolved" error. Responding via MCP still fires the callback and posts the outcome to the WhatsApp chat.
+Run directly with npx:
 
-```jsonc
-neuron_respond_approval({
-  "apiKey": "nrn_...",
-  "approvalId": "b1f...",
-  "decision": "reject",
-  "reason": "duplicate charge",
-  "responderName": "Ops"
-})
+```bash
+npx neuron-mcp-server
 ```
 
-### Poll flow (simplest)
-
-```jsonc
-// 1. Request — omit `callback` for a poll-only flow
-neuron_request_approval({
-  "apiKey": "nrn_...",
-  "to": "2348012345678",
-  "prompt": "Approve refund of ₦45,000 for order #1042?",
-  "metadata": { "orderId": "1042" }
-})
-// → { "approvalId": "b1f...", "status": "pending", "expiresAt": "..." }
-
-// 2. Wait for the human (blocks up to 60s, repeat until resolved/expired)
-neuron_get_approval({ "apiKey": "nrn_...", "approvalId": "b1f...", "waitSeconds": 60 })
-// → { "status": "approved", "decision": "approve", "responder": { "name": "Tunde" }, ... }
-```
+Or install globally:
 
-### Webhook flow (no polling)
-
-Supply a `callback.delivery` scheme and Neuron pushes the decision to you when it resolves:
-
-```jsonc
-neuron_request_approval({
-  "apiKey": "nrn_...",
-  "to": "2348012345678",
-  "prompt": "Ship deploy #42 to production?",
-  "callback": {
-    "response": { "schemes": ["keyword"] },
-    "delivery": { "scheme": "webhook_signed", "config": { "url": "https://your-app.com/hooks/approvals", "secret": "whsec_..." } }
-  },
-  "idempotencyKey": "deploy-42"
-})
+```bash
+npm install -g neuron-mcp-server
 ```
 
-Your endpoint receives `{ "event": "approval.resolved", "data": { "approvalId", "decision", "reason", "responder", "metadata", ... } }`. For `webhook_signed`, verify the `X-Neuron-Signature: sha256=...` header (HMAC-SHA256 of the raw body with your secret).
-
-### Callback schemes
-
-- **`response.schemes`** — how a reply becomes a decision: `interactive` · `keyword` · `code` (one-time code in the prompt) · `llm` (natural-language). Ordered fallback; default `["keyword"]`.
-- **`delivery.scheme`** — how the decision reaches you: `webhook_signed` (HMAC) · `webhook_simple` (URL-as-secret) · `neuron_message` (send as a WhatsApp message) · `neuron_tool` (invoke another Neuron tool) · `none` (poll).
-- **`await: true`** — hold `neuron_request_approval` until resolved and return the decision inline (up to `awaitTimeoutSec`).
-
-Full endpoint reference: `https://api.neuron.ng/api/docs` (see the **Approvals** tag).
-
-## Tasks — scheduled autonomous bot actions
-
-A **task** is a natural-language instruction a bot carries out on its own, on a schedule (e.g. *"every morning at 8am, message 10 people we haven't heard from in 10+ days with our intro offer"*). Each run is an agentic tool-loop. Within a run the bot can:
-
-- **Select an audience** — by staleness (no reply in N days), tag, contact list, or search.
-- **Compose accurately** — look facts, prices, menus, and links up in the bot's **knowledge base** (never guesses).
-- **Reach people** — send text, image/document/video/audio, or polls to individuals; **broadcast** to many at once; **schedule** a future message; **post to a WhatsApp group**.
-- **Orchestrate** — read a contact's history for context, tag contacts / add them to lists, enrol them in drip sequences, **compile an activity report**, notify the team, and schedule follow-up tasks.
+Claude Code config (`~/.claude/mcp.json`):
+
+```json
+{
+  "mcpServers": {
+    "neuron": {
+      "command": "npx",
+      "args": ["-y", "neuron-mcp-server"]
+    }
+  }
+}
+```
 
-Every send is automatically screened against the org's Do-Not-Contact list, a per-run action cap, and a no-repeat window; a task can optionally require WhatsApp approval before sending, or run as a dry run. You describe all of this in plain English in the `instruction` — the tools above are what the bot uses under the hood.
+## Authentication
 
-These tools use the session token (from `neuron_login`).
+Three ways to authenticate:
 
-| Tool | Purpose |
-| --- | --- |
-| `neuron_draft_task` | Turn a plain-English description into a structured task spec (does **not** create it) |
-| `neuron_create_task` | Create a task for a bot |
-| `neuron_list_tasks` | List a bot's tasks |
-| `neuron_update_task` | Update a task (partial) |
-| `neuron_toggle_task` | Pause / resume a task |
-| `neuron_run_task` | Run a task immediately (in addition to its schedule) |
-| `neuron_get_task_runs` | Paginated run history — status, AI summary, tool steps, stats |
-| `neuron_delete_task` | Delete a task (soft delete; stops it running) |
+### 1. Browser Login (Recommended)
 
-### Schedule shapes
+Call `neuron_login()` with no arguments. The server returns a URL — open it in your browser to authorize securely. No credentials are shared with the AI.
 
-`scheduleKind` + `schedule`:
+### 2. MCP Token
 
-- **`cron`** — recurring at a clock time: `{ "time": "08:00", "days": [1,4] }` (`days` 0=Sun..6=Sat; empty/omitted = every day)
-- **`interval`** — `{ "everyMinutes": 360 }`
-- **`once`** — `{ "runAt": "2026-08-10T14:00:00Z" }`
-- **`manual`** — `{}` (only runs via `neuron_run_task`)
+Generate a token from your Neuron dashboard (**Settings > MCP Tokens**), then:
 
-`timezone` is IANA (e.g. `Africa/Lagos`). `config` accepts `{ channelId?, maxActions?, noRepeatDays?, requiresApproval?, approvalPhone?, dryRun? }`.
+```
+neuron_login({ token: "your-mcp-token" })
+```
 
-### Typical flow
+### 3. Environment Variable
 
-```jsonc
-// 1. Draft from natural language, review, then create.
-neuron_draft_task({ "botId": "…", "prompt": "every morning at 8am, re-engage 10 contacts we haven't heard from in 10+ days with our intro message", "timezone": "Africa/Lagos" })
-// -> { title, instruction, scheduleKind:"cron", schedule:{time:"08:00"}, timezone, config:{maxActions:10} }
+Set `NEURON_AUTH_TOKEN` for unattended/CI use:
 
-neuron_create_task({ "botId": "…", "title": "Morning re-engage", "instruction": "…", "scheduleKind": "cron", "schedule": { "time": "08:00" }, "timezone": "Africa/Lagos", "config": { "maxActions": 10, "noRepeatDays": 14 } })
+```bash
+NEURON_AUTH_TOKEN=your-token npx neuron-mcp-server
+```
 
-neuron_run_task({ "id": "…" })          // fire once now to test
-neuron_get_task_runs({ "id": "…" })     // inspect what it did
+## Available Tools (300+)
+
+| Category | Tools | Description |
+|----------|-------|-------------|
+| **Authentication** | 9 | Login, register, org switching, token refresh |
+| **Bot Management** | 11 | Create and manage AI chatbots with configurable LLM models |
+| **Conversations & Messaging** | 20 | Message management, human takeover, send WhatsApp messages, polls |
+| **Approvals** | 5 | Human-in-the-loop approve/reject over WhatsApp |
+| **Channels & Sessions** | 19 | WhatsApp connections, QR/pair-code, session management |
+| **Social Channels** | 11 | Post to X, Instagram, Facebook, LinkedIn, TikTok |
+| **Broadcasts** | 7 | Bulk messaging to contact lists |
+| **Campaigns** | 16 | Sponsored campaigns, marketplace, funding |
+| **List Campaigns** | 8 | Paced, per-run messaging to list members |
+| **Contacts** | 12 | CRUD, import/export, semantic search, sync |
+| **Contact Lists** | 11 | Segmentation, merge, membership management |
+| **Leads** | 7 | Multi-source lead capture, pool, convert |
+| **Knowledge Bases** | 14 | Upload documents, semantic search, sync, ingest content |
+| **Newsletters** | 9 | WhatsApp Channel/newsletter management |
+| **Products & Sales** | 17 | Sell products, checkout, orders, delivery, memberships |
+| **Flows** | 11 | Event-driven automation flows and runs |
+| **Tasks & Scheduling** | 12 | Scheduled autonomous bot tasks and messages |
+| **Personas** | 9 | Build and apply voice personas |
+| **Group Management** | 11 | Create groups, manage members, settings |
+| **Webhooks** | 10 | Inbound and outbound webhook management |
+| **Custom Tools** | 10 | HTTP API tools for bots with secret injection |
+| **Bot API** | 8 | Bot-scoped API keys, chat and messaging |
+| **Marketplace & Pool** | 23 | Publish and install bots, tools, and contact lists |
+| **Blog** | 6 | Content publishing |
+| **Organizations & Audit** | 11 | Team management, audit logs, member invitations |
+| **Billing & Wallet** | 12 | Subscriptions, wallet, payouts, bank accounts |
+| **Profile & Privacy** | 10 | Profile name/status/picture, privacy settings |
+| **Reflections** | 4 | Self-learning bot improvement suggestions |
+| **Media & AI** | 2 | Upload media, AI text rewriting |
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `NEURON_API_URL` | API base URL | `https://api.neuron.ng/api/v1` |
+| `NEURON_AUTH_TOKEN` | Pre-set auth token | — |
+| `MCP_TRANSPORT` | Transport mode: `stdio` or `http` | `stdio` |
+| `PORT` | HTTP server port (when using `http` transport) | `3001` |
+
+## IDE Setup
+
+### Claude Code
+
+Add to `~/.claude/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "neuron": {
+      "command": "npx",
+      "args": ["-y", "neuron-mcp-server"]
+    }
+  }
+}
 ```
 
-Bots can also create their own tasks mid-conversation via the built-in `create_task` tool (enable it per bot under Built-in Tools).
+Or use the remote server:
+
+```json
+{
+  "mcpServers": {
+    "neuron": {
+      "type": "url",
+      "url": "https://mcp.neuron.ng/mcp"
+    }
+  }
+}
+```
 
-Full endpoint reference: `https://api.neuron.ng/api/docs` (see the **Tasks** tag, and **Bot API** for the API-key-scoped `/bot-api/tasks*` endpoints).
+### Cursor
 
-## Leads — lead generation
+**Settings > MCP Servers > Add Streamable HTTP**
 
-A **lead** is a potential contact captured from a source: CSV, pasted text, a document, a web page, another tool's output, Instagram/X search, or a **live scraper** piping into the ingest endpoint. Leads live in a pool (deduped), and can be **converted** to contacts once they have a phone — then Tasks nurture them.
+URL: `https://mcp.neuron.ng/mcp`
 
-| Tool | Purpose |
-| --- | --- |
-| `neuron_create_lead_source` | Configure a source (type + config, optional recurring schedule) |
-| `neuron_list_lead_sources` | List sources |
-| `neuron_run_lead_source` | Run a source now → pull leads into the pool |
-| `neuron_extract_leads` | One-off extraction (no persistent source) — e.g. paste text, scrape a page |
-| `neuron_list_leads` | List/filter the pool by status/source/search |
-| `neuron_lead_stats` | Counts by status |
-| `neuron_convert_lead` | Promote a phone-bearing lead → contact (optionally add to a list) |
+### Windsurf
 
-**Source `config` by type:** `text_paste {text}` · `web_scrape {url|urls[]|query}` · `document {mediaUrl,mimeType}` · `tool_output {toolId,args?}` · `instagram`/`x` `{channelId? OR usernames[]/handles[]/query, limit?}` · `facebook {query, country?}` (Meta Ads Library advertisers) · `csv {rows[]}` · `stream {triggerTaskId?}`. Add `enrich: true` to any source's config to auto-enrich new leads.
+**Settings > AI > MCP Servers > Add**
 
-**Scraping backbone:** web / Instagram / X / Facebook scraping is **native when DeepAPI is configured** (`DEEPAPI_API_KEY`); without a connected social account it needs DeepAPI. `web_scrape` falls back to a basic static fetch. **TikTok** has no native provider — pipe a scraper in via `tool_output` or the ingest endpoint. **Enrichment:** `POST /leads/:id/enrich` researches a lead externally (DeepAPI) and fills missing email/company/title/bio. **Webhook:** subscribe an outbound webhook to `lead.created` to get every new lead pushed to your system.
+Use either the remote URL or local npx command.
 
-**Live / external scrapers** push leads in continuously with a **bot API key** (not the session token):
+## Development
 
 ```bash
-curl -X POST https://api.neuron.ng/api/v1/bot-api/leads/ingest/bulk \
-  -H "Authorization: Bearer nrn_YOUR_KEY" -H "Content-Type: application/json" \
-  -d '{ "sourceId": "…optional stream source…", "leads": [ { "name": "Ada", "phone": "234…", "handle": "@ada", "company": "…" } ] }'
+git clone https://github.com/conquext/neuron-mcp-server.git
+cd neuron-mcp-server
+npm install
+npm run dev
 ```
 
-Dedup is automatic (by phone → email → platform:handle). If the `sourceId` is a stream source with `config.triggerTaskId`, that Task fires on new leads.
-
-### Tasks × Leads
-
-Inside a Task you can `generate_leads` (run a source), `list_leads`, and `convert_leads` — so a scheduled Task becomes **generate → convert → message/enrol**. Note: cold outreach on WhatsApp is a ban risk; lead messaging still runs behind the Do-Not-Contact list, the per-run cap, and the no-repeat window.
-
-Full endpoint reference: `https://api.neuron.ng/api/docs` — dashboard `/leads` + `/lead-sources`, and **Bot API** `/bot-api/leads/ingest`.
-
-## Personas — voice studio
-
-A **persona** is a reusable *voice* distilled from a Collection of mined content (the web agent scrolls IG/X/TikTok/LinkedIn/Facebook and captures top-engagement posts into Collections). Building a persona analyzes the highest-engagement samples and reverse-engineers a **voiceProfile** (tone, diction, cadence, emoji/formatting habits, themes, dos/donts) plus representative **exemplars**. You then **generate** content in that voice, or **apply** the voice to a bot's persona.
+## Links
 
-| Tool | Purpose |
-| --- | --- |
-| `neuron_build_persona` | Distill a voice from a Collection's top-engagement items (needs ≥3 samples) |
-| `neuron_list_personas` | List voice personas |
-| `neuron_get_persona` | Get one persona's full voiceProfile + exemplars |
-| `neuron_generate_from_persona` | Generate N content variations in the voice (topic/platform/format) |
-| `neuron_apply_persona_to_bot` | Give a bot this voice — idempotent merge into its system prompt |
-| `neuron_update_persona` | Rename or hand-tune the voiceProfile / exemplars |
-| `neuron_delete_persona` | Delete a persona |
+- **Website:** [neuron.ng](https://neuron.ng)
+- **Documentation:** [neuron.ng/docs](https://neuron.ng/docs)
+- **MCP Server Docs:** [neuron.ng/docs/mcp-server](https://neuron.ng/docs/mcp-server)
+- **npm:** [npmjs.com/package/neuron-mcp-server](https://www.npmjs.com/package/neuron-mcp-server)
 
-**The loop:** the web agent *mines* content into a Collection → `neuron_build_persona` *distills* the voice → `neuron_generate_from_persona` *writes* in it, and `neuron_apply_persona_to_bot` makes an engagement bot *speak* in it. Applying is idempotent (re-applying or swapping a persona replaces the voice block cleanly and is reversible).
+Free to start — no credit card required.
 
-**Bot API:** the same surface is on the bot API key — `GET /bot-api/personas`, `POST /bot-api/personas/build`, `GET /bot-api/personas/:id`, `POST /bot-api/personas/:id/generate`, and `POST /bot-api/personas/:id/apply` (applies the voice to the key's **own** bot).
+## License
 
-Full endpoint reference: `https://api.neuron.ng/api/docs` — dashboard `/personas`.
+[MIT](LICENSE)

package/package.json

@@ -1,22 +1,55 @@
 {
   "name": "neuron-mcp-server",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "mcpName": "io.github.conquext/neuron",
-  "description": "MCP server exposing all Neuron AI chatbot platform functionality",
+  "description": "MCP server for Neuron — the WhatsApp automation platform. 300+ tools for AI chatbots, broadcasts, campaigns, contacts, knowledge bases, newsletters, products, flows, and more.",
   "type": "module",
   "main": "dist/index.js",
   "bin": {
     "neuron-mcp-server": "dist/index.js"
   },
+  "files": [
+    "dist",
+    "README.md"
+  ],
   "scripts": {
     "start": "node dist/index.js",
     "dev": "tsx watch src/index.ts",
     "build": "tsc",
-    "clean": "rm -rf dist"
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run build"
   },
   "engines": {
     "node": ">=18"
   },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "whatsapp",
+    "whatsapp-api",
+    "whatsapp-automation",
+    "chatbot",
+    "ai",
+    "claude",
+    "cursor",
+    "neuron",
+    "messaging",
+    "broadcast",
+    "campaign",
+    "knowledge-base",
+    "newsletter",
+    "contacts"
+  ],
+  "author": "Neuron <hello@neuron.ng>",
+  "license": "MIT",
+  "homepage": "https://neuron.ng",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/conquext/neuron-mcp-server.git"
+  },
+  "bugs": {
+    "url": "https://github.com/conquext/neuron-mcp-server/issues"
+  },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.12.1",
     "axios": "^1.7.9",

package/.env

@@ -1,13 +0,0 @@
-# NEURON_API_URL="https://neuron-api.dlvh.site/api/v1"
-NEURON_EMAIL="dev@delivahere.com"
-NEURON_PASSWORD="Password123#"
-
-NEURON_API_URL="https://api.neuron.ng/api/v1"
-# NEURON_EMAIL="a.rasheedalabi@gmail.com"
-# NEURON_PASSWORD="12345678"
-# MCP_TRANSPORT="stdio"
-MCP_TRANSPORT="http"
-PORT="3456"
-
-
-# Write(~/Developer/Code/Pro-bono/neuron/.mcp.json)