# microsoft/fabric-rti-mcp architecture

> Architecture diagram of the GitHub repository microsoft/fabric-rti-mcp, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-08-25). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/microsoft/fabric-rti-mcp
- Repository: https://github.com/microsoft/fabric-rti-mcp

## Overview

##### Project Type & Purpose
- Type: Full-stack Python MCP server (Model Context Protocol)
- Purpose: Acts as a bridge between AI agents (e.g., in VS Code via the UV/UVX tool) and Microsoft Fabric Real-Time Intelligence services. Exposes Fabric RTI tooling (Kusto/Eventstreams) over the MCP interface.

##### Key Components
1. Client Layer
– AI Agent / VS Code extension (UV/UVX)
- Sends MCP requests (JSON RPC)
- Receives tool responses
2. MCP Server (fabric_rti_mcp/server.py)
– Protocol Handler
- Parses incoming MCP messages
- Dispatches calls to tool implementations
3. Tool Modules
A. Kusto Tools (fabric_rti_mcp/kusto/*.py)
- kusto_service.py: Orchestrates Kusto operations
- kusto_connection.py: Manages low-level ADX/Eventhouse REST or SDK calls
- kusto_response_formatter.py: Normalizes Kusto results for MCP
- kusto_tools.py: Exposes individual “tools” (kusto_query, kusto_list_databases, etc.)
B. Eventstream Tools (fabric_rti_mcp/eventstream/*.py)
- eventstream_service.py: Business logic for listing and describing Eventstreams
- eventstream_connection.py: Handles HTTP/SDK calls to the Microsoft Fabric Eventstream API
- eventstream_tools.py: Exposes MCP tools (list_eventstreams, get_eventstream, etc.)
4. Common Utilities (fabric_rti_mcp/common.py)
– Shared helpers, error handling, configuration loading
5. Infrastructure & Configuration
– Environment variables (KUSTO_SERVICE_URI, AZ_OPENAI_EMBEDDING_ENDPOINT, etc.)
– Azure Identity (DefaultAzureCredential) for secure auth
– pyproject.toml / setup.cfg for packaging
– scripts/ and Makefile for local build/deploy

##### External Systems
- Microsoft Fabric RTI
– Eventhouse (Azure Data Explorer / Kusto)
– Eventstreams service
- Azure Identity Endpoints (for authentication)
- (Optional) Azure OpenAI embeddings endpoint for semantic-search shots

##### Relationships & Data Flows
1. The AI Agent issues a tool request (e.g., “kusto_query”) → MCP Server
2. MCP Server’s Protocol Handler → Appropriate tool in kusto_tools.py or eventstream_tools.py
3. Tool calls its Service (e.g., KustoService) → Service calls its Connection (KustoConnection)
4. Connection uses Azure SDK/REST → Fabric RTI service → returns raw response
5. Service passes data to ResponseFormatter → structured result
6. Protocol Handler wraps result → returns to AI Agent

##### Architectural Patterns & Principles
- Layered Architecture
– Protocol Layer → Tool Layer → Service Layer → Connection Layer → External API
- Separation of Concerns
– Each tool focuses on one Fabric RTI capability
– Service vs. Connection vs. Formatting are distinct
- Dependency Injection via environment variables & config files
- Plug-in style: new services (e.g., “Activator”) can be added under fabric_rti_mcp/

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Client Layer
    AI["AI Agent / VS Code Extension"]:::client
    AI -->|Invoke MCP Request| Server

    %% Server Layer
    Server["Protocol Handler\n(server.py)"]:::server
    Server -->|Dispatch to Tool| KustoTools
    Server -->|Dispatch to Tool| EventTools
    Server -->|Uses Utilities| Common

    %% Tools Layer
    subgraph "Kusto Tool Module" 
        direction TB
        KustoTools["KustoTools\n(kusto_tools.py)"]:::tools
        KustoTools -->|Calls| KustoService
        KustoTools -->|Loads Config| KustoConfig
    end

    subgraph "Eventstream Tool Module"
        direction TB
        EventTools["EventstreamTools\n(eventstream_tools.py)"]:::tools
        EventTools -->|Calls| EventService
    end

    %% Service Layer
    subgraph "Service Layer"
        direction TB
        KustoService["KustoService\n(kusto_service.py)"]:::service
        EventService["EventstreamService\n(eventstream_service.py)"]:::service
        KustoService -->|Formats Response| KustoFormatter
        KustoService -->|Uses Connection| KustoConnection
        EventService -->|Uses Connection| EventConnection
    end

    %% Formatter Layer
    KustoFormatter["KustoResponseFormatter\n(kusto_response_formatter.py)"]:::service

    %% Connection Layer
    subgraph "Connection Layer"
        direction TB
        KustoConnection["KustoConnection\n(kusto_connection.py)"]:::connection
        EventConnection["EventstreamConnection\n(eventstream_connection.py)"]:::connection
        KustoConnection -->|Azure SDK/REST| FabricKusto
        EventConnection -->|Azure SDK/REST| FabricEventstreams
        AzureIdentity["Azure Identity Endpoint"]:::external
        AzureIdentity -->|Provides Credential| KustoConnection
        AzureIdentity -->|Provides Credential| EventConnection
    end

    %% External Systems
    FabricKusto["Fabric RTI - Kusto"]:::external
    FabricEventstreams["Fabric RTI - Eventstreams"]:::external
    OpenAI["Azure OpenAI Embeddings"]:::external
    KustoConnection -->|Optional Semantic Search| OpenAI

    %% Common Utilities
    Common["Common Utilities\n(common.py)"]:::utils

    %% Configuration & Packaging
    subgraph "Config & Packaging"
        direction TB
        Pyproject["pyproject.toml"]:::config
        SetupCfg["setup.cfg"]:::config
        Makefile["Makefile"]:::config
        BuildLocalSH["build_deploy_local.sh"]:::config
        BuildLocalBAT["build_deploy_local.bat"]:::config
        FmtSH["fmt.sh"]:::config
        FmtBAT["fmt.bat"]:::config
    end

    %% Tests
    subgraph "Tests (Kusto)"
        direction TB
        Conftest["conftest.py"]:::config
        TestTimeout["test_global_timeout.py"]:::config
        TestService["test_kusto_service.py"]:::config
    end

    %% Data Flow Back to Client
    FabricKusto -->|Return Raw Data| KustoConnection
    FabricEventstreams -->|Return Raw Data| EventConnection
    KustoFormatter -->|Return Formatted| KustoService
    EventService -->|Return Result| Server
    KustoService -->|Return Result| Server
    Server -->|Return MCP Response| AI

    %% Click Events
    click Server "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/server.py"
    click Common "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/common.py"
    click KustoTools "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/kusto/kusto_tools.py"
    click KustoConfig "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/kusto/kusto_config.py"
    click KustoConnection "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/kusto/kusto_connection.py"
    click KustoService "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/kusto/kusto_service.py"
    click KustoFormatter "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/kusto/kusto_response_formatter.py"
    click EventTools "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/eventstream/eventstream_tools.py"
    click EventConnection "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/eventstream/eventstream_connection.py"
    click EventService "https://github.com/microsoft/fabric-rti-mcp/blob/main/fabric_rti_mcp/eventstream/eventstream_service.py"
    click Pyproject "https://github.com/microsoft/fabric-rti-mcp/blob/main/pyproject.toml"
    click SetupCfg "https://github.com/microsoft/fabric-rti-mcp/blob/main/setup.cfg"
    click Makefile "https://github.com/microsoft/fabric-rti-mcp/tree/main/makefile"
    click BuildLocalSH "https://github.com/microsoft/fabric-rti-mcp/blob/main/scripts/build_deploy_local.sh"
    click BuildLocalBAT "https://github.com/microsoft/fabric-rti-mcp/blob/main/scripts/build_deploy_local.bat"
    click FmtSH "https://github.com/microsoft/fabric-rti-mcp/blob/main/scripts/fmt.sh"
    click FmtBAT "https://github.com/microsoft/fabric-rti-mcp/blob/main/scripts/fmt.bat"
    click Conftest "https://github.com/microsoft/fabric-rti-mcp/blob/main/tests/kusto/conftest.py"
    click TestTimeout "https://github.com/microsoft/fabric-rti-mcp/blob/main/tests/kusto/test_global_timeout.py"
    click TestService "https://github.com/microsoft/fabric-rti-mcp/blob/main/tests/kusto/test_kusto_service.py"

    %% Styles
    classDef client fill:#a2f5a2,stroke:#333
    classDef server fill:#add8e6,stroke:#333
    classDef tools fill:#87cefa,stroke:#333
    classDef service fill:#b0e0e6,stroke:#333
    classDef connection fill:#b0e0e6,stroke:#333,stroke-dasharray: 5 5
    classDef external fill:#fff2cc,stroke:#333
    classDef utils fill:#d3d3d3,stroke:#333
    classDef config fill:#eeeeee,stroke:#333
```
