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'], ]);