Skip to main content
Glama

EspoCRM-MCP

by zaphod-black
README.md34.6 kB
# 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**

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/zaphod-black/EspoMCP'

If you have feedback or need assistance with the MCP directory API, please join our Discord server