graph TD
    subgraph AI Host Environment
        Agent[AI Agent / LLM Host<br/>Claude / Cursor / OpenCode / Antigravity]
        ClientTransport[MCP Client Transport]
    end

    subgraph Protheus Research MCP Engine
        StdioTransport[StdioServerTransport<br/>JSON-RPC 2.0]
        Router[Tool Execution Router]
        Cache[In-Memory TTL Cache<br/>600s TTL / Deduplication]
        
        subgraph Toolset [Registered Capabilities]
            T1[search_protheus_docs]
            T2[search_community]
            T3[search_release_notes]
            T4[compare_sources]
            T5[deep_research]
            T6[generate_advpl_example]
            T7[debug_protheus_error]
        end

        Ranker[Source Ranker & Normalizer]
        Heuristic[Error Categorization Matrix]
    end

    subgraph External Technical Knowledge
        TDN[(TOTVS TDN / Central de Atendimento)]
        GH[(Official TOTVS Repositories)]
        COMM[(Recognized Community Portals)]
    end

    Agent <-->|JSON-RPC Tools| ClientTransport
    ClientTransport <-->|stdio stream| StdioTransport
    StdioTransport --> Router
    Router --> Cache
    Router --> Toolset
    T1 & T2 & T3 & T4 & T5 --> Ranker
    T7 --> Heuristic
    Ranker --> TDN & GH & COMM

sequenceDiagram
    autonumber
    actor Engineer as Software Engineer
    participant Agent as AI Agent (Claude / Cursor / Antigravity)
    participant MCP as Protheus Research MCP Server
    participant Cache as In-Memory Cache
    participant Engine as Search & Parser Pipeline
    participant Sources as TDN & Knowledge Portals

    Engineer->>Agent: "Diagnose AppServer error: array out of bounds in U_MYFUNC"
    Agent->>MCP: CallToolRequest("debug_protheus_error", { errorMessage: "...", stackTrace: "..." })
    
    MCP->>Cache: Check cached diagnostic fingerprint
    alt Cache Hit
        Cache-->>MCP: Return cached diagnosis
    else Cache Miss
        MCP->>MCP: Execute heuristic error classification
        MCP->>Engine: Dispatch targeted documentation search
        Engine->>Sources: Query TDN articles & known issues
        Sources-->>Engine: Raw documentation snippets & URLs
        Engine->>MCP: Normalized, relevance-scored references
        MCP->>Cache: Store result (10-minute TTL)
    end

    MCP-->>Agent: CallToolResult(Structured diagnosis, root causes, corrective code)
    Agent-->>Engineer: Synthesizes precise root cause and validated ADVPL patch

// Input Schema
{
  "query": "FWRest",
  "module": "SIGAFAT",
  "version": "12.1.2210"
}

// Sample Output Payload
{
  "results": [
    {
      "title": "FWRest - Framework ADVPL - TDN",
      "url": "https://tdn.totvs.com/display/tec/FWRest",
      "snippet": "Classe para consumo de serviços RESTful em ADVPL, suportando métodos HTTP padronizados, SSL e manipulação de cabeçalhos.",
      "sourceType": "official_tdn",
      "sourceLevel": 1,
      "relevance": 95
    }
  ],
  "totalFound": 12
}

// Input Schema
{
  "errorMessage": "array out of bounds [0] of [1] on U_MYFUNC(MYFUNC.PRW)",
  "stackTrace": "U_MYFUNC (MYFUNC.PRW) 15/08/2026 14:22:01",
  "environment": "Protheus 12.1.2210, SQL Server 2019"
}

// Sample Output Payload
{
  "diagnosis": "Category: Array Bounds. 6 authoritative references located.",
  "probableCauses": [
    "Attempting to read index <= 0 or beyond array length (Len(aArray)).",
    "Empty dataset returned by query/DbSeek without length validation prior to indexing."
  ],
  "verificationSteps": [
    "Inspect AppServer console log for full execution context.",
    "Verify RPO compilation status and dictionary synchronization."
  ],
  "fixes": [
    "Enforce defensive boundary checks using If Len(aData) >= nIndex before accessing aData[nIndex].",
    "Initialize dynamic collections safely using AAdd() or aClone()."
  ]
}

// Input Schema
{
  "language": "advpl",
  "description": "Query customers from SA1 with logic deletion handling and JSON serialization",
  "context": "Faturamento (SIGAFAT)"
}

// Sample Output Payload
{
  "language": "advpl",
  "bestPractices": [
    "Enforce explicit Local variable declarations for predictable memory scope.",
    "Use GetNextAlias() to avoid cursor collisions in concurrent threads.",
    "Apply ChangeQuery() for cross-database portability.",
    "Always verify logical deletion flag (D_E_L_E_T_)."
  ]
}