Cursor rule

1---
2description: MCP tool implementation pattern and structure
3globs: ["src/tools/**/*.py"]
4alwaysApply: true
5---
6 
7# MCP Tool Implementation Pattern
8 
9Every MCP tool should follow this structure:
10 
11```python
12from typing import Optional, Literal
13from pydantic import BaseModel, Field
14from fastmcp import FastMCP
15 
16mcp = FastMCP("UniFi MCP Server")
17 
18@mcp.tool()
19async def tool_name(
20    # Required parameters first
21    site_id: str,
22    resource_id: str,
23 
24    # Optional parameters with defaults
25    optional_param: Optional[str] = None,
26 
27    # Safety parameters for mutating operations
28    confirm: bool = False,
29    dry_run: bool = False
30) -> dict:
31    """
32    Clear, concise description of what the tool does.
33 
34    Args:
35        site_id: Always include site_id for multi-site support
36        resource_id: Specific resource identifier
37        optional_param: Description of optional parameter
38        confirm: REQUIRED True for mutating operations (safety)
39        dry_run: Preview changes without applying them
40 
41    Returns:
42        Dictionary with operation results. Specify structure.
43 
44    Raises:
45        MCPError: For all MCP-specific errors
46        ValueError: For invalid inputs
47        UniFiConnectionError: For API connection issues
48    """
49    # 1. Input validation
50    if not site_id:
51        raise ValueError("site_id is required")
52 
53    # 2. Safety checks for mutating operations
54    if not confirm and not dry_run:
55        raise MCPError("This operation requires confirm=True")
56 
57    # 3. Audit logging
58    logger.info(
59        f"tool_name: site={site_id}, id={resource_id}, dry_run={dry_run}",
60        extra={"operation": "tool_name", "site_id": site_id}
61    )
62 
63    # 4. Dry-run mode
64    if dry_run:
65        preview = await generate_preview(site_id, resource_id)
66        return {"status": "preview", "changes": preview}
67 
68    # 5. Execute operation
69    try:
70        result = await execute_operation(site_id, resource_id)
71    except UniFiAPIError as e:
72        logger.error(f"Operation failed: {e}")
73        raise MCPError(f"Failed to execute operation: {str(e)}")
74 
75    # 6. Cache invalidation (if applicable)
76    if result.get("success"):
77        await cache.invalidate(f"resource:{site_id}")
78 
79    # 7. Return structured result
80    return {
81        "status": "success",
82        "resource_id": resource_id,
83        "data": result
84    }
85```
86 
87## MCP-Specific Guidelines
88 
89- Use `@mcp.tool()` decorator for tool definitions
90- Use `@mcp.resource()` decorator for resource endpoints
91- Always include `site_id` for multi-site support
92- Implement proper error handling with custom exceptions
93- Return structured dictionaries for consistency
94