Talk2YourData MCP is a production-ready AI orchestrator that enables natural language querying of DHIS2 health data. It combines LangGraph workflow orchestration with the Model Context Protocol (MCP) to provide an intelligent, conversational interface for health data analysts to explore DHIS2 analytics without needing to know the API.
Talk2YourData transforms natural language questions into DHIS2 analytics queries through a 4-part AI workflow:
- Part A: Query understanding and decomposition
- Part B: Parameter discovery (organization units, data elements, periods)
- Part C: Validation and DHIS2 data retrieval
- Part D: Answer generation with iterative refinement
For detailed architectural design and workflow patterns, see docs/ARCHITECTURE.md.
The system is built on:
- LangGraph: State machine orchestration with conditional routing and parallel execution
- Model Context Protocol (MCP): Standardized interface between LLMs and DHIS2 API tools
- LangChain: LLM abstractions, structured outputs, and message handling
The workflow uses parallel subgraph execution for parameter discovery, automatic ambiguity detection with human-in-the-loop clarification, and iterative answer refinement. For implementation details, see src/talk2yourdata_mcp/README.md.
Talk2YourData can be used through two interfaces:
Interactive terminal application with real-time progress tracking, session management, and debug capabilities.
Quick start:
uv run talk2yourdata-mcpSee src/talk2yourdata_mcp/cli/README.md for complete CLI documentation.
FastAPI backend with React frontend, featuring Server-Sent Events (SSE) streaming, visual parameter discovery, and chat history.
Quick start:
# Backend
uv run uvicorn src.talk2yourdata_mcp.webapp.main:app --port 8000
# Frontend (separate terminal)
cd src/webapp/frontend && npm run devSee src/webapp/README.md for complete web interface documentation.
- Python 3.11+ (tested with Python 3.13.7)
- uv package manager (or pip)
- DHIS2 instance with API access
- OpenAI API access (or compatible LLM API)
- Clone the repository:
git clone <repository-url>
cd dhis2-mcp-project- Install dependencies:
# Basic installation
uv sync
# Development installation (includes testing tools)
uv sync --all-extras
# Or using pip
pip install -e .Configuration is managed through environment variables. Create a .env file in the project root:
# DHIS2 Configuration
DHIS2_API_URL=https://your-dhis2-instance.org/api
DHIS2_API_TOKEN=your_dhis2_api_token
# LLM Configuration
LLM_API_URL=https://api.openai.com/v1
LLM_API_KEY=your_openai_api_key
LLM_MODEL_NAME=gpt-4o
LLM_TEMPERATURE=0.2
# Workflow Configuration
MAX_REFINEMENT_LOOPS=3
MAX_STEPS=20See docs/CONFIGURATION.md for all configuration options.
The project uses a comprehensive testing strategy:
- Health checks: Verify LLM, MCP, and DHIS2 connectivity
- Node tests: Test individual workflow components
- Workflow tests: Test multi-node interactions
- End-to-end tests: Test complete workflow with real DHIS2 queries
# Run health checks first
uv run pytest tests/health -v
# Run all tests
uv run pytestFor detailed testing documentation, see tests/README.md.
- docs/ARCHITECTURE.md - System architecture and workflow design principles
- src/talk2yourdata_mcp/README.md - Workflow implementation details
- src/talk2yourdata_mcp/cli/README.md - CLI usage and architecture
- src/webapp/README.md - Web interface setup and API reference
- tests/README.md - Testing strategy and guidelines
- docs/CONFIGURATION.md - Configuration options