mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/content-masking-tool.ts:1093-1151 (handler)

  The primary MCP tool handler function for 'apply_basic_content_masking'. It receives arguments, applies basic masking using imported utilities from content-masking.ts, validates the result, and returns a formatted MCP response.

  export async function applyBasicContentMasking(args: {
    content: string;
    maskingStrategy?: 'full' | 'partial' | 'placeholder';
  }): Promise<any> {
    const { content, maskingStrategy = 'full' } = args;
  
    try {
      const { applyBasicMasking, validateMasking } = await import('../utils/content-masking.js');
  
      if (!content || content.trim().length === 0) {
        throw new McpAdrError('Content is required for masking', 'INVALID_INPUT');
      }
  
      const maskedContent = applyBasicMasking(content, maskingStrategy);
      const validation = validateMasking(content, maskedContent);
  
      return {
        content: [
          {
            type: 'text',
            text: `# Basic Content Masking Applied
  
  ## Masking Strategy
  ${maskingStrategy}
  
  ## Original Content Length
  ${content.length} characters
  
  ## Masked Content
  \`\`\`
  ${maskedContent}
  \`\`\`
  
  ## Validation Results
  - **Security Score**: ${(validation.securityScore * 100).toFixed(1)}%
  - **Is Valid**: ${validation.isValid ? '✅ Yes' : '❌ No'}
  
  ${
    validation.issues.length > 0
      ? `## Issues Found
  ${validation.issues.map(issue => `- ${issue}`).join('\n')}`
      : '## ✅ No Issues Found'
  }
  
  ## Recommendations
  - For better security analysis, use AI-powered detection with \`analyze_content_security\`
  - Consider using custom patterns for project-specific sensitive information
  - Review masked content to ensure it maintains necessary functionality
  `,
          },
        ],
      };
    } catch (error) {
      throw new McpAdrError(
        `Failed to apply basic masking: ${error instanceof Error ? error.message : String(error)}`,
        'MASKING_ERROR'
      );
    }
  }

• src/tools/tool-catalog.ts:510-528 (registration)

  Central tool catalog registration including metadata, category, input schema, and CE-MCP directive for the 'apply_basic_content_masking' tool.

  TOOL_CATALOG.set('apply_basic_content_masking', {
    name: 'apply_basic_content_masking',
    shortDescription: 'Apply basic content masking',
    fullDescription: 'Applies basic content masking using predefined patterns.',
    category: 'content-security',
    complexity: 'simple',
    tokenCost: { min: 200, max: 500 },
    hasCEMCPDirective: true, // Phase 4.3: Simple tool - single masking operation
    relatedTools: ['generate_content_masking', 'configure_custom_patterns'],
    keywords: ['masking', 'apply', 'basic', 'content'],
    requiresAI: false,
    inputSchema: {
      type: 'object',
      properties: {
        content: { type: 'string' },
      },
      required: ['content'],
    },
  });

• src/types/tool-arguments.ts:245-248 (schema)

  TypeScript interface defining the input arguments for the apply_basic_content_masking tool.

  export interface ApplyBasicContentMaskingArgs {
    content: string;
    maskingStrategy?: 'full' | 'partial' | 'placeholder';
  }

• src/utils/content-masking.ts:224-272 (helper)

  Core utility function implementing the basic regex-based content masking logic used by the tool handler.

  export function applyBasicMasking(
    content: string,
    maskingStrategy: 'full' | 'partial' | 'placeholder' = 'full'
  ): string {
    // Basic patterns for common sensitive information
    const patterns = [
      // API Keys
      {
        pattern: /sk-[a-zA-Z0-9]{32,}/g,
        replacement: maskingStrategy === 'partial' ? 'sk-...****' : '[API_KEY_REDACTED]',
      },
      {
        pattern: /ghp_[a-zA-Z0-9]{36}/g,
        replacement: maskingStrategy === 'partial' ? 'ghp_...****' : '[GITHUB_TOKEN_REDACTED]',
      },
  
      // AWS Keys
      {
        pattern: /AKIA[0-9A-Z]{16}/g,
        replacement: maskingStrategy === 'partial' ? 'AKIA...****' : '[AWS_ACCESS_KEY_REDACTED]',
      },
  
      // Email addresses
      {
        pattern: /\b[A-Za-z0-9._%+-]+@[A-Za-z0-9.-]+\.[A-Z|a-z]{2,}\b/g,
        replacement: maskingStrategy === 'partial' ? '***@***.***' : '[EMAIL_REDACTED]',
      },
  
      // IP Addresses (private ranges)
      {
        pattern: /\b(?:10\.|172\.(?:1[6-9]|2[0-9]|3[01])\.|192\.168\.)\d{1,3}\.\d{1,3}\b/g,
        replacement: '[IP_ADDRESS_REDACTED]',
      },
  
      // Common password patterns
      {
        pattern: /password\s*[:=]\s*["']?[^"'\s]+["']?/gi,
        replacement: 'password=[PASSWORD_REDACTED]',
      },
    ];
  
    let maskedContent = content;
  
    for (const { pattern, replacement } of patterns) {
      maskedContent = maskedContent.replace(pattern, replacement);
    }
  
    return maskedContent;
  }

• src/utils/content-masking.ts:277-315 (helper)

  Utility function that validates the masking effectiveness by checking for remaining sensitive patterns and computing a security score.

  export function validateMasking(
    originalContent: string,
    maskedContent: string
  ): {
    isValid: boolean;
    issues: string[];
    securityScore: number;
  } {
    const issues: string[] = [];
    let securityScore = 1.0;
  
    // Check for common patterns that should have been masked
    const sensitivePatterns = [
      /sk-[a-zA-Z0-9]{32,}/g,
      /ghp_[a-zA-Z0-9]{36}/g,
      /AKIA[0-9A-Z]{16}/g,
      /password\s*[:=]\s*["']?[^"'\s\\[\\]]+["']?/gi,
    ];
  
    for (const pattern of sensitivePatterns) {
      const matches = maskedContent.match(pattern);
      if (matches) {
        issues.push(`Potential unmasked sensitive content found: ${matches[0].substring(0, 10)}...`);
        securityScore -= 0.2;
      }
    }
  
    // Check that masking was actually applied
    if (originalContent === maskedContent) {
      issues.push('No masking appears to have been applied');
      securityScore = 0;
    }
  
    return {
      isValid: issues.length === 0,
      issues,
      securityScore: Math.max(0, securityScore),
    };
  }