quality-mcp/src/core/plugin-definitions.js

An MCP server that analyzes to your codebase, with plugin support for DCD and Simian. 🏍️ "The only Zen you find on the tops of mountains is the Zen you bring up there."

/**
 * Enhanced Plugin Definition System
 * Provides rich, AI-friendly descriptions of plugin capabilities
 */

/**
 * Plugin Capability Definition
 * Defines what a plugin can do with detailed descriptions for AI consumption
 */
export class PluginCapabilityDefinition {
  constructor(pluginName, config = {}) {
    this.pluginName = pluginName;
    this.config = config;
    this.tools = new Map();
    this.resources = new Map();
    this.prompts = new Map();
    this.operations = new Map();
  }

  /**
   * Define a tool with comprehensive description
   */
  defineTool(name, definition) {
    this.tools.set(name, {
      name,
      description: definition.description,
      longDescription: definition.longDescription,
      inputSchema: definition.inputSchema,
      outputSchema: definition.outputSchema,
      examples: definition.examples || [],
      useCases: definition.useCases || [],
      limitations: definition.limitations || [],
      performanceNotes: definition.performanceNotes || [],
      relatedTools: definition.relatedTools || [],
    });
  }

  /**
   * Define a resource with comprehensive description
   */
  defineResource(uri, definition) {
    this.resources.set(uri, {
      uri,
      name: definition.name,
      description: definition.description,
      longDescription: definition.longDescription,
      mimeType: definition.mimeType,
      structure: definition.structure,
      examples: definition.examples || [],
      updateFrequency: definition.updateFrequency,
    });
  }

  /**
   * Define an operation (internal method) with description
   */
  defineOperation(name, definition) {
    this.operations.set(name, {
      name,
      description: definition.description,
      purpose: definition.purpose,
      parameters: definition.parameters,
      returns: definition.returns,
      sideEffects: definition.sideEffects || [],
      complexity: definition.complexity,
      dependencies: definition.dependencies || [],
    });
  }

  /**
   * Get tool definitions in MCP format
   */
  getToolDefinitions() {
    return Array.from(this.tools.values()).map(tool => {
      return {
        name: tool.name,
        description: tool.description,
        inputSchema: tool.inputSchema,
      };
    });
  }

  /**
   * Get resource definitions in MCP format
   */
  getResourceDefinitions() {
    return Array.from(this.resources.values()).map(resource => {
      return {
        uri: resource.uri,
        name: resource.name,
        description: resource.description,
        mimeType: resource.mimeType,
      };
    });
  }

  /**
   * Get comprehensive capability description for AI
   */
  getCapabilityDescription() {
    return {
      pluginName: this.pluginName,
      tools: Array.from(this.tools.values()),
      resources: Array.from(this.resources.values()),
      operations: Array.from(this.operations.values()),
    };
  }
}

/**
 * DCD Plugin Capability Definition
 * Based on actual DCD documentation and capabilities
 */
export function createDCDCapabilityDefinition() {
  const definition = new PluginCapabilityDefinition('dcd', {
    name: 'DCD (Duplicate Code Detector)',
    version: '1.1.0',
    license: 'AGPL-3.0',
    author: 'Ben Boyter',
    homepage: 'https://github.com/boyter/dcd',
  });

  // Define analyze_duplicates_dcd tool
  definition.defineTool('analyze_duplicates_dcd', {
    description:
      'Detect duplicate code using DCD (open source alternative to Simian). Returns optimized overview by default. Say "show details" for complete analysis.',
    longDescription: `
      Analyzes files or directories to identify duplicate code blocks using DCD (Duplicate Code Detector).
      DCD is a fast, open-source tool that finds exact and fuzzy matches in source code.
      
      Key Features:
      - Language-independent text-based detection
      - Configurable minimum match length (default: 6 lines)
      - Fuzzy matching support (0-255 fuzziness levels)
      - File extension filtering
      - Respects .gitignore and .ignore files
      - Fast performance on large codebases
      
      DCD identifies duplicate code by comparing line sequences and can handle:
      - Exact matches (fuzziness = 0)
      - Minor variations (fuzziness 1-50)
      - Significant variations (fuzziness 51-255)
      
      Output includes detailed location information, line counts, and similarity fingerprints.
      
      IMPORTANT: This tool requires DCD to be installed. If DCD is not available, the tool will not be exposed.
      Install DCD with: go install github.com/boyter/dcd@latest
    `,
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'File or directory path to analyze (required)',
        },
        matchLength: {
          type: 'integer',
          description:
            'Minimum number of consecutive lines to consider as duplicate (default: 6, minimum: 1)',
          minimum: 1,
          default: 6,
        },
        extensions: {
          type: 'array',
          items: { type: 'string' },
          description:
            'File extensions to include (e.g., [".js", ".ts", ".jsx", ".tsx"]). If not specified, all text files are analyzed.',
        },
        fuzziness: {
          type: 'integer',
          description:
            'Fuzzy matching level where 0 = exact match, 255 = very fuzzy. Higher values detect more variations but may have false positives.',
          minimum: 0,
          maximum: 255,
          default: 0,
        },
      },
      required: ['path'],
    },
    outputSchema: {
      type: 'object',
      properties: {
        summary: {
          type: 'object',
          description: 'Analysis summary statistics',
          properties: {
            totalFiles: { type: 'integer', description: 'Total files analyzed' },
            duplicateLines: { type: 'integer', description: 'Total duplicate lines found' },
            duplicateBlocks: { type: 'integer', description: 'Number of duplicate blocks found' },
            analysisTime: { type: 'string', description: 'Time taken for analysis' },
            tool: { type: 'string', description: 'Tool used (DCD)' },
          },
        },
        duplicates: {
          type: 'array',
          description: 'Detailed duplicate code blocks found',
          items: {
            type: 'object',
            properties: {
              fingerprint: {
                type: 'string',
                description: 'Unique identifier for this duplicate pattern',
              },
              lineCount: { type: 'integer', description: 'Number of lines in the duplicate block' },
              occurrences: {
                type: 'array',
                description: 'All locations where this duplicate appears',
                items: {
                  type: 'object',
                  properties: {
                    file: { type: 'string', description: 'File path' },
                    startLine: { type: 'integer', description: 'Starting line number' },
                    endLine: { type: 'integer', description: 'Ending line number' },
                  },
                },
              },
            },
          },
        },
      },
    },
    examples: [
      {
        name: 'Basic JavaScript analysis',
        input: { path: 'src/', matchLength: 6, extensions: ['.js', '.jsx'] },
        description: 'Find duplicates in JavaScript files with minimum 6 lines',
      },
      {
        name: 'Fuzzy matching for similar code',
        input: { path: 'components/', matchLength: 4, fuzziness: 10 },
        description: 'Find similar code blocks allowing minor variations',
      },
      {
        name: 'Strict exact matching',
        input: { path: 'utils.js', matchLength: 3, fuzziness: 0 },
        description: 'Find exact duplicates in a single file',
      },
    ],
    useCases: [
      'Code review and quality assessment',
      'Identifying refactoring opportunities',
      'Technical debt analysis',
      'Detecting copy-paste programming',
      'Code cleanup and consolidation',
      'Pre-commit duplicate detection',
    ],
    limitations: [
      'Text-based detection only (no semantic analysis)',
      'Minimum match length affects sensitivity',
      'Fuzzy matching may produce false positives',
      'Large files may be truncated (10MB limit)',
      'Minified files may be skipped',
    ],
    performanceNotes: [
      'Very fast on large codebases (written in Go)',
      'Memory efficient',
      'Respects .gitignore to skip irrelevant files',
      'Can handle repositories with thousands of files',
    ],
    relatedTools: ['scan_repository_dcd'],
  });

  // Define scan_repository_dcd tool
  definition.defineTool('scan_repository_dcd', {
    description:
      'Comprehensive repository scan using DCD. Returns optimized overview by default. Say "show details" for complete analysis.',
    longDescription: `
      Performs a comprehensive duplicate code analysis across an entire repository using DCD.
      This tool is optimized for large-scale analysis and includes advanced filtering options.
      
      Features:
      - Repository-wide analysis
      - Intelligent file filtering
      - Exclude pattern support (e.g., node_modules, .git)
      - Automatic .gitignore and .ignore file respect
      - Progress tracking for large repositories
      - Optimized for CI/CD integration
      
      The tool automatically excludes common non-source directories and respects project
      ignore files to focus on relevant source code. Results are structured for easy
      integration with code quality tools and dashboards.
      
      IMPORTANT: This tool requires DCD to be installed. If DCD is not available, the tool will not be exposed.
      Install DCD with: go install github.com/boyter/dcd@latest
    `,
    inputSchema: {
      type: 'object',
      properties: {
        repository: {
          type: 'string',
          description: 'Repository root path to scan (required)',
        },
        matchLength: {
          type: 'integer',
          description: 'Minimum number of consecutive lines to consider as duplicate (default: 6)',
          minimum: 1,
          default: 6,
        },
        excludePatterns: {
          type: 'array',
          items: { type: 'string' },
          description:
            'Patterns to exclude from analysis (e.g., ["node_modules", ".git", "dist", "vendor"])',
        },
      },
      required: ['repository'],
    },
    outputSchema: {
      type: 'object',
      properties: {
        summary: {
          type: 'object',
          description: 'Repository analysis summary',
          properties: {
            totalFiles: { type: 'integer', description: 'Total files analyzed' },
            duplicateLines: { type: 'integer', description: 'Total duplicate lines found' },
            duplicateBlocks: { type: 'integer', description: 'Number of duplicate blocks found' },
            analysisTime: { type: 'string', description: 'Time taken for analysis' },
            tool: { type: 'string', description: 'Tool used (DCD)' },
          },
        },
        duplicates: {
          type: 'array',
          description: 'All duplicate code blocks found in the repository',
        },
      },
    },
    examples: [
      {
        name: 'Full repository scan',
        input: { repository: '.', matchLength: 6 },
        description: 'Scan entire repository with default settings',
      },
      {
        name: 'Exclude common directories',
        input: { repository: '.', excludePatterns: ['node_modules', 'dist', '.git'] },
        description: 'Scan repository excluding build and dependency directories',
      },
    ],
    useCases: [
      'Repository quality assessment',
      'Technical debt measurement',
      'Code review preparation',
      'Refactoring planning',
      'Team code quality monitoring',
      'CI/CD quality gates',
    ],
    limitations: [
      'Large repositories may take time to process',
      'Exclude patterns must be carefully configured',
      'Results may be large for repositories with many duplicates',
    ],
    performanceNotes: [
      'Optimized for large repositories',
      'Automatic file filtering reduces analysis time',
      'Progress tracking available for long-running scans',
    ],
    relatedTools: ['analyze_duplicates_dcd'],
  });

  // Define get_optimization_info tool
  definition.defineTool('get_optimization_info', {
    description: '📖 Learn about response optimization: how to get detailed vs overview responses',
    longDescription: `
      Explains the simple optimization system used by this plugin:
      
      - By default, all analysis tools return optimized overviews (90%+ smaller responses)
      - These overviews include key insights, summaries, and actionable recommendations
      - To get complete detailed analysis, simply say "show details" in your request
      - No complex keywords to remember - just "show details" when you need everything
      
      This progressive disclosure approach ensures fast, relevant responses by default
      while providing an easy way to access full details when needed.
    `,
    inputSchema: {
      type: 'object',
      properties: {},
      required: [],
    },
    outputSchema: {
      type: 'object',
      properties: {
        system: {
          type: 'string',
          description: 'Description of the optimization system',
        },
        usage: {
          type: 'object',
          description: 'How to use the optimization system',
        },
        benefits: {
          type: 'object',
          description: 'Benefits of the optimization approach',
        },
      },
    },
    examples: [
      {
        name: 'Learn about optimization',
        input: {},
        description: 'Get information about how response optimization works',
      },
    ],
    useCases: [
      'Understanding response optimization',
      'Learning how to get detailed responses',
      'Optimizing AI agent workflows',
    ],
    limitations: ['Simple system with only two modes: overview (default) and detailed'],
    performanceNotes: ['Overview responses are typically 90%+ smaller than detailed responses'],
    relatedTools: ['analyze_duplicates_dcd', 'scan_repository_dcd'],
  });

  // Define status resource
  definition.defineResource('dcd://status', {
    name: 'DCD Plugin Status',
    description: 'Current status and capabilities of the DCD plugin',
    longDescription: `
      Provides real-time status information about the DCD plugin including:
      - Plugin initialization status
      - DCD executable availability
      - Configuration details
      - Operation mode (real vs mock)
      - Performance metrics
      - Error states and diagnostics
      
      This resource is essential for troubleshooting and verifying proper plugin setup.
    `,
    mimeType: 'application/json',
    structure: {
      pluginName: 'string',
      version: 'string',
      isDCDAvailable: 'boolean',
      mockMode: 'boolean',
      status: 'string',
      configuration: 'object',
      lastError: 'string|null',
    },
    examples: [
      {
        name: 'Healthy status',
        data: {
          pluginName: 'dcd',
          version: '1.0.0',
          isDCDAvailable: true,
          mockMode: false,
          status: 'ready',
        },
      },
    ],
    updateFrequency: 'real-time',
  });

  // Define install guide resource
  definition.defineResource('dcd://install-guide', {
    name: 'DCD Installation Guide',
    description: 'How to install DCD (open source duplicate detector)',
    longDescription: `
      Comprehensive installation guide for DCD including:
      - Prerequisites (Go 1.19+)
      - Installation methods (go install, manual download)
      - Platform-specific instructions
      - Troubleshooting common issues
      - Verification steps
      - Configuration options
      
      This guide ensures users can properly set up DCD for use with the MCP server.
    `,
    mimeType: 'text/markdown',
    structure: 'markdown formatted installation instructions',
    updateFrequency: 'static',
  });

  // Define internal operations
  definition.defineOperation('runDCDAnalysis', {
    description: 'Execute DCD command-line tool with specified parameters',
    purpose:
      'Core operation that interfaces with the DCD executable to perform duplicate detection',
    parameters: {
      path: 'string - Target path to analyze',
      options: 'object - Analysis configuration including matchLength, fuzziness, extensions',
    },
    returns: 'object - Parsed analysis results with duplicates and summary',
    sideEffects: ['Spawns DCD process', 'Reads file system'],
    complexity: 'O(n*m) where n is files and m is lines per file',
    dependencies: ['DCD executable', 'File system access'],
  });

  definition.defineOperation('parseDCDOutput', {
    description: 'Parse DCD command output into structured format',
    purpose: "Convert DCD's text output into JSON format suitable for MCP responses",
    parameters: {
      output: 'string - Raw DCD command output',
    },
    returns: 'object - Structured duplicate analysis results',
    complexity: 'O(n) where n is output lines',
    dependencies: ['Regular expression parsing'],
  });

  definition.defineOperation('buildDCDArgs', {
    description: 'Construct command-line arguments for DCD execution',
    purpose: 'Translate plugin parameters into DCD command-line arguments',
    parameters: {
      path: 'string - Target path',
      options: 'object - Analysis options',
    },
    returns: 'array - Command-line arguments for DCD',
    complexity: 'O(1)',
    dependencies: ['None'],
  });

  return definition;
}

/**
 * Simian Plugin Capability Definition
 * Based on Simian's commercial duplicate detection capabilities
 */
export function createSimianCapabilityDefinition() {
  const definition = new PluginCapabilityDefinition('simian', {
    name: 'Simian (Similarity Analyzer)',
    version: '2.5.10',
    license: 'Commercial License Required',
    author: 'RedHill Consulting',
    homepage: 'https://simian.quandarypeak.com/',
  });

  // Define analyze_duplicates tool
  definition.defineTool('analyze_duplicates', {
    description: 'Detect duplicate code in files or directories using Simian',
    longDescription: `
      Analyzes source code to identify duplicate and similar code blocks using Simian,
      a mature commercial duplicate detection tool with advanced features.
      
      Key Features:
      - Language-aware duplicate detection with built-in parsers
      - Configurable similarity thresholds (line-based detection)
      - Multiple output formats (XML, text, plain) for integration
      - Advanced filtering options (ignore strings, numbers, identifiers, formatting)
      - High precision duplicate detection with low false positives
      - Proven track record in enterprise environments since 2003
      
      Simian provides more sophisticated analysis than text-based tools by understanding
      code structure and offering fine-grained control over what constitutes a duplicate.
      It's particularly effective for large enterprise codebases requiring precise results.
      
      IMPORTANT: This tool requires Simian to be installed and licensed. If Simian is not available, the tool will not be exposed.
      Simian requires a commercial license. Install at ~/lib/simian-4.0.0/simian-4.0.0.jar
    `,
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'File or directory path to analyze (required)',
        },
        threshold: {
          type: 'integer',
          description: 'Minimum number of consecutive duplicate lines (default: 6, minimum: 2)',
          minimum: 2,
          default: 6,
        },
        extensions: {
          type: 'array',
          items: { type: 'string' },
          description:
            'File extensions to include (e.g., [".java", ".js", ".cs", ".cpp"]). Simian supports 20+ languages.',
        },
        options: {
          type: 'object',
          description: 'Advanced Simian analysis options for fine-tuning detection',
          properties: {
            ignoreStrings: { type: 'boolean', description: 'Ignore string literal differences' },
            ignoreNumbers: { type: 'boolean', description: 'Ignore numeric literal differences' },
            ignoreCharacters: {
              type: 'boolean',
              description: 'Ignore character literal differences',
            },
            ignoreCurlyBraces: { type: 'boolean', description: 'Ignore curly brace formatting' },
            ignoreIdentifiers: {
              type: 'boolean',
              description: 'Ignore variable/method name differences',
            },
          },
        },
      },
      required: ['path'],
    },
    outputSchema: {
      type: 'object',
      properties: {
        summary: {
          type: 'object',
          description: 'Analysis summary with key metrics',
          properties: {
            totalFiles: { type: 'integer', description: 'Total files analyzed' },
            duplicateLines: { type: 'integer', description: 'Total duplicate lines found' },
            duplicateBlocks: { type: 'integer', description: 'Number of duplicate blocks found' },
            analysisTime: { type: 'string', description: 'Time taken for analysis' },
            tool: { type: 'string', description: 'Tool used (Simian)' },
          },
        },
        duplicates: {
          type: 'array',
          description: 'Detailed duplicate code blocks with locations and metrics',
        },
      },
    },
    examples: [
      {
        name: 'Enterprise Java analysis',
        input: { path: 'src/main/java/', threshold: 6, extensions: ['.java'] },
        description: 'Analyze Java codebase with standard threshold for enterprise projects',
      },
      {
        name: 'Flexible C# analysis',
        input: {
          path: 'src/',
          threshold: 4,
          options: { ignoreIdentifiers: true, ignoreStrings: true },
        },
        description: 'Find structural duplicates in C# code ignoring variable names and strings',
      },
      {
        name: 'Multi-language analysis',
        input: { path: 'project/', extensions: ['.js', '.ts', '.jsx', '.tsx'] },
        description: 'Comprehensive analysis of TypeScript/JavaScript project',
      },
    ],
    useCases: [
      'Enterprise code quality assessment and compliance',
      'Large-scale refactoring projects with risk analysis',
      'Code review automation and quality gates',
      'Technical debt measurement and reporting',
      'Compliance and audit requirements for regulated industries',
      'Cross-team code similarity detection',
    ],
    limitations: [
      'Requires commercial license for production use (evaluation available)',
      'May be slower than text-based tools due to sophisticated analysis',
      'Configuration complexity for optimal results in diverse codebases',
      'Language support depends on built-in parsers',
      'Licensing costs may be prohibitive for small teams',
    ],
    performanceNotes: [
      'Optimized for large enterprise codebases (tested on millions of lines)',
      'Memory usage scales with codebase size and threshold settings',
      'XML output format recommended for programmatic processing',
      'Performance improves with appropriate file filtering',
    ],
    relatedTools: ['scan_repository', 'suggest_refactoring'],
  });

  // Define scan_repository tool
  definition.defineTool('scan_repository', {
    description: 'Perform comprehensive repository analysis for code duplicates',
    longDescription: `
      Comprehensive repository-wide analysis using Simian's advanced duplicate detection.
      Designed for enterprise environments requiring detailed reporting and compliance tracking.
      
      Features:
      - Repository-wide scanning with intelligent file discovery
      - Advanced include/exclude pattern support
      - Detailed reporting suitable for management and compliance
      - Integration-friendly output formats
      - Progress tracking for large repositories
      - Historical comparison capabilities
      
      Ideal for establishing quality baselines, tracking technical debt over time,
      and generating reports for stakeholders and compliance requirements.
      
      IMPORTANT: This tool requires Simian to be installed and licensed. If Simian is not available, the tool will not be exposed.
      Simian requires a commercial license. Install at ~/lib/simian-4.0.0/simian-4.0.0.jar
    `,
    inputSchema: {
      type: 'object',
      properties: {
        repository: {
          type: 'string',
          description: 'Repository root path to scan (required)',
        },
        threshold: {
          type: 'integer',
          description: 'Minimum number of consecutive duplicate lines (default: 6)',
          minimum: 2,
          default: 6,
        },
        includePatterns: {
          type: 'array',
          items: { type: 'string' },
          description:
            'File patterns to include (glob patterns, e.g., ["src/**/*.java", "**/*.cs"])',
        },
        excludePatterns: {
          type: 'array',
          items: { type: 'string' },
          description:
            'File patterns to exclude (e.g., ["**/test/**", "**/generated/**", "node_modules/**"])',
        },
      },
      required: ['repository'],
    },
    outputSchema: {
      type: 'object',
      properties: {
        summary: {
          type: 'object',
          description: 'Repository analysis summary',
          properties: {
            totalFiles: { type: 'integer', description: 'Total files analyzed' },
            duplicateLines: { type: 'integer', description: 'Total duplicate lines found' },
            duplicateBlocks: { type: 'integer', description: 'Number of duplicate blocks found' },
            analysisTime: { type: 'string', description: 'Time taken for analysis' },
            tool: { type: 'string', description: 'Tool used (Simian)' },
          },
        },
        duplicates: {
          type: 'array',
          description: 'All duplicate code blocks found in the repository',
        },
      },
    },
    examples: [
      {
        name: 'Enterprise Java repository',
        input: {
          repository: '.',
          threshold: 6,
          includePatterns: ['src/**/*.java'],
          excludePatterns: ['**/test/**', '**/generated/**'],
        },
        description: 'Scan Java enterprise project excluding tests and generated code',
      },
      {
        name: 'Multi-technology repository',
        input: {
          repository: '.',
          includePatterns: ['**/*.js', '**/*.ts', '**/*.java', '**/*.cs'],
          excludePatterns: ['node_modules/**', 'dist/**', 'target/**'],
        },
        description: 'Comprehensive scan of polyglot codebase with proper exclusions',
      },
    ],
    useCases: [
      'Enterprise repository auditing and compliance reporting',
      'Cross-project duplicate detection in large organizations',
      'Quality gate implementation in CI/CD pipelines',
      'Continuous integration quality checks and trend tracking',
      'Technical debt assessment for management reporting',
      'Code review preparation and baseline establishment',
    ],
    limitations: [
      'Large repositories may require significant processing time',
      'Include/exclude patterns must be carefully configured for accuracy',
      'Results may be large and require post-processing for specific use cases',
      'Memory requirements scale with repository size',
    ],
    performanceNotes: [
      'Designed for enterprise-scale repositories',
      'Intelligent file filtering improves performance significantly',
      'Progress reporting available for long-running scans',
      'Results can be cached for incremental analysis',
    ],
    relatedTools: ['analyze_duplicates', 'suggest_refactoring'],
  });

  // Define suggest_refactoring tool
  definition.defineTool('suggest_refactoring', {
    description: 'Analyze duplicates and suggest refactoring opportunities',
    longDescription: `
      Advanced analysis that combines Simian's duplicate detection with intelligent
      refactoring recommendations. Provides actionable insights for improving code quality.
      
      Features:
      - Priority-based refactoring suggestions
      - Risk assessment for each refactoring opportunity
      - Complexity analysis and impact estimation
      - ROI calculation for refactoring efforts
      - Integration with project management tools
      - Template-based refactoring patterns
      
      Goes beyond simple duplicate detection to provide strategic guidance for
      technical debt reduction and code quality improvement initiatives.
    `,
    inputSchema: {
      type: 'object',
      properties: {
        path: {
          type: 'string',
          description: 'File or directory path to analyze for refactoring opportunities (required)',
        },
        minOccurrences: {
          type: 'integer',
          description:
            'Minimum number of duplicate occurrences to suggest refactoring (default: 3)',
          minimum: 2,
          default: 3,
        },
        complexityThreshold: {
          type: 'integer',
          description: 'Minimum complexity score for refactoring suggestions (default: 10)',
          minimum: 1,
          default: 10,
        },
      },
      required: ['path'],
    },
    examples: [
      {
        name: 'High-impact refactoring',
        input: { path: 'src/', minOccurrences: 5, complexityThreshold: 15 },
        description:
          'Focus on high-impact refactoring opportunities with significant code reuse potential',
      },
      {
        name: 'Comprehensive refactoring analysis',
        input: { path: 'components/', minOccurrences: 2, complexityThreshold: 5 },
        description: 'Detailed analysis including smaller refactoring opportunities',
      },
    ],
    useCases: [
      'Automated refactoring planning and prioritization',
      'Technical debt prioritization with ROI analysis',
      'Code quality improvement roadmap development',
      'Team training on refactoring best practices',
      'Management reporting on code quality initiatives',
      'Integration with agile planning and estimation',
    ],
    limitations: [
      'Recommendations require human review and validation',
      'Context-specific knowledge may affect suggestion relevance',
      'Complex refactoring may require architectural expertise',
      'Suggestions are based on structural analysis, not business logic',
    ],
    performanceNotes: [
      'Combines analysis results with heuristic evaluation',
      'Processing time includes duplicate detection plus suggestion generation',
      'Results include confidence scores for prioritization',
    ],
    relatedTools: ['analyze_duplicates', 'scan_repository'],
  });

  // Define get_plugin_status tool
  definition.defineTool('get_plugin_status', {
    description: 'Check the status and availability of all plugins and their tools',
    longDescription: `
      Provides comprehensive status information about all available plugins and their tools.
      This tool helps determine which analysis capabilities are available and what needs to be installed.
      
      Returns information about:
      - Plugin availability (installed/not installed)
      - Tool availability (which tools are exposed)
      - Installation instructions for missing dependencies
      - Mock mode status
      - Licensing requirements
      
      Use this tool to understand what code analysis capabilities are available before attempting
      to use specific analysis tools.
    `,
    inputSchema: {
      type: 'object',
      properties: {
        plugin: {
          type: 'string',
          description: 'Specific plugin to check (optional - if not provided, checks all plugins)',
          enum: ['dcd', 'simian', 'all'],
          default: 'all',
        },
      },
      required: [],
    },
    outputSchema: {
      type: 'object',
      properties: {
        available: {
          type: 'array',
          description: 'List of available plugins and their tools',
          items: {
            type: 'object',
            properties: {
              plugin: { type: 'string', description: 'Plugin name' },
              name: { type: 'string', description: 'Plugin display name' },
              status: { type: 'string', description: 'Plugin status (available/unavailable)' },
              tools: {
                type: 'array',
                items: { type: 'string' },
                description: 'Available tool names',
              },
              message: { type: 'string', description: 'Status message' },
            },
          },
        },
        unavailable: {
          type: 'array',
          description: 'List of unavailable plugins and installation instructions',
          items: {
            type: 'object',
            properties: {
              plugin: { type: 'string', description: 'Plugin name' },
              name: { type: 'string', description: 'Plugin display name' },
              installation: { type: 'object', description: 'Installation instructions' },
              message: { type: 'string', description: 'Why plugin is unavailable' },
            },
          },
        },
        summary: {
          type: 'object',
          description: 'Summary of available capabilities',
          properties: {
            totalPlugins: { type: 'integer', description: 'Total number of plugins' },
            availablePlugins: { type: 'integer', description: 'Number of available plugins' },
            totalTools: { type: 'integer', description: 'Total number of available tools' },
            recommendations: {
              type: 'array',
              items: { type: 'string' },
              description: 'Installation recommendations',
            },
          },
        },
      },
    },
    examples: [
      {
        name: 'Check all plugins',
        input: {},
        description: 'Get status of all plugins and their tools',
      },
      {
        name: 'Check DCD specifically',
        input: { plugin: 'dcd' },
        description: 'Check if DCD plugin is available and what tools it provides',
      },
    ],
    useCases: [
      'Determine available analysis capabilities',
      'Check if dependencies are installed',
      'Get installation instructions for missing tools',
      'Understand licensing requirements',
      'Verify tool availability before analysis',
    ],
    limitations: [
      'Status is checked at server startup',
      'Does not verify tool functionality beyond basic availability',
      'Mock mode status may not reflect real tool capabilities',
    ],
    relatedTools: [
      'analyze_duplicates_dcd',
      'scan_repository_dcd',
      'analyze_duplicates',
      'scan_repository',
    ],
  });

  // Define status resource
  definition.defineResource('simian://status', {
    name: 'Simian Plugin Status',
    description: 'Current status and capabilities of the Simian plugin',
    longDescription: `
      Provides comprehensive status information about the Simian plugin including:
      - Plugin initialization status and health
      - Simian executable availability and version
      - License status and compliance information
      - Configuration details and optimization settings
      - Operation mode (real vs mock) and performance metrics
      - Error states, diagnostics, and troubleshooting information
      
      Essential for verifying proper plugin setup, license compliance, and operational status.
    `,
    mimeType: 'application/json',
    structure: {
      pluginName: 'string',
      version: 'string',
      isSimianAvailable: 'boolean',
      licenseStatus: 'string',
      mockMode: 'boolean',
      status: 'string',
      configuration: 'object',
      lastError: 'string|null',
    },
    examples: [
      {
        name: 'Licensed production status',
        data: {
          pluginName: 'simian',
          version: '2.5.10',
          isSimianAvailable: true,
          licenseStatus: 'valid',
          mockMode: false,
          status: 'ready',
        },
      },
    ],
    updateFrequency: 'real-time',
  });

  // Define configuration resource
  definition.defineResource('simian://config/current', {
    name: 'Current Simian Configuration',
    description: 'Current Simian plugin configuration and settings',
    longDescription: `
      Detailed configuration information including:
      - Executable path and version information
      - Default analysis parameters and thresholds
      - Cache settings and performance optimizations
      - License configuration and compliance settings
      - Integration settings for enterprise environments
      
      Useful for troubleshooting, optimization, and compliance verification.
    `,
    mimeType: 'application/json',
    structure: 'configuration object with all current settings',
    updateFrequency: 'on configuration change',
  });

  // Define install guide resource
  definition.defineResource('simian://install-guide', {
    name: 'Simian Installation Guide',
    description: 'How to install and license Simian properly',
    longDescription: `
      Comprehensive installation and licensing guide including:
      - Manual download and installation instructions
      - Licensing requirements and compliance information
      - Configuration setup for different environments
      - Troubleshooting common installation issues
      - Enterprise deployment considerations
      
      Emphasizes proper licensing compliance and manual installation requirements.
    `,
    mimeType: 'text/markdown',
    structure: 'markdown formatted installation and licensing guide',
    updateFrequency: 'static',
  });

  // Define internal operations
  definition.defineOperation('runSimianAnalysis', {
    description: 'Execute Simian command-line tool with specified parameters',
    purpose:
      'Core operation that interfaces with Simian executable to perform sophisticated duplicate detection',
    parameters: {
      path: 'string - Target path to analyze',
      options:
        'object - Analysis configuration including threshold, extensions, and filtering options',
    },
    returns: 'object - Parsed analysis results with detailed duplicates and summary metrics',
    sideEffects: ['Spawns Simian process', 'Reads file system', 'May create temporary files'],
    complexity: 'O(n*m*k) where n is files, m is lines per file, k is language complexity',
    dependencies: ['Simian executable', 'Valid license', 'File system access'],
  });

  definition.defineOperation('buildSimianArgs', {
    description: 'Construct command-line arguments for Simian execution',
    purpose:
      'Translate plugin parameters into Simian-specific command-line arguments with proper formatting',
    parameters: {
      path: 'string - Target path',
      options: 'object - Analysis options including thresholds and filters',
    },
    returns: 'array - Command-line arguments optimized for Simian',
    complexity: 'O(1)',
    dependencies: ['Simian configuration knowledge'],
  });

  definition.defineOperation('parseSimianOutput', {
    description: 'Parse Simian XML/text output into structured format',
    purpose:
      "Convert Simian's XML or text output into JSON format suitable for MCP responses and AI consumption",
    parameters: {
      output: 'string - Raw Simian command output',
      format: 'string - Output format (xml, text, plain)',
    },
    returns: 'object - Structured duplicate analysis results with enhanced metadata',
    complexity: 'O(n) where n is output size',
    dependencies: ['XML parsing library', 'Output format knowledge'],
  });

  return definition;
}