# System Architecture OParl Logo FastMCP Logo **Comprehensive overview of the OParl MCP Server architecture** This document shows how FastMCP integrates with the OParl API to provide AI models with structured access to parliamentary data.

High-Level Architecture

graph TB
    subgraph "AI Layer"
        AI[AI Model/Assistant]
        MCP_CLIENT[MCP Client]
    end

    subgraph "MCP Layer"
        MCP_SERVER[OParl MCP Server]
        FASTMCP[FastMCP Framework]
    end

    subgraph "API Layer"
        HTTP_CLIENT[HTTP Client]
        AUTH[Authentication]
    end

    subgraph "Data Layer"
        OPARL_API[OParl API]
        MUNICH[Munich OParl]
        COLOGNE[Cologne OParl]
        HAMBURG[Hamburg OParl]
        GENERIC[Generic OParl]
    end

    AI --> MCP_CLIENT
    MCP_CLIENT --> MCP_SERVER
    MCP_SERVER --> FASTMCP
    FASTMCP --> HTTP_CLIENT
    HTTP_CLIENT --> AUTH
    AUTH --> OPARL_API

    OPARL_API --> MUNICH
    OPARL_API --> COLOGNE
    OPARL_API --> HAMBURG
    OPARL_API --> GENERIC

Component Details

1. AI Model/Assistant

  • Purpose: Consumes parliamentary data via MCP protocol
  • Interface: MCP client protocol
  • Capabilities: Natural language queries, data analysis, report generation

2. MCP Client

  • Purpose: Implements MCP protocol for AI model communication
  • Protocol: Model Context Protocol (MCP)
  • Features: Resource discovery, tool invocation, data streaming

3. OParl MCP Server

  • Purpose: Main server implementation
  • Components: Configuration, authentication, route mapping
  • Features: Multi-tenant support, flexible configuration

4. FastMCP Framework

  • Purpose: OpenAPI to MCP translation
  • Features: Automatic API mapping, type safety, async support
  • Input: OpenAPI specification (oparl_openapi.json)

5. HTTP Client

  • Purpose: HTTP communication with OParl APIs
  • Library: httpx (async HTTP client)
  • Features: Connection pooling, retry logic, timeout handling

6. Authentication

  • Methods: API key, Bearer token, public access
  • Flexibility: Per-implementation configuration
  • Security: Secure credential management

7. OParl API Implementations

  • Munich: https://oparl.muenchen.de
  • Cologne: https://oparl.koeln.de
  • Hamburg: https://oparl.hamburg.de
  • Generic: https://api.oparl.org

Data Flow

1. Query Processing

sequenceDiagram
    participant AI as AI Model
    participant MCP as MCP Client
    participant Server as MCP Server
    participant FastMCP as FastMCP
    participant API as OParl API

    AI->>MCP: Query parliamentary data
    MCP->>Server: MCP request
    Server->>FastMCP: Route to appropriate handler
    FastMCP->>API: HTTP request
    API->>FastMCP: JSON response
    FastMCP->>Server: MCP response
    Server->>MCP: Structured data
    MCP->>AI: Parliamentary information

2. Resource Discovery

sequenceDiagram
    participant AI as AI Model
    participant MCP as MCP Client
    participant Server as MCP Server
    participant FastMCP as FastMCP

    AI->>MCP: List available resources
    MCP->>Server: list_resources()
    Server->>FastMCP: Get resource catalog
    FastMCP->>Server: Resource definitions
    Server->>MCP: Resource list
    MCP->>AI: Available parliamentary data

MCP Component Architecture

Resource Types

graph LR
    subgraph "MCP Resources"
        R1[System Info]
        R2[Body List]
        R3[Meeting List]
        R4[Person List]
        R5[Paper List]
    end

    subgraph "MCP Resource Templates"
        RT1[Meeting Details]
        RT2[Person Profile]
        RT3[Paper Content]
        RT4[Organization Info]
    end

    subgraph "MCP Tools"
        T1[Search]
        T2[Filter]
        T3[Export]
    end

Route Mapping Logic

flowchart TD
    A[HTTP Request] --> B{URL Pattern}
    B -->|/meeting/{id}| C[Resource Template]
    B -->|/meeting| D[Resource]
    B -->|/search| E[Tool]
    B -->|/admin/*| F[Exclude]

    C --> G[Individual Meeting Data]
    D --> H[Meeting Collection]
    E --> I[Search Functionality]
    F --> J[Not Exposed]

Configuration Architecture

Environment-Based Configuration

# Environment Variables
OPARL_BASE_URL: "https://oparl.muenchen.de"
OPARL_API_KEY: "your-api-key"
OPARL_TIMEOUT: 30.0
OPARL_LOG_LEVEL: "INFO"
OPARL_SERVER_NAME: "Munich OParl Server"

Multi-Implementation Support

# Configuration for different implementations
configs = {
    "munich": OParlConfig(
        base_url="https://oparl.muenchen.de",
        api_key="munich-key"
    ),
    "cologne": OParlConfig(
        base_url="https://oparl.koeln.de",
        api_key="cologne-key"
    ),
    "generic": OParlConfig(
        base_url="https://api.oparl.org"
    )
}

Security Architecture

Authentication Flow

sequenceDiagram
    participant Client as MCP Client
    participant Server as MCP Server
    participant Auth as Auth Module
    participant API as OParl API

    Client->>Server: Request with credentials
    Server->>Auth: Validate credentials
    Auth->>API: Test authentication
    API->>Auth: Auth response
    Auth->>Server: Auth result
    Server->>Client: Authorized request

Security Layers

  1. MCP Protocol Security: Encrypted communication
  2. API Authentication: Bearer tokens, API keys
  3. Rate Limiting: Request throttling
  4. Input Validation: Parameter sanitization
  5. Error Handling: Secure error responses

Performance Architecture

Caching Strategy

graph TB
    subgraph "Cache Layers"
        L1[Memory Cache]
        L2[HTTP Cache]
        L3[API Cache]
    end

    subgraph "Cache Policies"
        P1[TTL: 1 hour]
        P2[ETag support]
        P3[Conditional requests]
    end

    L1 --> P1
    L2 --> P2
    L3 --> P3

Connection Pooling

# HTTP connection pooling
client = httpx.AsyncClient(
    limits=httpx.Limits(
        max_keepalive_connections=20,
        max_connections=100
    )
)

Deployment Architecture

Container Deployment

graph TB
    subgraph "Docker Container"
        APP[OParl MCP Server]
        DEPS[Python Dependencies]
        CONFIG[Configuration]
    end

    subgraph "Host System"
        DOCKER[Docker Engine]
        NETWORK[Network Interface]
    end

    subgraph "External Services"
        OPARL[OParl APIs]
        MCP_CLIENT[MCP Clients]
    end

    APP --> DEPS
    APP --> CONFIG
    DOCKER --> APP
    NETWORK --> OPARL
    NETWORK --> MCP_CLIENT

Scaling Considerations

  • Horizontal Scaling: Multiple server instances
  • Load Balancing: Distribute MCP client connections
  • Database: Optional caching layer
  • Monitoring: Health checks and metrics

Error Handling Architecture

Error Propagation

flowchart TD
    A[OParl API Error] --> B[HTTP Client]
    B --> C[FastMCP]
    C --> D[MCP Server]
    D --> E[MCP Client]
    E --> F[AI Model]

    B --> G[Log Error]
    C --> H[Transform Error]
    D --> I[Add Context]
    E --> J[Format Error]

Error Types

  1. Network Errors: Connection timeouts, DNS failures
  2. Authentication Errors: Invalid credentials, expired tokens
  3. API Errors: 404 Not Found, 500 Internal Server Error
  4. Validation Errors: Invalid parameters, malformed requests
  5. Rate Limit Errors: Too many requests, quota exceeded

Monitoring and Observability

Metrics Collection

  • Request Count: Number of MCP requests
  • Response Time: API response latency
  • Error Rate: Failed request percentage
  • Cache Hit Rate: Cache effectiveness
  • Active Connections: Current client count

Logging Strategy

# Structured logging
logger.info(
    "OParl request completed",
    extra={
        "endpoint": "/meeting/123",
        "response_time": 0.245,
        "status_code": 200,
        "client_id": "ai-model-1"
    }
)

Future Architecture Considerations

Planned Enhancements

  1. GraphQL Support: More flexible querying
  2. WebSocket Support: Real-time updates
  3. Batch Operations: Multiple requests in one call
  4. Custom Aggregations: Pre-computed data views
  5. Machine Learning: Predictive analytics

Scalability Improvements

  1. Microservices: Split into smaller services
  2. Message Queues: Async processing
  3. Distributed Caching: Redis/Memcached
  4. API Gateway: Centralized routing
  5. Service Mesh: Advanced networking

Next Steps