backend/mcp_server/tools/candidate_query.py

from __future__ import annotations

from fastmcp import FastMCP

from core.db import SessionLocal
from services.candidate_service import CandidateService


def register(mcp: FastMCP) -> None:
    candidate_service = CandidateService()

    @mcp.tool()
    def candidate_metadata_query(query: str, limit: int = 10) -> dict:
        """Query candidate metadata from SQLite using keyword matching."""
        with SessionLocal() as db:
            rows = candidate_service.search_candidates(db=db, query=query, limit=limit)

        if not rows:
            return {
                "status": "no_results",
                "message": "No metadata matches found in SQLite.",
                "results": [],
            }

        ui_payload = candidate_service.build_genui_payload(query=query, candidates=rows)
        return {
            "status": "success",
            "count": len(ui_payload.get("cards") or []),
            "results": ui_payload.get("cards") or [],
            "ui": ui_payload,
        }