@iriseller/mcp-server/README.md

Model Context Protocol (MCP) server providing access to IRISeller's AI sales intelligence platform with 7 AI agents, multi-CRM integration, advanced sales workflows, email automation (detection/sending/campaigns), and robust asynchronous agent execution h

# IRISeller MCP Server

A Model Context Protocol (MCP) server that provides access to the IRISeller AI Agent Ecosystem, enabling external systems to leverage advanced sales AI capabilities.

## Overview

The IRISeller MCP Server exposes 26 powerful tools that give external systems access to:

- **7 AI Agents**: Lead qualification, prospecting, personalization, sequencing, social selling, nurturing, and objection handling
- **Multi-CRM Data**: Real-time access to Salesforce, Dynamics, and Oracle CRM data
- **6 Workflows**: Complete multi-agent sales processes
- **Sales Intelligence**: Company research, forecasting, and analytics
- **Email Automation**: Email detection, sending, campaigns, templates, and status monitoring
- **Web Search**: Real-time web search capabilities using Claude's native web search tool

## Features

### 🤖 **AI Agent Tools**
- **Lead Qualification**: BANT analysis with AI-powered insights
- **Company Research**: Multi-source intelligence gathering
- **Personalization**: AI-generated personalized outreach
- **Workflow Execution**: Complete multi-agent sales processes
- **Asynchronous Execution**: Robust handling of long-running agent tasks with completion polling and result retrieval

### 📊 **CRM Integration**
- **Multi-CRM Support**: Salesforce, Microsoft Dynamics, Oracle CX
- **Real-time Data**: Live lead, opportunity, contact, and account data
- **Advanced Querying**: Filtering, sorting, and pagination

### 📈 **Sales Intelligence**
- **Forecasting**: AI-powered sales predictions
- **Analytics**: Performance metrics and insights
- **Health Monitoring**: Service status and agent availability

### 📧 **Email Automation**
- **Email Detection**: Monitor incoming emails with advanced filtering
- **Email Sending**: Send personalized emails with template support
- **Campaign Management**: Automated email sequences and tracking
- **Template Management**: Create and manage email templates
- **Status Monitoring**: Real-time email system health and statistics

## Quick Start

### Option 1: NPX (Recommended)

Run directly with npx - no installation required:

```bash
npx @iriseller/mcp-server@latest --email your-email@example.com --password your-password --api-url https://beta.iriseller.com
```

### Option 2: Global Installation

```bash
# Install globally
npm install -g @iriseller/mcp-server

# Run with credentials
iriseller-mcp-server --email your-email@example.com --password your-password
```

### Option 3: Local Development

```bash
cd packages/mcp-server
npm install
npm run build
npm start
```

### CLI Options

```bash
iriseller-mcp-server --help

Options:
  --email <email>           IRISeller account email
  --password <password>     IRISeller account password  
  --api-url <url>          IRISeller API URL (default: "https://beta.iriseller.com")
  --crewai-url <url>       CrewAI API URL
  --debug                  Enable debug mode
  --jwt-secret <secret>    JWT secret for token generation
  -h, --help               display help for command
```

### Environment Variables

You can also use environment variables instead of CLI options:

```env
# IRISeller Backend API Configuration
IRISELLER_API_URL=https://beta.iriseller.com
CREWAI_API_URL=http://localhost:8001
CRM_CONNECT_API_URL=https://beta.iriseller.com/api/crm-connect

# Authentication
IRISELLER_EMAIL=your-email@example.com
IRISELLER_PASSWORD=your-password
JWT_SECRET=your_jwt_secret_here

# Optional: Debug mode
DEBUG=true
```

## Available Tools

### Core CRM Tools

#### `qualify_lead`
Analyze and qualify leads using IRISeller's BANT framework with AI-powered insights.

```json
{
  "name": "qualify_lead",
  "arguments": {
    "contact_name": "John Smith",
    "company_name": "TechCorp Inc",
    "title": "VP of Sales",
    "industry": "Technology",
    "email": "john@techcorp.com"
  }
}
```

#### `query_crm`
Search and retrieve data from multiple CRM systems.

```json
{
  "name": "query_crm",
  "arguments": {
    "entity_type": "leads",
    "filters": {
      "status": "Open",
      "industry": "Technology"
    },
    "limit": 10
  }
}
```

#### `research_company`
Perform comprehensive company research using AI agents.

```json
{
  "name": "research_company",
  "arguments": {
    "company_name": "TechCorp Inc",
    "research_depth": "comprehensive",
    "include_competitors": true
  }
}
```

### AI Agent Tools

#### `execute_agent`
Execute individual AI agents for specific sales tasks.

```json
{
  "name": "execute_agent",
  "arguments": {
    "agent_name": "personalization",
    "input_data": {
      "prospect_data": {
        "name": "John Smith",
        "company": "TechCorp Inc"
      },
      "message_type": "email"
    }
  }
}
```

#### `get_agent_results`
Retrieve results from a completed or running agent execution.

```json
{
  "name": "get_agent_results",
  "arguments": {
    "execution_id": "abc123-def456-ghi789",
    "wait_for_completion": true,
    "timeout_seconds": 30
  }
}
```

#### `wait_for_agent_completion`
Wait for an agent execution to complete and return final results.

```json
{
  "name": "wait_for_agent_completion",
  "arguments": {
    "execution_id": "abc123-def456-ghi789",
    "timeout_seconds": 120,
    "check_interval_seconds": 5
  }
}
```

#### `execute_workflow`
Execute multi-agent workflows for complete sales processes.

```json
{
  "name": "execute_workflow",
  "arguments": {
    "workflow_type": "full_sdr_workflow",
    "input_data": {
      "company_name": "TechCorp Inc",
      "contact_name": "John Smith"
    }
  }
}
```

#### `personalize_outreach`
Generate personalized outreach messages using AI.

```json
{
  "name": "personalize_outreach",
  "arguments": {
    "prospect_data": {
      "name": "John Smith",
      "company": "TechCorp Inc",
      "title": "VP of Sales"
    },
    "message_type": "email",
    "tone": "professional"
  }
}
```

### Analytics Tools

#### `forecast_sales`
Generate sales forecasts and pipeline analysis.

```json
{
  "name": "forecast_sales",
  "arguments": {
    "time_period": "90d",
    "include_scenarios": true
  }
}
```

### Web Search Tools

#### `web_search`
Search the web for real-time information using Claude's native web search capability.

```json
{
  "name": "web_search",
  "arguments": {
    "query": "latest AI trends 2024",
    "max_uses": 3,
    "allowed_domains": ["nature.com", "arxiv.org", "techcrunch.com"],
    "user_location": {
      "type": "approximate",
      "city": "San Francisco",
      "region": "California", 
      "country": "US",
      "timezone": "America/Los_Angeles"
    }
  }
}
```

**Parameters:**
- `query` (required): The search query to execute
- `max_uses` (optional): Maximum number of search operations (1-5, default: 3)
- `allowed_domains` (optional): Array of domains to restrict search to
- `blocked_domains` (optional): Array of domains to exclude from search
- `user_location` (optional): Location context for localized results
  - `type`: Must be "approximate"
  - `city`: City name
  - `region`: State or region name
  - `country`: Country code (e.g., "US", "CA")
  - `timezone`: IANA timezone (e.g., "America/New_York")

**Features:**
- **Native Integration**: Uses Claude's built-in web search capability
- **AI Summaries**: Provides comprehensive summaries with citations
- **Domain Filtering**: Control which sites to include or exclude
- **Localization**: Get location-specific search results
- **No External APIs**: Requires only your Anthropic API key

### Utility Tools

#### `list_agents`
Get list of available AI agents and their capabilities.

```json
{
  "name": "list_agents",
  "arguments": {
    "include_status": true
  }
}
```

#### `list_workflows`
Get list of available workflows and their descriptions.

```json
{
  "name": "list_workflows",
  "arguments": {
    "include_details": true
  }
}
```

#### `health_check`
Check the health status of IRISeller services and agents.

```json
{
  "name": "health_check",
  "arguments": {
    "detailed": true
  }
}
```

## Integration Examples

### Claude Desktop Integration

#### Option 1: NPX (Recommended)
Add to your Claude Desktop configuration (`~/Library/Application Support/Claude/claude_desktop_config.json` on macOS):

```json
{
  "mcpServers": {
    "iriseller": {
      "command": "npx",
      "args": ["@iriseller/mcp-server@latest", "--email", "your-email@company.com", "--password", "your-password", "--api-url", "https://beta.iriseller.com"],
      "env": {
        "JWT_SECRET": "your-jwt-secret-here"
      },
      "disabled": false,
      "autoApprove": ["qualify_lead", "query_crm", "research_company"]
    }
  }
}
```

#### Option 2: Global Installation
```json
{
  "mcpServers": {
    "iriseller": {
      "command": "iriseller-mcp-server",
      "args": ["--email", "your-email@company.com", "--password", "your-password"],
      "env": {
        "IRISELLER_API_URL": "https://beta.iriseller.com",
        "JWT_SECRET": "your-jwt-secret-here"
      }
    }
  }
}
```

#### Option 3: Local Development
```json
{
  "mcpServers": {
    "iriseller": {
      "command": "node",
      "args": ["/path/to/IRISeller/packages/mcp-server/dist/index.js"],
      "env": {
        "IRISELLER_API_URL": "http://localhost:3001",
        "CREWAI_API_URL": "http://localhost:8001",
        "DEBUG": "false"
      }
    }
  }
}
```

### Custom Application Integration

```typescript
import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';

const transport = new StdioClientTransport({
  command: 'node',
  args: ['path/to/mcp-server/dist/index.js']
});

const client = new Client({
  name: 'my-app',
  version: '1.0.0'
}, {
  capabilities: {}
});

await client.connect(transport);

// Qualify a lead
const result = await client.request({
  method: 'tools/call',
  params: {
    name: 'qualify_lead',
    arguments: {
      contact_name: 'John Smith',
      company_name: 'TechCorp Inc'
    }
  }
});
```

## Error Handling

The MCP server provides detailed error information:

```json
{
  "error": {
    "code": -32602,
    "message": "Invalid params: contact_name and company_name are required"
  }
}
```

Common error codes:
- `-32601`: Method not found (unknown tool)
- `-32602`: Invalid params (validation failed)
- `-32603`: Internal error (service unavailable)

## Development

### Project Structure

```
src/
├── types/           # TypeScript type definitions
├── services/        # API service integrations
├── handlers/        # Tool request handlers
├── tools/           # MCP tool definitions
└── index.ts         # Main server implementation
```

### Building

```bash
npm run build
```

### Testing

```bash
# Run the server in debug mode
DEBUG=true npm run dev

# Test with a simple tool call
echo '{"jsonrpc": "2.0", "id": 1, "method": "tools/list", "params": {}}' | npm run dev
```

### Adding New Tools

1. Define the tool in `src/tools/index.ts`
2. Add the handler in `src/handlers/tool-handlers.ts`
3. Update types if needed in `src/types/index.ts`
4. Test the new tool

## Troubleshooting

### Common Issues

1. **Service Connection Errors**
   - Ensure IRISeller backend is running on port 3001
   - Ensure CrewAI service is running on port 8001
   - Check network connectivity

2. **Authentication Errors**
   - Verify API keys in environment variables
   - Check JWT token configuration

3. **Tool Execution Timeouts**
   - AI agents may take 30-60 seconds for complex operations
   - Increase timeout settings if needed

### Debug Mode

Enable debug logging:

```bash
DEBUG=true npm run dev
```

This will show:
- API requests and responses
- Tool execution details
- Service health checks

## License

MIT License - see LICENSE file for details.

## Support

For support and questions:
- Check the IRISeller documentation
- Review the MCP protocol specification
- Open an issue in the repository