DHIS2 MCP Server

Instructions

Implementation Reference

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

  Main handler function for 'dhis2_resolve_build_issues' tool. Analyzes build issues for DHIS2 apps and generates comprehensive markdown diagnosis and solutions including fixes for various build tools, dependency conflicts, and migration guidance.
  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 handler switch statement. Calls the resolveBuildIssues function from debugging-helpers.ts.
  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 mapping the tool to 'canDebugApplications' permission in the TOOL_PERMISSIONS static map.
  ['dhis2_resolve_build_issues', 'canDebugApplications'],
• src/debugging-helpers.ts:1066-1154 (helper)

  Helper function called by resolveBuildIssues to generate build tool-specific fixes.
  function generateBuildToolFixes(buildTool: string, dependencies: any): string { switch (buildTool) { case 'app_platform': return `### DHIS2 App Platform Fixes #### Update to Latest Version \`\`\`bash npm install --save-dev @dhis2/cli-app-scripts@latest \`\`\` #### Configuration Check \`\`\`javascript // d2.config.js validation const config = { type: 'app', name: 'my-app', // Must be valid package name title: 'My App', description: 'App description', // Optional: Custom entry points entryPoints: { app: './src/App.js' } }; module.exports = config; \`\`\` #### Common App Platform Issues 1. **Missing d2.config.js**: App Platform requires this configuration file 2. **Invalid app name**: Must follow npm package naming rules 3. **Missing manifest.webapp**: Required for DHIS2 app installation`; case 'webpack': return `### Webpack Configuration Fixes #### Update Webpack \`\`\`bash npm install --save-dev webpack@latest webpack-cli@latest \`\`\` #### Basic webpack.config.js \`\`\`javascript const path = require('path'); module.exports = { entry: './src/index.js', output: { path: path.resolve(__dirname, 'dist'), filename: 'bundle.js' }, module: { rules: [ { test: /\\.jsx?$/, exclude: /node_modules/, use: 'babel-loader' } ] } }; \`\`\``; case 'vite': return `### Vite Configuration Fixes #### Update Vite \`\`\`bash npm install --save-dev vite@latest @vitejs/plugin-react@latest \`\`\` #### vite.config.js \`\`\`javascript import { defineConfig } from 'vite'; import react from '@vitejs/plugin-react'; export default defineConfig({ plugins: [react()], build: { outDir: 'build' } }); \`\`\``; default: return '### Custom Build Tool Fixes\n```bash\n# Add specific fixes for your build tool\n```'; } }