# chronulusai/chronulus-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/chronulusai/chronulus-mcp
- Repository: https://github.com/chronulusai/chronulus-mcp

## Overview

Based on reviewing the provided file structure and README, this project is a Python-based server – the “MCP Server for Chronulus” – that integrates Chronulus AI forecasting and prediction agents with Claude. It can be run directly via a Python module (or via a Docker image/uvx command), and even includes frontend assets (HTML and React components) for rendering visual elements such as binary prediction analysis and scorecards.

##### Main Components
- MCP Server Core:
– The core logic lives under src/chronulus_mcp. This includes the __main__.py file that enables the application to be run as a module.
– The core is responsible for initializing and managing components.
- Agent Subsystem:
– Found in src/chronulus_mcp/agent. Contains predictor.py, forecaster.py, and type definitions (_types.py) that encapsulate the forecasting/prediction logic.
- Assets and Frontend Components:
– Located under src/chronulus_mcp/_assets. There are HTML files (for static displays) and React components (BetaPlot.jsx, Scorecard.jsx) for dynamic visualizations.
- Session, IO, and Stats Modules:
– Session management (src/chronulus_mcp/session.py) handles client or connection sessions.
– IO utilities (src/chronulus_mcp/io.py) manage input/output operations.
– Stats and analytics components (src/chronulus_mcp/stats)―e.g., odds calculations―support forecast analysis.
- Deployment and Configuration Interface:
– Dockerfile, pyproject.toml, requirements.txt, and uv.lock files indicate various deployment strategies.
- External Integrations:
– The README suggests integration with third-party servers (like filesystem, fetch) via Claude’s configuration.
– The command configuration examples (using docker, uvx, or pip) show that the server is meant to be an external “agent” accessible via defined commands.

##### Depicting Relationships and Interactions
- Inside the core, show distinct modules for:
– Agent Management: where forecasting and prediction logic happens.
– Session Manager: to track and manage active sessions.
– IO Handler: for reading from/writing to external systems.
– Stats Processor: to compute and analyze odds or other performance metrics.
- Front-end assets separately:
- An “External Configuration/Integration” area:
– Outline how different deployment options (Python, Docker, uvx) fit in.
– Mark dependencies on third-party servers such as filesystem and fetch which show up in the Claude config.
– For instance, from incoming requests (via the CLI or Docker container) to the server, then to the Agent subsystem.

##### Architectural Patterns and Design Principles
- Separation of Concerns:
– Modular design is reflected by distinct directories for agents, session handling, IO, and stats.
- Extensibility:
– The use of react components and HTML assets enables a flexible front-end display.
- Containerization & Deployment Flexibility:
– The inclusion of Dockerfile and alternative methods (pip, uvx) emphasize that the server is intended to be deployed in various environments.
- Integration Strategy:
– Clear external service communication protocols are outlined in the README (i.e., integration with filesystem and fetch servers).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Configuration & Deployment Layer
    subgraph "External Configuration & Deployment"
        DC("Dockerfile/pyproject.toml/requirements.txt/uv.lock"):::config
    end

    %% Client Initiation
    Client("Claude Desktop"):::client

    %% MCP Server Core and its Components
    Core("MCP Server Core"):::core
    Agent("Agent Module"):::agent
    Session("Session Manager"):::session
    IO("IO Utilities"):::io
    Stats("Stats Processor"):::stats

    %% Frontend Assets
    Assets("Frontend Assets (HTML/React)"):::assets

    %% External Integrations
    Ext("External Integrations (Filesystem,Fetch)"):::external

    %% Data Flow/Relationships
    Client -->|"sends_config_commands"| DC
    DC -->|"launches_server"| Core

    Core -->|"initializes"| Agent
    Core -->|"manages"| Session
    Core -->|"delegates_IO"| IO
    Core -->|"analyzes_data"| Stats

    Core -->|"sends_UI_data"| Assets
    Ext -->|"interfaces_with"| Core
    Assets -->|"renders_output"| Client

    %% Click Events for Mapped Components
    click Core "https://github.com/chronulusai/chronulus-mcp/tree/main/src/chronulus_mcp"
    click Agent "https://github.com/chronulusai/chronulus-mcp/tree/main/src/chronulus_mcp/agent"
    click Assets "https://github.com/chronulusai/chronulus-mcp/tree/main/src/chronulus_mcp/_assets"
    click Session "https://github.com/chronulusai/chronulus-mcp/blob/main/src/chronulus_mcp/session.py"
    click IO "https://github.com/chronulusai/chronulus-mcp/blob/main/src/chronulus_mcp/io.py"
    click Stats "https://github.com/chronulusai/chronulus-mcp/tree/main/src/chronulus_mcp/stats"

    %% Styles
    classDef core fill:#f9c,stroke:#333,stroke-width:2px;
    classDef agent fill:#ccf,stroke:#333,stroke-width:2px;
    classDef session fill:#cfc,stroke:#333,stroke-width:2px;
    classDef io fill:#fcf,stroke:#333,stroke-width:2px;
    classDef stats fill:#cff,stroke:#333,stroke-width:2px;
    classDef assets fill:#ffc,stroke:#333,stroke-width:2px;
    classDef config fill:#eef,stroke:#333,stroke-width:2px;
    classDef client fill:#efe,stroke:#333,stroke-width:2px;
    classDef external fill:#fee,stroke:#333,stroke-width:2px;
```
