DHIS2 MCP Server

Instructions

Implementation Reference

• src/debugging-helpers.ts:816-1064 (handler)

  The core handler function for 'dhis2_resolve_build_issues' that analyzes build issues (CORS, auth, proxy, dependencies, etc.) and generates detailed markdown troubleshooting guides with diagnosis, step-by-step solutions, code snippets, and migration advice.

  export function resolveBuildIssues(args: any): string {
    const { buildTool, issueType, errorMessage = '', packageManager = 'npm', nodeVersion, dependencies = {} } = args;
  
    const diagnosis = [];
    const solutions = [];
  
    // Analyze build tool specific issues
    if (buildTool === 'd2_cli_deprecated') {
      diagnosis.push('⚠️  The d2 CLI library has been deprecated');
      solutions.push('Migrate to @dhis2/app-platform for modern DHIS2 development');
      solutions.push('Use the migration assistant: `dhis2_migration_assistant` tool');
      solutions.push('Reference: https://developers.dhis2.org/docs/app-platform/getting-started');
    }
  
    // Analyze specific issue types
    switch (issueType) {
      case 'dependency_conflicts':
        diagnosis.push('Conflicting package versions or peer dependency issues');
        solutions.push('Clear node_modules and package lock file');
        solutions.push(`rm -rf node_modules ${packageManager === 'yarn' ? 'yarn.lock' : 'package-lock.json'}`);
        solutions.push(`${packageManager} install`);
        if (packageManager === 'yarn' && dependencies.dhis2Cli) {
          solutions.push('Ensure using yarn for DHIS2 projects (yarn.lock included)');
        }
        break;
  
      case 'module_resolution':
        diagnosis.push('Module resolution failing - TypeScript or import path issues');
        solutions.push('Check tsconfig.json paths configuration');
        solutions.push('Verify all imports use correct file extensions');
        solutions.push('Ensure moduleResolution is set to "node" in tsconfig.json');
        break;
  
      case 'bundle_size':
        diagnosis.push('Bundle size exceeding limits or performance issues');
        solutions.push('Implement code splitting with React.lazy()');
        solutions.push('Use tree shaking to eliminate dead code');
        solutions.push('Analyze bundle with: npm run build -- --analyze');
        break;
  
      case 'tree_shaking':
        diagnosis.push('Dead code elimination not working properly');
        solutions.push('Ensure using ES6 modules (import/export)');
        solutions.push('Check sideEffects configuration in package.json');
        solutions.push('Upgrade to latest @dhis2/cli-app-scripts version');
        break;
  
      case 'compilation_errors':
        diagnosis.push('TypeScript or JavaScript compilation failing');
        solutions.push('Check for TypeScript version compatibility');
        solutions.push('Verify all types are properly imported');
        solutions.push('Run type check separately: npm run type-check');
        break;
  
      case 'memory_issues':
        diagnosis.push('Build process running out of memory');
        solutions.push('Increase Node.js memory limit: --max-old-space-size=4096');
        solutions.push('Use incremental builds when possible');
        solutions.push('Consider splitting large applications');
        break;
    }
  
    // Node.js version specific issues
    if (nodeVersion) {
      const majorVersion = parseInt(nodeVersion.split('.')[0]);
      if (majorVersion < 16) {
        diagnosis.push(`Node.js version ${nodeVersion} may be too old for modern DHIS2 development`);
        solutions.push('Upgrade to Node.js 16+ (LTS recommended)');
        solutions.push('Use Node Version Manager (nvm) for easy version switching');
      } else if (majorVersion >= 18) {
        diagnosis.push('Node.js 18+ may have stricter module resolution');
        solutions.push('Ensure all dependencies support Node.js ' + majorVersion);
      }
    }
  
    return `# Build Issues Resolution
  
  ## Issue Analysis
  - **Build Tool**: ${buildTool.replace(/_/g, ' ').toUpperCase()}
  - **Issue Type**: ${issueType.replace(/_/g, ' ').toUpperCase()}
  - **Package Manager**: ${packageManager.toUpperCase()}
  - **Node Version**: ${nodeVersion || 'Not specified'}
  - **Error**: ${errorMessage}
  
  ## Diagnosis
  ${diagnosis.map(d => `- ${d}`).join('\n')}
  
  ## Immediate Solutions
  ${solutions.map((s, i) => `${i + 1}. ${s}`).join('\n')}
  
  ## Build Tool Specific Fixes
  
  ${generateBuildToolFixes(buildTool, dependencies)}
  
  ## Version Compatibility Check
  
  ### Current Dependencies
  ${Object.entries(dependencies).map(([key, version]) => `- **${key}**: ${version}`).join('\n')}
  
  ### Recommended Versions
  - **@dhis2/cli-app-scripts**: ^10.3.0+
  - **@dhis2/app-platform**: ^11.0.0+
  - **Node.js**: 16.x or 18.x (LTS)
  - **npm**: 8.x+
  - **yarn**: 1.22.x+
  
  ## Generic Build Troubleshooting
  
  ### Clear Build Artifacts
  \`\`\`bash
  # Clear all caches and artifacts
  rm -rf node_modules
  rm -rf dist
  rm -rf build
  rm -rf .cache
  ${packageManager === 'yarn' ? 'rm yarn.lock' : 'rm package-lock.json'}
  
  # Fresh install
  ${packageManager} install
  \`\`\`
  
  ### Memory Issues
  \`\`\`bash
  # Increase memory limit
  export NODE_OPTIONS="--max-old-space-size=4096"
  npm run build
  
  # Alternative: Set in package.json scripts
  "build": "NODE_OPTIONS='--max-old-space-size=4096' react-scripts build"
  \`\`\`
  
  ### Debug Build Process
  \`\`\`bash
  # Verbose build output
  npm run build -- --verbose
  
  # TypeScript compilation check
  npx tsc --noEmit
  
  # ESLint check
  npx eslint src/
  \`\`\`
  
  ## Performance Optimization
  
  ### Bundle Analysis
  \`\`\`bash
  # Analyze bundle size
  npm run build -- --analyze
  
  # Alternative tools
  npx webpack-bundle-analyzer build/static/js/*.js
  npx source-map-explorer build/static/js/*.js
  \`\`\`
  
  ### Code Splitting Example
  \`\`\`javascript
  // Implement lazy loading
  const LazyComponent = React.lazy(() => import('./LazyComponent'));
  
  function App() {
    return (
      <Suspense fallback={<div>Loading...</div>}>
        <LazyComponent />
      </Suspense>
    );
  }
  \`\`\`
  
  ### Tree Shaking Configuration
  \`\`\`json
  // package.json
  {
    "sideEffects": false,
    "main": "lib/index.js",
    "module": "es/index.js"
  }
  \`\`\`
  
  ## Environment-Specific Issues
  
  ### Development Build Issues
  - Hot reload not working
  - Slow compilation times
  - Memory leaks in watch mode
  
  ### Production Build Issues
  - Minification errors
  - Missing environment variables
  - Asset path issues
  
  ## Migration Recommendations
  
  ${buildTool === 'd2_cli_deprecated' ? `
  ### Migrate from d2 CLI to App Platform
  
  1. **Install App Platform**
     \`\`\`bash
     npm install --save-dev @dhis2/cli-app-scripts
     \`\`\`
  
  2. **Update package.json scripts**
     \`\`\`json
     {
       "scripts": {
         "start": "d2-app-scripts start",
         "build": "d2-app-scripts build",
         "test": "d2-app-scripts test",
         "deploy": "d2-app-scripts deploy"
       }
     }
     \`\`\`
  
  3. **Create d2.config.js**
     \`\`\`javascript
     const config = {
       type: 'app',
       name: 'my-app',
       title: 'My DHIS2 App',
       description: 'A DHIS2 application'
     };
     
     module.exports = config;
     \`\`\`
  
  4. **Update imports**
     - Replace d2 library imports
     - Use @dhis2/app-runtime for API calls
     - Update component imports to @dhis2/ui
  ` : ''}
  
  ## Support Resources
  
  - **DHIS2 Developer Portal**: https://developers.dhis2.org
  - **Community Forum**: https://community.dhis2.org/c/development
  - **GitHub Issues**: https://github.com/dhis2/app-platform/issues
  - **Documentation**: https://docs.dhis2.org
  
  ## Automated Diagnostics
  
  \`\`\`bash
  # Run comprehensive diagnostics
  npx @dhis2/cli-app-scripts doctor
  
  # Check environment setup
  npx envinfo --binaries --languages --utilities
  \`\`\`
  `;
  }

• src/index.ts:1188-1198 (registration)

  Tool dispatch/registration in the main MCP server CallToolRequestSchema handler switch statement. Imports resolveBuildIssues from debugging-helpers and executes it with user arguments.

  case 'dhis2_resolve_build_issues':
    const buildIssueArgs = args as any;
    const buildSolution = resolveBuildIssues(buildIssueArgs);
    return {
      content: [
        {
          type: 'text',
          text: buildSolution,
        },
      ],
    };

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

  Permission registration associating 'dhis2_resolve_build_issues' with 'canDebugApplications' permission in the TOOL_PERMISSIONS Map, used to filter tools based on user DHIS2 authorities.

  ['dhis2_resolve_build_issues', 'canDebugApplications'],