list_items
Retrieve and filter items with pagination support to manage large datasets efficiently. Use optional name filters to find specific items quickly.
Instructions
List all items with optional filtering and pagination.
Args: page: Page number (1-indexed) page_size: Number of items per page filter_name: Optional filter by name (case-insensitive contains)
Returns: A dictionary containing: - items: List of item objects - total: Total number of items matching the filter - page: Current page number - page_size: Number of items per page
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| page_size | No | ||
| filter_name | No |
Output Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
No arguments | |||
Implementation Reference
- src/skeleton_mcp/api/example.py:39-78 (handler)The handler function implementing the list_items tool logic, supporting pagination, filtering, and returning structured item data using mock data.
async def list_items( page: int = 1, page_size: int = 10, filter_name: str | None = None, ) -> dict[str, Any]: """ List all items with optional filtering and pagination. Args: page: Page number (1-indexed) page_size: Number of items per page filter_name: Optional filter by name (case-insensitive contains) Returns: A dictionary containing: - items: List of item objects - total: Total number of items matching the filter - page: Current page number - page_size: Number of items per page """ # In a real implementation: # client = get_client() # return client.get("items", params={"page": page, "page_size": page_size}) items = list(MOCK_ITEMS.values()) if filter_name: items = [i for i in items if filter_name.lower() in i["name"].lower()] total = len(items) start = (page - 1) * page_size end = start + page_size items = items[start:end] return { "items": items, "total": total, "page": page, "page_size": page_size, } - src/skeleton_mcp/server.py:89-89 (registration)The registration of the list_items tool by applying the mcp.tool() decorator to example.list_items.
mcp.tool()(example.list_items) - Mock data structure used by the list_items handler to simulate item storage.
MOCK_ITEMS: dict[str, dict[str, Any]] = { "item-1": { "id": "item-1", "name": "Example Item 1", "description": "This is a sample item", "created_at": "2024-01-01T00:00:00Z", "updated_at": "2024-01-01T00:00:00Z", }, "item-2": { "id": "item-2", "name": "Example Item 2", "description": "Another sample item", "created_at": "2024-01-02T00:00:00Z", "updated_at": "2024-01-02T00:00:00Z", }, }