DHIS2 MCP Server

Instructions

Implementation Reference

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

  The core handler function that generates comprehensive proxy configuration markdown for various development tools (Webpack, CRA, Vite, Express) to resolve proxy/CORS issues in DHIS2 app development.
  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/index.ts:1176-1186 (registration)

  MCP tool registration and dispatch handler that maps the tool call to the generateProxyConfiguration function and returns the markdown response.
  case 'dhis2_fix_proxy_configuration': const proxyArgs = args as any; const proxyConfig = generateProxyConfiguration(proxyArgs); return { content: [ { type: 'text', text: proxyConfig, }, ], };
• src/permission-system.ts:148-148 (registration)

  Permission mapping that requires 'canDebugApplications' permission to use this debugging tool.
  ['dhis2_fix_proxy_configuration', 'canDebugApplications'],
• src/debugging-helpers.ts:674-814 (helper)

  Helper function that generates specific proxy configuration code for different build systems (Webpack, CRA, Vite, Express). Called by the main handler.
  function generateProxyConfig(proxyType: string, targetInstance: string, localPort: number, authentication: any, sslOptions: any): string { switch (proxyType) { case 'webpack_dev_server': return `### Webpack Dev Server Configuration \`\`\`javascript // webpack.config.js module.exports = { devServer: { port: ${localPort}, proxy: { '/api': { target: '${targetInstance}', changeOrigin: true, secure: ${sslOptions.secure !== false}, ${authentication ? `auth: '${authentication.username}:${authentication.password}',` : ''} headers: { 'Authorization': 'Basic ' + Buffer.from('${authentication?.username || 'username'}:${authentication?.password || 'password'}').toString('base64') } } } } }; \`\`\``; case 'create_react_app': return `### Create React App Configuration #### Option 1: package.json proxy field \`\`\`json { "name": "my-dhis2-app", "proxy": "${targetInstance}", "scripts": { "start": "react-scripts start" } } \`\`\` #### Option 2: setupProxy.js (for advanced configuration) \`\`\`javascript // src/setupProxy.js const { createProxyMiddleware } = require('http-proxy-middleware'); module.exports = function(app) { app.use( '/api', createProxyMiddleware({ target: '${targetInstance}', changeOrigin: true, secure: ${sslOptions.secure !== false}, ${authentication ? `auth: '${authentication.username}:${authentication.password}',` : ''} headers: { 'Authorization': 'Basic ' + Buffer.from('${authentication?.username || 'username'}:${authentication?.password || 'password'}').toString('base64') } }) ); }; \`\`\` #### Start with proxy \`\`\`bash npm start \`\`\``; case 'vite': return `### Vite Configuration \`\`\`javascript // vite.config.js import { defineConfig } from 'vite'; export default defineConfig({ server: { port: ${localPort}, proxy: { '/api': { target: '${targetInstance}', changeOrigin: true, secure: ${sslOptions.secure !== false}, configure: (proxy, options) => { proxy.on('proxyReq', (proxyReq, req, res) => { const auth = Buffer.from('${authentication?.username || 'username'}:${authentication?.password || 'password'}').toString('base64'); proxyReq.setHeader('Authorization', \`Basic \${auth}\`); }); } } } } }); \`\`\` #### Start development server \`\`\`bash npm run dev \`\`\``; case 'custom_express': return `### Custom Express Proxy Server \`\`\`javascript // proxy-server.js const express = require('express'); const { createProxyMiddleware } = require('http-proxy-middleware'); const app = express(); const proxyOptions = { target: '${targetInstance}', changeOrigin: true, secure: ${sslOptions.secure !== false}, ${authentication ? `auth: '${authentication.username}:${authentication.password}',` : ''} pathRewrite: { '^/proxy': '', // Remove /proxy prefix }, onProxyReq: (proxyReq, req, res) => { const auth = Buffer.from('${authentication?.username || 'username'}:${authentication?.password || 'password'}').toString('base64'); proxyReq.setHeader('Authorization', \`Basic \${auth}\`); }, logLevel: 'debug' }; app.use('/api', createProxyMiddleware(proxyOptions)); // Serve static files app.use(express.static('public')); app.listen(${localPort}, () => { console.log(\`Proxy server running on http://localhost:${localPort}\`); console.log(\`Forwarding to: ${targetInstance}\`); }); \`\`\` #### Start proxy server \`\`\`bash node proxy-server.js \`\`\``; default: return '### Custom Proxy Configuration\n```javascript\n// Add your proxy configuration here\n```'; } }