privateGPT MCP Server

# PrivateGPT MCP Server Development Log ## ⚠️ Warning: User Management Implementation **HANDLE WITH CARE**: The user management endpoints have significant impact and can potentially delete all users if not handled properly. While the API functionality has been tested successfully, implementation in the pgpt-mcp-server is pending due to these security considerations. The following user management endpoints require careful implementation: ### Create User (POST /api/v1/users) Required functionality: - Create new user with name, email, and password - Set optional language and timezone - Configure public access and group assignments - Assign user roles - Set up FTP access if needed - Handle all required fields: ```json { "name": "User Name", "email": "user@example.com", "password": "UserPassword123", "language": "en", "timezone": "UTC", "usePublic": true, "groups": ["Group A"], "roles": ["Sources"], "activateFtp": true, "ftpPassword": "FTPPassword!" } ``` ### Edit User (PATCH /api/v1/users) Required functionality: - Update user details by email - Modify name, language, and group assignments - Handle partial updates - Fields that can be updated: ```json { "email": "user@example.com", "name": "Updated Name", "language": "en", "groups": ["Updated Group"] } ``` ### Delete User (DELETE /api/v1/users) ⚠️ **Critical Operation** Required functionality: - Remove user by email - Clean up associated data - Handle dependencies: ```json { "email": "user@example.com" } ``` ## Implementation Status ### Core Server Structure - ✅ Basic MCP server setup with stdio transport - ✅ Error handling and graceful shutdown - ✅ Type-safe request handling - ✅ Input validation for all tools ### API Integration - ✅ Authentication with Bearer tokens - ✅ Automatic token refresh - ✅ Error mapping to MCP error codes - ✅ JSON response formatting ### Tools Implementation 1. Chat Tool - ✅ Chat creation with knowledge base selection - ✅ Support for public and document knowledge bases - ✅ Group-based access control - ✅ Language support - ✅ Chat continuation support 2. Source Management - ✅ Source creation with markdown formatting - ✅ Group assignment for private sources - ✅ Source listing by group - ✅ Source details retrieval - ✅ Source deletion - ✅ Source editing 3. Group Management - ✅ List personal and assignable groups - ✅ Group-based visibility control - ✅ Personal group handling - ✅ Group creation - ✅ Group deletion ## API Behavior Notes ### Authentication - Uses Bearer token authentication via `/api/v1/login` - Token required for all authenticated endpoints - Token invalidation via `/api/v1/logout` ### Group Management - GET `/api/v1/groups` returns personalGroups and assignableGroups arrays - Personal group appears in both arrays - Groups control access to sources and knowledge base - Full CRUD operations implemented and tested ### Source Management - Sources can be public or private - Private sources require group assignment - Sources are vectorized asynchronously - Source states: creation → vectorized - Source operations: - POST `/api/v1/sources` for creation - DELETE `/api/v1/sources/{sourceId}` for removal - PATCH `/api/v1/sources/{sourceId}` for editing - Can list sources by group - Can verify source state and visibility - All operations tested and verified ### Chat System - Two knowledge base types: - Public (usePublic: true) - Document (specific groups) - Chat operations: - Initial creation: POST `/api/v1/chats` - Continuation: PATCH `/api/v1/chats/{chatId}` - Details: GET `/api/v1/chats/{chatId}` - Chat features: - Preserves complete message history - Context-aware responses - Group-based access control - Language support ## Implementation Details ### Type Safety - Comprehensive TypeScript interfaces for all API interactions - Runtime validation for all tool inputs - Error type mapping between API and MCP ### Error Handling - API errors mapped to appropriate MCP error codes - Detailed error messages preserved - Authentication errors handled gracefully ### Resource Management - No direct resource exposure currently - All data access through tools - Future potential for direct resource access ## Future Improvements 1. Performance Optimizations: - Add caching layer - Optimize API requests - Improve response times 2. Monitoring and Observability: - Add comprehensive logging - Add metrics collection - Add performance tracking 3. Documentation: - Add API reference documentation - Add deployment guides - Add troubleshooting guides 4. Security Enhancements: - Add rate limiting - Implement request validation - Add security headers - Enhance token management - Add user session management ## Testing Notes - ✅ All major API endpoints tested - ✅ Group-based access control verified - ✅ Chat system behavior documented - ✅ Source visibility rules confirmed - ✅ Error handling validated - ✅ Source CRUD operations verified - ✅ Group CRUD operations verified - ✅ User management API functionality tested