TealFlowMCP

An MCP (Model Context Protocol) server that enables LLMs to discover, understand, and generate Teal R Shiny applications for clinical trial data analysis.

Currently supports two Teal module packages:

• teal.modules.general - General-purpose analysis modules
• teal.modules.clinical - Clinical trial-specific modules

Documentation

• Quickstart Guide - Get started with VSCode and GitHub Copilot
• Tool Reference - Complete reference for all 14 MCP tools
• Configuration Guide - Setup, usage examples, and FAQs

Quick Start

New to TealFlowMCP? Check out the Quickstart Guide 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

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:

{
  "tealflow-mcp": {
    "command": "tealflow-mcp"
  }
}

For source installation:

{
  "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 and Configuration Guide 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)

pip install tealflow-mcp

Option 2: Install from Source (Development)

Clone the repository and install dependencies:

git clone https://github.com/Appsilon/TealFlowMCP.git
cd TealFlowMCP
uv sync

Verify Installation

For pip installation, verify the package is installed:

python -c "import tealflow_mcp; print(f'TealFlowMCP version {tealflow_mcp.__version__}')"

For source installation, run the test suite:

uv run python -m pytest tests/test_mcp_server.py -v

Testing

Run All Tests

Run the complete test suite:

uv run python -m pytest tests/ -v

Run Specific Test Files

# 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

uv run python -m pytest tests/test_discovery.py::TestDatasetDiscovery::test_discover_rds_files -v

Run with Coverage

uv run python -m pytest tests/ --cov=tealflow_mcp --cov-report=term-missing -v

Code Quality

Check Linting

Check for linting issues:

uv run ruff check tealflow_mcp/ tests/

Auto-fix Linting Issues

Automatically fix linting issues:

uv run ruff check tealflow_mcp/ tests/ --fix

Format Code

Format code consistently:

uv run ruff format tealflow_mcp/ tests/

Type Checking

Run static type checking:

uv run mypy tealflow_mcp/

Run All Checks

Run all code quality checks at once (same as CI):

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:

# 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:

tealflow-mcp

For source installation:

uv --directory /absolute/path/to/TealFlowMCP/ run tealflow_mcp.py

You can also test the MCP using the MCP inspector:

PyPI installation:

npx @modelcontextprotocol/inspector tealflow-mcp

Source installation:

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 →

Configuration

TealFlowMCP works with any MCP-compatible client (Claude Desktop, Claude Code, GitHub Copilot, Cursor, etc.).

Basic Configuration:

{
  "servers": {
    "tealflow-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/TealFlowMCP",
        "run",
        "tealflow_mcp.py"
      ]
    }
  }
}

View complete configuration guide →

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 →

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 for detailed guidelines on our development workflow, branching strategy, and version management.

About Appsilon

TealFlowMCP is developed by Appsilon, 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

License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See the LICENSE file for details.