add-mcp-tool

name	add-mcp-tool
description	Use when adding a new MCP tool to the property MCP server (mcp_server/server.py). Provides the exact pattern with a copy-paste template.

Add an MCP Tool

Add a new tool to mcp_server/server.py following the established FastMCP pattern.

Step 1: Add the Tool Function

Add to mcp_server/server.py. The docstring becomes the tool description for AI hosts.

@mcp.tool()
async def new_tool(
    required_param: str,
    optional_param: Optional[str] = None,
    limit: int = 50,
) -> ToolResult:
    """One-line description of what this tool does.

    Args:
        required_param: UK postcode (e.g. "SW1A 1AA")
        optional_param: Optional filter description
        limit: Maximum results (default 50)
    """
    from property_core import SomeService  # Step 2: lazy import

    # Step 3: call property_core (sync → thread)
    result = await anyio.to_thread.run_sync(
        partial(
            SomeService().method,
            param=required_param,
            limit=limit,
        )
    )

    # Step 4: build and return ToolResult
    data = result.model_dump(mode="json")
    summary = f"Found {result.count} items for {required_param}"
    return ToolResult(content=_content(summary, data), structured_content=data)

Key Rules

1. Lazy imports — from property_core import X inside the function body, never at module top level
2. Async wrapping — use anyio.to_thread.run_sync(partial(...)) for sync property_core calls. For already-async functions, just await them directly.
3. ToolResult construction:
   • content = human-readable summary + slimmed JSON (via _content() helper)
   • structured_content = full data dict for programmatic consumers
4. Configuration-gated tools — if the data source needs credentials, check is_configured() and return early with an explanatory message if not configured. See property_epc() for the pattern.

Helpers Available

• _slim(obj) — strips raw, images, floorplans from dicts recursively
• _content(summary, data) — builds content string: summary + "\n\n" + slimmed JSON

Checklist

• Tool added to mcp_server/server.py with @mcp.tool()
• Function is async
• Imports are lazy (inside function body)
• Returns ToolResult with both content and structured_content
• Summary line includes key metrics (count, median, etc.)
• Docstring includes Args: section for all parameters