espocrm-mcp-server-extended/README.md

Full-featured EspoCRM MCP server with 47 tools for comprehensive CRM operations - based on zaphod-black/EspoMCP

# EspoCRM MCP Server

A comprehensive Model Context Protocol (MCP) server for seamless integration with EspoCRM. This server enables AI assistants to interact with your EspoCRM instance through a standardized interface, providing complete CRUD operations for Contacts, Accounts, Opportunities, Meetings, Users, Tasks, Leads, and advanced system management capabilities.

**🤖 NEW: AI Chatbot Integration** - Now includes a complete chatbot interface that embeds directly into your EspoCRM, providing natural language access to all 47 MCP tools!

## Features

### Core Capabilities
- **Complete CRUD Operations** - Create, read, update, and delete entities
- **Multi-Entity Support** - Contacts, Accounts, Opportunities, Meetings, Users, Tasks, and Leads
- **Advanced Search & Filtering** - Flexible search with date ranges, pagination, and complex filters
- **Task Management** - Complete task lifecycle with parent relationships and user assignment
- **Lead Management** - Full lead pipeline from creation to conversion
- **Meeting Management** - Full calendar integration with attendee management
- **User Management** - Comprehensive user search and lookup capabilities
- **Real-time Validation** - Zod-based schema validation for all operations
- **Comprehensive Logging** - Winston-powered logging with multiple levels

### Authentication & Security
- **Multiple Auth Methods** - API Key and HMAC authentication support
- **Secure Configuration** - Environment-based configuration management
- **Rate Limiting** - Built-in rate limiting for API protection
- **Error Handling** - Robust error handling with detailed logging

### Calendar Integration
- **Meeting Operations** - Create, search, update, and manage meetings
- **Attendee Management** - Link contacts and users to meetings
- **Date/Time Filtering** - Advanced date range search capabilities
- **Google Calendar Sync Compatibility** - Designed for calendar synchronization workflows

### AI Chatbot Integration 🤖
- **Floating Chat Widget** - Beautiful, non-intrusive chat bubble interface
- **Natural Language Processing** - Chat in plain English to perform CRM operations
- **Real-time Communication** - WebSocket-powered instant responses
- **47 MCP Tools Access** - Complete CRM functionality via chat
- **EspoCRM Embedding** - Integrates directly into your EspoCRM interface
- **Mobile Responsive** - Works seamlessly on all devices

### Developer Experience
- **TypeScript** - Full TypeScript support with strict typing
- **Docker Support** - Containerized deployment ready
- **Comprehensive Testing** - Multiple test scripts and validation tools
- **MCP 2024/2025 Compliant** - Latest MCP specification support

## Quick Start

### Prerequisites
- Node.js 18+ 
- npm or yarn
- EspoCRM instance with API access
- Valid API credentials

### Installation

1. **Clone the repository**
```bash
git clone https://github.com/zaphod-black/EspoMCP.git
cd EspoMCP
```

2. **Install dependencies**
```bash
npm install
```

3. **Configure environment**
```bash
cp .env.example .env
# Edit .env with your EspoCRM credentials
```

4. **Build the project**
```bash
npm run build
```

5. **Test the connection**
```bash
npm run test:config
```

## 🤖 AI Chatbot Quick Start

### Deploy Chatbot Interface

1. **Navigate to chatbot directory**
```bash
cd chatbot-bridge
```

2. **Install dependencies**
```bash
npm install
```

3. **Configure environment**
```bash
cp .env.example .env
# Edit .env with your EspoCRM settings
```

4. **Start chatbot server**
```bash
npm start
# Or with Docker: docker-compose up -d
```

5. **Integrate with EspoCRM**
Add to your EspoCRM footer template:
```html
<script>
  window.ESPOCRM_CHAT_SERVER = 'http://your-server:3001';
</script>
<script src="http://your-server:3001/socket.io/socket.io.js"></script>
<script src="http://your-server:3001/api/widget.js"></script>
```

6. **Try the Demo**
Visit `http://localhost:3001/widget` to see the chatbot in action!

### Environment Configuration

Create a `.env` file with your EspoCRM configuration:

```env
# EspoCRM Configuration
ESPOCRM_URL=https://your-espocrm-instance.com
ESPOCRM_API_KEY=your-api-key-here
ESPOCRM_AUTH_METHOD=apikey

# Optional: HMAC Authentication
# ESPOCRM_SECRET_KEY=your-secret-key
# ESPOCRM_AUTH_METHOD=hmac

# Server Configuration (Optional)
MCP_TRANSPORT=stdio
RATE_LIMIT=100
REQUEST_TIMEOUT=30000
LOG_LEVEL=info
```

### Required Configuration

| Variable | Description | Required | Default |
|----------|-------------|----------|---------|
| `ESPOCRM_URL` | Your EspoCRM instance URL | Yes | - |
| `ESPOCRM_API_KEY` | API key for authentication | Yes | - |
| `ESPOCRM_AUTH_METHOD` | Authentication method (`apikey` or `hmac`) | Yes | `apikey` |
| `ESPOCRM_SECRET_KEY` | Secret key for HMAC auth | No | - |
| `MCP_TRANSPORT` | MCP transport method | No | `stdio` |
| `RATE_LIMIT` | Requests per minute limit | No | `100` |
| `REQUEST_TIMEOUT` | Request timeout in milliseconds | No | `30000` |
| `LOG_LEVEL` | Logging level | No | `info` |

## Available Tools

The MCP server provides 47 comprehensive tools for EspoCRM integration:

### Contact Management
- **`create_contact`** - Create new contacts with full field support
- **`search_contacts`** - Search and filter contacts with date range filtering
- **`get_contact`** - Retrieve specific contact by ID

### Account Management  
- **`create_account`** - Create new company/organization accounts
- **`search_accounts`** - Search and filter accounts with date range filtering

### Opportunity Management
- **`create_opportunity`** - Create new sales opportunities
- **`search_opportunities`** - Search opportunities with advanced filters including amount ranges

### Meeting Management
- **`create_meeting`** - Create meetings with attendee management and calendar integration
- **`search_meetings`** - Search meetings with date ranges, status, and location filters
- **`get_meeting`** - Retrieve detailed meeting information including attendees
- **`update_meeting`** - Update existing meetings with support for all meeting fields

### User Management
- **`search_users`** - Search users by username, email, name, type, and status
- **`get_user_by_email`** - Direct email-based user lookup for calendar sync operations

### Task Management
- **`create_task`** - Create tasks with parent entity support (Lead, Account, Contact, Opportunity)
- **`search_tasks`** - Search tasks by assignee, status, priority, parent entity, and due dates
- **`get_task`** - Retrieve detailed task information including relationships
- **`update_task`** - Update task properties including status, priority, and due date
- **`assign_task`** - Assign or reassign tasks to specific users

### Lead Management
- **`create_lead`** - Create new leads with full field support and validation
- **`search_leads`** - Search leads by status, source, assignee, and date ranges
- **`update_lead`** - Update lead properties and status
- **`convert_lead`** - Convert leads to contacts, accounts, and/or opportunities
- **`assign_lead`** - Assign or reassign leads to specific users

### Team & Role Management
- **`add_user_to_team`** - Add users to teams with optional position assignment
- **`remove_user_from_team`** - Remove users from teams
- **`assign_role_to_user`** - Assign roles to users for permissions management
- **`get_user_teams`** - Get all teams that a user belongs to
- **`get_team_members`** - Get all members of a specific team
- **`search_teams`** - Search teams by name and description
- **`get_user_permissions`** - Get effective permissions for a user based on roles

### Generic Entity Operations
- **`create_entity`** - Create records for any entity type (including custom entities)
- **`search_entity`** - Search any entity type with flexible filters and field selection
- **`update_entity`** - Update any entity record by ID with flexible data
- **`delete_entity`** - Delete any entity record by ID
- **`get_entity`** - Get specific entity records with optional field selection

### Relationship Management
- **`link_entities`** - Create relationships between any two entity records
- **`unlink_entities`** - Remove relationships between entity records
- **`get_entity_relationships`** - Get all related records for an entity with relationship details

### Communication Tools
- **`create_call`** - Create call records with status, direction, and duration tracking
- **`search_calls`** - Search calls by status, direction, contact, and date ranges
- **`create_case`** - Create support cases with priority, type, and account linking
- **`search_cases`** - Search cases by status, priority, type, and assignment
- **`add_note`** - Add notes to any entity record for documentation and follow-up
- **`search_notes`** - Search notes by parent entity, author, and date ranges
- **`create_document`** - Create document records with file attachments and metadata

### System Tools
- **`health_check`** - Verify server and EspoCRM connectivity across all entities

## Enhanced Search Capabilities

All search tools now support advanced filtering options:

### Date Range Filtering
- **`createdFrom`** / **`createdTo`** - Filter by creation date range
- **`modifiedFrom`** / **`modifiedTo`** - Filter by modification date range
- **`dateFrom`** / **`dateTo`** - Filter meetings by date range

### Meeting-Specific Filters
- **`status`** - Filter by meeting status (Planned, Held, Not Held)
- **`location`** - Filter by meeting location
- **`assignedUserName`** - Filter by assigned user

### User-Specific Filters
- **`userName`** - Search by username
- **`emailAddress`** - Search by email address
- **`firstName`** / **`lastName`** - Search by name components
- **`isActive`** - Filter by active status
- **`type`** - Filter by user type (admin, regular, portal, api)

## Usage Examples

### Task Management

```javascript
// Create a task assigned to a user with parent relationship
await client.callTool('create_task', {
  name: 'Follow up on lead discussion',
  assignedUserId: 'user123',
  parentType: 'Lead',
  parentId: 'lead456',
  priority: 'High',
  status: 'Not Started',
  dateEnd: '2025-08-15',
  description: 'Contact lead about pricing questions'
});

// Search tasks by assignee and status
await client.callTool('search_tasks', {
  assignedUserId: 'user123',
  status: 'Started',
  priority: 'High',
  dueDateFrom: '2025-08-01',
  dueDateTo: '2025-08-31'
});

// Assign task to different user
await client.callTool('assign_task', {
  taskId: 'task789',
  assignedUserId: 'user456'
});
```

### Lead Management

```javascript
// Create a new lead
await client.callTool('create_lead', {
  firstName: 'John',
  lastName: 'Smith',
  emailAddress: 'john.smith@example.com',
  accountName: 'Smith Industries',
  source: 'Web Site',
  status: 'New',
  assignedUserId: 'user123',
  description: 'Interested in enterprise solution'
});

// Search leads by status and source
await client.callTool('search_leads', {
  status: 'In Process',
  source: 'Web Site',
  assignedUserName: 'Sales Rep',
  createdFrom: '2025-08-01',
  limit: 20
});

// Convert lead to contact and account
await client.callTool('convert_lead', {
  leadId: 'lead123',
  createContact: true,
  createAccount: true,
  createOpportunity: true,
  opportunityName: 'Smith Industries - Enterprise Deal',
  opportunityAmount: 50000
});
```

### Team & Role Management

```javascript
// Add user to team with position
await client.callTool('add_user_to_team', {
  userId: 'user123',
  teamId: 'sales-team',
  position: 'Sales Manager'
});

// Get all members of a team
await client.callTool('get_team_members', {
  teamId: 'sales-team',
  limit: 50
});

// Assign role to user for permissions
await client.callTool('assign_role_to_user', {
  userId: 'user123',
  roleId: 'manager-role'
});

// Search teams by criteria
await client.callTool('search_teams', {
  name: 'Sales',
  description: 'revenue'
});

// Get user's effective permissions
await client.callTool('get_user_permissions', {
  userId: 'user123'
});
```

### Generic Entity Operations

```javascript
// Create any entity type (including custom entities)
await client.callTool('create_entity', {
  entityType: 'CustomProduct',
  data: {
    name: 'Premium Widget',
    price: 199.99,
    category: 'Electronics',
    inStock: true
  }
});

// Search any entity with flexible filters
await client.callTool('search_entity', {
  entityType: 'CustomOrder',
  filters: {
    status: 'pending',
    totalAmount: 1000,
    customerType: 'enterprise'
  },
  select: ['id', 'orderNumber', 'customerName', 'totalAmount'],
  orderBy: 'createdAt',
  order: 'desc'
});

// Update any entity record
await client.callTool('update_entity', {
  entityType: 'CustomProduct',
  entityId: 'prod123',
  data: {
    price: 179.99,
    inStock: false,
    lastModified: '2025-07-20T10:30:00Z'
  }
});

// Delete any entity record
await client.callTool('delete_entity', {
  entityType: 'CustomProduct',
  entityId: 'prod123'
});

// Get specific entity with field selection
await client.callTool('get_entity', {
  entityType: 'CustomOrder',
  entityId: 'order456',
  select: ['orderNumber', 'customerName', 'items', 'totalAmount']
});
```

### Relationship Management

```javascript
// Link entities together (e.g., link contact to account)
await client.callTool('link_entities', {
  entityType: 'Contact',
  entityId: 'contact123',
  relatedEntityType: 'Account',
  relatedEntityId: 'account456',
  relationshipName: 'accounts'
});

// Get all relationships for an entity
await client.callTool('get_entity_relationships', {
  entityType: 'Contact',
  entityId: 'contact123',
  relationshipName: 'opportunities'
});

// Remove relationship between entities
await client.callTool('unlink_entities', {
  entityType: 'Contact',
  entityId: 'contact123',
  relatedEntityType: 'Account',
  relatedEntityId: 'account456',
  relationshipName: 'accounts'
});
```

### Communication Tools

```javascript
// Create a call record
await client.callTool('create_call', {
  name: 'Follow-up call with John Smith',
  status: 'Held',
  direction: 'Outbound',
  duration: 1800, // 30 minutes in seconds
  parentType: 'Contact',
  parentId: 'contact123',
  description: 'Discussed pricing options and next steps'
});

// Search calls by criteria
await client.callTool('search_calls', {
  status: 'Held',
  direction: 'Outbound',
  dateFrom: '2025-07-01',
  dateTo: '2025-07-31',
  limit: 20
});

// Create a support case
await client.callTool('create_case', {
  name: 'Login Issues',
  status: 'New',
  priority: 'High',
  type: 'Technical',
  accountId: 'account123',
  description: 'Customer unable to login to portal'
});

// Add a note to any entity
await client.callTool('add_note', {
  parentType: 'Lead',
  parentId: 'lead123',
  post: 'Customer expressed interest in enterprise features. Schedule demo next week.',
  data: {
    isInternal: false
  }
});

// Search notes by parent entity
await client.callTool('search_notes', {
  parentType: 'Lead',
  parentId: 'lead123',
  createdFrom: '2025-07-01',
  limit: 10
});
```

### AI Chatbot Usage

The embedded chatbot understands natural language and can perform any CRM operation:

```javascript
// Natural language examples users can type:
"Create a contact named Sarah Johnson with email sarah@techcorp.com"
"Find all accounts in the software industry"
"Show me opportunities over $50,000"
"Create a task to follow up with lead John Smith"
"Schedule a meeting for tomorrow at 2 PM"
"What's the system health status?"
"Link contact ID 123 to account TechCorp"
"Add a note to case #456 saying 'Customer satisfied with resolution'"
```

### Meeting Management

```javascript
// Create a meeting with attendees
await client.callTool('create_meeting', {
  name: 'Project Kickoff Meeting',
  dateStart: '2025-08-01T10:00:00',
  dateEnd: '2025-08-01T11:00:00',
  location: 'Conference Room A',
  description: 'Initial project planning session',
  status: 'Planned',
  contactsIds: ['contact123', 'contact456'],
  usersIds: ['user789']
});

// Search meetings by date range
await client.callTool('search_meetings', {
  dateFrom: '2025-08-01',
  dateTo: '2025-08-31',
  status: 'Planned',
  limit: 20
});
```

### User Management

```javascript
// Find user by email
await client.callTool('get_user_by_email', {
  emailAddress: 'john.doe@company.com'
});

// Search active users
await client.callTool('search_users', {
  isActive: true,
  type: 'regular',
  limit: 50
});
```

### Advanced Contact Search with Date Filtering

```javascript
// Search contacts created in the last week
await client.callTool('search_contacts', {
  searchTerm: 'manager',
  createdFrom: '2025-07-13',
  createdTo: '2025-07-20',
  limit: 10
});
```

### Calendar Integration Workflow

```javascript
// Complete workflow for calendar sync
const meetings = await client.callTool('search_meetings', {
  dateFrom: '2025-08-01',
  dateTo: '2025-08-31'
});

const user = await client.callTool('get_user_by_email', {
  emailAddress: 'calendar@company.com'
});

const newMeeting = await client.callTool('create_meeting', {
  name: 'Synced from Google Calendar',
  dateStart: '2025-08-15T14:00:00',
  dateEnd: '2025-08-15T15:00:00',
  googleEventId: 'google_event_123'
});
```

## Testing

### Automated Testing

The project includes comprehensive testing tools:

```bash
# Test configuration and connectivity
npm run test:config

# Test MCP client functionality
npm run test:client

# Run unit tests
npm test
```

### Manual Testing Scripts

#### Connection Testing
```bash
node test-connection.js
```
Tests basic connectivity, API endpoints, and authentication.

#### Enhanced Tools Testing
```bash
node test-enhanced-tools.js
```
Comprehensive test of all enhanced features including meetings and users.

#### Random Contact Generation
```bash
node create-random-contact.js
```
Creates a random test contact to verify CRUD operations.

## Development

### Project Structure

```
EspoMCP/
├── src/                     # Source code
│   ├── config/             # Configuration management
│   ├── espocrm/           # EspoCRM API client and types
│   │   ├── client.ts      # HTTP client with authentication
│   │   └── types.ts       # TypeScript interfaces for all entities
│   ├── tools/             # MCP tool implementations
│   ├── utils/             # Utility functions and formatting
│   │   ├── errors.ts      # Error handling utilities
│   │   ├── formatting.ts  # Entity formatting functions
│   │   ├── logger.ts      # Winston logger configuration
│   │   └── validation.ts  # Zod schema validation
│   └── index.ts           # Main server entry point
├── tests/                  # Test files
├── build/                  # Compiled JavaScript
├── logs/                   # Application logs
└── docs/                   # Documentation
```

### Key Components

#### MCP Server (`src/index.ts`)
Main server implementation with environment loading, graceful shutdown handling, and MCP protocol compliance.

#### EspoCRM Client (`src/espocrm/client.ts`)
HTTP client with authentication, error handling, logging, and comprehensive CRUD operations.

#### Entity Types (`src/espocrm/types.ts`)
Complete TypeScript interfaces for Contact, Account, Opportunity, Meeting, User, and related entities.

#### Tool Registry (`src/tools/index.ts`)
Central registry for all MCP tools with proper type safety, validation, and error handling.

#### Formatting Utilities (`src/utils/formatting.ts`)
Professional formatting functions for all entity types with consistent output formatting.

### Development Workflow

1. **Make changes** to source files in `src/`
2. **Build the project** with `npm run build`
3. **Test changes** with `npm run test:config`
4. **Test enhanced features** with `npm run test:client`
5. **Lint code** with `npm run lint`

## Docker Deployment

### Build and Run with Docker

```bash
# Build the Docker image
npm run docker:build

# Run with environment file
npm run docker:run
```

### Docker Compose

```yaml
version: '3.8'
services:
  espocrm-mcp:
    build: .
    environment:
      - ESPOCRM_URL=${ESPOCRM_URL}
      - ESPOCRM_API_KEY=${ESPOCRM_API_KEY}
      - ESPOCRM_AUTH_METHOD=apikey
      - MCP_TRANSPORT=stdio
      - RATE_LIMIT=100
      - LOG_LEVEL=info
    volumes:
      - ./logs:/app/logs
    restart: unless-stopped
```

## Calendar Sync Integration

This MCP server is specifically designed to work seamlessly with calendar synchronization systems:

### Google Calendar Sync Compatibility
- Meeting entities include `googleEventId` field for sync tracking
- User lookup by email for attendee management
- Date range filtering for efficient sync operations
- Attendee linking through `contactsIds` and `usersIds`

### Sync Prevention Features
- Comprehensive entity tracking to prevent duplicate creation
- Support for external system identifiers
- Robust error handling for sync operations

### Workflow Integration
```javascript
// Typical calendar sync workflow
const existingMeetings = await client.callTool('search_meetings', {
  dateFrom: syncStartDate,
  dateTo: syncEndDate
});

const user = await client.callTool('get_user_by_email', {
  emailAddress: assignedUserEmail
});

// Create meetings from external calendar
for (const externalEvent of externalEvents) {
  await client.callTool('create_meeting', {
    name: externalEvent.title,
    dateStart: externalEvent.start,
    dateEnd: externalEvent.end,
    googleEventId: externalEvent.id,
    description: externalEvent.description
  });
}
```

## Troubleshooting

### Common Issues

#### Connection Failures
```bash
# Test basic connectivity
node test-connection.js

# Check environment variables
npm run test:config

# Test specific endpoints
curl -H "X-Api-Key: YOUR_API_KEY" http://your-espocrm.com/api/v1/App/user
```

#### Authentication Issues
- Verify API key is correct and active
- Check user permissions in EspoCRM
- Ensure API access is enabled for the user
- Verify the correct API endpoint format

#### Meeting Creation Issues
- Ensure required fields (name, dateStart, dateEnd) are provided
- Verify date format is ISO 8601 (YYYY-MM-DDTHH:mm:ss)
- Check user permissions for meeting creation
- Validate contact and user IDs exist before linking

#### User Search Issues
- Verify user has permission to access User entity
- Check if users exist in the system
- Ensure email addresses are correctly formatted

### Debug Mode

Enable debug logging:
```env
LOG_LEVEL=debug
```

View detailed logs:
```bash
tail -f logs/espocrm-mcp.log
```

### Connection Diagnostics

Test specific API endpoints:
```bash
# Test user endpoint
curl -H "X-Api-Key: YOUR_KEY" http://your-espocrm.com/api/v1/App/user

# Test meeting search
curl -H "X-Api-Key: YOUR_KEY" "http://your-espocrm.com/api/v1/Meeting?maxSize=1"

# Test user search  
curl -H "X-Api-Key: YOUR_KEY" "http://your-espocrm.com/api/v1/User?maxSize=1"
```

## API Reference

### Tool Schemas

All tools use Zod schemas for validation. Key schemas include:

#### Contact Schema
```typescript
{
  firstName: string,
  lastName: string,
  emailAddress?: string,
  phoneNumber?: string,
  title?: string,
  department?: string,
  accountId?: string,
  description?: string
}
```

#### Meeting Schema
```typescript
{
  name: string,
  dateStart: string,        // ISO 8601 format
  dateEnd: string,          // ISO 8601 format
  location?: string,
  description?: string,
  status?: 'Planned' | 'Held' | 'Not Held',
  parentType?: string,
  parentId?: string,
  contactsIds?: string[],   // Array of contact IDs
  usersIds?: string[],      // Array of user IDs
  googleEventId?: string    // For calendar sync
}
```

#### User Schema
```typescript
{
  userName: string,
  firstName?: string,
  lastName?: string,
  emailAddress?: string,
  phoneNumber?: string,
  isActive?: boolean,
  type?: 'admin' | 'regular' | 'portal' | 'api'
}
```

#### Task Schema
```typescript
{
  name: string,
  assignedUserId?: string,
  parentType?: 'Lead' | 'Account' | 'Contact' | 'Opportunity',
  parentId?: string,
  status?: 'Not Started' | 'Started' | 'Completed' | 'Canceled' | 'Deferred',
  priority?: 'Low' | 'Normal' | 'High' | 'Urgent',
  dateEnd?: string,         // Due date in YYYY-MM-DD format
  description?: string
}
```

#### Lead Schema
```typescript
{
  firstName: string,
  lastName: string,
  emailAddress?: string,
  phoneNumber?: string,
  accountName?: string,     // Company name
  website?: string,
  status?: 'New' | 'Assigned' | 'In Process' | 'Converted' | 'Recycled' | 'Dead',
  source: 'Call' | 'Email' | 'Existing Customer' | 'Partner' | 'Public Relations' | 'Web Site' | 'Campaign' | 'Other',
  industry?: string,
  assignedUserId?: string,
  description?: string
}
```

#### Team Schema
```typescript
{
  name: string,
  description?: string,
  positionList?: string[],  // Available positions in the team
}
```

#### Generic Entity Schema
```typescript
{
  entityType: string,       // Entity type name (e.g., 'Contact', 'CustomProduct')
  data: {                   // Flexible key-value pairs
    [key: string]: any
  },
  // Optional for search/get operations
  filters?: {
    [field: string]: any
  },
  select?: string[],        // Fields to retrieve
  orderBy?: string,
  order?: 'asc' | 'desc'
}
```

#### Call Schema
```typescript
{
  name: string,
  status?: 'Planned' | 'Held' | 'Not Held',
  direction?: 'Inbound' | 'Outbound',
  duration?: number,        // Duration in seconds
  parentType?: string,      // Related entity type
  parentId?: string,        // Related entity ID
  assignedUserId?: string,
  description?: string
}
```

#### Case Schema
```typescript
{
  name: string,
  status?: 'New' | 'Assigned' | 'Pending' | 'Closed' | 'Rejected' | 'Duplicate',
  priority?: 'Low' | 'Normal' | 'High' | 'Urgent',
  type?: string,            // Case type
  accountId?: string,       // Related account
  contactId?: string,       // Related contact
  assignedUserId?: string,
  description?: string
}
```

#### Note Schema
```typescript
{
  parentType: string,       // Entity type the note is attached to
  parentId: string,         // Entity ID the note is attached to
  post: string,             // Note content
  data?: {                  // Additional note data
    isInternal?: boolean,   // Internal note flag
    [key: string]: any
  }
}
```

#### Relationship Schema
```typescript
{
  entityType: string,       // Source entity type
  entityId: string,         // Source entity ID
  relatedEntityType: string, // Target entity type
  relatedEntityId: string,  // Target entity ID
  relationshipName: string  // Relationship field name
}
```

#### Team Management Operations
```typescript
// Add user to team
{
  userId: string,
  teamId: string,
  position?: string         // Optional position within team
}

// Role assignment
{
  userId: string,
  roleId: string
}
```

#### Search Parameters
```typescript
{
  searchTerm?: string,
  limit?: number,           // Default: 20, Max: 200
  offset?: number,          // Default: 0
  createdFrom?: string,     // YYYY-MM-DD format
  createdTo?: string,       // YYYY-MM-DD format
  modifiedFrom?: string,    // YYYY-MM-DD format
  modifiedTo?: string,      // YYYY-MM-DD format
  // Entity-specific filters...
}
```

### Response Formats

#### Standard List Response
```json
{
  "total": 150,
  "list": [
    {
      "id": "entity123",
      "name": "Entity Name",
      "createdAt": "2025-07-20T10:30:00Z",
      "modifiedAt": "2025-07-20T15:45:00Z"
    }
  ]
}
```

#### Meeting Response
```json
{
  "id": "meeting123",
  "name": "Project Meeting",
  "status": "Planned",
  "dateStart": "2025-08-01T10:00:00Z",
  "dateEnd": "2025-08-01T11:00:00Z",
  "location": "Conference Room A",
  "assignedUserName": "John Doe",
  "contacts": ["contact1", "contact2"],
  "googleEventId": "google_event_123"
}
```

## Performance Considerations

### Pagination
- Default limit: 20 results
- Maximum limit: 200 results
- Use offset for pagination through large datasets

### Rate Limiting
- Default: 100 requests per minute
- Configurable via RATE_LIMIT environment variable
- Implements exponential backoff for rate limit handling

### Caching
- No built-in caching (recommended to implement at application level)
- EspoCRM API responses are not cached to ensure data freshness

### Bulk Operations
- Individual entity operations only
- For bulk operations, iterate through arrays at the application level
- Consider rate limiting when processing large datasets

## Security Best Practices

### API Key Management
- Store API keys in environment variables only
- Rotate API keys regularly
- Use dedicated API users with minimal required permissions
- Monitor API usage logs

### Network Security
- Use HTTPS for all EspoCRM connections
- Consider VPN or private networks for sensitive data
- Implement IP whitelisting if supported by your EspoCRM instance

### Data Validation
- All inputs are validated using Zod schemas
- Sanitization is applied to prevent injection attacks
- Error messages do not expose sensitive system information

## Contributing

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/enhanced-search`)
3. Commit your changes (`git commit -m 'Add enhanced search capabilities'`)
4. Push to the branch (`git push origin feature/enhanced-search`)
5. Open a Pull Request

### Development Guidelines

- Follow TypeScript best practices with strict typing
- Add comprehensive tests for new functionality
- Update documentation for any new features
- Ensure all tests pass before submitting
- Follow existing code formatting and structure
- Add appropriate error handling and logging

### Testing Requirements

- Unit tests for new functionality
- Integration tests with mock EspoCRM responses
- Manual testing with real EspoCRM instances
- Documentation updates for new features

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Support

- **Issues**: [GitHub Issues](https://github.com/zaphod-black/EspoMCP/issues)
- **Documentation**: Check the `docs/` directory for additional documentation
- **EspoCRM API**: [Official EspoCRM API Documentation](https://docs.espocrm.com/development/api/)
- **MCP Specification**: [Model Context Protocol Documentation](https://spec.modelcontextprotocol.io/)

## Changelog

### Version 2.0.0 - AI Chatbot Integration 🤖
- **Complete Chatbot Interface**: Floating chat bubble that embeds in EspoCRM
- **Natural Language Processing**: Chat in plain English to perform CRM operations
- **WebSocket Communication**: Real-time bidirectional communication
- **47 MCP Tools Access**: Full CRM functionality via conversational interface
- **Security & Rate Limiting**: Production-ready security with input validation
- **Docker Deployment**: Containerized chatbot server alongside MCP server
- **Mobile Responsive**: Beautiful interface that works on all devices
- **EspoCRM Integration**: Simple 3-line integration with existing EspoCRM instances
- **AI-Powered**: Optional OpenAI integration for advanced natural language understanding
- **Production Testing**: Comprehensive test suite and demo interface

### Version 1.5.0 - Phase 3 Complete Communication & Relationship Management
- **Relationship Management**: 3 new tools for linking/unlinking entities and managing relationships
- **Communication Tools**: 7 new tools for calls, cases, notes, and document management
- **Entity Relationship Operations**: Link/unlink any entities, get relationship details
- **Call Management**: Create and search call records with duration and direction tracking
- **Case Management**: Create and search support cases with priority and type categorization
- **Note System**: Add notes to any entity with internal/external visibility control
- **Document Management**: Create document records with file attachment support
- **Advanced Formatting**: Added specialized formatting for calls, cases, and notes
- **Tool Count**: Expanded from 39 to 47 comprehensive tools (+8 new tools)

### Version 1.4.0 - Phase 2 Complete Enterprise Solution
- **Team & Role Management**: 7 new tools for complete user/team/role administration
- **Generic Entity Operations**: 5 new tools for manipulating any EspoCRM entity (including custom entities)
- **Team Administration**: Add/remove users from teams, assign positions, get team members
- **Role Assignment**: Assign roles to users and get effective permissions
- **Universal Entity Support**: Create, read, update, delete, and search any entity type
- **Custom Entity Support**: Full support for custom EspoCRM entities and fields
- **Enhanced Type Safety**: Added Team, Role, and GenericEntity TypeScript interfaces
- **Tool Count**: Expanded from 27 to 39 comprehensive tools (+12 new tools)

### Version 1.3.0 - Phase 1 Expansion
- **Task Management**: Complete task lifecycle with 5 new tools (create, search, get, update, assign)
- **Lead Management**: Full lead pipeline with 5 new tools (create, search, update, convert, assign)
- **Parent Relationships**: Tasks can be linked to Leads, Accounts, Contacts, or Opportunities
- **Lead Conversion**: Convert leads to contacts, accounts, and opportunities in one operation
- **Advanced Task Features**: Priority levels, due dates, status tracking, and user assignment
- **Expanded Search**: Task and lead search with comprehensive filtering options
- **Type Safety**: Enhanced TypeScript interfaces for all new entities
- **Tool Count**: Expanded from 17 to 27 comprehensive tools

### Version 1.2.0
- **Enhanced Meeting Management**: Complete CRUD operations for meetings
- **User Management**: Search and lookup functionality for users
- **Advanced Date Filtering**: Date range support for all search operations
- **Calendar Sync Compatibility**: Google Calendar integration support
- **Improved Error Handling**: Better error messages and debugging
- **Connection Fix**: Resolved API endpoint compatibility issues

### Version 1.1.0
- **Extended Entity Support**: Added comprehensive type definitions
- **Enhanced Search**: Advanced filtering capabilities
- **Performance Improvements**: Optimized API client and error handling

### Version 1.0.0
- Initial release with full MCP 2024/2025 support
- Complete CRUD operations for Contacts, Accounts, Opportunities
- Docker support and comprehensive testing
- Multiple authentication methods
- Production-ready logging and error handling

---

**Enterprise-grade EspoCRM integration for modern AI applications**