1  # MCP Server Examples
  2  
  3  Examples demonstrating the MCP Server v2 features per MCP Protocol Version 2025-11-25.
  4  
  5  ## Features Demonstrated
  6  
  7  ### 1. Pagination (`pagination_example.py`)
  8  
  9  Demonstrates pagination for `tools/list`, `resources/list`, and `prompts/list`:
 10  
 11  - Opaque cursor encoding (base64url)
 12  - Server-determined page size (default: 50, max: 100)
 13  - `nextCursor` for fetching more results
 14  - Cursor validation with JSON-RPC errors
 15  
 16  ```bash
 17  python pagination_example.py
 18  ```
 19  
 20  ### 2. Tool Annotations (`tool_annotations_example.py`)
 21  
 22  Demonstrates MCP 2025-11-25 tool annotation hints:
 23  
 24  - `readOnlyHint`: Tool only reads data
 25  - `destructiveHint`: Tool may have destructive effects
 26  - `idempotentHint`: Safe to call multiple times
 27  - `openWorldHint`: Interacts with external world
 28  
 29  ```bash
 30  python tool_annotations_example.py
 31  ```
 32  
 33  ### 3. CLI Tools (`cli_tools_example.sh`)
 34  
 35  Demonstrates the new CLI commands:
 36  
 37  ```bash
 38  # List tools with pagination
 39  praisonai mcp list-tools --limit 10
 40  praisonai mcp list-tools --cursor <cursor> --json
 41  
 42  # Search tools
 43  praisonai mcp tools search "query"
 44  praisonai mcp tools search --category memory
 45  praisonai mcp tools search --read-only
 46  praisonai mcp tools search --json
 47  
 48  # Get tool info
 49  praisonai mcp tools info <tool-name>
 50  praisonai mcp tools info <tool-name> --json
 51  
 52  # Get tool schema
 53  praisonai mcp tools schema <tool-name>
 54  ```
 55  
 56  ## API Reference
 57  
 58  ### Pagination
 59  
 60  ```python
 61  from praisonai.mcp_server.registry import MCPToolRegistry
 62  
 63  registry = MCPToolRegistry()
 64  # ... register tools ...
 65  
 66  # Get first page
 67  tools, next_cursor = registry.list_paginated(page_size=50)
 68  
 69  # Get next page
 70  if next_cursor:
 71      more_tools, next_cursor = registry.list_paginated(cursor=next_cursor)
 72  ```
 73  
 74  ### Tool Search
 75  
 76  ```python
 77  # Search by query
 78  tools, next_cursor, total = registry.search(query="memory")
 79  
 80  # Filter by category
 81  tools, _, _ = registry.search(category="file")
 82  
 83  # Filter by read-only hint
 84  tools, _, _ = registry.search(read_only=True)
 85  
 86  # Combined filters with pagination
 87  tools, next_cursor, total = registry.search(
 88      query="data",
 89      category="storage",
 90      read_only=True,
 91      page_size=10,
 92  )
 93  ```
 94  
 95  ### Tool Annotations
 96  
 97  ```python
 98  from praisonai.mcp_server.registry import MCPToolDefinition
 99  
100  # Read-only tool
101  tool = MCPToolDefinition(
102      name="data.read",
103      description="Read data",
104      handler=read_handler,
105      input_schema={"type": "object"},
106      read_only_hint=True,
107      destructive_hint=False,
108  )
109  
110  # Destructive tool
111  tool = MCPToolDefinition(
112      name="file.delete",
113      description="Delete file",
114      handler=delete_handler,
115      input_schema={"type": "object"},
116      destructive_hint=True,
117      idempotent_hint=False,
118  )
119  ```
120  
121  ## MCP Protocol Compliance
122  
123  These examples comply with MCP Protocol Version 2025-11-25:
124  
125  - Pagination uses opaque cursors (base64url encoded)
126  - Server determines page size (client cannot override)
127  - Invalid cursors return JSON-RPC error code -32602
128  - Tool annotations follow the spec defaults:
129    - `readOnlyHint`: false
130    - `destructiveHint`: true
131    - `idempotentHint`: false
132    - `openWorldHint`: true