# WorkForceAI MCP Server

This is the "internal bot's toolbox" — a small standalone server that lets a chat/voice
bot look up and update things on the WorkForceAI platform (agents, campaigns, phone
numbers, call logs, stats) by calling the same backend the main app uses.

It is **completely separate from the `healthai-frontend` repo** — nothing here gets
pushed there. It speaks a standard protocol called **MCP** (Model Context Protocol),
which is what lets an AI (Claude, ElevenLabs' agent, etc.) discover "here are the
things I'm allowed to do" and call them during a conversation.

You do not need to understand MCP internals to run this — just follow the steps below.

---

## What it can do right now

Read-only (safe, look-things-up tools):
- `list_voice_agents` — list your CallFlow voice agents
- `list_campaigns` — list campaigns, or get one campaign's full details
- `list_phone_numbers` — list provisioned Twilio numbers
- `get_call_logs` — recent call records/transcripts
- `get_dashboard_stats` — call volume/usage stats
- `get_current_account` — which account the bot is logged in as

One action tool (changes real data):
- `update_campaign` — update a campaign's system prompt, greeting, name, objective,
  etc. Requires a `campaignId`; only the fields you pass get changed.

All of this is scoped to **whichever account's login you put in `.env`** — the bot
sees exactly what that account can see in the platform, nothing more.

---

## One-time setup

### 1. Install dependencies

Open a terminal in this folder (`E:\aiconnecthub\workforceai-mcp`) and run:

```
npm install
```

(Node.js is already installed on this machine — nothing else to install there.)

### 2. Set up your `.env` file

A `.env` file already exists here with your login filled in, pointing at the real
WorkForceAI backend (`https://workforceai.zapto.org`). If you ever need to change
which account the bot logs in as, edit `.env` directly:

```
BACKEND_BASE_URL=https://workforceai.zapto.org
BOT_ACCOUNT_EMAIL=your-login-email
BOT_ACCOUNT_PASSWORD=your-login-password
MCP_PORT=8787
```

**Never share this file or commit it anywhere** — it has a real password in it.
`.gitignore` already excludes it, so even if you turn this folder into a git repo
later, `.env` won't get committed by accident.

### 3. Start the server

```
npm start
```

You should see:

```
workforceai-mcp listening on http://localhost:8787
  MCP endpoint: http://localhost:8787/mcp
  Health check: http://localhost:8787/health
```

Leave this running in its own terminal window while you're testing or using the bot.
Press `Ctrl+C` to stop it.

### 4. Verify it's working

**Quick check (no extra tools needed):** open `http://localhost:8787/health` in a
browser — it should show `{"ok":true}`.

**Full check (see the actual tools and try one):** use the official MCP Inspector —
a browser-based tool for poking at an MCP server by hand. In a *second* terminal
(leave the server running in the first one):

```
npx @modelcontextprotocol/inspector
```

This opens a browser tab. In it:
1. Set **Transport Type** to `Streamable HTTP`
2. Set **URL** to `http://localhost:8787/mcp`
3. Click **Connect**
4. Go to the **Tools** tab, click a tool like `list_voice_agents`, click **Run** —
   you should see your real agents come back as JSON.

If that works, the server is fully verified and ready to be connected to a bot.

---

## How authentication works (so you're not surprised)

There's no separate "bot API key" system on the backend today — the bot logs in
with a normal email/password, exactly like the website's login form does, and gets
back a JWT token it attaches to every request. It keeps that token in memory (not
on disk) and automatically logs in again if the token expires or a request comes
back unauthorized. This mirrors what `utils/apiClient.js` does in the frontend app,
just without a browser.

Because of this, **the bot only ever sees/changes what that one login can see** —
its own agents, campaigns, numbers, and call logs. It cannot see or touch other
users' accounts.

---

## Project layout

```
workforceai-mcp/
├── .env              ← your real credentials (gitignored, never share)
├── .env.example       ← template, safe to share
├── src/
│   ├── config.js      ← reads .env
│   ├── backendClient.js ← logs in, attaches auth token, retries on expiry
│   ├── tools.js        ← the actual tool definitions (add new ones here)
│   └── server.js       ← the MCP server itself (Express + Streamable HTTP)
└── README.md          ← this file
```

To add a new tool later: add an entry to the `tools` array in `src/tools.js`
following the existing pattern (name, description, input fields, handler that
calls `http.get/post/put` against the backend), restart the server, done.

---

## What's NOT done yet (next phase)

This server currently only runs on your own machine (`localhost`) — it isn't
reachable from the internet. To wire it up to an ElevenLabs voice agent, ElevenLabs'
servers need to be able to reach this MCP endpoint over the internet, which means
either:
- exposing it temporarily via a tunnel (e.g. `ngrok`), or
- deploying it somewhere it stays running (a small always-on server/VPS/hosting
  service)

That, plus the actual ElevenLabs agent configuration, is intentionally a separate
next step — not part of this build.