Twenty MCP Server

# Twenty MCP Server Enhancement - Implementation Plan ## Overview This document outlines the comprehensive plan to enhance the Twenty MCP server with additional tools, resources, and prompts based on the Twenty CRM API capabilities. ## Current State The MCP server currently supports: - **People Management**: Create, get, update, search contacts - **Company Management**: Create, get, update, search companies - **Task Management**: Create tasks, get tasks - **Note Creation**: Create notes with rich text support ## Implementation Phases ### Phase 1: High Priority Features (Week 1-2) #### 1.1 Opportunities Management Tools **Priority**: High **Estimated Time**: 3-4 days **Tasks**: - [ ] Create opportunity tool (`create_opportunity`) - Fields: name, amount, stage, expectedCloseDate, probability, companyId, assigneeId - [ ] Get opportunity tool (`get_opportunity`) - Retrieve opportunity by ID with all fields - [ ] Update opportunity tool (`update_opportunity`) - Update stage, amount, probability, etc. - [ ] Search opportunities tool (`search_opportunities`) - Filter by stage, date range, amount, company - [ ] List opportunities by stage (`list_opportunities_by_stage`) - Pipeline view functionality **GraphQL Queries/Mutations to implement**: ```graphql mutation CreateOpportunity query GetOpportunity mutation UpdateOpportunity query SearchOpportunities ``` #### 1.2 Activities/Timeline Tools **Priority**: High **Estimated Time**: 2-3 days **Tasks**: - [ ] Get activities timeline (`get_activities`) - Unified view of tasks, notes, and events - [ ] Filter activities by type (`filter_activities`) - Support for date ranges and activity types - [ ] Create activity comment (`create_comment`) - Add comments to any record - [ ] Get activity history for entity (`get_entity_activities`) - All activities related to a person/company ### Phase 2: Medium Priority Features (Week 3-4) #### 2.1 Custom Objects Support **Priority**: Medium **Estimated Time**: 4-5 days **Tasks**: - [ ] List custom objects (`list_custom_objects`) - Use metadata API to discover available objects - [ ] Dynamic tool generation for custom objects - Auto-generate CRUD tools for each custom object - [ ] Custom object query builder - Flexible querying with custom fields **Implementation approach**: ```typescript // Dynamic tool registration based on metadata async function registerCustomObjectTools(server: McpServer, client: TwentyClient) { const customObjects = await client.getCustomObjects(); customObjects.forEach(obj => { registerCRUDToolsForObject(server, client, obj); }); } ``` #### 2.2 Webhooks Management **Priority**: Medium **Estimated Time**: 2-3 days **Tasks**: - [ ] Create webhook subscription (`create_webhook`) - Event types, target URL, filters - [ ] List webhooks (`list_webhooks`) - Show all active webhooks - [ ] Update webhook (`update_webhook`) - Modify subscription settings - [ ] Delete webhook (`delete_webhook`) - [ ] Test webhook (`test_webhook`) - Send test payload to endpoint #### 2.3 Metadata API Tools **Priority**: Medium **Estimated Time**: 2 days **Tasks**: - [ ] Get object schema (`get_object_schema`) - Field definitions, relationships, constraints - [ ] List all objects (`list_all_objects`) - Standard and custom objects - [ ] Get field metadata (`get_field_metadata`) - Field types, validation rules #### 2.4 Relationship Management Tools **Priority**: Medium **Estimated Time**: 3 days **Tasks**: - [ ] Link entities (`link_entities`) - Connect people to companies, opportunities to accounts - [ ] Unlink entities (`unlink_entities`) - Remove relationships - [ ] Get related entities (`get_related_entities`) - Fetch all related records - [ ] Bulk relationship operations ### Phase 3: Advanced Features (Week 5-6) #### 3.1 MCP Prompts System **Priority**: Medium **Estimated Time**: 3-4 days **Prompts to implement**: ```typescript const prompts = [ { name: "find_closing_opportunities", description: "Find all opportunities closing in a specified timeframe", arguments: ["timeframe", "minAmount", "stage"] }, { name: "create_follow_up_tasks", description: "Create follow-up tasks for contacts matching criteria", arguments: ["criteria", "taskTemplate", "dueDate"] }, { name: "generate_pipeline_report", description: "Generate a sales pipeline report", arguments: ["dateRange", "groupBy", "includeMetrics"] }, { name: "find_inactive_contacts", description: "Find contacts without recent activity", arguments: ["daysSinceLastActivity", "includeCompanies"] }, { name: "bulk_update_stage", description: "Update multiple opportunities to a new stage", arguments: ["currentStage", "newStage", "criteria"] } ]; ``` #### 3.2 Bulk Operations Support **Priority**: Low **Estimated Time**: 3 days **Tasks**: - [ ] Bulk create (`bulk_create`) - Create multiple records in one operation - [ ] Bulk update (`bulk_update`) - Update multiple records with filters - [ ] Bulk delete (`bulk_delete`) - Delete multiple records safely - [ ] Import/Export tools - CSV/JSON data handling #### 3.3 Advanced Search and Filtering **Priority**: Medium **Estimated Time**: 2-3 days **Tasks**: - [ ] Advanced search tool (`advanced_search`) - Multi-criteria search across objects - [ ] Saved searches (`save_search`, `get_saved_searches`) - [ ] Search templates for common queries ### Phase 4: Enhanced Features (Week 7-8) #### 4.1 Custom Fields Management **Priority**: Low **Estimated Time**: 3 days **Tasks**: - [ ] Add custom field (`add_custom_field`) - [ ] Update custom field (`update_custom_field`) - [ ] Delete custom field (`delete_custom_field`) - [ ] Support for RICH_TEXT_V2 fields - [ ] JSON object field support #### 4.2 Additional Utilities **Priority**: Low **Estimated Time**: 4-5 days **Tasks**: - [ ] File attachment support - Upload, download, list attachments - [ ] Tags/Labels system - Create, assign, search by tags - [ ] Comments system enhancement - Threaded comments, mentions - [ ] Audit log access - Track changes and activity ## Technical Implementation Details ### 1. Project Structure Updates ``` src/ ├── client/ │ └── twenty-client.ts (enhance with new methods) ├── tools/ │ ├── index.ts │ ├── opportunities.ts (new) │ ├── activities.ts (new) │ ├── webhooks.ts (new) │ ├── metadata.ts (new) │ ├── relationships.ts (new) │ ├── bulk-operations.ts (new) │ └── custom-objects.ts (new) ├── prompts/ │ ├── index.ts (new) │ └── crm-workflows.ts (new) ├── types/ │ ├── twenty.ts (extend with new types) │ ├── opportunities.ts (new) │ └── activities.ts (new) └── utils/ ├── dynamic-tools.ts (new) └── query-builder.ts (new) ``` ### 2. GraphQL Client Enhancement - Implement query batching for performance - Add request caching layer - Implement retry logic for failed requests - Add query complexity analysis ### 3. Error Handling Strategy - Implement comprehensive error types - Add retry mechanisms for transient failures - Provide meaningful error messages to users - Log errors for debugging ### 4. Testing Strategy - Unit tests for each new tool - Integration tests with mock Twenty API - End-to-end tests using test client - Performance benchmarks for bulk operations ### 5. Documentation Updates - Update README with new tools - Create examples for each tool category - Document prompt usage patterns - Add troubleshooting guide ## Development Guidelines ### Code Standards - TypeScript strict mode - Comprehensive type definitions - JSDoc comments for all public methods - Follow existing code patterns ### Performance Considerations - Implement pagination for list operations - Use GraphQL field selection to minimize data transfer - Cache metadata queries - Batch operations where possible ### Security Considerations - Validate all inputs - Sanitize data before sending to API - Never log sensitive information - Implement rate limiting awareness ## Deployment Strategy ### Version Management - Semantic versioning for releases - Maintain changelog - Tag releases in git - Update MCP SDK dependencies regularly ### Testing Phases 1. Local development testing 2. Integration testing with Twenty sandbox 3. Beta testing with limited users 4. Production release ### Migration Support - Backward compatibility for existing tools - Deprecation warnings for changed APIs - Migration guides for breaking changes ## Success Metrics - All tools have >95% test coverage - Response time <500ms for standard operations - Support for 100+ concurrent operations - Zero critical bugs in production - Positive user feedback on new features ## Timeline Summary - **Week 1-2**: High priority features (Opportunities, Activities) - **Week 3-4**: Medium priority features (Custom Objects, Webhooks, Metadata) - **Week 5-6**: Advanced features (Prompts, Bulk Operations) - **Week 7-8**: Enhanced features and polish ## Next Steps 1. Review and approve implementation plan 2. Set up development environment 3. Create feature branches for each phase 4. Begin Phase 1 implementation 5. Regular progress reviews and adjustments ## Appendix: Twenty CRM API Resources - API Documentation: https://twenty.com/developers - GraphQL Playground: Available in Twenty app settings - GitHub Repository: https://github.com/twentyhq/twenty - Community Discord: For API questions and support