- Restructured integration libraries to have dedicated directories for each integration (e.g., Telegram, future Gmail) under `src/lib/<integration>/`, improving organization and clarity.
- Updated state management to ensure all Redux dispatches for each integration are routed through specific state functions, enhancing maintainability.
- Consolidated services related to each integration within their respective folders, separating them from cross-cutting services.
This update streamlines the architecture for better scalability and maintainability of integrations.
- Moved `mtprotoService` and other Telegram-related services to a dedicated `src/lib/telegram/services/` directory for better organization.
- Updated import paths across various files to reflect the new service structure.
- Enhanced state management by ensuring all Redux dispatches for Telegram state are routed through dedicated functions, improving maintainability and clarity.
- Consolidated unit tests to ensure they align with the new service structure and state management approach.
This update streamlines the Telegram integration and enhances the overall architecture of the application.
- Introduced a new `messageLoader` service to handle smart message fetching with three-direction loading, request cancellation via AbortController, and batch ID fetching.
- Implemented a `mtprotoService` for managing the MTProto client lifecycle, including initialization, connection, and authentication processes.
- Added an `updateManager` service to track and process updates with gap detection and recovery mechanisms, ensuring reliable message delivery.
- Included comprehensive tests for the update manager to validate its functionality and state management.
This update enhances the Telegram integration by providing robust message handling and update processing capabilities.
- Added the `debug` package to enhance logging capabilities across the application.
- Included `@types/debug` for TypeScript support, ensuring type safety in logging implementations.
- Updated package-lock and yarn.lock files to reflect these changes.
This update aims to facilitate better debugging and monitoring of the Telegram MCP system.
- Updated import paths for Telegram types and API functions to improve module organization.
- Introduced new helper functions for reading typed values from MCP tool arguments.
- Added comprehensive API functions for managing Telegram contacts, chats, and messages, including creating groups, channels, and polls.
- Implemented a tool action parser to convert tool inputs into human-readable descriptions.
- Added tests for new functionalities to ensure reliability and correctness.
This update enhances the Telegram MCP server's capabilities and improves code maintainability.
API read functions previously fetched data from Telegram but never
persisted it to Redux, causing the cache to stay empty after API calls.
Now all read functions that fetch from the Telegram API dispatch Redux
actions to update chats, messages, and users in the store.
Introduces src/lib/mcp/telegram/state/ with dispatch helpers for chat,
message, and user state updates. Modifies 15 API functions to call
these after successful API fetches.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Set up Vitest with node polyfills and add 338 tests across 18 test files
covering the MCP tools, API layer, Redux state, selectors, and update
manager. Fix shallow-copy bug in ensureUser that caused shared state
between Redux user entries.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
Split monolithic tool handlers into a clean two-layer architecture:
- `api/` layer: ~80 files with raw Telegram API calls returning typed `ApiResult<T>` with `fromCache` boolean
- `tools/` layer: thinned to validation + formatting wrappers delegating to api/
Key changes:
- Add `ApiResult<T>` type and `fromCache` field to `MCPToolResult`
- Extract shared helpers (getChatById, formatMessage, etc.) into `api/helpers.ts`
- Move `apiResultTypes.ts` and `apiCastHelpers.ts` into `api/`
- Delete `telegramApi.ts` (all logic migrated to individual api/ files)
- Add `validatePositiveInt` to validation utilities
- Auto-infer `fromCache` in server.ts via `isStateOnlyTool()` safety net
- Update `bulk.ts` skill to import from new api layer
Net reduction of ~2,475 lines across 86 files.
Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
- Introduced a three-tier tool classification system for rate limiting: state_only, api_read, and api_write, improving the management of tool execution based on their API call characteristics.
- Updated rate limiting configuration to reflect new classifications, ensuring appropriate delays for different tool types.
- Implemented API fallback mechanisms in various tools to first attempt data retrieval from cached Redux state before falling back to Telegram API calls, enhancing performance and reliability.
- Refactored multiple Telegram tools to utilize the new API fallback approach, improving user experience during data retrieval.
This update significantly enhances the efficiency and responsiveness of the MCP by optimizing tool execution and data retrieval processes.
- Introduced a new rate limiter to manage tool execution frequency, preventing excessive API calls and ensuring smoother performance.
- Added bulk operations skill for batch processing of messages, including sending, archiving, and deleting across multiple chats.
- Implemented reminders skill for creating and managing time-based reminders, enhancing user interaction capabilities.
- Updated MCP server to integrate new skills and enforce rate limits on tool execution, improving overall system reliability and user experience.
This update significantly enhances the functionality of the MCP by providing powerful new tools while ensuring responsible API usage through rate limiting.
* Add UserProvider to App component and enhance user data fetching logic
- Integrated UserProvider into the App component to manage user state.
- Updated UserProvider to fetch current user data on token availability and handle token expiration by clearing the token on fetch failure.
- Improved user data fetching logic for better error handling and user experience.
* Enhance Telegram connection handling and error management
- Added logic to handle Telegram account mismatch, providing user feedback and resetting connection state.
- Improved user verification during authentication to ensure the logged-in account matches the Telegram account.
- Refactored connection status checks and error handling for better user experience.
- Introduced a method to clear session and disconnect when account mismatch occurs.
- Updated polling mechanism for authentication status to ensure timely updates.
This update improves the robustness of the Telegram connection process and enhances user feedback during authentication failures.
* ran prettier
* Refactor socket and auth state management for user-specific handling
- Updated socket state management to support multiple users by introducing user-specific selectors and actions.
- Refactored connection status handling in the socket service to dispatch user-specific status updates.
- Enhanced onboarding state management to track completion per user, allowing for more granular control.
- Introduced new selectors for socket and auth states to improve readability and maintainability.
- Updated relevant components to utilize the new user-specific state management.
This update improves the application's ability to handle multiple users and enhances the overall user experience during onboarding and socket connections.
* Enhance MTProto client session management and introduce user-specific session handling
- Updated the MTProtoService to manage sessions per user by storing session data under a user-specific key.
- Modified the initialize method to accept a userId parameter, allowing for user-specific session initialization and management.
- Improved session loading and saving logic to ensure proper handling of user sessions.
- Added a utility function to generate session keys based on userId for better maintainability.
This update enhances the application's ability to handle multiple user sessions effectively.
* Refactor Telegram state management for user-specific handling
- Introduced user-specific state management in the Telegram store, allowing for better handling of multiple users.
- Updated selectors to retrieve state based on the current user, improving data encapsulation and reducing global state dependencies.
- Enhanced reducers and thunks to ensure actions are dispatched with user context, maintaining user-specific data integrity.
- Modified persistence configuration to store Telegram state scoped by user, ensuring isolated state management.
This update significantly improves the application's ability to manage multiple user sessions effectively and enhances overall user experience.
* Enhance MTProtoService connection handling with user-specific initialization
- Updated the checkConnection method to accept an optional userId parameter, allowing for user-specific connection initialization.
- Modified the connection logic to ensure proper initialization only occurs when a userId is provided, improving session management.
- Refactored related thunks to use a consistent naming convention for userId parameters, enhancing code clarity.
This update improves the handling of user sessions in the MTProtoService, aligning with recent enhancements in user-specific state management.
* Refactor Telegram connection handling for user-specific management
- Updated the TelegramConnectionModal to utilize user-specific identifiers for connection status and authentication processes, enhancing session management.
- Refactored related components and selectors to ensure userId is consistently passed and utilized, improving clarity and maintainability.
- Enhanced the ConnectionsPanel and ConnectStep to check for saved sessions based on userId, allowing for better handling of multiple user connections.
This update significantly improves the application's ability to manage user-specific Telegram connections and enhances the overall user experience.
* Refactor Telegram connection logic to simplify session management
- Removed unnecessary userId checks and localStorage interactions from ConnectionsPanel and ConnectStep components, streamlining the connection status determination.
- Updated MTProtoService to manage session data through Redux instead of localStorage, enhancing consistency and maintainability.
- Improved session loading and saving logic to focus solely on Redux state, ensuring better integration with user-specific session handling.
This update enhances the clarity and efficiency of the Telegram connection management process, aligning with recent improvements in user-specific state management.
* Update CLAUDE.md to clarify localStorage usage and emphasize Redux for state management
- Revised documentation to discourage the use of localStorage and sessionStorage for app state, advocating for Redux and Redux Persist instead.
- Added guidelines for removing existing localStorage usage and migrating relevant data to Redux.
- Updated service layer documentation to reflect changes in session management, specifying that session data is now stored in Redux rather than localStorage.
- Enhanced clarity on deep link handling and the prevention of infinite reload loops.
This update aligns with recent improvements in user-specific state management and reinforces best practices for state handling.
* Enhance onboarding process with error handling and API integration
- Updated the Onboarding component to include an API call for marking onboarding as complete, with error handling to provide user feedback.
- Refactored the GetStartedStep component to support asynchronous completion handling, including loading state and error messages.
- Introduced a new onboardingComplete method in the userApi service to facilitate the onboarding completion process.
This update improves the user experience during onboarding by ensuring proper error management and feedback.
* Enhance TelegramConnectionModal with socket connection management and improved initialization flow
- Integrated socket connection handling in the TelegramConnectionModal to ensure the socket is connected when the modal opens, enhancing real-time features.
- Refactored the initialization logic to streamline the connection process, including user verification and error handling.
- Introduced a reference to track the QR code flow state, preventing multiple initiations and improving user experience during authentication.
This update improves the reliability of the Telegram connection process and enhances user feedback during the onboarding experience.
* Refactor Telegram connection checks for improved logic consistency
- Updated the ConnectionsPanel and ConnectStep components to refine the logic for determining if a Telegram connection is established, ensuring that both session string and authentication status are required for a valid connection.
- Simplified className definitions in the UI components for better readability and maintainability.
This update enhances the clarity of connection status checks and improves the overall user experience during the onboarding process.
* Refactor Telegram authentication flow and improve error handling
- Simplified the TelegramLoginButton component by removing complex authentication logic and replacing it with a direct link to the Telegram bot for login.
- Enhanced the Login page to consume a login token from the URL, providing better error handling and user feedback during the authentication process.
- Introduced a new API service for consuming login tokens, ensuring secure retrieval of JWT tokens from the backend.
This update streamlines the authentication experience and improves error management, enhancing overall user experience during login.
- Introduced `apiCastHelpers.ts` to centralize type casting functions for Telegram's complex union types, improving type safety and code clarity.
- Updated multiple Telegram tools to utilize these helpers for casting input entities, enhancing maintainability and consistency across the codebase.
- Modified `apiResultTypes.ts` to refine type definitions, ensuring better integration with the Telegram API.
These changes streamline type handling in Telegram MCP tools, facilitating improved development practices and reducing the risk of type-related errors.
- Updated ApiPhoto interface in apiResultTypes.ts to require accessHash and fileReference properties, enhancing type safety.
- Modified getContactIds, getMediaInfo, getRecentActions, getUserPhotos, listTopics, and subscribePublicChannel tools to utilize type casting for better type handling and clarity.
- Ensured consistent handling of input entities across multiple tools by using 'unknown' type casting.
These changes strengthen the reliability and maintainability of the Telegram MCP tools, facilitating better integration with the Telegram API.
- Created CLAUDE.md to provide comprehensive guidance on the project, including architecture, commands, and environment variables.
- Introduced apiResultTypes.ts to define TypeScript interfaces for various API responses from the Telegram MTProto API, enhancing type safety and clarity in tool implementations.
- Updated multiple Telegram MCP tools to utilize the new type definitions, improving consistency and maintainability across the codebase.
These changes establish a solid foundation for documentation and type safety, facilitating better development practices and integration with the Telegram API.
- Removed MCPProvider from App.tsx to streamline the component hierarchy.
- Added cleanup functionality for the Telegram MCP server in SocketProvider to ensure proper resource management on socket disconnection.
- Introduced a new cleanup function in the Telegram MCP tools to enhance server management.
These changes enhance the overall structure of the application and improve resource handling within the Telegram MCP integration.
- Replaced instances of BigInt with the 'big-integer' library across multiple Telegram tools, ensuring uniformity in handling large integers.
- Updated type casting for input entities and user IDs to improve type safety and maintainability.
- Enhanced overall code clarity by standardizing import statements and ensuring consistent use of type casting practices.
These changes strengthen the reliability and consistency of the Telegram MCP tools, facilitating better integration with the Telegram API.
- Developed various tools for managing user interactions, including adding, deleting, and blocking contacts, as well as managing chat drafts and polls.
- Enhanced error handling and input validation across all tools, ensuring clear feedback for invalid inputs and operational errors.
- Improved logging and error formatting to streamline error management and enhance the reliability of user and chat operations.
These updates significantly enhance the Telegram MCP tools, providing comprehensive functionalities for user and chat management while ensuring a smooth user experience through improved error handling and validation.
- Replaced BrowserRouter with HashRouter in App.tsx for better routing management.
- Enhanced type safety in multiple Telegram tools by standardizing string and number checks.
- Updated return statements in various tools to ensure consistent formatting of response content.
- Improved overall code clarity by unifying import statements and ensuring consistent use of double quotes.
These changes enhance the maintainability and reliability of the Telegram MCP tools, facilitating better integration with the Telegram API.
- Updated multiple Telegram tools to cast input entities and chat IDs using 'unknown' for improved type safety.
- Replaced instances of BigInt with the 'big-integer' library for consistent handling of large integers across tools.
- Enhanced overall code clarity and maintainability by ensuring uniform type casting practices.
These changes strengthen the type safety and reliability of the Telegram MCP tools, facilitating better integration with the Telegram API.
- Developed various Telegram tools for managing chats, including archiving, unarchiving, muting, and unmuting chats, as well as inviting users to groups and managing chat photos.
- Enhanced user management capabilities with tools for banning, unbanning, promoting, and demoting users in groups and channels.
- Integrated robust error handling and input validation across all tools, ensuring clear feedback for invalid inputs and operational errors.
- Improved logging and error formatting to streamline error management and enhance the reliability of chat and user operations.
These updates significantly enhance the Telegram MCP tools, providing comprehensive functionalities for chat and user management while ensuring a smooth user experience through improved error handling and validation.
- Refactored multiple Telegram tools to replace the notImplemented function with actual implementations for deleting, editing, forwarding, pinning, unpinning, and marking messages as read.
- Added input validation for message IDs and chat IDs, ensuring robust error handling and user feedback for invalid inputs.
- Integrated logging and error formatting to enhance error management across all tools, improving the overall reliability of message operations.
- Implemented functionality to retrieve message history and context, providing users with better access to chat information.
These changes significantly enhance the Telegram MCP tools, enabling comprehensive message management capabilities while ensuring a smooth user experience through improved error handling and validation.
- Added MCPProvider to manage the initialization and updates of MCP servers within the SocketProvider context.
- Introduced utility functions for handling typed values from MCP tool arguments, improving input validation across various tools.
- Updated TelegramMCPServer to include enhanced logging and type safety for tool handling.
- Refactored multiple Telegram tools to utilize the new argument handling functions, ensuring consistent input processing and error management.
These changes enhance the overall structure and functionality of the Telegram MCP integration, providing a more robust framework for managing Telegram interactions.
- Introduced core components for Telegram MCP integration, including server management, API helpers, and tool action parsers.
- Implemented various tools for user and chat management, such as adding contacts, archiving chats, and sending messages.
- Created utility functions for handling Telegram-specific actions and responses, improving interaction with the Telegram API.
- Defined types and context for better type safety and clarity in tool implementations.
These changes establish a comprehensive framework for Telegram MCP interactions, enhancing the application's capabilities in managing Telegram functionalities.
- Introduced error handling utilities in errorHandler.ts, including a structured error logging mechanism and a function for generating error codes.
- Added a logger module in logger.ts for standardized logging with a [MCP] prefix.
- Implemented validation utilities in validation.ts to ensure proper input handling for MCP tools, including ID validation and error management.
- Created transport.ts to manage Socket.IO communication, facilitating interaction between frontend and backend MCP components.
- Defined shared types in types.ts to standardize data structures used across MCP modules.
- Updated index.ts to export new modules, ensuring a cohesive structure for MCP integration.
These changes lay the groundwork for a robust MCP framework, enhancing error management, logging, and communication capabilities within the application.
Steven Enamakel