CME Prediction Markets MCP Server

# Project Documentation This document provides a comprehensive overview of the project structure and the purpose of each file within the CME Prediction Markets MCP Server. ## Project Tree ``` . |-- Dockerfile |-- README.md |-- docker-compose.yml |-- poetry.lock |-- pyproject.toml |-- scripts | `-- init_db.py |-- src | |-- api | | |-- health_routes.py | | `-- mcp_routes.py | |-- config.py | |-- data | | |-- ingestion | | | |-- fetcher.py | | | `-- parser.py | | |-- models | | | |-- __init__.py | | | |-- contracts.py | | | |-- database.py | | | |-- settlements.py | | | `-- trades.py | | `-- storage | | |-- cache.py | | `-- repository.py | |-- integrations | | |-- slack | | | |-- blocks.py | | | |-- bot.py | | | |-- commands.py | | | `-- events.py | | `-- workflows | | `-- tasks.py | |-- main.py | |-- mcp | | |-- server.py | | `-- tools | | |-- __init__.py | | |-- get_contract_info.py | | |-- query_trading_data.py | | `-- verify_claim.py | |-- utils | | `-- logger.py | `-- verification | |-- logic | | `-- evaluator.py | |-- nlp | | |-- claim_parser.py | | `-- temporal_parser.py | |-- query | | `-- executor.py | `-- reporting | `-- formatter.py `-- tests `-- verification |-- logic | `-- test_claim_evaluator.py `-- nlp |-- test_claim_parser.py `-- test_temporal_parser.py ``` ## File Explanations ### Root Directory - **`Dockerfile`**: Defines the instructions for building the Docker image for the application. It installs dependencies, copies the application code, and specifies the command to run the application. - **`README.md`**: The main project README file, providing a high-level overview of the project, features, and instructions for getting started. - **`docker-compose.yml`**: A Docker Compose file for orchestrating the multi-container application, including the main app, PostgreSQL database, Redis cache, and Celery workers. - **`poetry.lock`**: The lock file generated by Poetry, which ensures deterministic builds by pinning the exact versions of all project dependencies. - **`pyproject.toml`**: The project's configuration file, used by Poetry to manage dependencies, project metadata, and tool configurations (like pytest). ### `scripts/` - **`init_db.py`**: A script to initialize the database with the required tables and, optionally, seed it with sample data. ### `src/` This directory contains the main source code for the application. #### `src/api/` - **`health_routes.py`**: Defines API endpoints for health checks (`/health`) and readiness checks (`/ready`), which are crucial for monitoring the application's status in a containerized environment. - **`mcp_routes.py`**: Defines the main API endpoint (`/mcp/messages`) for handling requests that adhere to the Model Context Protocol. #### `src/data/` This module is responsible for all data-related concerns, including ingestion, database models, and storage. - **`ingestion/`**: - `fetcher.py`: Contains the `CMEDataFetcher` class, which is responsible for fetching raw data from the CME Group's data source with retry logic. - `parser.py`: Contains the `CMEDataParser` class for parsing and validating the raw CSV data fetched from the CME Group. - **`models/`**: - `__init__.py`: Makes the database models easily importable from other parts of the application. - `contracts.py`: Defines the `Contract` SQLAlchemy model, representing a prediction market contract. - `database.py`: Sets up the asynchronous database connection using SQLAlchemy and provides a `get_db` dependency for use in the application. - `settlements.py`: Defines the `Settlement` SQLAlchemy model, representing the settlement of a contract. - `trades.py`: Defines the `Trade` SQLAlchemy model, representing a single trade in a prediction market. - **`storage/`**: - `cache.py`: Implements a `RedisCache` class, providing a caching layer for the application to reduce database load and improve performance. - `repository.py`: Implements the repository pattern, providing a clean and abstracted interface for interacting with the database models. #### `src/integrations/` - **`slack/`**: - `blocks.py`: A utility for formatting verification results into Slack's Block Kit UI framework for rich, interactive messages. - `bot.py`: Implements the `SlackBot` class, which connects to Slack using Socket Mode and handles incoming events and commands. - `commands.py`: A placeholder for handling Slack slash commands. - `events.py`: Logic for handling Slack events, such as app mentions, to trigger the claim verification process. - **`workflows/`**: - `tasks.py`: Defines the Celery application and is the entry point for defining background tasks. #### `src/mcp/` - **`server.py`**: Implements the `MCPServer` class, which handles the core logic of the Model Context Protocol, including tool registration and request routing. - **`tools/`**: - `__init__.py`: Registers all the available tools with the `MCPServer`. - `get_contract_info.py`: An MCP tool that provides detailed information about a specific prediction market contract. - `query_trading_data.py`: An MCP tool for querying historical trading data for a given contract. - `verify_claim.py`: The main MCP tool that orchestrates the entire claim verification process. #### `src/utils/` - **`logger.py`**: Configures structured logging for the application using `structlog`. #### `src/verification/` This module contains the core business logic for the claim verification pipeline. - **`logic/`**: - `evaluator.py`: The `ClaimEvaluator` class, which takes a parsed claim and the results from the query executor to determine a verdict (e.g., TRUE, FALSE, INCONCLUSIVE). - **`nlp/`**: - `claim_parser.py`: The `ClaimParser` class, responsible for parsing natural language claims into a structured format using regular expressions. - `temporal_parser.py`: The `TemporalParser` class, which parses and resolves temporal expressions (e.g., "yesterday", "last week") into concrete datetime ranges. - **`query/`**: - `executor.py`: The `QueryExecutor` class, which takes a parsed claim and executes the necessary queries against the database to fetch relevant data. - **`reporting/`**: - `formatter.py`: The `ReportFormatter` class, which formats the final verification result into a structured report. #### Other Files - **`config.py`**: Defines the application's configuration using Pydantic's `BaseSettings`, allowing for configuration via environment variables. - **`main.py`**: The main entry point for the FastAPI application, where the app is created, middleware is configured, and routers are included. ### `tests/` This directory contains all the tests for the application. - **`verification/`**: - `logic/test_claim_evaluator.py`: Unit tests for the `ClaimEvaluator` to ensure it correctly evaluates claims based on mock data. - `nlp/test_claim_parser.py`: Unit tests for the `ClaimParser` to verify that it correctly parses a variety of natural language claims. - `nlp/test_temporal_parser.py`: Unit tests for the `TemporalParser` to ensure it correctly handles various temporal expressions.