Skip to content

ForDummies.md

Latest commit

 

History

History
175 lines (145 loc) · 6.34 KB

ForDummies.md

File metadata and controls

175 lines (145 loc) · 6.34 KB

DHIS2 MCP For Dummies (A very friendly guide)

This guide is for someone brand-new to coding, Cursor, and DHIS2. Follow the steps exactly. Copy and paste where told. If anything feels confusing, don’t worry—just do the next step.

What you’re about to do

  • Use Cursor (an AI coding editor) + this DHIS2 MCP “helper” to build a DHIS2 app with almost no code knowledge.
  • Click buttons → MCP runs specialized DHIS2 tools → You get ready-to-use app snippets.

0) What you need (once)

  • A Mac with internet
  • Node.js 18 or newer
  • Git

Install Node.js 18 (recommended)

# Install Homebrew if you don’t have it
/bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"

# Install Node.js 18
brew install node@18

# Make sure Node is on 18+
node -v

1) Get the DHIS2 MCP on your computer

# Pick a folder you like and open Terminal
cd ~/Documents

# Download the project
git clone https://github.com/yourusername/dhis2-mcp.git
cd dhis2-mcp

# Install and build (first time takes a bit)
npm install
npm run build

2) Start the MCP “helper”

You have two easy options. Either one is fine.

Option A (recommended): Let Cursor launch it for you

  1. Open Cursor
  2. Go to Settings → MCP (Model Context Protocol) → Add Server (or “Custom Server”)
  3. Fill it in:
    • Name: dhis2-mcp
    • Command: node
    • Args: dist/index.js
    • Working directory: the folder you cloned, e.g. /Users/yourname/Documents/dhis2-mcp
  4. Save. You should see dhis2-mcp in Cursor’s Tools list for your chats.

Option B: Run it manually (works too)

# In the project folder
npm start

Leave that Terminal window open. In Cursor, open a chat and make sure the tool dhis2-mcp is available.

3) Connect to a DHIS2 server (the demo one)

We’ll use the public demo server so you don’t need to set up anything.

  • Base URL: https://play.dhis2.org/2.40.4
  • Username: admin
  • Password: district

In Cursor:

  1. Open a chat
  2. Make sure the tool dhis2-mcp is enabled for that chat
  3. Run the tool named dhis2_configure
  4. Fill the boxes:
    • baseUrl: https://play.dhis2.org/2.40.4
    • username: admin
    • password: district
  5. Run it. You should get “Successfully connected …”

If it fails, check your internet, then try again.

4) Create your DHIS2 web app (the fastest way)

We’ll scaffold a DHIS2 app using official tooling.

In Terminal (not in Cursor):

# In a separate folder where you keep projects
cd ~/Documents

# Create a new DHIS2 app (you’ll be asked a few simple questions)
npx @dhis2/cli-app-scripts init my-health-app
cd my-health-app

# Start the dev server
yarn install
yarn start

This opens a browser tab at your local app. Keep it running.

5) Add smart UI pieces from the MCP

Now, we’ll ask the MCP to generate ready-to-copy UI components and configuration that match DHIS2 best practices.

In Cursor (chat with dhis2-mcp tools):

  • Generate a form (names, dates, file upload, validation):
    • Run: dhis2_generate_ui_form_patterns
    • Example options to fill:
      • componentName: DataElementForm
      • includeValidation: true
      • includeDatePicker: true
      • includeFileUpload: true
      • includeMultiSelect: true
  • Generate a data table + cards + modal (with loading and empty states):
    • Run: dhis2_generate_ui_data_display
    • Example:
      • componentName: DataElementDisplay
      • includeTable: true
      • includePagination: true
      • includeCards: true
      • includeModal: true
  • Generate navigation layout (header, sidebar, breadcrumbs, tabs):
    • Run: dhis2_generate_ui_navigation_layout
    • Example:
      • componentName: AppLayout
      • includeHeaderBar: true
      • includeSidebar: true
      • includeBreadcrumbs: true
      • includeTabs: true
  • Generate design-system tokens (colors, fonts, spacing, dark mode):
    • Run: dhis2_generate_design_system
    • Example:
      • theme: default
      • enableDarkMode: true

Each tool returns a Markdown page. Copy the code blocks into your app:

  • Components: put in src/components/YourName.jsx(x)
  • Styles/tokens: keep in a src/theme/ or similar
  • Then import them into src/App.jsx(x) and render them

6) Make it talk to DHIS2 (no stress)

Your app should use @dhis2/app-runtime queries. Ask the MCP to generate an example for you:

  • Run: dhis2_generate_app_runtime_config
  • Paste the example provider + queries into your app (follow the instructions it prints)
  • Keep dev server running (yarn start) and check your UI

7) Android UI (optional)

If you also want an Android app UI (using Compose):

  • Run: android_generate_material_form (form with validation/date/multi-select)
  • Run: android_generate_list_adapter (lists)
  • Run: android_generate_navigation_drawer (drawer layout)
  • Run: android_generate_bottom_sheet (bottom sheet) These output Kotlin/Compose snippets you copy into your Android project.

8) What to say to the AI (you can be very simple)

  • “Generate a DHIS2 form for creating data elements with name, value type, and validation.”
  • “Give me a data table with pagination and loading states.”
  • “Add a design system with dark mode and compact spacing.”
  • “Help connect my app to DHIS2 Play server and render data elements.”

You don’t need fancy words. Be literal and specific.

9) Troubleshooting (common fixes)

  • Can’t connect to DHIS2: Check the URL. Try the demo https://play.dhis2.org/2.40.4 + admin/district.
  • Dev server shows errors: Stop it and yarn start again.
  • CORS/auth errors in browser: Ask the MCP tool dhis2_diagnose_cors_issues or dhis2_debug_authentication with your details. It prints fixes.
  • Stuck? Ask the AI: “Explain this error in plain English, and fix it.”

10) When you’re ready to share

  • Build your app: yarn build
  • Talk to your DHIS2 admin to install your app package or use DHIS2 App Hub docs for publishing.

Quick glossary (no pain)

  • DHIS2: A platform for health data apps.
  • MCP: A helper that gives Cursor superpowers (special tools for DHIS2).
  • Tool: A button you click in Cursor that runs something useful (like “make a form”).
  • Scaffold: A starter app the computer creates for you.

You did it 🎉

You can make more screens by running more tools and pasting the code into your app. If you get lost, say: “Walk me through the next step like I’m new.”