@abhinavyadav/bolna-mcp 1.0.0 → 1.0.1

package/README.md

@@ -1,87 +1,104 @@
 # Bolna MCP Server
 
-A production-ready [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server that exposes the full [Bolna Voice AI](https://api.bolna.ai) platform as MCP tools. Connect any MCP-compatible AI client (Claude Desktop, Cursor, etc.) to Bolna so you can create and manage voice agents, make and monitor calls, run batch campaigns, manage knowledgebases, and handle phone numbers all through natural language.
+[![npm version](https://img.shields.io/npm/v/@abhinavyadav/bolna-mcp.svg)](https://www.npmjs.com/package/@abhinavyadav/bolna-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+Manage voice AI agents, make calls, run campaigns, and more — through natural language.
+
+## Supported Features
+
+### 🤖 Agents
+
+Build and manage AI voice agents on the Bolna platform.
+
+**Create & Configure** — Create agents with custom system prompts, voices, and task configs
+
+**Manage** — Get, list, update, patch, and delete agents
+
+**Control** — Stop all queued calls for an agent instantly
 
 ---
 
-## Prerequisites
+### 📞 Calls
+
+Make and manage outbound voice calls.
+
+**Outbound Calls** — Initiate calls with optional scheduling, retry logic, and dynamic user context
 
-- **Node.js 18+**
-- A **Bolna API key** — sign up at [bolna.ai](https://bolna.ai) and find your key in the dashboard
+**Call Control** — Stop an active call at any time
 
 ---
 
-## Installation
+### 📋 Batch Campaigns
 
-```bash
-# 1. Clone or download the repository
-git clone https://github.com/your-org/bolna-mcp.git
-cd bolna-mcp
+Run outbound call campaigns at scale.
 
-# 2. Install dependencies
-npm install
+**Create & Schedule** — Upload a list of numbers and schedule campaigns
 
-# 3. Build the TypeScript source
-npm run build
-```
+**Monitor** — Track batch status, call counts, and execution history
 
-The compiled server will be available at `dist/index.js`.
+**Control** — Stop running batches or delete them
 
 ---
 
-## MCP Client Configuration
-
-The Bolna MCP server runs as a background process. Here is how you can add it to your favorite MCP clients:
-
-> [!TIP]
-> **How to get the absolute path to `dist/index.js` on your machine:**
-> 
-> First, ensure you have navigated (using `cd`) into the root of the cloned `bolna-mcp` directory. Then run:
-> - **macOS / Linux**: Run:
->   ```bash
->   echo "$(pwd)/dist/index.js"
->   ```
-> - **Windows (PowerShell)**: Run:
->   ```powershell
->   (Get-Item .).FullName + "\dist\index.js"
->   ```
-> - **Windows (Command Prompt)**: Run:
->   ```cmd
->   echo %cd%\dist\index.js
->   ```
-> Use the resulting path (e.g., `/Users/username/Developer/bolna-mcp/dist/index.js`) as the replacement for `/path/to/bolna-mcp/dist/index.js` in the configs below.
-
-### 1. Claude Desktop App
-Add the following to your Claude Desktop configuration file:
-- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
-- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+### 📊 Call History
+
+**Executions** — Retrieve full call details including transcripts, recording URLs, and telephony data
+
+**Raw Logs** — Access low-level call logs for debugging
+
+---
+
+### 📚 Knowledgebases
+
+**Create** — Build knowledgebases from PDF files (base64) or web URLs
+
+**Manage** — List, get, and delete knowledgebases
+
+---
+
+### 📱 Phone Numbers
+
+**Search & Buy** — Find and purchase phone numbers for your account
+
+**Inbound Routing** — Link phone numbers to agents for inbound call handling
+
+---
+
+### 🎯 Dispositions
+
+**Extraction** — Define structured outputs to extract from call transcripts
+
+**Bulk & Test** — Create multiple dispositions at once and test them against sample transcripts
+
+---
+
+### 🔌 Providers & Integrations
+
+**Providers** — Add, list, and remove telephony / LLM / TTS providers
+
+**Custom LLMs** — Plug in your own LLM endpoint
+
+---
+
+### 🏢 Sub-Accounts & SIP Trunks
+
+**Sub-Accounts** — Create and manage sub-accounts with usage tracking
+
+**SIP Trunks** — Configure SIP trunks and manage their associated numbers
+
+---
+
+## Quick Start
+
 
-```json
-{
-  "mcpServers": {
-    "bolna": {
-      "command": "node",
-      "args": ["/path/to/bolna-mcp/dist/index.js"],
-      "env": {
-        "BOLNA_API_KEY": "your_api_key_here"
-      }
-    }
-  }
-}
-```
 
-### 2. Claude Code (CLI)
-You can add the Bolna MCP server to Claude Code by running:
-```bash
-claude mcp add node /path/to/bolna-mcp/dist/index.js --env BOLNA_API_KEY=your_api_key_here
-```
-Or manually configure it in your `~/.claude.json` configuration file:
 ```json
 {
   "mcpServers": {
     "bolna": {
-      "command": "node",
-      "args": ["/path/to/bolna-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@abhinavyadav/bolna-mcp"],
       "env": {
         "BOLNA_API_KEY": "your_api_key_here"
       }
@@ -90,17 +107,24 @@ Or manually configure it in your `~/.claude.json` configuration file:
 }
 ```
 
-### 3. Antigravity / Codex (Antigravity CLI / IDE)
-Antigravity (Codex) loads its configuration from:
-- **Path**: `~/.gemini/config/mcp_config.json`
+Get your API key at [bolna.ai](https://bolna.ai) → Dashboard → API Keys.
+
+---
+
+## Setup Instructions
+
+### Claude Desktop
+
+Config file:
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
 
-Add the server configuration under `mcpServers`:
 ```json
 {
   "mcpServers": {
     "bolna": {
-      "command": "node",
-      "args": ["/path/to/bolna-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@abhinavyadav/bolna-mcp"],
       "env": {
         "BOLNA_API_KEY": "your_api_key_here"
       }
@@ -109,25 +133,25 @@ Add the server configuration under `mcpServers`:
 }
 ```
 
-### 4. Cursor
-1. Open Cursor and navigate to **Settings** (Gear icon in top right) -> **Features** -> **MCP**.
-2. Click **+ Add New MCP Server**.
-3. Fill out the fields:
+### Cursor
+
+1. Open **Settings** → **Features** → **MCP**
+2. Click **+ Add New MCP Server**
+3. Set:
    - **Name**: `bolna`
    - **Type**: `command`
-   - **Command**: `env BOLNA_API_KEY=your_api_key_here node /path/to/bolna-mcp/dist/index.js`
+   - **Command**: `env BOLNA_API_KEY=your_api_key_here npx -y @abhinavyadav/bolna-mcp`
+
+### Windsurf
 
-### 5. Windsurf
-Windsurf reads its configuration from:
-- **Path**: `~/.codeium/windsurf/mcp_config.json`
+Config file: `~/.codeium/windsurf/mcp_config.json`
 
-Add the server under `mcpServers`:
 ```json
 {
   "mcpServers": {
     "bolna": {
-      "command": "node",
-      "args": ["/path/to/bolna-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@abhinavyadav/bolna-mcp"],
       "env": {
         "BOLNA_API_KEY": "your_api_key_here"
       }
@@ -136,18 +160,17 @@ Add the server under `mcpServers`:
 }
 ```
 
-### 6. VS Code (via extensions like Cline / Roo Code)
-If you use Cline or Roo Code inside VS Code, they read their MCP configurations from:
+### VS Code (Cline / Roo Code)
+
+Config file:
 - **macOS**: `~/Library/Application Support/Code/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json`
-- **Windows**: `%APPDATA%\Code\User\globalStorage\saoudrizwan.claude-dev\settings\cline_mcp_settings.json`
 
-Add the configuration block:
 ```json
 {
   "mcpServers": {
     "bolna": {
-      "command": "node",
-      "args": ["/path/to/bolna-mcp/dist/index.js"],
+      "command": "npx",
+      "args": ["-y", "@abhinavyadav/bolna-mcp"],
       "env": {
         "BOLNA_API_KEY": "your_api_key_here"
       }
@@ -156,137 +179,36 @@ Add the configuration block:
 }
 ```
 
-> [!IMPORTANT]
-> Make sure to replace `/path/to/bolna-mcp` with the absolute path where the repository is located on your local machine, and set your real Bolna API key.
-
----
-
-## Available Tools
-
-### 🤖 Agents
-| Tool | Description |
-|------|-------------|
-| `bolna_create_agent` | Create a new voice AI agent with system prompt and task config |
-| `bolna_get_agent` | Retrieve full configuration of an agent by ID |
-| `bolna_list_agents` | List all agents in your account (paginated) |
-| `bolna_update_agent` | Update an existing agent's config or system prompt |
-| `bolna_delete_agent` | Permanently delete an agent |
-
-### 📞 Calls
-| Tool | Description |
-|------|-------------|
-| `bolna_make_call` | Initiate an outbound call with optional scheduling and retry logic |
-| `bolna_stop_call` | Immediately terminate an active call |
-
-### 📋 Batch Campaigns
-| Tool | Description |
-|------|-------------|
-| `bolna_create_batch` | Upload a CSV of phone numbers to create a batch campaign |
-| `bolna_schedule_batch` | Schedule a batch to run at a specific datetime |
-| `bolna_stop_batch` | Stop a running batch and cancel pending calls |
-| `bolna_get_batch` | Get status and call counts for a batch |
-| `bolna_list_batches` | List all batches for an agent (paginated) |
-| `bolna_get_batch_executions` | List all call executions within a batch |
-
-### 📊 Call History (Executions)
-| Tool | Description |
-|------|-------------|
-| `bolna_get_execution` | Get full call details: transcript, recording URL, telephony data |
-| `bolna_list_agent_executions` | List all call executions for an agent (paginated) |
-
-### 📚 Knowledgebases
-| Tool | Description |
-|------|-------------|
-| `bolna_create_knowledgebase` | Create a knowledgebase from a PDF file (base64) or a web URL |
-| `bolna_list_knowledgebases` | List all knowledgebases with status and metadata |
-| `bolna_delete_knowledgebase` | Delete a knowledgebase |
+### Claude Code (CLI)
 
-### 📱 Phone Numbers
-| Tool | Description |
-|------|-------------|
-| `bolna_search_phone_numbers` | Search available numbers by country, area code, or pattern |
-| `bolna_buy_phone_number` | Purchase a phone number for your account |
-| `bolna_list_phone_numbers` | List all phone numbers on your account |
+```bash
+claude mcp add npx -- -y @abhinavyadav/bolna-mcp --env BOLNA_API_KEY=your_api_key_here
+```
 
 ---
 
-## Example Claude Prompts
+## Example Prompts
 
-### 1. Create an agent and make a test call
 ```
-Create a Hindi appointment booking agent for a hospital. 
-The agent should greet callers warmly, collect their name and preferred appointment time, 
-and confirm the booking. Then make a test call to +919999999999 using that agent.
+Call +919999999999 using my "Demo Agent" and pass candidate name as "Rahul Sharma", age 25.
 ```
 
-### 2. Review batch call results
 ```
-Show me all call executions for agent <agent_id> from the last batch. 
-Include the transcript and recording URL for any calls that lasted more than 2 minutes.
+Create a Hindi appointment booking agent for a hospital, then make a test call to +919999999999.
 ```
 
-### 3. Purchase an Indian phone number
 ```
-Search for available Indian phone numbers with area code 080 (Bangalore).
-Show me the top 3 options with their prices, then buy the cheapest one using Twilio as the provider.
+Show me all executions for agent <agent_id>. Include transcripts for calls longer than 2 minutes.
 ```
 
----
-
-## Environment Variables
-
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `BOLNA_API_KEY` | ✅ Yes | Your Bolna platform API key |
-
----
-
-## Development
-
-```bash
-# Run in development mode (no build step)
-BOLNA_API_KEY=your_key npm run dev
-
-# Build for production
-npm run build
-
-# Run built server
-BOLNA_API_KEY=your_key npm start
 ```
-
----
-
-## Testing
-
-The project ships with a Jest + ts-jest test suite located in `src/__tests__/`. Tests are entirely offline — no real API calls are made; the Bolna client is fully mocked.
-
-```bash
-# Run all tests
-BOLNA_API_KEY=any-value npm test
-
-# Run with coverage report
-BOLNA_API_KEY=any-value npm run test:coverage
+Create a batch campaign for agent <agent_id> and schedule it for tomorrow at 10 AM IST.
 ```
 
-### Test Coverage
-
-| File | Statements | Branches | Functions | Lines |
-|------|-----------|----------|-----------|-------|
-| `client.ts` | 95% | 78% | 100% | 95% |
-| `calls.ts` | 100% | 96% | 100% | 100% |
-| `agents.ts` | 33% | 6% | 50% | 33% |
-
-> **Note**: `agents.ts` coverage is intentionally lower — the test suite focuses on `list`, `get`, and `delete` endpoints (most commonly used). More tool coverage can be added to `src/__tests__/agents.test.ts`.
-
-### Test Files
-
-| File | What's tested |
-|------|---------------|
-| `src/__tests__/calls.test.ts` | `bolna_make_call` (6 cases) + `bolna_stop_call` (2 cases) |
-| `src/__tests__/agents.test.ts` | `bolna_list_agents`, `bolna_get_agent`, `bolna_delete_agent` |
-| `src/__tests__/client.test.ts` | `handleAxiosError` (4 cases) + `bolnaClient` factory (3 cases) |
+```
+Search for Indian phone numbers in area code 080, show the top 3 with prices, then buy the cheapest.
+```
 
----
 
 ## License
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@abhinavyadav/bolna-mcp",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "MCP server for the Bolna Voice AI platform — manage agents, calls, batches, knowledgebases, and phone numbers through natural language",
   "main": "dist/index.js",
   "bin": {