DHIS2 MCP Server

Instructions

Implementation Reference

• src/index.ts:1140-1150 (handler)

  Handler for the 'dhis2_diagnose_cors_issues' tool call. Receives arguments, passes them to diagnoseCORSIssues function from debugging-helpers, and returns the analysis as text content.
  case 'dhis2_diagnose_cors_issues': const corsArgs = args as any; const corsAnalysis = diagnoseCORSIssues(corsArgs); return { content: [ { type: 'text', text: corsAnalysis, }, ], };
• src/debugging-helpers.ts:6-149 (helper)

  Main implementation logic for diagnosing CORS issues. Analyzes browser, symptoms, DHIS2 instance type, and generates comprehensive markdown report with diagnosis, immediate/long-term solutions, testing commands, and browser checklists.
  export function diagnoseCORSIssues(args: any): string { const { dhis2Instance, localDevelopmentUrl, browser, errorMessage = '', symptoms = [] } = args; const diagnosis = []; const solutions = []; // Analyze browser-specific issues if (browser === 'chrome') { diagnosis.push('Chrome has strict SameSite cookie policies since version 94+'); solutions.push('Use the --proxy flag when starting your DHIS2 app: `yarn start --proxy`'); solutions.push('Alternative: Start Chrome with disabled security for development: `google-chrome --disable-web-security --user-data-dir=/tmp/chrome-dev`'); } else if (browser === 'firefox') { diagnosis.push('Firefox recently changed SameSite cookie behavior to be more strict'); solutions.push('Temporarily modify Firefox settings:'); solutions.push(' 1. Open about:config'); solutions.push(' 2. Set `network.cookie.sameSite.laxByDefault` to `false`'); solutions.push(' 3. Set `network.cookie.sameSite.noneRequiresSecure` to `false`'); } // Analyze specific symptoms symptoms.forEach((symptom: string) => { switch (symptom) { case 'login_fails': diagnosis.push('Authentication requests are being blocked by CORS policy'); solutions.push('Add your development URL to DHIS2 CORS allowlist'); solutions.push('Check if DHIS2 instance supports cross-origin authentication'); break; case 'api_requests_blocked': diagnosis.push('API calls are failing due to cross-origin restrictions'); solutions.push('Configure proxy to route requests through same origin'); break; case 'cookies_not_sent': diagnosis.push('Browser is not sending cookies with cross-origin requests'); solutions.push('Use credentials: "include" in fetch requests'); solutions.push('Ensure SameSite cookie settings allow cross-origin'); break; case '302_errors': diagnosis.push('Login endpoint is redirecting, causing CORS preflight failure'); solutions.push('Use direct API authentication instead of login forms'); break; case 'preflight_failed': diagnosis.push('CORS preflight OPTIONS requests are failing'); solutions.push('Check DHIS2 server CORS configuration'); break; } }); // DHIS2 Play server specific issues if (dhis2Instance.includes('play.dhis2.org')) { diagnosis.push('DHIS2 Play instances use nginx with hardened security settings'); solutions.push('⚠️ DHIS2 Play instances prevent cross-site cookies completely'); solutions.push('Recommended: Use local DHIS2 instance for development'); solutions.push('Alternative: Run DHIS2 locally with Docker: `d2 cluster up`'); } return `# CORS Issues Diagnosis ## Configuration Details - **DHIS2 Instance**: ${dhis2Instance} - **Local Development**: ${localDevelopmentUrl} - **Browser**: ${browser.toUpperCase()} - **Error Message**: ${errorMessage} - **Symptoms**: ${symptoms.join(', ')} ## Diagnosis ${diagnosis.map(d => `- ${d}`).join('\n')} ## Recommended Solutions ### Immediate Solutions ${solutions.map((s, i) => `${i + 1}. ${s}`).join('\n')} ### Long-term Solutions 1. **Configure CORS Allowlist** - Login to your DHIS2 instance as admin - Go to Apps → System Settings → Access - Add your development URL to "CORS allowlist" 2. **Use Proxy Configuration** \`\`\`bash # Start with proxy (recommended) yarn start --proxy \`\`\` 3. **Local Development Instance** \`\`\`bash # Set up local DHIS2 instance npx @dhis2/cli cluster init d2 cluster up \`\`\` ## Testing CORS Configuration \`\`\`bash # Test CORS headers curl -H "Origin: ${localDevelopmentUrl}" \\ -H "Access-Control-Request-Method: GET" \\ -H "Access-Control-Request-Headers: X-Requested-With" \\ -X OPTIONS \\ ${dhis2Instance}/api/me # Expected response should include: # Access-Control-Allow-Origin: ${localDevelopmentUrl} # Access-Control-Allow-Credentials: true \`\`\` ## Browser Dev Tools Checklist 1. Open Network tab and check for: - OPTIONS requests (preflight) - Response headers with Access-Control-* - Cookie header presence in requests 2. Console errors related to: - "Cross-Origin Request Blocked" - "CORS policy" messages - SameSite warnings ## Alternative Development Approaches ${dhis2Instance.includes('play.dhis2.org') ? ` ⚠️ Since you're using DHIS2 Play, consider these alternatives: 1. **Local DHIS2 Instance (Recommended)** \`\`\`bash # Quick setup with Docker docker run -d -p 8080:8080 dhis2/core:2.40.4 \`\`\` 2. **Use DHIS2 CLI Cluster** \`\`\`bash npx @dhis2/cli cluster init my-cluster cd my-cluster d2 cluster up \`\`\` 3. **Request Dedicated Development Instance** - Contact your DHIS2 administrator - Request CORS configuration for development URLs ` : ''} ## Security Considerations ⚠️ **Development Only**: Never disable browser security in production ⚠️ **Temporary**: Revert Firefox settings after development ⚠️ **Credentials**: Use separate development credentials `; }
• src/permission-system.ts:145-145 (registration)

  Maps the tool to required permission 'canDebugApplications' in TOOL_PERMISSIONS, used for filtering tools based on user permissions.
  ['dhis2_diagnose_cors_issues', 'canDebugApplications'],