alpsla · alpsla · Jun 7, 2025 · Jun 7, 2025 · Jun 7, 2025 · Jun 7, 2025
diff --git a/apps/api/src/services/pr-context-service.ts b/apps/api/src/services/pr-context-service.ts
@@ -1,4 +1,5 @@
 import axios from 'axios';
+import { RepositorySizeCategory } from '@codequal/core/services/model-selection/ModelVersionSync';
 
 export interface PRDetails {
   number: number;
@@ -178,7 +179,7 @@ export class PRContextService {
   /**
    * Estimate repository size category
    */
-  async estimateRepositorySize(repositoryUrl: string): Promise<'small' | 'medium' | 'large'> {
+  async estimateRepositorySize(repositoryUrl: string): Promise<RepositorySizeCategory> {
     try {
       const repoInfo = this.parseRepositoryUrl(repositoryUrl);
 
@@ -190,16 +191,16 @@ export class PRContextService {
 
         const sizeKB = response.data.size; // GitHub returns size in KB
 
-        if (sizeKB < 1000) return 'small';      // < 1MB
-        if (sizeKB < 50000) return 'medium';    // < 50MB
-        return 'large';                         // >= 50MB
+        if (sizeKB < 1000) return RepositorySizeCategory.SMALL;      // < 1MB
+        if (sizeKB < 50000) return RepositorySizeCategory.MEDIUM;    // < 50MB
+        return RepositorySizeCategory.LARGE;                         // >= 50MB
       }
 
       // Default to medium if we can't determine size
-      return 'medium';
+      return RepositorySizeCategory.MEDIUM;
     } catch (error) {
       console.error('Failed to estimate repository size:', error);
-      return 'medium';
+      return RepositorySizeCategory.MEDIUM;
     }
   }
 

diff --git a/apps/api/src/services/result-orchestrator.ts b/apps/api/src/services/result-orchestrator.ts
@@ -7,7 +7,7 @@ import { storeAnalysisInHistory } from '../routes/analysis';
 
 // Import existing packages
 import { EnhancedMultiAgentExecutor } from '@codequal/agents/multi-agent/enhanced-executor';
-import { ModelVersionSync } from '@codequal/core/services/model-selection/ModelVersionSync';
+import { ModelVersionSync, RepositorySizeCategory } from '@codequal/core/services/model-selection/ModelVersionSync';
 import { VectorContextService } from '@codequal/agents/multi-agent/vector-context-service';
 import { createLogger } from '@codequal/core/utils';
 import { AuthenticatedUser as AgentAuthenticatedUser, UserRole, UserStatus, UserPermissions } from '@codequal/agents/multi-agent/types/auth';
@@ -27,7 +27,7 @@ export interface PRContext {
   diff: any;
   changedFiles: string[];
   primaryLanguage: string;
-  repositorySize: 'small' | 'medium' | 'large';
+  repositorySize: RepositorySizeCategory;
   analysisMode: string;
   baseBranch?: string;
   files?: Array<{

diff --git a/apps/api/tsconfig.tsbuildinfo b/apps/api/tsconfig.tsbuildinfo
diff --git a/docs/mcp-hybrid-commit-ready.md b/docs/mcp-hybrid-commit-ready.md
@@ -0,0 +1,128 @@
+# MCP Hybrid Implementation - Ready for Commit
+
+## Summary of Changes
+
+### New Package Created: `@codequal/mcp-hybrid`
+
+Located at `/packages/mcp-hybrid/`, this package implements a comprehensive tool integration system for CodeQual agents.
+
+### Key Components Implemented:
+
+1. **Core Architecture (100% Complete)**
+   - PR-focused interfaces and types
+   - Tool registry with role-based mappings
+   - MCPToolManager for server-side execution
+   - Context-aware tool selector
+   - Parallel execution engine with 3 strategies
+   - Tool-aware agent integration
+
+2. **Tool Adapters (7/25 implemented - 28%)**
+   - MCP-Scan (security verification)
+   - Context MCP (educational knowledge retrieval)
+   - Chart.js MCP (visualizations)
+   - Grafana Direct (dashboard integration)
+   - Prettier Direct (formatting)
+   - Dependency Cruiser Direct (architecture)
+   - MCP Docs Service (being replaced)
+
+3. **Infrastructure**
+   - Installation scripts
+   - Security verification
+   - Health checks
+   - Comprehensive documentation
+
+### Files Created:
+```
+/packages/mcp-hybrid/
+├── src/
+│   ├── core/
+│   │   ├── interfaces.ts
+│   │   ├── registry.ts
+│   │   ├── tool-manager.ts
+│   │   ├── executor.ts
+│   ├── context/
+│   │   └── selector.ts
+│   ├── adapters/
+│   │   ├── mcp/
+│   │   │   ├── mcp-scan.ts
+│   │   │   ├── context-mcp.ts
+│   │   │   ├── chartjs-mcp.ts
+│   │   │   └── docs-service.ts
+│   │   └── direct/
+│   │       ├── base-adapter.ts
+│   │       └── grafana-adapter.ts
+│   ├── integration/
+│   │   └── tool-aware-agent.ts
+│   ├── scripts/
+│   │   ├── install-tools.sh
+│   │   ├── verify-security.sh
+│   │   └── health-check.sh
+│   └── index.ts
+├── package.json
+├── tsconfig.json
+├── README.md
+├── IMPLEMENTATION_PLAN.md (updated with status)
+└── .gitignore
+```
+
+## Next Steps Before Merge:
+
+### 1. Build Verification
+```bash
+cd packages/mcp-hybrid
+npm install
+npm run build
+```
+
+### 2. TypeScript Compilation
+```bash
+npx tsc --noEmit
+```
+
+### 3. Update Root package.json (if needed)
+Add to workspaces array if not already included.
+
+### 4. Run Validation
+```bash
+# From project root
+npm run validate:fast  # Skip tests for now
+```
+
+### 5. Commit Changes
+```bash
+git add packages/mcp-hybrid/
+git add docs/session-summaries/2025-06-08-session-summary.md
+git commit -m "feat(mcp-hybrid): implement PR-focused tool integration system
+
+- Create comprehensive tool architecture for agent enhancement
+- Implement parallel execution engine with 3 strategies
+- Add 7 initial tool adapters (28% of planned tools)
+- Support all agent roles with 2+ tools each
+- Remove Repomix (requires full repo access)
+- Add proper educational tools (Context MCP) 
+- Add dual visualization approach (Chart.js + Grafana)
+- Include installation and security scripts"
+```
+
+### 6. Merge with Origin
+```bash
+git pull origin main --rebase
+git push origin main
+```
+
+## Important Notes:
+
+1. **No Breaking Changes**: This is a new package that doesn't affect existing functionality
+2. **PR-Focused Design**: All tools work with PR diffs, not full repositories
+3. **Parallel Execution**: Significant performance improvement potential
+4. **Educational/Reporting Tools**: Properly designed for their actual purposes
+
+## Testing Strategy:
+
+After merge, the next priority is:
+1. Implement ESLint MCP adapter
+2. Create integration test with real PR data
+3. Benchmark parallel vs sequential execution
+4. Integrate with EnhancedMultiAgentExecutor
+
+The foundation is solid and ready for the remaining tool implementations!
diff --git a/docs/research/MCP candidates.md b/docs/research/MCP candidates.md
@@ -0,0 +1,161 @@
+# Secure and Stable MCP Tools for CodeQual Integration
+
+Based on extensive security analysis and stability assessment, here's a curated list of 10-15 most trustworthy MCP tools organized by priority and use case.
+
+## Critical Security Infrastructure (Install First)
+
+### 1. **MCP-Scan by Invariant Labs** ⭐⭐⭐⭐⭐
+- **Source**: Open source by Invariant Labs (AI security specialists)
+- **Repository**: Available via `uvx mcp-scan@latest` or `npx mcp-scan@latest`
+- **Security**: A+ (Addresses Tool Poisoning Attacks, includes security monitoring)
+- **Setup Complexity**: Very Low
+- **Purpose**: Security scanning and monitoring of all other MCP tools
+- **Key Feature**: Real-time proxy monitoring and tool integrity verification
+- **Integration**: Run before installing any other tools, use for ongoing monitoring
+
+## Code Quality and Linting Tools
+
+### 2. **ESLint Official MCP Server** ⭐⭐⭐⭐⭐
+- **Source**: Official ESLint team
+- **Repository**: `@eslint/mcp` (npm package)
+- **Security**: A+ (Official tool from trusted organization)
+- **Setup Complexity**: Very Low - Just `npx @eslint/mcp@latest`
+- **Language Support**: JavaScript, TypeScript, JSX
+- **Configuration**: Zero-config, uses existing ESLint setup
+- **Known Limitations**: JavaScript ecosystem only
+
+### 3. **Repomix MCP Server** ⭐⭐⭐⭐⭐
+- **Source**: yamadashy/repomix (16.5K GitHub stars)
+- **Repository**: `npx -y @modelcontextprotocol/server-repomix`
+- **Security**: A (Community project with high trust, fully local)
+- **Setup Complexity**: Very Low
+- **Purpose**: Repository analysis and AI-friendly code packaging
+- **Key Features**: 70% token reduction, security validation, project structure analysis
+- **Language Support**: All languages
+
+### 4. **Lucidity MCP** ⭐⭐⭐⭐
+- **Source**: hyperb1iss/lucidity-mcp
+- **Security**: B+ (Individual developer, transparent codebase)
+- **Setup Complexity**: Low (UV package manager)
+- **Purpose**: Git-aware code quality analysis
+- **Unique Feature**: Analyzes code changes in git context
+- **Language Support**: Language-agnostic
+
+## Security Scanning and Analysis
+
+### 5. **Semgrep MCP Server** ⭐⭐⭐⭐
+- **Source**: Official Semgrep (established SAST company)
+- **Security**: A (Proven security tool vendor)
+- **Setup Complexity**: Medium (optional Semgrep account)
+- **Purpose**: Static Application Security Testing (SAST)
+- **Features**: 5,000+ security rules, multi-language support
+- **Authentication**: Optional for enhanced features
+
+### 6. **MCP Security Audit Server** ⭐⭐⭐⭐
+- **Source**: qianniuspace (uses official npm audit API)
+- **Repository**: `npx -y mcp-security-audit`
+- **Security**: B+ (Leverages official npm security data)
+- **Setup Complexity**: Very Low
+- **Purpose**: Dependency vulnerability scanning
+- **Limitation**: npm packages only
+
+## Testing and Validation
+
+### 7. **MCP Inspector** ⭐⭐⭐⭐⭐
+- **Source**: Official Model Context Protocol project
+- **Repository**: `npx @modelcontextprotocol/inspector`
+- **Security**: A+ (Official Anthropic tool)
+- **Setup Complexity**: Very Low
+- **Purpose**: Testing and debugging MCP integrations
+- **Key Feature**: Visual testing interface for MCP tools
+
+## Documentation and Repository Management
+
+### 8. **Git MCP Server** ⭐⭐⭐⭐⭐
+- **Source**: Official Anthropic reference implementation
+- **Repository**: `uvx mcp-server-git`
+- **Security**: A+ (Official implementation)
+- **Setup Complexity**: Low
+- **Purpose**: Git repository analysis and manipulation
+- **Features**: Read-only by default, configurable access controls
+
+### 9. **MCP Documentation Service** ⭐⭐⭐⭐
+- **Source**: Community-maintained with test coverage
+- **Installation**: `npm install -g mcp-docs-service`
+- **Security**: B+ (Fully local, no external dependencies)
+- **Setup Complexity**: Low
+- **Purpose**: Markdown documentation management
+- **Features**: Quality analysis, metadata handling
+
+### 10. **Context7 MCP Server** ⭐⭐⭐⭐
+- **Source**: Upstash (established company)
+- **Repository**: `npx -y @upstash/context7-mcp`
+- **Security**: B+ (Fetches only public documentation)
+- **Setup Complexity**: Very Low
+- **Purpose**: Real-time documentation fetching
+- **Note**: Requires internet for documentation updates
+
+## Specialized Analysis Tools
+
+### 11. **MCP Code Checker** ⭐⭐⭐
+- **Source**: MarcusJellinghaus/mcp-code-checker
+- **Security**: B (Individual developer, transparent code)
+- **Setup Complexity**: Medium (Python environment)
+- **Purpose**: Python code analysis (Pylint + Pytest)
+- **Language Support**: Python only
+
+### 12. **SQL Analyzer MCP** ⭐⭐⭐
+- **Source**: j4c0bs/mcp-server-sql-analyzer
+- **Security**: B (Individual developer, MIT license)
+- **Setup Complexity**: Low
+- **Purpose**: SQL syntax validation and dialect conversion
+- **Features**: Supports 40+ SQL dialects
+
+### 13. **Dependency MCP Server** ⭐⭐⭐
+- **Source**: mkearl/dependency-mcp
+- **Security**: B+ (Local analysis only, no external calls)
+- **Setup Complexity**: Medium
+- **Purpose**: Multi-language dependency analysis
+- **Language Support**: TypeScript, JavaScript, C#, Python
+
+## Implementation Roadmap
+
+### Phase 1: Security Foundation (Day 1)
+1. Install **MCP-Scan** for security monitoring
+2. Set up **MCP Inspector** for testing
+3. Configure security policies and monitoring
+
+### Phase 2: Core Tools (Week 1)
+4. Deploy **ESLint MCP** for JavaScript/TypeScript
+5. Add **Repomix** for repository analysis
+6. Install **Git MCP Server** for version control integration
+
+### Phase 3: Extended Capabilities (Week 2)
+7. Add language-specific tools (Python, SQL analyzers)
+8. Set up documentation tools if needed
+9. Configure dependency scanning tools
+
+### Phase 4: Production Hardening (Week 3)
+10. Implement continuous security scanning
+11. Set up automated monitoring
+12. Document security procedures
+
+## Security Best Practices
+
+1. **Always run MCP-Scan** before adding new tools
+2. **Use local-only mode** when available
+3. **Review tool permissions** carefully
+4. **Monitor tool behavior** for anomalies
+5. **Keep tools updated** but test updates first
+6. **Implement access controls** per repository
+7. **Log all MCP activities** for audit trails
+
+## Tools to Avoid
+
+- Abandoned projects (no updates in 6+ months)
+- Tools requiring excessive permissions
+- Servers without source code visibility
+- Tools with known security vulnerabilities
+- Complex enterprise tools (unless specifically needed)
+
+This curated list prioritizes security, stability, and relevance to code analysis while maintaining ease of integration for the CodeQual project.