DHIS2 MCP Server

Instructions

Implementation Reference

• src/debugging-helpers.ts:1578-1783 (handler)

  The main handler function that executes the tool logic. It generates a comprehensive markdown report validating the DHIS2 development environment, checking Node.js version, package managers, DHIS2 CLI, browser settings, network connectivity, and CORS configuration. Includes automated scripts and troubleshooting guides.

  export function validateEnvironment(args: any): string {
    const { checkAll = false, components = [], nodeVersion, dhis2Instance, operatingSystem = 'unknown' } = args;
  
    const checks = checkAll ? [
      'node_version', 'npm_yarn', 'dhis2_cli', 'browser_settings', 'network_connectivity', 'cors_config'
    ] : components;
  
    return `# DHIS2 Development Environment Validation
  
  ## Environment Information
  - **Operating System**: ${operatingSystem.toUpperCase()}
  - **Node Version**: ${nodeVersion || 'Not provided'}
  - **DHIS2 Instance**: ${dhis2Instance || 'Not provided'}
  
  ## Validation Results
  
  ${checks.map((check: string) => generateEnvironmentCheck(check, { nodeVersion, dhis2Instance, operatingSystem })).join('\n\n')}
  
  ## Automated Validation Script
  
  \`\`\`bash
  #!/bin/bash
  # DHIS2 Environment Validator
  
  echo "🔍 DHIS2 Development Environment Validation"
  echo "============================================"
  
  # Node.js version check
  echo "📦 Checking Node.js version..."
  NODE_VERSION=$(node --version)
  echo "Node.js: $NODE_VERSION"
  
  if [[ "$NODE_VERSION" < "v16" ]]; then
    echo "❌ Node.js 16+ required"
  else
    echo "✅ Node.js version OK"
  fi
  
  # Package manager check
  echo "📦 Checking package managers..."
  if command -v npm &> /dev/null; then
    echo "✅ npm: $(npm --version)"
  else
    echo "❌ npm not found"
  fi
  
  if command -v yarn &> /dev/null; then
    echo "✅ yarn: $(yarn --version)"
  else
    echo "⚠️  yarn not found (recommended for DHIS2)"
  fi
  
  # DHIS2 CLI check
  echo "🔧 Checking DHIS2 CLI tools..."
  if command -v d2 &> /dev/null; then
    echo "✅ d2 CLI: $(d2 --version)"
  else
    echo "❌ d2 CLI not found"
    echo "Install: npm install -g @dhis2/cli"
  fi
  
  # Network connectivity check
  ${dhis2Instance ? `
  echo "🌐 Testing DHIS2 instance connectivity..."
  if curl -Is "${dhis2Instance}/api/system/info" | head -n 1 | grep -q "200 OK"; then
    echo "✅ DHIS2 instance reachable"
  else
    echo "❌ Cannot reach DHIS2 instance"
  fi
  ` : ''}
  
  echo "✅ Environment validation complete"
  \`\`\`
  
  ## Fix Common Issues
  
  ### Node.js Version Issues
  \`\`\`bash
  # Install Node Version Manager
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
  
  # Install and use Node.js 18 LTS
  nvm install 18
  nvm use 18
  nvm alias default 18
  \`\`\`
  
  ### Package Manager Issues
  \`\`\`bash
  # Install/Update yarn (recommended for DHIS2)
  npm install -g yarn
  
  # Clear package caches
  npm cache clean --force
  yarn cache clean
  \`\`\`
  
  ### DHIS2 CLI Issues
  \`\`\`bash
  # Install DHIS2 CLI tools
  npm install -g @dhis2/cli
  
  # Verify installation
  d2 --version
  d2 --help
  \`\`\`
  
  ## Development Environment Setup
  
  ### Complete Setup Script
  \`\`\`bash
  #!/bin/bash
  # Complete DHIS2 development environment setup
  
  echo "🚀 Setting up DHIS2 development environment..."
  
  # Install Node.js 18 LTS (if using nvm)
  nvm install 18
  nvm use 18
  
  # Install global tools
  npm install -g @dhis2/cli yarn
  
  # Verify installations
  echo "Node.js: $(node --version)"
  echo "npm: $(npm --version)"
  echo "yarn: $(yarn --version)"
  echo "DHIS2 CLI: $(d2 --version)"
  
  # Create development project
  mkdir my-dhis2-app
  cd my-dhis2-app
  
  # Initialize DHIS2 app
  d2 app scripts init my-app
  cd my-app
  
  # Install dependencies
  yarn install
  
  echo "✅ DHIS2 development environment ready!"
  echo "Run 'yarn start' to begin development"
  \`\`\`
  
  ## IDE Configuration
  
  ### VS Code Extensions
  \`\`\`json
  {
    "recommendations": [
      "ms-vscode.vscode-typescript-next",
      "bradlc.vscode-tailwindcss",
      "esbenp.prettier-vscode",
      "ms-vscode.vscode-eslint",
      "formulahendry.auto-rename-tag",
      "christian-kohler.path-intellisense"
    ]
  }
  \`\`\`
  
  ### VS Code Settings
  \`\`\`json
  {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "esbenp.prettier-vscode",
    "typescript.preferences.importModuleSpecifier": "relative",
    "emmet.includeLanguages": {
      "javascript": "javascriptreact"
    }
  }
  \`\`\`
  
  ## Troubleshooting Common Environment Issues
  
  ### Permission Issues (macOS/Linux)
  \`\`\`bash
  # Fix npm permissions
  sudo chown -R $(whoami) $(npm config get prefix)/{lib/node_modules,bin,share}
  
  # Alternative: Use nvm to avoid sudo
  curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.39.0/install.sh | bash
  \`\`\`
  
  ### Windows-Specific Issues
  \`\`\`powershell
  # Set execution policy (Windows PowerShell as Administrator)
  Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser
  
  # Install Node.js via Chocolatey
  choco install nodejs
  
  # Install yarn
  choco install yarn
  \`\`\`
  
  ### Network/Corporate Firewall Issues
  \`\`\`bash
  # Configure npm proxy (if behind corporate firewall)
  npm config set proxy http://proxy.company.com:8080
  npm config set https-proxy http://proxy.company.com:8080
  
  # Configure yarn proxy
  yarn config set proxy http://proxy.company.com:8080
  yarn config set https-proxy http://proxy.company.com:8080
  \`\`\`
  `;

• src/index.ts:1212-1222 (registration)

  The tool dispatch/registration in the main MCP server handler. Calls the validateEnvironment function from debugging-helpers.ts with user arguments and returns the markdown result.

  case 'dhis2_validate_environment':
    const envArgs = args as any;
    const envValidation = validateEnvironment(envArgs);
    return {
      content: [
        {
          type: 'text',
          text: envValidation,
        },
      ],
    };

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

  Permission mapping registration. Associates the tool with 'canDebugApplications' permission in the TOOL_PERMISSIONS map.

  ['dhis2_validate_environment', 'canDebugApplications'],