Deckbuilder MCP Server

# Deckbuilder Folder Structure This document provides an overview of the folder structure for the Deckbuilder project, explaining the purpose of key directories and files. It acts as a sitemap for the repository. ## Root Directory The root directory contains project configuration, documentation, and top-level directories for source code, tests, and other assets. - **`.github/`**: Contains GitHub-specific configurations. - `ISSUE_TEMPLATE/`: Templates for creating new GitHub issues. - `workflows/`: CI/CD pipeline configurations for GitHub Actions (e.g., testing, publishing). - **`.vscode/`**: Holds VS Code workspace settings, launch configurations, and recommended extensions for a consistent development environment. - **`assets/`**: Contains static assets used by the application, such as default templates. - **`docs/`**: Project documentation. - `Features/`: Detailed descriptions of implemented or planned features. - `old_docs/`: Archived documentation. - `CODE_REVIEW_DESIGN.md`, etc.: Design documents for various aspects of the project. - **`output/`**: The default directory where generated presentations and other output files are saved. - **`scripts/`**: A collection of utility and helper scripts for development and maintenance tasks (e.g., `check_no_os_environ.py`, `copy_golden_files.py`). - **`src/`**: Contains all the source code for the project. - **`templates/`**: A directory for user-supplied presentation templates that can be used by Deckbuilder. - **`tests/`**: Contains all the automated tests for the project. ### Root Configuration Files - **`.gitignore`**: A list of files and directories that Git should ignore (e.g., `__pycache__`, `.venv`). - **`.pre-commit-config.yaml`**: Configuration for pre-commit hooks to enforce code style and quality before committing code. - **`.python-version`**: Specifies the Python version used for this project, typically used by tools like `pyenv`. - **`bandit.yaml`**: Configuration file for Bandit, a security linter for Python code. - **`pyproject.toml`**: Defines project metadata and build dependencies for Python packaging (PEP 518). Used by tools like `pip` and `uv`. - **`README.md`**: The main entry point for developers, providing an overview of the project, setup instructions, and usage examples. - **`requirements.txt`**: Lists the Python dependencies for the project. - **`TASK.md`**: A file for tracking development tasks and progress. - **`uv.lock`**: A lock file generated by the `uv` package manager to ensure deterministic installation of dependencies. ## `src` Directory The `src` directory is the heart of the project, containing the Python source code for the application and its components. - **`deckbuilder/`**: The core Python package for the Deckbuilder application. This is where the main logic for creating presentations from Markdown and data resides. - **`mcp_server/`**: A server component, likely standing for "Multi-Content Presentation" server, which provides content analysis and layout recommendations. - **`placekitten/`**: A utility module for integrating with the `placekitten.com` service to provide placeholder images in presentations. - **`shared/`**: A package for code that is shared across different parts of the application (e.g., `deckbuilder` and `mcp_server`). ### `src/deckbuilder` This is the main application package, with a structure that separates concerns into the following functional subdirectories: - **`__init__.py`**: Marks the directory as a Python package. - **`cli.py`**: Legacy CLI entry point. The logic is being moved to the `cli/` directory. - **`deckbuilder-completion.bash`**: Bash completion script for the CLI. - **`layout_intelligence.json`**: Data file for layout intelligence. - **`assets/`**: Contains assets specific to the `deckbuilder` package. - `master_default_presentation.json`: Default presentation data. - `master_default_presentation.md`: Default presentation content. - `templates/`: Default templates. - **`cli/`**: Contains all Command-Line Interface (CLI) logic. - `__init__.py`: Package initializer. - `main.py`: Main entry point for the CLI. - `commands.py`: Defines the CLI commands. - `naming_conventions.py`: Defines naming conventions for the CLI. - **`content/`**: Handles all content processing. - `__init__.py`: Package initializer. - `converter.py`: Converts content between different formats. - `formatter.py`: Formats content for presentation. - `frontmatter.py`: Processes frontmatter from Markdown files. - `matcher.py`: Matches content to slide layouts. - `placeholder_types.py`: Defines different types of placeholders. - `processor.py`: Main content processor. - `formatting_support.py`: Helper functions for formatting. - **`core/`**: Houses the core presentation generation engine. - `__init__.py`: Package initializer. - `engine.py`: The core presentation generation engine. - `presentation_builder.py`: Builds the final presentation. - `slide_builder.py`: Builds individual slides. - `table_builder.py`: Builds tables in slides. - `validation.py`: Validates presentation content. - **`image/`**: Manages all image handling. - `__init__.py`: Package initializer. - `image_handler.py`: Handles image processing. - `placeholder.py`: Manages image placeholders. - `placekitten_integration.py`: Integration with the PlaceKitten service. - **`language_mappings/`**: Contains language mapping files. - **`structured_frontmatter_patterns/`**: Contains JSON schemas for structured frontmatter. - **`templates/`**: Responsible for template management. - `__init__.py`: Package initializer. - `layout_analyzer.py`: Analyzes template layouts. - `layout_intelligence.py`: Provides layout recommendations. - `manager.py`: Manages templates. - `metadata.py`: Handles template metadata. - `pattern_loader.py`: Loads template patterns. - `pattern_schema.py`: Defines the schema for template patterns. - `recommendation_engine.py`: Recommends templates based on content. - `table_styles.py`: Defines styles for tables. - **`utils/`**: Contains shared utilities. - `__init__.py`: Package initializer. - `logging.py`: Logging configuration. - `path.py`: Path management utilities. ### `src/mcp_server` This package contains the source code for the MCP server. - **`__init__.py`**: Package initializer. - **`main.py`**: The main entry point for the server application. - **`tools.py`**: Various tools for the server. - **`content_analysis.py`**: Tools for analyzing content. - **`content_first_tools.py`**: Tools that prioritize content. - **`content_optimization.py`**: Tools for optimizing content. - **`layout_recommendations.py`**: Logic for recommending slide layouts. - **`README_CONTENT_FIRST_TOOLS.md`**: Documentation for the content-first tools. ### `src/placekitten` This package provides functionality for using placeholder images from `placekitten.com`. - **`__init__.py`**: Package initializer. - **`core.py`**: Core logic for fetching and processing kitten images. - **`filters.py`**: Image filters. - **`processor.py`**: Image processor. - **`smart_crop.py`**: Logic for intelligently cropping images. - **`README.md`**: Documentation for the `placekitten` package. - **`images/`**: Directory for storing kitten images. ### `src/shared` This package contains code shared across the project. - **`__init__.py`**: Package initializer. ## `tests` Directory This directory contains the automated tests for the project, mirroring the structure of the `src` directory. - **`deckbuilder/`**: Tests specifically for the `deckbuilder` package. - **`mcp_server/`**: Tests for the `mcp_server`. - **`placekitten/`**: Tests for the `placekitten` integration. - **`fixtures/`**: Contains test fixtures, such as sample data, mock objects, and templates used in tests. - **`utils/`**: Contains testing utilities, like content generators and validators. - **`conftest.py`**: A pytest file for configuring tests and defining hooks and fixtures that are shared across multiple test files.