rag_books_mcp/server.py

"""
MCP Server (transporte stdio): RAG sobre ESL, ISLP, FES y PDSH con ChromaDB.

Expone las 4 tools definidas en `rag_books_mcp.tools` vía FastMCP / stdio.
Ideal para clientes que se conectan vía `uv run python -m rag_books_mcp.server`
(p. ej. configuración local en `~/.kiro/settings/mcp.json`).

Libros indexados:
- ESL  : The Elements of Statistical Learning (Hastie, Tibshirani, Friedman)
- ISLP : An Introduction to Statistical Learning with Python (James, Witten, Hastie, Tibshirani)
- FES  : Feature Engineering and Selection (Kuhn, Johnson)
- PDSH : Python Data Science Handbook (VanderPlas)

Para la variante HF Spaces (Gradio + `mcp_server=True`), ver `rag_books_mcp.app`.
"""

from mcp.server.fastmcp import FastMCP

from rag_books_mcp.tools import (
    cite_foundation as _cite_foundation,
    get_section as _get_section,
    list_available_topics as _list_available_topics,
    search_theory as _search_theory,
)


# --- MCP Server ---
mcp = FastMCP(
    "rag-books-mcp",
    instructions=(
        "RAG sobre los libros ESL (The Elements of Statistical Learning), "
        "ISLP (Introduction to Statistical Learning with Python), "
        "FES (Feature Engineering and Selection) y "
        "PDSH (Python Data Science Handbook). "
        "Permite buscar teoría, obtener secciones específicas y citar fundamentos."
    ),
)


# Re-export las tools como funciones de módulo (las usa el smoke test).
# El decorador @mcp.tool() las registra además en el servidor MCP stdio.
@mcp.tool()
def search_theory(query: str, book: str = "all", top_k: int = 5) -> str:
    """Busca fragmentos relevantes en ESL/ISLP/FES/PDSH usando búsqueda semántica.

    Args:
        query: Consulta en lenguaje natural (ej: "bias-variance tradeoff").
        book: "esl", "islp", "fes", "pdsh", "both" (ESL+ISLP) o "all" (los 4, default).
        top_k: Número de resultados (1-10, default: 5).
    """
    return _search_theory(query=query, book=book, top_k=top_k)


@mcp.tool()
def get_section(book: str, chapter: str, section: str = "", max_chunks: int = 5) -> str:
    """Recupera una sección específica de ESL, ISLP, FES o PDSH por referencia exacta.

    Args:
        book: "esl", "islp", "fes" o "pdsh".
        chapter: Nombre del capítulo (búsqueda parcial soportada).
        section: Nombre de la sección dentro del capítulo (opcional).
        max_chunks: Máximo de chunks a devolver (default: 5).
    """
    return _get_section(book=book, chapter=chapter, section=section, max_chunks=max_chunks)


@mcp.tool()
def cite_foundation(topic: str, detail_level: str = "medium") -> str:
    """Fundamentación teórica de un tema citando los libros (ESL + ISLP + FES + PDSH).

    Args:
        topic: Tema a fundamentar (ej: "ridge regression", "feature engineering").
        detail_level: "brief", "medium" (default) o "deep".
    """
    return _cite_foundation(topic=topic, detail_level=detail_level)


@mcp.tool()
def list_available_topics() -> str:
    """Lista los capítulos y temas indexados en la base de conocimiento."""
    return _list_available_topics()


def main():
    """Punto de entrada del MCP server (stdio)."""
    mcp.run(transport="stdio")


if __name__ == "__main__":
    main()