"""
MCP server creation and configuration for REM.

Design Pattern 
1. Create FastMCP server with tools and resources
2. Register tools using @mcp.tool() decorator
3. Register resources using resource registration functions
4. Mount on FastAPI at /api/v1/mcp
5. Support both HTTP and SSE transports

Key Concepts:
- Tools: Functions LLM can call (search, query, parse, etc.)
- Resources: Read-only data sources (entity lookups, schema docs, etc.)
- Instructions: System-level guidance for LLM on how to use MCP server

FastMCP Features:
- Stateless HTTP mode (stateless_http=True) prevents stale session errors
- Path="/" creates routes at root, then mount at custom path
- Built-in auth that can be disabled for testing
"""

from fastmcp import FastMCP

from ...settings import settings


def create_mcp_server(is_local: bool = False) -> FastMCP:
    """
    Create and configure the REM MCP server with all tools and resources.

    Args:
        is_local: True if running as local/stdio server (enables file ingestion from local paths)

    Returns:
        Configured FastMCP server instance

    Usage Modes:
        # Stdio mode (for local dev / Claude Desktop)
        mcp = create_mcp_server(is_local=True)
        mcp.run(transport="stdio")

        # HTTP mode (for production / API)
        mcp = create_mcp_server(is_local=False)
        mcp_app = mcp.http_app(path="/", transport="http", stateless_http=True)
        # Then mount: app.mount("/api/v1/mcp", mcp_app)

    Design Pattern
    - Instructions provide LLM guidance on workflow
    - Tools implement specific operations
    - Resources provide read-only access to data
    - All modular and testable
    """
    mcp = FastMCP(
        name=f"REM MCP Server ({settings.team}/{settings.environment})",
        version="0.1.0",
        instructions=(
            "REM (Resource-Entity-Moment) MCP Server - Unified memory infrastructure for agentic systems.\n\n"
            "═══════════════════════════════════════════════════════════════════════════\n"
            "REM QUERY WORKFLOW - Schema-Agnostic Natural Language Queries\n"
            "═══════════════════════════════════════════════════════════════════════════\n"
            "\n"
            "**IMPORTANT:** REM uses natural language labels, NOT UUIDs. You query with:\n"
            "- LOOKUP \"Sarah Chen\" (what user knows)\n"
            "- NOT LOOKUP \"sarah-chen-uuid-1234\" (internal ID)\n"
            "\n"
            "REM Query Types:\n"
            "\n"
            "1. LOOKUP - O(1) entity resolution across ALL tables\n"
            "   Example: LOOKUP \"Sarah Chen\"\n"
            "   Returns: All entities named \"Sarah Chen\" (resources, moments, users)\n"
            "\n"
            "2. FUZZY - Indexed fuzzy text matching\n"
            "   Example: FUZZY \"sara\" threshold=0.7\n"
            "   Returns: \"Sarah Chen\", \"Sara Martinez\", etc.\n"
            "\n"
            "3. SEARCH - Semantic vector search (table-specific)\n"
            "   Example: SEARCH \"database migration\" table=resources\n"
            "   Returns: Semantically similar resources\n"
            "\n"
            "4. SQL - Direct table queries with WHERE clauses\n"
            "   Example: SQL table=moments WHERE moment_type='meeting'\n"
            "   Returns: All meeting moments\n"
            "\n"
            "5. TRAVERSE - Multi-hop graph traversal\n"
            "   Example: TRAVERSE manages WITH LOOKUP \"Sally\" DEPTH 2\n"
            "   Returns: Sally + her team hierarchy\n"
            "\n"
            "═══════════════════════════════════════════════════════════════════════════\n"
            "ITERATED RETRIEVAL PATTERN - Multi-Turn Exploration\n"
            "═══════════════════════════════════════════════════════════════════════════\n"
            "\n"
            "REM is designed for multi-turn exploration, not single-shot queries:\n"
            "\n"
            "Turn 1: Find entry point\n"
            "  LOOKUP \"Sarah Chen\"\n"
            "  → Found person entity with 3 graph edges\n"
            "\n"
            "Turn 2: Analyze neighborhood (PLAN mode - depth 0)\n"
            "  ask_rem(\"What are Sarah Chen's connections?\", plan_mode=True)\n"
            "  → Agent uses TRAVERSE with max_depth=0\n"
            "  → Edge summary: manages(2), authored_by(15), mentors(3)\n"
            "\n"
            "Turn 3: Selective traversal\n"
            "  ask_rem(\"Show Sarah Chen's team hierarchy\")\n"
            "  → Agent uses TRAVERSE with rel_type=\"manages\", max_depth=2\n"
            "  → Returns: Sarah + team hierarchy (depth 2)\n"
            "\n"
            "Turn 4: Follow reference chain\n"
            "  TRAVERSE references,builds-on WITH LOOKUP \"api-design-v2\" DEPTH 1\n"
            "  → Returns: Design lineage\n"
            "\n"
            "**Key Concepts:**\n"
            "- Depth 0 = PLAN mode (analyze edges without traversal)\n"
            "- Depth 1+ = Full traversal with cycle detection\n"
            "- Plan memo = Agent scratchpad for multi-turn tracking\n"
            "- Edge filters = Selective relationship types\n"
            "\n"
            "═══════════════════════════════════════════════════════════════════════════\n"
            "AVAILABLE TOOLS\n"
            "═══════════════════════════════════════════════════════════════════════════\n"
            "\n"
            "• rem_query - Execute REM queries (LOOKUP, FUZZY, SEARCH, SQL, TRAVERSE)\n"
            "• ask_rem - Natural language to REM query conversion\n"
            "  - plan_mode=True: Hints agent to use TRAVERSE with depth=0 for edge analysis\n"
            "• parse_and_ingest_file - Ingest files from local paths (local server only), s3://, or https://\n"
            "\n"
            "═══════════════════════════════════════════════════════════════════════════\n"
            "AVAILABLE RESOURCES (Read-Only)\n"
            "═══════════════════════════════════════════════════════════════════════════\n"
            "\n"
            "Schema Information:\n"
            "• rem://schema/entities - Entity schemas (Resource, Message, User, File, Moment)\n"
            "• rem://schema/query-types - REM query type documentation\n"
            "\n"
            "Agent Schemas:\n"
            "• rem://agents - List available agent schemas with descriptions and usage\n"
            "\n"
            "File Operations:\n"
            "• rem://files/presigned-url - Generate presigned S3 URLs for file download\n"
            "\n"
            "System Status:\n"
            "• rem://status - System health and statistics\n"
            "\n"
            "**Quick Start:**\n"
            "1. User: \"Who is Sarah?\"\n"
            "   → Call: search_rem(query_type=\"lookup\", entity_key=\"Sarah\", user_id=\"...\")\n"
            "\n"
            "2. User: \"Find documents about database migration\"\n"
            "   → Call: search_rem(query_type=\"search\", query_text=\"database migration\", table=\"resources\", user_id=\"...\")\n"
            "\n"
            "3. User: \"Who reports to Sally?\"\n"
            "   → Call: search_rem(query_type=\"traverse\", initial_query=\"Sally\", edge_types=[\"reports-to\"], depth=2, user_id=\"...\")\n"
            "\n"
            "4. User: \"Show me Sarah's org chart\" (Multi-turn example)\n"
            "   → Turn 1: search_rem(query_type=\"lookup\", entity_key=\"Sarah\", user_id=\"...\")\n"
            "   → Turn 2: search_rem(query_type=\"traverse\", initial_query=\"Sarah\", depth=0, user_id=\"...\")  # PLAN mode\n"
            "   → Turn 3: search_rem(query_type=\"traverse\", initial_query=\"Sarah\", edge_types=[\"manages\", \"reports-to\"], depth=2, user_id=\"...\")\n"
            "\n"
            "5. User: \"What did we discuss last week about the TiDB migration?\"\n"
            "   → Call: ask_rem_agent(query=\"What did we discuss last week about the TiDB migration?\", user_id=\"...\")\n"
            "\n"
            "6. User: \"Ingest this PDF file\"\n"
            "   → Call: ingest_into_rem(file_uri=\"s3://bucket/file.pdf\", user_id=\"...\")\n"
        ),
    )

    # Register REM tools
    from .tools import ask_rem_agent, ingest_into_rem, read_resource, search_rem

    mcp.tool()(search_rem)
    mcp.tool()(ask_rem_agent)
    mcp.tool()(read_resource)

    # File ingestion tool (with local path support for local servers)
    # Wrap to inject is_local parameter
    from functools import wraps

    @wraps(ingest_into_rem)
    async def ingest_into_rem_wrapper(
        file_uri: str,
        user_id: str | None = None,
        category: str | None = None,
        tags: list[str] | None = None,
    ):
        return await ingest_into_rem(
            file_uri=file_uri,
            user_id=user_id,
            category=category,
            tags=tags,
            is_local_server=is_local,
        )

    mcp.tool()(ingest_into_rem_wrapper)

    # Register prompts
    from .prompts import register_prompts

    register_prompts(mcp)

    # Register schema resources
    from .resources import (
        register_agent_resources,
        register_file_resources,
        register_schema_resources,
        register_status_resources,
    )

    register_schema_resources(mcp)
    register_agent_resources(mcp)
    register_file_resources(mcp)
    register_status_resources(mcp)

    return mcp
