implementing the user tools

Author: barduinor

README.md

@@ -27,71 +27,6 @@ Search for files in Box.
   - `ancestor_folder_ids` (List[str], optional): List of folder IDs in which to search.
 - **Returns:** The search results as a newline‑separated list of file names and IDs.
 
-### `box_read_tool`
-Read the text content of a Box file.
-
-**Parameters:**
-- `file_id` (str): ID of the file to read
-
-**Returns:** File content
-
-### `box_ask_ai_tool`
-Ask Box AI about a file.
-
-**Parameters:**
-- `file_id` (str): ID of the file
-- `prompt` (str): Question for the AI
-
-**Returns:** AI response
-
-### `box_hubs_ask_ai_tool`
-Ask Box AI about a hub. There is currently no way via API to discover a hub ID, so you must know the ID to use this tool. We will fix this in the future.
-
-**Parameters:**
-- `hubs_id` (str): ID of the hub
-- `prompt` (str): Question for the AI
-
-**Returns:** AI response
-
-### `box_search_folder_by_name`
-Locate a folder by name.
-
-**Parameters:**
-- `folder_name` (str): Name of the folder
-
-**Returns:** Folder ID
-
-### `box_ai_extract_data`
-Extract data from a file using AI.
-
-**Parameters:**
-- `file_id` (str): ID of the file
-- `fields` (str): Fields to extract
-
-**Returns:** Extracted data in JSON format
-
-### `box_list_folder_content_by_folder_id`
-List folder contents.
-
-**Parameters:**
-- `folder_id` (str): ID of the folder
-- `is_recursive` (bool): Whether to list recursively
-
-**Returns:** Folder content in JSON format with id, name, type, and description
-
-### `box_manage_folder_tool`
-Create, update, or delete folders in Box.
-
-**Parameters:**
-- `action` (str): Action to perform: "create", "delete", or "update"
-- `folder_id` (str, optional): ID of the folder (required for delete/update)
-- `name` (str, optional): Folder name (required for create, optional for update)
-- `parent_id` (str, optional): Parent folder ID (required for create, optional for update)
-- `description` (str, optional): Folder description (optional for update)
-- `recursive` (bool, optional): Whether to delete recursively (optional for delete)
-
-**Returns:** Status message with folder details
-
 #### `box_search_folder_by_name_tool`
 Locate a folder in Box by its name.
 - **Parameters:**
@@ -153,15 +88,41 @@ Extract structured data from files using AI with enhanced processing and specifi
 - **Parameters:**
   - `file_ids` (List[str]): The IDs of the files to read.
   - `fields` (List[dict]): The fields to extract from the files.
+  - `ai_agent_id` (str, optional): The ID of the AI agent to use.
 - **Returns:** Enhanced extracted structured data in JSON format.
 
 #### `box_ai_extract_structured_enhanced_using_template_tool`
 Extract structured data from files using AI with enhanced processing and a template.
 - **Parameters:**
   - `file_ids` (List[str]): The IDs of the files to read.
   - `template_key` (str): The ID of the template to use for extraction.
+  - `ai_agent_id` (str, optional): The ID of the AI agent to use.
 - **Returns:** Enhanced extracted structured data in JSON format.
 
+### Box User Tools
+
+#### `box_users_list_tool`
+List all users in the Box enterprise.
+- **Returns:** List of user dictionaries.
+
+#### `box_users_locate_by_email_tool`
+Find a user by their email address.
+- **Parameters:**
+  - `email` (str): The user's email address.
+- **Returns:** User dictionary if found.
+
+#### `box_users_locate_by_name_tool`
+Find a user by their name.
+- **Parameters:**
+  - `name` (str): The user's name.
+- **Returns:** User dictionary if found.
+
+#### `box_users_search_by_name_or_email_tool`
+Search for users by name or email.
+- **Parameters:**
+  - `query` (str): Name or email to search for.
+- **Returns:** List of user dictionaries matching the query.
+
 ### Box File Tools
 
 #### `box_read_tool`
@@ -392,17 +353,17 @@ List all Doc Gen jobs that used a specific template.
     uv lock
     ```
 
-4. Create a `.env` file in the root directory and add your Box API credentials:
+4. Create a [.env](http://_vscodecontentref_/0) file in the root directory and add your Box API credentials:
 
 For OAuth
-    ```.env
+    ```
     BOX_CLIENT_ID=your_client_id
     BOX_CLIENT_SECRET=your_client_secret
     BOX_REDIRECT_URL = http://localhost:8000/callback
     ```
 
 For CCG
-    ```.env
+    ```
     BOX_CLIENT_ID=your_client_id
     BOX_CLIENT_SECRET=your_client_secret
     BOX_SUBJECT_TYPE = user # or enterprise

pyproject.toml

@@ -5,7 +5,7 @@ description = "Add your description here"
 readme = "README.md"
 requires-python = ">=3.13"
 dependencies = [
-    "box-ai-agents-toolkit>=0.0.48",
+    "box-ai-agents-toolkit>=0.0.49",
     "fastapi>=0.116.2",
     "mcp[cli]>=1.14.0",
     "python-dotenv>=1.1.1",

src/box_tools_users.py

@@ -0,0 +1,53 @@
+
+from box_ai_agents_toolkit import (
+    box_users_list,
+    box_users_locate_by_name,
+    box_users_locate_by_email,
+    box_users_search_by_name_or_email,
+)
+from mcp.server.fastmcp import Context
+
+from box_tools_generic import get_box_client
+
+
+async def box_users_list_tool(ctx: Context) -> dict:
+    """List all users in the Box account.
+    Args:
+        ctx (Context): The context object containing the request and lifespan context.
+    Returns:
+        dict: A dictionary containing the list of users."""
+    client = get_box_client(ctx)
+    return box_users_list(client)
+
+
+async def box_users_locate_by_name_tool(ctx: Context, name: str) -> dict:
+    """Locate a user by their name. This is an exact match search.
+    Args:
+        ctx (Context): The context object containing the request and lifespan context.
+        name (str): The name of the user to locate.
+    Returns:
+        dict: A dictionary containing the user information if found, otherwise a message with no user found."""
+    client = get_box_client(ctx)
+    return box_users_locate_by_name(client, name)
+
+
+async def box_users_locate_by_email_tool(ctx: Context, email: str) -> dict:
+    """Locate a user by their email address. This is an exact match search.
+    Args:
+        ctx (Context): The context object containing the request and lifespan context.
+        email (str): The email address of the user to locate.
+    Returns:
+        dict: A dictionary containing the user information if found, otherwise a message with no user found."""
+    client = get_box_client(ctx)
+    return box_users_locate_by_email(client, email)
+
+
+async def box_users_search_by_name_or_email_tool(ctx: Context, query: str) -> dict:
+    """Search for users by name or email. This is a partial match search.
+    Args:
+        ctx (Context): The context object containing the request and lifespan context.
+        query (str): The search query to match against user names and email addresses.
+    Returns:
+        dict: A dictionary containing the list of matching users."""
+    client = get_box_client(ctx)
+    return box_users_search_by_name_or_email(client, query)

src/mcp_server_box.py

@@ -54,6 +54,12 @@
     box_metadata_update_instance_on_file_tool,
 )
 from box_tools_search import box_search_folder_by_name_tool, box_search_tool
+from box_tools_users import (
+    box_users_list_tool,
+    box_users_locate_by_email_tool,
+    box_users_locate_by_name_tool,
+    box_users_search_by_name_or_email_tool,
+)
 from server_context import box_lifespan_ccg, box_lifespan_oauth
 
 # Disable all logging
@@ -143,6 +149,12 @@ def register_tools(mcp: FastMCP):
     mcp.tool()(box_metadata_update_instance_on_file_tool)
     mcp.tool()(box_metadata_template_create_tool)
 
+    # User Tools
+    mcp.tool()(box_users_list_tool)
+    mcp.tool()(box_users_locate_by_name_tool)
+    mcp.tool()(box_users_locate_by_email_tool)
+    mcp.tool()(box_users_search_by_name_or_email_tool)
+
 
 if __name__ == "__main__":
     parser = argparse.ArgumentParser(description="Box MCP Server")

tests/test_box_tools_users.py

@@ -0,0 +1,69 @@
+import pytest
+from unittest.mock import MagicMock, patch
+
+from src.box_tools_users import (
+    box_users_list_tool,
+    box_users_locate_by_email_tool,
+    box_users_locate_by_name_tool,
+    box_users_search_by_name_or_email_tool,
+)
+from mcp.server.fastmcp import Context
+
+
+@pytest.mark.asyncio
+async def test_box_users_list_tool():
+    ctx = MagicMock(spec=Context)
+    with (
+        patch("src.box_tools_users.get_box_client") as mock_get_client,
+        patch("src.box_tools_users.box_users_list") as mock_list,
+    ):
+        mock_get_client.return_value = "client"
+        mock_list.return_value = [{"id": "1", "name": "Test User"}]
+        result = await box_users_list_tool(ctx)
+        assert isinstance(result, list)
+        assert result[0]["name"] == "Test User"
+
+
+@pytest.mark.asyncio
+async def test_box_users_locate_by_email_tool():
+    ctx = MagicMock(spec=Context)
+    email = "test@example.com"
+    with (
+        patch("src.box_tools_users.get_box_client") as mock_get_client,
+        patch("src.box_tools_users.box_users_locate_by_email") as mock_locate,
+    ):
+        mock_get_client.return_value = "client"
+        mock_locate.return_value = {"id": "1", "email": email}
+        result = await box_users_locate_by_email_tool(ctx, email)
+        assert isinstance(result, dict)
+        assert result["email"] == email
+
+
+@pytest.mark.asyncio
+async def test_box_users_locate_by_name_tool():
+    ctx = MagicMock(spec=Context)
+    name = "Test User"
+    with (
+        patch("src.box_tools_users.get_box_client") as mock_get_client,
+        patch("src.box_tools_users.box_users_locate_by_name") as mock_locate,
+    ):
+        mock_get_client.return_value = "client"
+        mock_locate.return_value = {"id": "1", "name": name}
+        result = await box_users_locate_by_name_tool(ctx, name)
+        assert isinstance(result, dict)
+        assert result["name"] == name
+
+
+@pytest.mark.asyncio
+async def test_box_users_search_by_name_or_email_tool():
+    ctx = MagicMock(spec=Context)
+    query = "Test"
+    with (
+        patch("src.box_tools_users.get_box_client") as mock_get_client,
+        patch("src.box_tools_users.box_users_search_by_name_or_email") as mock_search,
+    ):
+        mock_get_client.return_value = "client"
+        mock_search.return_value = [{"id": "1", "name": "Test User"}]
+        result = await box_users_search_by_name_or_email_tool(ctx, query)
+        assert isinstance(result, list)
+        assert result[0]["name"] == "Test User"

tests/test_mcp_server_box.py

@@ -4,7 +4,6 @@
 import pytest
 from mcp.server.fastmcp import FastMCP
 
-from mcp_server_box import get_mcp_server
 
 
 @pytest.fixture