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'],