DHIS2 MCP Server

Instructions

Implementation Reference

• src/index.ts:1489-1530 (handler)

  Handler for the dhis2_get_permission_info tool. Generates a comprehensive permission report including user details, permission level, allowed/restricted operations, available tools count by category, and authority count.

        case 'dhis2_get_permission_info':
          const filteredTools = PermissionSystem.filterToolsByPermissions(tools, userPermissions);
          const permInfo = PermissionSystem.getPermissionSummary(userPermissions);
          
          auditLogger.log({
            toolName: name,
            parameters: {},
            outcome: 'success',
            dhis2Instance: dhis2Client?.baseURL,
            userId: currentUser?.username,
            executionTime: Date.now() - startTime
          });
          
          return {
            content: [{
              type: 'text',
              text: `🔐 Permission Information
  
  👤 **User Details:**
    • Name: ${currentUser?.displayName || 'Unknown'}
    • Username: ${currentUser?.username || 'Unknown'}
    • User Groups: ${currentUser?.userGroups?.map((g: any) => g.name).join(', ') || 'None'}
  
  🎯 **Permission Level:** ${permInfo.level}
  📝 **Description:** ${permInfo.description}
  
  ✅ **Allowed Operations:**
  ${permInfo.allowedOperations.map(op => `  • ${op}`).join('\n')}
  
  ${permInfo.restrictedOperations.length > 0 ? `⛔ **Restricted Operations:**
  ${permInfo.restrictedOperations.map(op => `  • ${op}`).join('\n')}` : ''}
  
  🛠️ **Available Tools:** ${filteredTools.length} of ${tools.length} total
    • Configuration: ${filteredTools.filter(t => t.name.includes('configure')).length}
    • Data Management: ${filteredTools.filter(t => t.name.includes('list') || t.name.includes('get')).length}
    • Creation Tools: ${filteredTools.filter(t => t.name.includes('create')).length}
    • Analytics: ${filteredTools.filter(t => t.name.includes('analytics')).length}
    • Development: ${filteredTools.filter(t => t.name.includes('init') || t.name.includes('generate')).length}
  
  🔑 **DHIS2 Authorities:** ${userPermissions.authorities.length} authorities assigned`
            }]
          };

• src/permission-system.ts:287-335 (helper)

  Core helper function that categorizes user permissions into levels (read-only, data-entry, metadata-manager, system-admin, developer) and provides descriptions of allowed and restricted operations. Used by the tool handler.

  static getPermissionSummary(permissions: UserPermissions): {
    level: 'read-only' | 'data-entry' | 'metadata-manager' | 'system-admin' | 'developer';
    description: string;
    allowedOperations: string[];
    restrictedOperations: string[];
  } {
    if (permissions.isReadOnly) {
      return {
        level: 'read-only',
        description: 'Read-only access to DHIS2 data and metadata',
        allowedOperations: ['View data', 'List metadata', 'Run analytics'],
        restrictedOperations: ['Create', 'Update', 'Delete', 'Import operations']
      };
    }
  
    if (permissions.canManageSystem) {
      return {
        level: 'system-admin',
        description: 'Full system administration capabilities',
        allowedOperations: ['All operations', 'User management', 'System configuration'],
        restrictedOperations: []
      };
    }
  
    if (permissions.canConfigureApps && permissions.canDebugApplications) {
      return {
        level: 'developer',
        description: 'Development and debugging capabilities',
        allowedOperations: ['App development', 'Debugging tools', 'Mobile development', 'UI tools'],
        restrictedOperations: permissions.canDeleteMetadata ? [] : ['Metadata deletion']
      };
    }
  
    if (permissions.canCreateMetadata) {
      return {
        level: 'metadata-manager',
        description: 'Metadata management and configuration',
        allowedOperations: ['Create/update metadata', 'Manage programs', 'Configure system'],
        restrictedOperations: permissions.canDeleteMetadata ? [] : ['Delete operations']
      };
    }
  
    return {
      level: 'data-entry',
      description: 'Data entry and basic operations',
      allowedOperations: ['Enter data', 'View reports', 'Basic analytics'],
      restrictedOperations: ['Metadata management', 'System configuration', 'Delete operations']
    };
  }

• src/permission-system.ts:258-284 (helper)

  Helper function that filters available tools based on user permissions. Used in both ListTools response and the permission info tool to count available tools.

  static filterToolsByPermissions(tools: Tool[], permissions: UserPermissions): Tool[] {
    if (permissions.isReadOnly) {
      // In read-only mode, only allow viewing operations
      return tools.filter(tool => 
        !tool.name.includes('create') && 
        !tool.name.includes('update') && 
        !tool.name.includes('delete') &&
        !tool.name.includes('import') &&
        (tool.name.includes('list') || tool.name.includes('get') || tool.name === 'dhis2_configure')
      );
    }
  
    return tools.filter(tool => {
      const requiredPermissions = this.TOOL_PERMISSIONS.get(tool.name);
      if (!requiredPermissions) {
        // If no specific permission is defined, allow by default
        return true;
      }
  
      if (Array.isArray(requiredPermissions)) {
        // All permissions in the array must be satisfied
        return requiredPermissions.every(permission => permissions[permission]);
      } else {
        // Single permission must be satisfied
        return permissions[requiredPermissions];
      }
    });

• src/index.ts:104-111 (registration)

  ListTools handler that registers all tools by returning the filtered list including dhis2_get_permission_info based on permissions.

  server.setRequestHandler(ListToolsRequestSchema, async () => {
    // Filter tools based on user permissions
    const filteredTools = PermissionSystem.filterToolsByPermissions(tools, userPermissions);
    
    return {
      tools: filteredTools,
    };
  });

• src/permission-system.ts:3-42 (schema)

  Type definition for UserPermissions interface used throughout the permission system, serving as schema for permission checks.

  export interface UserPermissions {
    // Core permissions
    canCreateMetadata: boolean;
    canUpdateMetadata: boolean;
    canDeleteMetadata: boolean;
    canViewMetadata: boolean;
    
    // Data permissions
    canEnterData: boolean;
    canViewData: boolean;
    canImportData: boolean;
    canExportData: boolean;
    canDeleteData: boolean;
    
    // System permissions
    canManageUsers: boolean;
    canManageSystem: boolean;
    canViewSystemInfo: boolean;
    canRunAnalytics: boolean;
    canManageDashboards: boolean;
    
    // Program permissions
    canManagePrograms: boolean;
    canEnrollTEI: boolean;
    canViewTEI: boolean;
    canManageTrackerData: boolean;
    
    // Mobile/Android permissions
    canUseMobileFeatures: boolean;
    canConfigureMobile: boolean;
    
    // UI/Development permissions
    canUseUITools: boolean;
    canConfigureApps: boolean;
    canDebugApplications: boolean;
    
    // Special permissions
    isReadOnly: boolean;
    authorities: string[];
  }