DHIS2 MCP Server

Instructions

Implementation Reference

• src/index.ts:1224-1234 (handler)

  Main handler for the dhis2_migration_assistant tool in the MCP server request handler switch statement. Calls generateMigrationGuide function.

  case 'dhis2_migration_assistant':
    const migrationArgs = args as any;
    const migrationGuide = generateMigrationGuide(migrationArgs);
    return {
      content: [
        {
          type: 'text',
          text: migrationGuide,
        },
      ],
    };

• src/debugging-helpers.ts:1921-2021 (handler)

  Core implementation function generateMigrationGuide that generates comprehensive DHIS2 migration guides from d2 library to App Platform. This is the main logic executed by the tool.

  export function generateMigrationGuide(args: any): string {
    const { currentStack, targetPlatform = {}, migrationScope = 'incremental', codeComplexity = 'moderate' } = args;
  
    return `# DHIS2 Migration Guide: d2 Library to App Platform
  
  ## Migration Overview
  - **Current Stack**: d2 ${currentStack?.d2Version || 'unknown'}, React ${currentStack?.reactVersion || 'unknown'}, ${currentStack?.buildSystem || 'unknown'}
  - **Target Platform**: App Platform ${targetPlatform?.appPlatformVersion || 'latest'}
  - **Migration Scope**: ${migrationScope.replace(/_/g, ' ').toUpperCase()}
  - **Code Complexity**: ${codeComplexity.toUpperCase()}
  
  ⚠️  **Important**: The d2 library is deprecated. Modern DHIS2 development uses @dhis2/app-platform.
  
  ## Pre-Migration Checklist
  - [ ] Backup current codebase
  - [ ] Document current dependencies
  - [ ] Test current functionality thoroughly
  - [ ] Review breaking changes in target platform
  - [ ] Plan rollback strategy
  
  ## Step-by-Step Migration
  
  ### 1. Environment Setup
  \`\`\`bash
  # Install modern DHIS2 tooling
  npm install -g @dhis2/cli
  
  # Create new App Platform project (for reference)
  d2 app scripts init migration-reference
  \`\`\`
  
  ### 2. Package.json Updates
  ${generatePackageJsonMigration(currentStack, targetPlatform)}
  
  ### 3. Configuration Migration
  ${generateConfigMigration(currentStack)}
  
  ### 4. Code Migration
  ${generateCodeMigration(migrationScope, codeComplexity)}
  
  ### 5. API Migration
  ${generateAPIMigration(targetPlatform.features)}
  
  ## Migration Phases
  
  ${generateMigrationPhases(migrationScope, codeComplexity)}
  
  ## Testing Strategy
  ${generateTestingStrategy(codeComplexity)}
  
  ## Rollback Plan
  \`\`\`bash
  # If migration fails, rollback strategy:
  git stash
  git checkout pre-migration-branch
  npm install
  npm start
  \`\`\`
  
  ## Post-Migration Validation
  - [ ] All features working correctly
  - [ ] Performance comparable or better
  - [ ] Bundle size acceptable
  - [ ] Tests passing
  - [ ] No console errors
  - [ ] Authentication working
  - [ ] API calls functioning
  
  ## Common Migration Issues
  
  ### Dependency Conflicts
  **Issue**: Conflicting versions between d2 and App Platform dependencies
  **Solution**: Remove all d2-related dependencies and use App Platform equivalents
  
  ### API Changes  
  **Issue**: d2.Api methods don't exist in App Runtime
  **Solution**: Replace with useDataQuery/useDataMutation hooks
  
  ### Styling Conflicts
  **Issue**: d2-ui styles conflict with @dhis2/ui components  
  **Solution**: Gradually replace d2-ui components with @dhis2/ui
  
  ### Build Configuration
  **Issue**: Custom webpack config no longer works
  **Solution**: Use d2.config.js for App Platform configuration
  
  ## Resources and Support
  - **Migration Documentation**: https://developers.dhis2.org/docs/app-platform/migration
  - **App Platform Guide**: https://developers.dhis2.org/docs/app-platform/getting-started  
  - **Community Forum**: https://community.dhis2.org/c/development
  - **Code Examples**: https://github.com/dhis2/app-platform
  
  ## Success Metrics
  After migration, you should have:
  - ✅ Modern, maintainable codebase
  - ✅ Better development experience
  - ✅ Improved performance
  - ✅ Future-proof architecture
  - ✅ Access to latest DHIS2 features
  `;
  }

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

  Tool permission registration in TOOL_PERMISSIONS Map. Associates 'dhis2_migration_assistant' with 'canDebugApplications' permission.

  ['dhis2_migration_assistant', 'canDebugApplications'],