DHIS2 MCP Server

Instructions

Implementation Reference

• src/index.ts:1152-1162 (handler)

  The primary handler for the 'dhis2_configure_cors_allowlist' tool. It receives arguments, calls generateCORSConfiguration from debugging-helpers.ts, and returns the generated Markdown guide as tool response content.

  case 'dhis2_configure_cors_allowlist':
    const corsAllowlistArgs = args as any;
    const corsConfig = generateCORSConfiguration(corsAllowlistArgs);
    return {
      content: [
        {
          type: 'text',
          text: corsConfig,
        },
      ],
    };

• src/debugging-helpers.ts:151-308 (helper)

  Core helper function that generates comprehensive Markdown documentation for configuring DHIS2 CORS allowlist. Includes step-by-step GUI instructions, system properties config, environment-specific examples, validation curl commands, troubleshooting, and security best practices.

  export function generateCORSConfiguration(args: any): string {
    const { allowedOrigins, dhis2Version = '2.40.4', includeSteps = true } = args;
  
    return `# DHIS2 CORS Configuration Guide
  
  ## System Settings Configuration
  
  ${includeSteps ? `
  ### Step-by-Step Instructions
  1. **Login to DHIS2** as a user with system administration privileges
  2. **Navigate to System Settings**
     - Click on the Apps icon (grid icon)
     - Search for "System Settings"
     - Click on the System Settings app
  3. **Configure CORS**
     - In the left sidebar, click "Access"
     - Scroll down to find "CORS allowlist"
     - Add your development URLs
  4. **Save Changes**
     - Click "Save" at the bottom of the page
     - Wait for confirmation message
  ` : ''}
  
  ## CORS Allowlist Configuration
  
  ### URLs to Add
  ${allowedOrigins.map((url: string) => `- ${url}`).join('\n')}
  
  ### Configuration Format
  \`\`\`
  ${allowedOrigins.join('\n')}
  \`\`\`
  
  ## Advanced CORS Configuration (System Properties)
  
  For system administrators, you can also configure CORS via system properties:
  
  ### dhis.conf Configuration
  \`\`\`properties
  # CORS Configuration
  cors.allowedOrigins=${allowedOrigins.join(',')}
  cors.allowCredentials=true
  cors.allowedMethods=GET,POST,PUT,DELETE,OPTIONS,PATCH
  cors.allowedHeaders=Accept,Content-Type,Origin,X-Requested-With,Authorization
  cors.maxAge=3600
  \`\`\`
  
  ## Environment-Specific Configurations
  
  ### Development Environment
  \`\`\`
  # Local development
  http://localhost:3000
  http://localhost:3001
  http://127.0.0.1:3000
  
  # Common development ports
  http://localhost:8080
  http://localhost:9000
  \`\`\`
  
  ### Staging Environment  
  \`\`\`
  https://staging-app.yourdomain.com
  https://test-app.yourdomain.com
  \`\`\`
  
  ### Production Environment
  \`\`\`
  https://app.yourdomain.com
  https://health-dashboard.yourdomain.com
  \`\`\`
  
  ## Validation Commands
  
  ### Test CORS Configuration
  \`\`\`bash
  # Test basic CORS
  curl -H "Origin: ${allowedOrigins[0]}" \\
       ${dhis2Version ? `https://your-dhis2-instance.com/api/system/info` : 'https://your-dhis2-instance.com/api/system/info'}
  
  # Test with authentication
  curl -H "Origin: ${allowedOrigins[0]}" \\
       -H "Authorization: Basic $(echo -n 'username:password' | base64)" \\
       https://your-dhis2-instance.com/api/me
  
  # Test preflight request
  curl -H "Origin: ${allowedOrigins[0]}" \\
       -H "Access-Control-Request-Method: POST" \\
       -H "Access-Control-Request-Headers: Content-Type" \\
       -X OPTIONS \\
       https://your-dhis2-instance.com/api/dataElements
  \`\`\`
  
  ### Expected Response Headers
  \`\`\`
  Access-Control-Allow-Origin: ${allowedOrigins[0]}
  Access-Control-Allow-Credentials: true
  Access-Control-Allow-Methods: GET, POST, PUT, DELETE, OPTIONS, PATCH
  Access-Control-Allow-Headers: Accept, Content-Type, Origin, X-Requested-With, Authorization
  Access-Control-Max-Age: 3600
  \`\`\`
  
  ## Troubleshooting Common Issues
  
  ### Issue: "CORS allowlist not found"
  **Solution**: Update to DHIS2 2.35+ (older versions use different settings)
  
  ### Issue: "Changes not taking effect"
  **Solutions**:
  1. Clear browser cache completely
  2. Restart DHIS2 server (if self-hosted)
  3. Wait 5-10 minutes for changes to propagate
  4. Check if nginx/reverse proxy needs updating
  
  ### Issue: "Still getting CORS errors"
  **Checklist**:
  - [ ] URLs match exactly (including protocol)
  - [ ] No trailing slashes mismatch
  - [ ] Case sensitivity check
  - [ ] Wildcard not used (DHIS2 doesn't support wildcards)
  - [ ] Browser cache cleared
  
  ## Security Best Practices
  
  ### Development
  - Only add localhost URLs for development
  - Use specific ports, not wildcards
  - Remove development URLs before production
  
  ### Production
  - Only add your production domain(s)
  - Use HTTPS URLs only
  - Regularly audit allowed origins
  - Document all entries with purpose
  
  ### Monitoring
  \`\`\`bash
  # Check current CORS settings via API
  curl -u admin:password \\
    https://your-dhis2-instance.com/api/systemSettings/keyJsCorallowlist
  \`\`\`
  
  ## Version-Specific Notes
  
  ${dhis2Version >= '2.38' ? `
  ### DHIS2 ${dhis2Version}+
  - Full CORS support available
  - GUI configuration available
  - API endpoint for configuration
  ` : `
  ### DHIS2 ${dhis2Version}
  - Limited CORS support
  - May require manual configuration
  - Check documentation for version-specific settings
  `}
  `;
  }

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

  Tool permission registration in TOOL_PERMISSIONS Map. Associates 'dhis2_configure_cors_allowlist' with 'canDebugApplications' permission, enabling permission-based filtering of available tools.

  ['dhis2_configure_cors_allowlist', 'canDebugApplications'],