TealFlowMCP

# TealFlowMCP [](https://badge.fury.io/py/tealflow-mcp) [](https://pypi.org/project/tealflow-mcp/) [](https://www.gnu.org/licenses/agpl-3.0) [](https://pepy.tech/project/tealflow-mcp) [](https://appsilon.github.io/TealFlowMCP/) An MCP (Model Context Protocol) server that enables LLMs to discover, understand, and generate [Teal](https://insightsengineering.github.io/teal/) R Shiny applications for clinical trial data analysis. Currently supports two Teal module packages: - [teal.modules.general](https://insightsengineering.github.io/teal.modules.general/) - General-purpose analysis modules - [teal.modules.clinical](https://insightsengineering.github.io/teal.modules.clinical/) - Clinical trial-specific modules ## Documentation - **[Quickstart Guide](https://appsilon.github.io/TealFlowMCP/QUICKSTART/)** - Get started with VSCode and GitHub Copilot - **[Tool Reference](https://appsilon.github.io/TealFlowMCP/TOOLS/)** - Complete reference for all 14 MCP tools - **[Configuration Guide](https://appsilon.github.io/TealFlowMCP/CONFIGURATION/)** - Setup, usage examples, and FAQs ## Quick Start **New to TealFlowMCP?** Check out the [Quickstart Guide](https://appsilon.github.io/TealFlowMCP/QUICKSTART/) for step-by-step instructions to get up and running with VSCode and GitHub Copilot. ## Prerequisites * Python 3.10+ * R (required for running generated Teal applications) **For development/source installation only:** * uv (Python project manager) - [Installation guide](https://docs.astral.sh/uv/getting-started/installation/) ## MCP Compatibility This server implements the **Model Context Protocol (MCP)** standard and works with any MCP-compatible LLM client, including: - **Claude Code** - **GitHub Copilot** - **Cursor** - **Other MCP-compatible tools** that support the MCP stdio protocol The server is LLM-agnostic—it provides tools that any LLM can use to build Teal applications. ### Adding to Your Editor/IDE **For PyPI installation:** ```json { "tealflow-mcp": { "command": "tealflow-mcp" } } ``` **For source installation:** ```json { "tealflow-mcp": { "command": "uv", "args": ["--directory", "/absolute/path/to/TealFlowMCP", "run", "tealflow_mcp.py"] } } ``` Replace `/absolute/path/to/TealFlowMCP` with the actual absolute path to your cloned repository. Consult your editor's documentation for the exact location of the MCP configuration file. See the [Quickstart Guide](https://appsilon.github.io/TealFlowMCP/QUICKSTART/) and [Configuration Guide](https://appsilon.github.io/TealFlowMCP/CONFIGURATION/) for detailed setup instructions. ## Architecture The MCP server is organized as a modular Python package for maintainability and extensibility: ``` TealFlowMCP/ ├── tealflow_mcp.py # Backward-compatibility wrapper ├── tealflow_mcp/ # Main package │ ├── core/ # Constants and enums │ ├── data/ # Data loaders │ ├── knowledge_base/ # Metadata and templates │ ├── models/ # Pydantic input models │ ├── server.py # MCP server implementation │ ├── tools/ # MCP tool implementations │ └── utils/ # Utilities and formatters ├── docs/ # Documentation ├── tests/ # Automated tests ├── sample_data/ # Sample ADaM datasets ├── .github/ # CI/CD workflows ├── pyproject.toml # Project metadata & dependencies ├── uv.lock # Lockfile for exact versions └── README.md ``` ## Installation ### Option 1: Install from PyPI (Recommended) ```bash pip install tealflow-mcp ``` ### Option 2: Install from Source (Development) Clone the repository and install dependencies: ```bash git clone https://github.com/Appsilon/TealFlowMCP.git cd TealFlowMCP uv sync ``` ### Verify Installation For pip installation, verify the package is installed: ```bash python -c "import tealflow_mcp; print(f'TealFlowMCP version {tealflow_mcp.__version__}')" ``` For source installation, run the test suite: ```bash uv run python -m pytest tests/test_mcp_server.py -v ``` ## Testing ### Run All Tests Run the complete test suite: ```bash uv run python -m pytest tests/ -v ``` ### Run Specific Test Files ```bash # Test MCP server functionality uv run python -m pytest tests/test_mcp_server.py -v # Test dataset discovery uv run python -m pytest tests/test_discovery.py -v # Test ADaM name extraction uv run python -m pytest tests/test_extract_adam_name.py -v ``` ### Run Single Test ```bash uv run python -m pytest tests/test_discovery.py::TestDatasetDiscovery::test_discover_rds_files -v ``` ### Run with Coverage ```bash uv run python -m pytest tests/ --cov=tealflow_mcp --cov-report=term-missing -v ``` ## Code Quality ### Check Linting Check for linting issues: ```bash uv run ruff check tealflow_mcp/ tests/ ``` ### Auto-fix Linting Issues Automatically fix linting issues: ```bash uv run ruff check tealflow_mcp/ tests/ --fix ``` ### Format Code Format code consistently: ```bash uv run ruff format tealflow_mcp/ tests/ ``` ### Type Checking Run static type checking: ```bash uv run mypy tealflow_mcp/ ``` ### Run All Checks Run all code quality checks at once (same as CI): ```bash uv run ruff check tealflow_mcp/ tests/ && \ uv run ruff format tealflow_mcp/ tests/ --check && \ uv run mypy tealflow_mcp/ && \ uv run python -m pytest tests/ -v ``` ## Continuous Integration This project uses GitHub Actions for automated testing and code quality checks. The CI pipeline runs on every push and pull request: - ✅ Linting and formatting checks - ✅ Type checking with mypy - ✅ Tests on Python 3.10, 3.11, and 3.12 - ✅ Code coverage reporting ## Manual Testing For quick manual verification: ```bash # Test MCP server manually uv run python tests/test_mcp_server.py # Test discovery tool with sample data uv run python -c " from tealflow_mcp.tools.discovery import discover_datasets import os result = discover_datasets(os.path.abspath('sample_data')) print(f'Found {result[\"count\"]} datasets') " ``` ## Running the MCP **For PyPI installation:** ```bash tealflow-mcp ``` **For source installation:** ```bash uv --directory /absolute/path/to/TealFlowMCP/ run tealflow_mcp.py ``` You can also test the MCP using the MCP inspector: **PyPI installation:** ```bash npx @modelcontextprotocol/inspector tealflow-mcp ``` **Source installation:** ```bash npx @modelcontextprotocol/inspector uv --directory /absolute/path/to/TealFlowMCP/ run tealflow_mcp.py ``` ## Available Tools TealFlowMCP provides 14 tools for building Teal applications: **Agent Guidance:** - `tealflow_agent_guidance` - **START HERE** - Get comprehensive development guidance and learn how to use all other tools **Module Discovery & Search:** - `tealflow_list_modules` - List all available Teal modules - `tealflow_search_modules_by_analysis` - Find modules by analysis type - `tealflow_get_module_details` - Get detailed module information **Code Generation:** - `tealflow_generate_module_code` - Generate R code for modules - `tealflow_get_app_template` - Get base Teal app template - `tealflow_generate_data_loading` - Generate R script for loading datasets **Dataset Management:** - `tealflow_list_datasets` - List available clinical trial datasets - `tealflow_discover_datasets` - Scan directories for ADaM datasets - `tealflow_check_dataset_requirements` - Check dataset compatibility - `tealflow_get_dataset_info` - Get information about ADaM datasets **Environment & Validation:** - `tealflow_setup_renv_environment` - Initialize R environment with renv - `tealflow_snapshot_renv_environment` - Snapshot current R environment state - `tealflow_check_shiny_startup` - Validate app startup **[View complete tool reference →](https://appsilon.github.io/TealFlowMCP/TOOLS/)** ## Configuration TealFlowMCP works with any MCP-compatible client (Claude Desktop, Claude Code, GitHub Copilot, Cursor, etc.). **Basic Configuration:** ```json { "servers": { "tealflow-mcp": { "command": "uv", "args": [ "--directory", "/absolute/path/to/TealFlowMCP", "run", "tealflow_mcp.py" ] } } } ``` **[View complete configuration guide →](https://appsilon.github.io/TealFlowMCP/CONFIGURATION/)** ## Quick Start Once configured, you can use natural language to build Teal apps: **Example:** > I have ADSL and ADTTE datasets. Build me a Teal app with Kaplan-Meier plots and Cox regression. The LLM will automatically: - Setup the R environment - Search for relevant modules - Validate dataset compatibility - Generate complete app code **[View usage examples and FAQs →](https://appsilon.github.io/TealFlowMCP/CONFIGURATION/)** ## Contributing We welcome contributions to TealFlowMCP! Whether you're fixing bugs, adding features, or improving documentation, your help is appreciated. Please see the [Contributing Guide](https://appsilon.github.io/TealFlowMCP/CONTRIBUTING/) for detailed guidelines on our development workflow, branching strategy, and version management. ## About Appsilon TealFlowMCP is developed by [Appsilon](https://appsilon.com), a trusted technology partner for pharmaceutical and life sciences companies specializing in accelerating drug development through open-source solutions. Appsilon helps organizations transition from legacy systems to modern, validated open-source analytics while maintaining strict regulatory compliance. Learn more at [appsilon.com](https://appsilon.com) ## License This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.