DHIS2 MCP Server

Instructions

Implementation Reference

• src/webapp-generators.ts:1193-1224 (handler)

  The primary handler function that generates comprehensive Markdown documentation for DHIS2 app testing setup. It supports multiple frameworks (Jest, Cypress, Playwright), test types (unit, integration, E2E, visual), coverage configuration, and mock setups by composing helper functions to produce ready-to-use config files, examples, and commands.

  export function generateTestSetup(args: any): string {
    const { testFramework, testTypes = [], coverage = {}, mockSetup = {} } = args;
  
    return `# DHIS2 Testing Setup
  
  ## ${testFramework.toUpperCase()} Configuration
  
  ${generateTestFrameworkConfig(testFramework, coverage)}
  
  ${testTypes.includes('unit') ? generateUnitTestExamples() : ''}
  ${testTypes.includes('integration') ? generateIntegrationTestExamples() : ''}
  ${testTypes.includes('e2e') ? generateE2ETestExamples(testFramework) : ''}
  ${testTypes.includes('visual') ? generateVisualTestExamples() : ''}
  
  ${Object.keys(mockSetup).length > 0 ? generateMockConfiguration(mockSetup) : ''}
  
  ## Test Commands
  \`\`\`bash
  # Run all tests
  ${testFramework === 'jest' ? 'npm test' : testFramework === 'cypress' ? 'npx cypress open' : 'npx playwright test'}
  
  # Run with coverage
  ${testFramework === 'jest' ? 'npm test -- --coverage' : 'npm run test:coverage'}
  
  # Run specific test file
  ${testFramework === 'jest' ? 'npm test -- MyComponent.test.js' : testFramework === 'cypress' ? 'npx cypress run --spec "cypress/integration/MyComponent.spec.js"' : 'npx playwright test tests/MyComponent.spec.ts'}
  
  # Watch mode
  ${testFramework === 'jest' ? 'npm test -- --watch' : 'npm run test:watch'}
  \`\`\`
  `;
  }

• src/index.ts:1127-1137 (registration)

  The tool dispatch logic in the main MCP server CallToolRequest handler. Receives arguments, invokes the generateTestSetup handler, and formats the response as MCP content.

  case 'dhis2_generate_test_setup':
    const testArgs = args as any;
    const testSetup = generateTestSetup(testArgs);
    return {
      content: [
        {
          type: 'text',
          text: testSetup,
        },
      ],
    };

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

  Permission mapping in TOOL_PERMISSIONS Map associating the tool with 'canConfigureApps' permission for runtime access control via PermissionSystem.filterToolsByPermissions().

  ['dhis2_generate_test_setup', 'canConfigureApps'],

• src/webapp-generators.ts:1875-1993 (helper)

  Key helper function called by the handler to generate framework-specific test configuration (jest.config.js, cypress.json, playwright.config.ts) including DHIS2-specific mocks and coverage thresholds.

  function generateTestFrameworkConfig(framework: string, coverage: any): string {
    switch (framework) {
      case 'jest':
        return `### Jest Configuration (jest.config.js)
  \`\`\`javascript
  module.exports = {
    testEnvironment: 'jsdom',
    setupFilesAfterEnv: ['<rootDir>/src/setupTests.js'],
    moduleNameMapping: {
      '\\\\.(css|less|scss|sass)$': 'identity-obj-proxy',
    },
    transform: {
      '^.+\\\\.(js|jsx|ts|tsx)$': 'babel-jest',
    },
    collectCoverageFrom: [
      'src/**/*.{js,jsx,ts,tsx}',
      '!src/index.js',
      '!src/serviceWorker.js',
    ],
    coverageThreshold: {
      global: {
        branches: ${coverage.threshold || 80},
        functions: ${coverage.threshold || 80},
        lines: ${coverage.threshold || 80},
        statements: ${coverage.threshold || 80},
      },
    },
    coverageReporters: ${JSON.stringify(coverage.reports || ['text', 'html'])},
  };
  \`\`\`
  
  ### Setup File (src/setupTests.js)
  \`\`\`javascript
  import '@testing-library/jest-dom';
  import { configure } from '@testing-library/react';
  
  configure({ testIdAttribute: 'data-test' });
  
  // Mock DHIS2 App Runtime
  jest.mock('@dhis2/app-runtime', () => ({
    useDataQuery: jest.fn(),
    useDataMutation: jest.fn(),
    useAlert: jest.fn(() => ({ show: jest.fn() })),
  }));
  \`\`\``;
  
      case 'cypress':
        return `### Cypress Configuration (cypress.json)
  \`\`\`json
  {
    "baseUrl": "http://localhost:3000",
    "integrationFolder": "cypress/integration",
    "fixturesFolder": "cypress/fixtures",
    "supportFile": "cypress/support/index.js",
    "video": true,
    "screenshotOnRunFailure": true,
    "defaultCommandTimeout": 10000,
    "env": {
      "dhis2BaseUrl": "https://play.dhis2.org/2.40.4",
      "dhis2Username": "admin",
      "dhis2Password": "district"
    }
  }
  \`\`\`
  
  ### Cypress Commands (cypress/support/commands.js)
  \`\`\`javascript
  Cypress.Commands.add('loginToDHIS2', (username, password) => {
    cy.request({
      method: 'POST',
      url: \`\${Cypress.env('dhis2BaseUrl')}/api/auth/login\`,
      body: { username, password }
    }).then((resp) => {
      window.localStorage.setItem('dhis2.auth', JSON.stringify(resp.body));
    });
  });
  \`\`\``;
  
      case 'playwright':
        return `### Playwright Configuration (playwright.config.ts)
  \`\`\`typescript
  import { defineConfig, devices } from '@playwright/test';
  
  export default defineConfig({
    testDir: './tests',
    fullyParallel: true,
    forbidOnly: !!process.env.CI,
    retries: process.env.CI ? 2 : 0,
    workers: process.env.CI ? 1 : undefined,
    reporter: 'html',
    use: {
      baseURL: 'http://localhost:3000',
      trace: 'on-first-retry',
    },
    projects: [
      {
        name: 'chromium',
        use: { ...devices['Desktop Chrome'] },
      },
      {
        name: 'firefox',
        use: { ...devices['Desktop Firefox'] },
      },
      {
        name: 'webkit',
        use: { ...devices['Desktop Safari'] },
      },
    ],
    webServer: {
      command: 'npm start',
      port: 3000,
    },
  });
  \`\`\``;
  
      default:
        return '### Custom Test Configuration\n```javascript\n// Add your configuration here\n```';
    }
  }