fix: harden all tools against crashes and improve search_users and pagination

- search_users: remove N+1 load() calls, read directly from _data dict
  to avoid PararamModelNotLoadedError, add pm_chat_id to response
- get_chat_messages: implement before_message_id pagination support
- upload_file_to_chat: fallback to local file metadata when API response
  lacks name/size fields
- Add catch-all except Exception handlers to all 12 tool functions to
  prevent MCP server crashes on unexpected errors
- Make UserInfo.active, organizations optional (not available from search API)
- Make UploadFilePayload.file_id, url optional (not always returned by API)

Author: ivolnistov

src/pararam_nexus_mcp/models.py

@@ -179,10 +179,10 @@ class BuildConversationThreadResponse(BaseModel):
 class UploadFilePayload(BaseModel):
     """Payload for upload_file_to_chat response."""
 
-    file_id: str = Field(..., description='Unique identifier for the file')
+    file_id: str | None = Field(None, description='Unique identifier for the file')
     filename: str = Field(..., description='Name of the uploaded file')
     size: int = Field(..., description='File size in bytes')
-    url: str = Field(..., description='URL to access the file')
+    url: str | None = Field(None, description='URL to access the file')
     chat_id: str = Field(..., description='ID of the chat')
 
 
@@ -276,9 +276,10 @@ class UserInfo(BaseModel):
     id: int = Field(..., description='User ID')
     name: str = Field(..., description="User's display name")
     unique_name: str = Field(..., description="User's unique username")
-    active: bool = Field(..., description='Whether user is active')
+    active: bool | None = Field(None, description='Whether user is active')
     is_bot: bool = Field(..., description='Whether user is a bot')
-    organizations: list[int] = Field(..., description='List of organization IDs')
+    pm_chat_id: int | None = Field(None, description='PM chat ID for direct messaging this user')
+    organizations: list[int] | None = Field(None, description='List of organization IDs')
 
 
 class SearchUsersPayload(BaseModel):

src/pararam_nexus_mcp/tools/chats.py

@@ -114,3 +114,10 @@ async def search_chats(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while searching chats: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )

src/pararam_nexus_mcp/tools/posts.py

@@ -345,6 +345,13 @@ async def search_messages(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while searching messages: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
 
     @mcp.tool()
     async def get_chat_messages(
@@ -358,15 +365,18 @@ async def get_chat_messages(
         Args:
             chat_id: ID of the chat to get messages from
             limit: Maximum number of messages to return (default: 50)
-            before_message_id: Get messages before this message ID (for pagination, currently not used)
+            before_message_id: Get messages before this message ID (for pagination).
+                If provided, returns messages older than this ID.
 
         Returns:
             ToolResponse with GetChatMessagesPayload containing chat messages including sender, text, and timestamp
         """
         try:
             client = await get_client()
 
-            logger.info(f'Getting messages from chat {chat_id}, limit: {limit}')
+            logger.info(
+                f'Getting messages from chat {chat_id}, limit: {limit}, before_message_id: {before_message_id}'
+            )
 
             # Get chat by ID
             chat = await client.client.get_chat_by_id(int(chat_id))
@@ -376,9 +386,14 @@ async def get_chat_messages(
                     error='Chat not found',
                 )
 
-            # Get recent messages using load_posts (negative indices mean from the end)
-            # -limit to -1 means last 'limit' messages
-            messages = await chat.load_posts(start_post_no=-limit, end_post_no=-1)
+            # Load posts: if before_message_id is set, load range ending before it
+            if before_message_id:
+                end_no = int(before_message_id) - 1
+                start_no = max(end_no - limit + 1, 1)
+                messages = await chat.load_posts(start_post_no=start_no, end_post_no=end_no)
+            else:
+                # Get last 'limit' messages
+                messages = await chat.load_posts(start_post_no=-limit, end_post_no=-1)
 
             if not messages:
                 return error_response(
@@ -459,6 +474,13 @@ async def get_chat_messages(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while getting chat messages: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
 
     @mcp.tool()
     async def send_message(
@@ -539,6 +561,13 @@ async def send_message(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while sending message: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
 
     @mcp.tool()
     async def build_conversation_thread(
@@ -697,6 +726,13 @@ def collect_thread_posts(post_no: int) -> None:
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while building conversation thread: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
 
     @mcp.tool()
     async def upload_file_to_chat(
@@ -775,17 +811,22 @@ async def upload_file_to_chat(
             reply_no = int(reply_to_message_id) if reply_to_message_id else None
             uploaded_file = await chat.upload_file(upload_path, reply_no=reply_no)
 
+            # Fallback to local file info when API response lacks fields
+            actual_path = Path(upload_path)
+            file_name = uploaded_file.name or actual_path.name
+            file_size = uploaded_file.size or actual_path.stat().st_size
+
             chat_name = chat.title or 'Unknown'
             message_text = (
-                f"File '{uploaded_file.name}' uploaded successfully to chat '{chat_name}' ({uploaded_file.size} bytes)"
+                f"File '{file_name}' uploaded successfully to chat '{chat_name}' ({file_size} bytes)"
             )
 
             return success_response(
                 message=message_text,
                 payload=UploadFilePayload(
                     file_id=uploaded_file.guid,
-                    filename=uploaded_file.name,
-                    size=uploaded_file.size,
+                    filename=file_name,
+                    size=file_size,
                     url=uploaded_file.url,
                     chat_id=chat_id,
                 ),
@@ -827,6 +868,13 @@ async def upload_file_to_chat(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while uploading file: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
         finally:
             # Clean up temporary file if created
             if temp_file_path and temp_file_path.exists():
@@ -961,6 +1009,13 @@ async def get_message_from_url(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while getting message from URL: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
 
     @mcp.tool()
     async def get_post_attachments(
@@ -1124,6 +1179,13 @@ async def get_post_attachments(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while getting post attachments: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
 
     @mcp.tool()
     async def download_post_attachment(
@@ -1422,3 +1484,10 @@ async def download_post_attachment(
                 size=0,
                 mime_type='',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while downloading attachment: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )

src/pararam_nexus_mcp/tools/users.py

@@ -65,22 +65,18 @@ async def search_users(
             # Apply limit
             users = users[:limit]
 
-            # Format results
-            formatted_users = []
-            for user in users:
-                # Load user data
-                await user.load()
-
-                formatted_users.append(
-                    UserInfo(
-                        id=user.id,
-                        name=user.name,
-                        unique_name=user.unique_name,
-                        active=user.active,
-                        is_bot=user.is_bot,
-                        organizations=user.organizations,
-                    )
+            # Format results — use _data dict directly to avoid PararamModelNotLoadedError
+            # when optional fields are missing from search API response
+            formatted_users = [
+                UserInfo(
+                    id=user._data.get('id', 0),
+                    name=user._data.get('name', ''),
+                    unique_name=user._data.get('unique_name', ''),
+                    is_bot=user._data.get('is_bot', False),
+                    pm_chat_id=user._data.get('pm_thread_id'),
                 )
+                for user in users
+            ]
 
             message_text = f"Found {len(formatted_users)} users matching '{query}'"
 
@@ -117,6 +113,13 @@ async def search_users(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while searching users: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
 
     @mcp.tool()
     async def get_user_info(
@@ -194,6 +197,13 @@ async def get_user_info(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while getting user info: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )
 
     @mcp.tool()
     async def get_user_team_status(
@@ -294,3 +304,10 @@ async def get_user_team_status(
                 message='Network error occurred',
                 error=f'Network error: {e!s}',
             )
+        except Exception as e:
+            # Top-level handler to prevent MCP server crash on unexpected errors
+            logger.error('Unexpected error while getting team status: %s', e, exc_info=True)
+            return error_response(
+                message='Unexpected error occurred',
+                error=f'Unexpected error: {e!s}',
+            )