DHIS2 MCP Server

Instructions

Implementation Reference

• src/index.ts:1176-1186 (handler)

  MCP tool handler implementation. Extracts proxy configuration arguments and calls generateProxyConfiguration helper to produce a markdown configuration guide, which is returned as tool response content.

  case 'dhis2_fix_proxy_configuration':
    const proxyArgs = args as any;
    const proxyConfig = generateProxyConfiguration(proxyArgs);
    return {
      content: [
        {
          type: 'text',
          text: proxyConfig,
        },
      ],
    };

• src/debugging-helpers.ts:571-672 (helper)

  Main helper function that generates detailed proxy configuration markdown for different proxy types (webpack_dev_server, create_react_app, vite, custom_express). Includes testing commands, troubleshooting, security notes, and environment variables.

  export function generateProxyConfiguration(args: any): string {
    const { proxyType, targetInstance, localPort = 3000, authentication, sslOptions = {} } = args;
  
    return `# Proxy Configuration for DHIS2 Development
  
  ## ${proxyType.replace(/_/g, ' ').toUpperCase()} Configuration
  
  ${generateProxyConfig(proxyType, targetInstance, localPort, authentication, sslOptions)}
  
  ## Testing Proxy Configuration
  
  ### Test Proxy Connection
  \`\`\`bash
  # Test direct connection to DHIS2
  curl ${targetInstance}/api/me
  
  # Test through proxy  
  curl http://localhost:${localPort}/api/me
  \`\`\`
  
  ### Browser Testing
  1. Start your application with proxy enabled
  2. Open browser dev tools Network tab
  3. Navigate to your application
  4. Check that API requests go to localhost:${localPort}
  5. Verify requests are forwarded to ${targetInstance}
  
  ## Common Proxy Issues and Solutions
  
  ### Issue: 502 Bad Gateway
  **Causes**:
  - Target DHIS2 instance is unreachable
  - Authentication credentials are incorrect
  - SSL certificate verification failing
  
  **Solutions**:
  - Verify target instance URL: ${targetInstance}
  - Check authentication credentials
  - ${sslOptions.secure === false ? 'SSL verification is disabled (good for development)' : 'Consider disabling SSL verification for development'}
  
  ### Issue: Authentication Not Working
  **Solutions**:
  - Ensure credentials are correct: ${authentication?.username || '[username]'}
  - Check if user account is locked
  - Verify proxy is forwarding auth headers
  
  ### Issue: CORS Still Occurring  
  **Solutions**:
  - Restart development server after proxy configuration
  - Clear browser cache completely
  - Check proxy configuration syntax
  
  ## Security Considerations
  
  ### Development Environment
  ✅ **Safe for development**:
  - Using proxy to avoid CORS issues
  - Credentials stored in configuration files
  ${sslOptions.secure === false ? '- SSL verification disabled for development certificates' : ''}
  
  ⚠️ **Security reminders**:
  - Never commit credentials to version control
  - Use separate development credentials
  - Enable SSL verification in production
  
  ### Production Environment
  ❌ **Not suitable for production**:
  - This proxy configuration is for development only
  - Production should use proper authentication flows
  - Enable all security features for production deployment
  
  ## Environment Variables
  
  Create a \`.env.local\` file:
  \`\`\`bash
  # Proxy configuration
  DHIS2_PROXY_TARGET=${targetInstance}
  DHIS2_PROXY_USERNAME=${authentication?.username || 'your-username'}
  DHIS2_PROXY_PASSWORD=${authentication?.password || 'your-password'}
  PROXY_PORT=${localPort}
  \`\`\`
  
  ## Alternative Solutions
  
  ### 1. DHIS2 CLI Proxy
  \`\`\`bash
  # Use built-in DHIS2 CLI proxy
  yarn start --proxy
  \`\`\`
  
  ### 2. Local DHIS2 Instance
  \`\`\`bash
  # Set up local development instance
  npx @dhis2/cli cluster init
  d2 cluster up
  \`\`\`
  
  ### 3. Browser Extension
  - Use CORS browser extensions for development
  - ⚠️ Remember to disable in production
  `;
  }

• src/permission-system.ts:59-178 (registration)

  Permission registration mapping TOOL_PERMISSIONS that associates the tool 'dhis2_fix_proxy_configuration' with required permission 'canDebugApplications'. Used by filterToolsByPermissions to control tool visibility based on user permissions.

  private static readonly TOOL_PERMISSIONS = new Map<string, keyof UserPermissions | Array<keyof UserPermissions>>([
    // Configuration and connection
    ['dhis2_configure', 'canViewSystemInfo'],
    ['dhis2_get_system_info', 'canViewSystemInfo'],
    
    // Metadata operations - Data Elements
    ['dhis2_list_data_elements', 'canViewMetadata'],
    ['dhis2_create_data_element', 'canCreateMetadata'],
    ['dhis2_update_data_element', 'canUpdateMetadata'],
    ['dhis2_delete_data_element', 'canDeleteMetadata'],
    
    // Metadata operations - Data Sets
    ['dhis2_list_data_sets', 'canViewMetadata'],
    ['dhis2_create_data_set', 'canCreateMetadata'],
    
    // Metadata operations - Categories
    ['dhis2_list_categories', 'canViewMetadata'],
    ['dhis2_create_category', 'canCreateMetadata'],
    ['dhis2_list_category_options', 'canViewMetadata'],
    ['dhis2_create_category_option', 'canCreateMetadata'],
    ['dhis2_list_category_combos', 'canViewMetadata'],
    ['dhis2_create_category_combo', 'canCreateMetadata'],
    ['dhis2_list_category_option_combos', 'canViewMetadata'],
    
    // Organisation Units
    ['dhis2_list_org_units', 'canViewMetadata'],
    ['dhis2_list_org_unit_groups', 'canViewMetadata'],
    ['dhis2_create_org_unit_group', 'canCreateMetadata'],
    
    // Validation Rules
    ['dhis2_list_validation_rules', 'canViewMetadata'],
    ['dhis2_create_validation_rule', 'canCreateMetadata'],
    ['dhis2_run_validation', ['canViewData', 'canRunAnalytics']],
    
    // Data Values
    ['dhis2_get_data_values', 'canViewData'],
    ['dhis2_bulk_import_data_values', 'canImportData'],
    
    // Analytics
    ['dhis2_get_analytics', 'canRunAnalytics'],
    ['dhis2_get_data_statistics', 'canRunAnalytics'],
    
    // Programs (Tracker)
    ['dhis2_list_programs', 'canViewMetadata'],
    ['dhis2_create_program', 'canManagePrograms'],
    ['dhis2_list_tracked_entity_types', 'canViewMetadata'],
    ['dhis2_create_tracked_entity_type', 'canManagePrograms'],
    ['dhis2_list_tracked_entity_attributes', 'canViewMetadata'],
    ['dhis2_create_tracked_entity_attribute', 'canManagePrograms'],
    ['dhis2_list_program_stages', 'canViewMetadata'],
    ['dhis2_create_program_stage', 'canManagePrograms'],
    ['dhis2_list_program_rules', 'canViewMetadata'],
    ['dhis2_create_program_rule', 'canManagePrograms'],
    
    // Tracker Data
    ['dhis2_list_tracked_entity_instances', 'canViewTEI'],
    ['dhis2_create_tracked_entity_instance', 'canEnrollTEI'],
    ['dhis2_list_enrollments', 'canViewTEI'],
    ['dhis2_create_enrollment', 'canEnrollTEI'],
    ['dhis2_list_events', 'canViewTEI'],
    ['dhis2_create_event', 'canManageTrackerData'],
    ['dhis2_bulk_import_events', 'canImportData'],
    ['dhis2_get_event_analytics', 'canRunAnalytics'],
    ['dhis2_get_enrollment_analytics', 'canRunAnalytics'],
    
    // Dashboards and Visualizations
    ['dhis2_list_dashboards', 'canViewData'],
    ['dhis2_create_dashboard', 'canManageDashboards'],
    ['dhis2_list_visualizations', 'canViewData'],
    ['dhis2_create_visualization', 'canManageDashboards'],
    ['dhis2_list_reports', 'canViewData'],
    ['dhis2_generate_report', 'canExportData'],
    
    // Web App Platform Tools
    ['dhis2_init_webapp', 'canConfigureApps'],
    ['dhis2_configure_app_manifest', 'canConfigureApps'],
    ['dhis2_configure_build_system', 'canConfigureApps'],
    ['dhis2_setup_dev_environment', 'canConfigureApps'],
    ['dhis2_generate_app_runtime_config', 'canConfigureApps'],
    ['dhis2_create_datastore_namespace', 'canConfigureApps'],
    ['dhis2_manage_datastore_key', 'canConfigureApps'],
    ['dhis2_setup_authentication_patterns', 'canConfigureApps'],
    ['dhis2_create_ui_components', 'canUseUITools'],
    ['dhis2_generate_test_setup', 'canConfigureApps'],
    
    // Debugging Tools
    ['dhis2_diagnose_cors_issues', 'canDebugApplications'],
    ['dhis2_configure_cors_allowlist', 'canDebugApplications'],
    ['dhis2_debug_authentication', 'canDebugApplications'],
    ['dhis2_fix_proxy_configuration', 'canDebugApplications'],
    ['dhis2_resolve_build_issues', 'canDebugApplications'],
    ['dhis2_optimize_performance', 'canDebugApplications'],
    ['dhis2_validate_environment', 'canDebugApplications'],
    ['dhis2_migration_assistant', 'canDebugApplications'],
    
    // Android SDK Tools
    ['dhis2_android_init_project', 'canUseMobileFeatures'],
    ['dhis2_android_configure_gradle', 'canUseMobileFeatures'],
    ['dhis2_android_setup_sync', 'canConfigureMobile'],
    ['dhis2_android_configure_storage', 'canConfigureMobile'],
    ['dhis2_android_setup_location_services', 'canUseMobileFeatures'],
    ['dhis2_android_configure_camera', 'canUseMobileFeatures'],
    ['dhis2_android_setup_authentication', 'canConfigureMobile'],
    ['dhis2_android_generate_data_models', 'canUseMobileFeatures'],
    ['dhis2_android_setup_testing', 'canUseMobileFeatures'],
    ['dhis2_android_configure_ui_patterns', 'canUseMobileFeatures'],
    ['dhis2_android_setup_offline_analytics', 'canUseMobileFeatures'],
    ['dhis2_android_configure_notifications', 'canUseMobileFeatures'],
    ['dhis2_android_performance_optimization', 'canUseMobileFeatures'],
    
    // UI Library Tools
    ['dhis2_generate_ui_form_patterns', 'canUseUITools'],
    ['dhis2_generate_ui_data_display', 'canUseUITools'],
    ['dhis2_generate_ui_navigation_layout', 'canUseUITools'],
    ['dhis2_generate_design_system', 'canUseUITools'],
    ['android_generate_material_form', 'canUseMobileFeatures'],
    ['android_generate_list_adapter', 'canUseMobileFeatures'],
    ['android_generate_navigation_drawer', 'canUseMobileFeatures'],
    ['android_generate_bottom_sheet', 'canUseMobileFeatures'],
  ]);