# Astra Insight MCP

A standalone MCP server + interactive CLI that provides a **self-contained agent optimization loop** — read data, update instructions, run tests, evaluate, and iterate — all through the Astra Gateway public API.

**v0.2.0** — 134 MCP tools, 140+ gateway API methods.

## Install

```bash
pip install wati-astra-cli
astra version          # verify
astra auth             # configure keys (interactive)
astra                  # start interactive REPL
astra server           # run Streamable HTTP MCP server
```

Or build from source:

```bash
go install github.com/ClareAI/astra-insight-mcp/cmd/astra@latest
```

## Architecture

```
┌──────────────────────────────────────────────────────────────────────┐
│                    astra-insight-mcp (this repo)                     │
│                                                                      │
│  Streamable HTTP MCP Server (spec 2025-03-26)                        │
│  POST /mcp  — JSON-RPC 2.0 (JSON or SSE response)                   │
│  GET  /mcp  — SSE notification stream                                │
│  DELETE /mcp — Terminate session                                     │
│  GET /healthz — Health check                                         │
│                                                                      │
│  134 tools across 15 categories                                      │
│  Agent / Chat / KB / Testing / Voice / Integrations / Analytics      │
└───────────────────────────┬──────────────────────────────────────────┘
                            │  HTTP (Bearer token)
                            ▼
                 Astra Gateway API
              astra-gateway.wati.io/v1
```

## CLI Commands

```
astra                      Interactive REPL (default)
astra chat                 Same as above
astra server               Run Streamable HTTP MCP server
astra auth                 Configure LLM + Astra platform keys
astra auth clear           Remove all saved credentials
astra auth status          Show current auth configuration
astra auth --oauth         Browser OAuth PKCE login
astra version              Print version
astra help                 Show help
```

## Supported API Endpoints (v0.2.0)

### Agents (12 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `list_agents` | GET | `/v1/agents` | List all agents with summaries |
| `get_agent` | GET | `/v1/agents/{id}` | Get agent details |
| `create_agent` | POST | `/v1/agents` | Create a new agent |
| `update_agent` | PUT | `/v1/agents/{id}` | Update agent fields |
| `delete_agent` | DELETE | `/v1/agents/{id}` | Delete an agent |
| `publish_agent` | POST | `/v1/agents/{id}/publish` | Publish draft to live |
| `clone_agent` | POST | `/v1/agents/{id}/clone` | Clone agent for experiments |
| `update_agent_instruction` | PUT | `/v1/agents/{id}/instruction` | Update draft instructions |
| `get_runtime_config` | GET | `/v1/agents/{id}/runtime-config` | Get live/draft runtime config |
| `update_agent_attributes` | PUT | `/v1/agents/{id}/attributes` | Update agent attributes |
| `set_agent_enabled` | PUT | `/v1/agents/{id}/enabled` | Enable/disable agent |
| `export_contacts` | GET | `/v1/agents/{id}/contacts/export` | Export agent contacts as CSV |

### Brandkit (6 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `get_brandkit` | GET | `/v1/agents/{id}/brandkit` | Get brand kit |
| `fetch_brandkit` | POST | `/v1/brandkit` | Fetch brand from domain |
| `create_brandkit` | POST | `/v1/agents/{id}/brandkit` | Create brand kit |
| `update_brandkit` | PUT | `/v1/agents/{id}/brandkit` | Update brand kit |
| `delete_brandkit` | DELETE | `/v1/agents/{id}/brandkit` | Delete brand kit |

### Chat (4 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `send_test_message` | POST | `/v1/chat` | Send message (supports streaming & multi-turn) |
| `send_test_message` (preview) | POST | `/v1/chat-preview` | Preview chat (no conversation saved) |
| `send_test_message` (test) | POST | `/v1/chat-test` | Test chat with evaluation |
| `retrieve_knowledge` | POST | `/v1/knowledge/retrieve` | Retrieve from knowledge base |

### Conversations (9 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `list_conversations` | GET | `/v1/conversations` | List conversations with filters |
| `get_conversation` | GET | `/v1/conversations/{id}` | Get conversation details |
| `get_conversation_messages` | GET | `/v1/conversations/{id}/messages` | Get message history |
| `get_conversation_contact` | GET | `/v1/conversations/{id}/contact` | Get conversation contact |
| `get_conversations_batch` | GET | `/v1/conversations/{id}` x N | Batch fetch conversations |
| `get_conversation_params` | GET | `/v1/conversations/{id}/params` | Get conversation parameters |
| `upsert_conversation_params` | PUT | `/v1/conversations/{id}/params` | Upsert conversation parameters |
| `delete_conversation_params` | DELETE | `/v1/conversations/{id}/params` | Delete conversation parameters |

### Contacts (5 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `get_contacts_and_leads` | GET | `/v1/contacts` | List contacts with filters |
| `get_contact` | GET | `/v1/contacts/{id}` | Get contact details |
| `get_contact_conversations` | GET | `/v1/contacts/{id}/conversations` | Contact's conversations |
| `create_contact` | POST | `/v1/contacts` | Create a contact |
| `delete_contact` | DELETE | `/v1/contacts/{id}` | Delete a contact |

### Knowledge Base (8 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `create_knowledge_base` | POST | `/v1/knowledge-bases` | Create empty KB |
| `list_knowledge_documents` | GET | `/v1/knowledge-bases/{id}/documents` | List KB documents |
| `create_knowledge_document` | POST | `/v1/knowledge-bases/{id}/documents` | Create text document |
| `delete_knowledge_document` | DELETE | `/v1/knowledge-bases/{id}/documents/{did}` | Delete document |
| `import_knowledge_from_url` | POST | `/v1/knowledge-bases/{id}/import/url` | Import from URL |
| `import_knowledge_from_website` | POST | `/v1/knowledge-bases/{id}/import/website` | Crawl & import website |
| `import_knowledge_from_file` | POST | `/v1/knowledge-bases/{id}/import/file` | Upload file (PDF, etc.) |
| `get_import_status` | GET | `/v1/knowledge-bases/{id}/import/status` | Check import job status |

### Annotations (6 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `list_annotations` | GET | `/v1/agents/{id}/annotations` | List FAQ annotations |
| `create_annotation` | POST | `/v1/agents/{id}/annotations` | Create FAQ annotation |
| `get_annotation` | GET | `/v1/agents/{id}/annotations/{aid}` | Get annotation details |
| `update_annotation` | PUT | `/v1/agents/{id}/annotations/{aid}` | Update annotation |
| `delete_annotation` | DELETE | `/v1/agents/{id}/annotations/{aid}` | Delete annotation |
| `batch_delete_annotations` | DELETE | `/v1/agents/{id}/annotations/batch` | Batch delete annotations |

### Integrations & MCP Actions (22 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `list_integration_templates` | GET | `/v1/mcp/action_templates` | Available action templates |
| `list_configured_integrations` | GET | `/v1/mcp/actions` | All configured actions |
| `get_configured_integration` | GET | `/v1/mcp/actions/{id}` | Get action details |
| `create_integration` | POST | `/v1/mcp/actions` | Create an action |
| `delete_integration` | DELETE | `/v1/mcp/actions/{id}` | Delete an action |
| `execute_integration_action` | POST | `/v1/mcp/actions/{id}/execute` | Execute action |
| `create_integration_auth` | POST | `/v1/mcp/auth` | Initiate OAuth flow |
| `get_integration_auth` | GET | `/v1/mcp/auth/{id}` | Get auth connection |
| `delete_integration_auth` | DELETE | `/v1/mcp/auth/{id}` | Delete auth connection |
| `wait_integration_auth` | POST | `/v1/mcp/auth/{id}/wait` | Wait for OAuth callback |
| `refresh_integration_auth` | POST | `/v1/mcp/auth/{id}/refresh` | Refresh connection token |
| `register_agent_integrations` | POST | `/v1/mcp/register` | Register tools to agent |
| `deregister_agent_integrations` | POST | `/v1/mcp/deregister` | Remove tools from agent |
| `list_agent_integrations` | GET | `/v1/mcp/agents/{id}/tools` | List agent's registered tools |
| `get_integration_platforms` | GET | `/v1/mcp/info` | Available platforms |
| `get_slack_channels` | GET | `/v1/mcp/platforms/slack/channels` | Slack channels |
| `get_wati_attributes` | GET | `/v1/mcp/platforms/wati/attributes` | WATI attributes |
| `get_wati_channels` | GET | `/v1/mcp/platforms/wati/channels` | WATI channels |
| `get_wati_templates` | GET | `/v1/mcp/platforms/wati/templates` | WATI templates |
| `get_hubspot_properties` | GET | `/v1/mcp/platforms/hubspot/properties` | HubSpot properties |
| `get_salesforce_fields` | GET | `/v1/mcp/platforms/salesforce/fields` | Salesforce fields |
| `get_google_sheets_spreadsheets` | GET | `/v1/mcp/platforms/google-sheets/spreadsheets` | Google Sheets |

### Connections (4 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `list_connections` | GET | `/v1/connections` | List platform connections |
| `create_connection` | POST | `/v1/connections` | Create connection mapping |
| `get_connection` | GET | `/v1/connections/{id}` | Get connection details |
| `delete_connection` | DELETE | `/v1/connections/{id}` | Delete connection |

### Analytics (2 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `get_analytics` | GET | `/v1/analytics` | Conversation & lead analytics |
| `get_lead_distribution` | GET | `/v1/distribution` | Lead score distribution |

### Templates (3 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `list_templates` | GET | `/v1/templates` | List agent templates |
| `list_template_categories` | GET | `/v1/templates/categories` | Template categories |
| `get_template` | GET | `/v1/templates/{id}` | Template details |

### Webhooks (4 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `list_webhooks` | GET | `/v1/webhooks` | List webhooks |
| `create_webhook` | POST | `/v1/webhooks` | Create webhook |
| `update_webhook` | PUT | `/v1/webhooks/{id}` | Update webhook |
| `delete_webhook` | DELETE | `/v1/webhooks/{id}` | Delete webhook |

### Testing (24 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `start_test_pipeline` | POST | `/v1/testing/pipeline` | Full pipeline: generate → execute → analyze |
| `list_pipeline_jobs` | GET | `/v1/testing/pipeline/jobs` | List pipeline jobs |
| `get_pipeline_job` | GET | `/v1/testing/pipeline/jobs/{id}` | Get pipeline status |
| `create_test_suite` | POST | `/v1/testing/test-suites` | Create/generate test suite |
| `list_test_suites` | GET | `/v1/testing/test-suites` | List test suites |
| `get_test_suite` | GET | `/v1/testing/test-suites/{id}` | Get suite with cases |
| `get_test_suite_progress` | GET | `/v1/testing/test-suites/{id}/progress` | Generation progress |
| `add_test_case` | POST | `/v1/testing/test-suites/{id}/test-cases` | Add test case |
| `delete_test_case` | DELETE | `/v1/testing/test-cases/{id}` | Delete test case |
| `batch_delete_test_cases` | DELETE | `/v1/testing/test-cases/batch` | Batch delete cases |
| `create_test_run` | POST | `/v1/testing/test-suites/{id}/runs` | Execute test suite |
| `list_test_runs` | GET | `/v1/testing/runs` | List runs |
| `get_test_run` | GET | `/v1/testing/runs/{id}` | Get run results |
| `delete_test_run` | DELETE | `/v1/testing/runs/{id}` | Delete run |
| `list_runs_for_suite` | GET | `/v1/testing/test-suites/{id}/runs` | Runs for a suite |
| `create_run_analysis` | POST | `/v1/testing/runs/{id}/analyses` | AI-powered analysis |
| `get_run_analysis` | GET | `/v1/testing/runs/{id}/analyses` | Get analysis |
| `get_analysis` | GET | `/v1/testing/analyses/{id}` | Get analysis by ID |
| `analyze_failures` | POST | `/v1/testing/runs/{id}/analyze-failures` | Diagnose failures |
| `generate_instruction` | POST | `/v1/testing/generate-instruction` | AI-generate improved instruction |
| `get_agent_test_overview` | GET | `/v1/testing/agents/{id}/overview` | Agent test summary |
| `get_agent_latest_test_suite` | GET | `/v1/testing/agents/{id}/latest-suite` | Latest suite |
| `import_test_csv` | POST | `/v1/testing/agents/{id}/import-csv` | Import test cases from CSV |

### Voice (25 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `list_voice_agents` | GET | `/v1/voice/agents` | List voice agents |
| `get_voice_agent` | GET | `/v1/voice/agents/{id}` | Get voice agent |
| `get_voice_agent_by_text_agent` | GET | `/v1/voice/agents/by-text-agent` | Find by text agent |
| `get_default_tenant_voice_agents` | GET | `/v1/voice/agents/default` | Default tenant agents |
| `create_voice_agent` | POST | `/v1/voice/agents` | Create voice agent |
| `quick_create_voice_agent` | POST | `/v1/voice/agents/quick-create` | Quick create from template |
| `update_voice_agent` | PUT | `/v1/voice/agents/{id}` | Update voice agent config |
| `delete_voice_agent` | DELETE | `/v1/voice/agents/{id}` | Delete voice agent |
| `publish_voice_agent` | POST | `/v1/voice/agents/publish` | Publish voice agent |
| `get_voice_agent_count` | GET | `/v1/voice/agents/count` | Count voice agents |
| `check_voice_agent_exists` | HEAD | `/v1/voice/agents/{id}` | Check existence |
| `new_voice_call` | POST | `/v1/voice/calls/new` | Start voice call |
| `web_new_voice_call` | POST | `/v1/voice/calls/web-new` | WebRTC voice call |
| `test_new_voice_call` | POST | `/v1/voice/calls/test-new` | Test voice call |
| `terminate_voice_call` | POST | `/v1/voice/calls/terminate` | Terminate call |
| `test_terminate_voice_call` | POST | `/v1/voice/calls/test-terminate` | Terminate test call |
| `initiate_outbound_call` | POST | `/v1/voice/calls/outbound/initiate` | Initiate outbound call |
| `get_webrtc_config` | GET | `/v1/voice/webrtc/config` | WebRTC configuration |
| `list_minimax_voices` | GET | `/v1/voice/minimax-voices` | List Minimax voices |
| `get_minimax_voice` | GET | `/v1/voice/minimax-voices/{id}` | Get voice details |
| `submit_voice_clone` | POST | `/v1/voice/minimax-voices/submit-clone` | Start voice cloning |
| `search_voice_library` | GET | `/v1/voice/minimax-voices/voice-library/search` | Search voice library |
| `update_minimax_voice` | PUT | `/v1/voice/minimax-voices/{id}` | Update voice |
| `search_collected_voices` | GET | `/v1/voice/minimax-voices/collected` | Tenant's collected voices |
| `upload_user_voice` | POST | `/v1/voice/minimax-voices/upload-user-voice` | Upload audio for cloning |

### Utility (4 tools)

| Tool | Method | Endpoint | Description |
|------|--------|----------|-------------|
| `perplexity_search` | POST | `/v1/search` | Web search via Perplexity |
| `get_wati_settings` | GET | `/v1/settings/wati` | WATI platform settings |
| `list_skills` | — | — | List available agent skills |
| `activate_skill` / `deactivate_skill` | — | — | Toggle skill context |

## Running Modes

### 1. PyPI Package (recommended)

```bash
pip install wati-astra-cli
astra                      # interactive REPL
astra server               # MCP server on :8080
```

### 2. Go Binary

```bash
go run ./cmd/astra         # interactive REPL
go run ./cmd/astra server  # MCP server
go run ./cmd/main.go       # legacy MCP server entry point
```

### 3. Docker

```bash
docker build -t astra-insight-mcp .
docker run -p 8080:8080 \
  -e ASTRA_GATEWAY_BASE_URL=https://astra-gateway.wati.io \
  -e ASTRA_API_KEY=sk_live_... \
  astra-insight-mcp
```

## Authentication

Every tool call requires an auth token, resolved in this order:

| Priority | Source | Example |
|----------|--------|---------|
| 1 | `api_key` argument in tool call | `"api_key": "sk_live_xxx"` |
| 2 | `ASTRA_API_KEY` env var | `export ASTRA_API_KEY=sk_live_xxx` |
| 3 | `ASTRA_ACCESS_TOKEN` env var | `export ASTRA_ACCESS_TOKEN=astra_at_xxx` |
| 4 | `ASTRA_OAUTH_ACCESS_TOKEN` env var | `export ASTRA_OAUTH_ACCESS_TOKEN=astra_at_xxx` |
| 5 | `~/.astra/oauth_token.json` file | Written by `astra auth --oauth` |

### OAuth Login

```bash
astra auth --oauth --env dev     # browser OAuth (dev)
astra auth --oauth --env prod    # browser OAuth (prod)
```

## Environment Variables

### MCP Server

| Variable | Default | Description |
|----------|---------|-------------|
| `PORT` | `8080` | Server port |
| `ASTRA_GATEWAY_BASE_URL` | `https://astra-gateway.wati.io` | Gateway API URL |
| `ASTRA_API_KEY` | — | API key (`sk_live_*`) |
| `ASTRA_ACCESS_TOKEN` | — | OAuth token |
| `RATE_LIMIT_PER_MIN` | `60` | Rate limit per IP |

### CLI Agent

| Variable | Default | Description |
|----------|---------|-------------|
| `LLM_API_KEY` / `OPENAI_API_KEY` | — | LLM API key |
| `LLM_BASE_URL` | `https://api.openai.com/v1` | LLM endpoint |
| `LLM_MODEL` | `anthropic/claude-sonnet-4` | Model name |

## Quick Start

```bash
# Start MCP server
astra server

# List all tools
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

# List agents
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":2,"method":"tools/call",
    "params":{"name":"list_agents","arguments":{"api_key":"sk_live_xxx"}}
  }'

# Create an agent
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":3,"method":"tools/call",
    "params":{"name":"create_agent","arguments":{
      "api_key":"sk_live_xxx",
      "name":"My Agent",
      "knowledge_base_id":"kb-uuid"
    }}
  }'

# Run full test pipeline
curl -X POST http://localhost:8080/mcp \
  -H "Content-Type: application/json" \
  -d '{
    "jsonrpc":"2.0","id":4,"method":"tools/call",
    "params":{"name":"start_test_pipeline","arguments":{
      "api_key":"sk_live_xxx","agent_id":"uuid","user_id":"tester"
    }}
  }'
```

## Recipes

Pre-built optimization recipes are available at [astra-docs.wati.io/recipes](https://astra-docs.wati.io/recipes):

- **Create Agent End-to-End** — 5-step agent creation with brand kit, KB, annotations
- **Setup Knowledge Base** — KB creation with import strategies
- **Optimize Agent Instructions** — Analyze performance and improve instructions
- **Setup Voice Agent** — Voice agent creation and configuration
- **Clone Voice** — Voice cloning via Minimax TTS
- **Connect Integration (OAuth)** — OAuth flow for HubSpot, Slack, Salesforce, etc.
- **Run Test Pipeline** — Systematic testing with analysis
- **Analyze Conversations** — Conversation analysis and annotation
- **Check Agent Performance** — Performance metrics dashboard
- **Debug API Errors** — Common error diagnosis and fixes
- **WATI MCP Auth** — WATI platform auth troubleshooting
- **Voice Operations** — Voice agent operations quick reference

## License

Proprietary — WATI / Clare.AI
