SACL MCP Server

# SACL Usage Examples This document provides comprehensive examples of using the SACL MCP Server for bias-aware code analysis and retrieval. ## Table of Contents - [Basic Usage Examples](#basic-usage-examples) - [Relationship Analysis Examples](#relationship-analysis-examples) - [Context-Aware Query Examples](#context-aware-query-examples) - [File Update Examples](#file-update-examples) - [Bias Analysis Examples](#bias-analysis-examples) - [Advanced Workflows](#advanced-workflows) ## Basic Usage Examples ### Repository Analysis **Scenario**: Initial setup of SACL for a new project ```json { "tool": "analyze_repository", "arguments": { "repositoryPath": "/workspace/my-react-app", "incremental": false } } ``` **Expected Response**: ``` 📊 Repository Analysis Complete **Processing Statistics:** • Files processed: 147/150 • Average bias score: 0.425 • High bias files detected: 12 • Processing time: 23.4s 🔍 SACL Framework Applied: • Textual bias detection completed • Semantic augmentation applied • Knowledge graph populated • Ready for bias-aware code retrieval Use 'query_code' to search with reduced textual bias. ``` ### Basic Code Query **Scenario**: Finding authentication-related code ```json { "tool": "query_code", "arguments": { "query": "user authentication and validation", "repositoryPath": "/workspace/my-react-app", "maxResults": 3 } } ``` **Expected Response**: ``` 🔍 SACL Query Results for: "user authentication and validation" Found 3 bias-aware matches: **1. src/auth/AuthService.js** • Bias Score: 45.2% 🟡 • SACL Score: 87.3% • Pattern: Service layer authentication with validation pipeline ```javascript class AuthService { async validateUser(credentials) { // Validate user credentials const user = await this.userRepository.findByEmail(credentials.email); if (!user || !await this.comparePasswords(credentials.password, user.hashedPassword)) { throw new AuthenticationError('Invalid credentials'); } return this.generateToken(user); } } ``` 📝 SACL Ranking Analysis: • Query: "user authentication and validation" • Textual Similarity: 78.5% • Semantic Similarity: 91.2% • Functional Relevance: 89.7% • Bias Level: Medium (45.2%) • Final Score: 87.3% ``` ## Relationship Analysis Examples ### File Relationship Exploration **Scenario**: Understanding dependencies of a controller ```json { "tool": "get_relationships", "arguments": { "filePath": "src/controllers/UserController.js", "maxDepth": 2, "relationshipTypes": ["imports", "calls"] } } ``` **Expected Response**: ``` 🔗 Code Relationships Analysis **File:** src/controllers/UserController.js **Traversal Depth:** 2 **Related Components:** 8 **Key Relationships:** 1. **UserService** (imports) • File: src/services/UserService.js • Relationship: Service imported by controller • Relevance: 95.0% • Distance: 1 hop 2. **validateRequest** (calls) • File: src/middleware/validation.js • Relationship: Validation middleware called in routes • Relevance: 88.0% • Distance: 1 hop 3. **DatabaseConnection** (calls) • File: src/database/connection.js • Relationship: Database operations through service • Relevance: 75.0% • Distance: 2 hops **Traversal Statistics:** • Nodes Visited: 12 • Edges Traversed: 8 • Max Depth Reached: 2 • Processing Time: 145ms ``` ### File Context Analysis **Scenario**: Understanding a component's role in the system ```json { "tool": "get_file_context", "arguments": { "filePath": "src/models/User.js", "includeSnippets": true } } ``` **Expected Response**: ``` 🎯 File Context Analysis **File:** src/models/User.js **Total Related:** 12 **Context Summary:** • imports: 3 components • exports: 1 components • calls: 6 components • extends: 1 components **Relationship Breakdown:** **IMPORTS (3):** • mongoose └─ Database modeling framework imported └─ Code: const mongoose = require('mongoose'); • bcrypt └─ Password hashing utility imported └─ Code: const bcrypt = require('bcrypt'); **EXTENDS (1):** • BaseModel └─ Inherits from base model class └─ Code: class User extends BaseModel { constructor(data) { super(data); **CALLS (6):** • hashPassword └─ Password hashing method called in pre-save hook • validateEmail └─ Email validation called in schema validation • generateToken └─ JWT token generation for authentication **Usage Recommendations:** • Use 'query_code_with_context' to find similar patterns • Check imports/exports when modifying interfaces • Consider impact on calling functions when refactoring ``` ## Context-Aware Query Examples ### Enhanced Search with Relationships **Scenario**: Finding middleware with full context ```json { "tool": "query_code_with_context", "arguments": { "query": "error handling middleware", "repositoryPath": "/workspace/express-api", "maxResults": 2, "includeRelated": true } } ``` **Expected Response**: ``` 🔍 Enhanced SACL Query Results for: "error handling middleware" Found 2 context-aware matches: **1. src/middleware/errorHandler.js** • Bias Score: 32.1% 🟢 • SACL Score: 92.4% • Pattern: Express middleware for centralized error handling • Key Region: Lines 15-45 • Related Components: 4 └─ Logger (imports) └─ AppError (imports) └─ ValidationError (calls) ```javascript const errorHandler = (err, req, res, next) => { // Log error details logger.error(`${err.name}: ${err.message}`, { stack: err.stack, url: req.url, method: req.method }); // Handle different error types if (err instanceof ValidationError) { return res.status(400).json({ error: 'Validation Error', details: err.details }); } ``` 🧠 **Context:** src/middleware/errorHandler.js has 4 related components including 2 imports, 1 function calls, and 0 inheritance relationships. Most relevant for "error handling middleware": Logger service imported for error tracking. **Key Dependencies:** 🔴 imports: Logger service imported for error tracking 🟡 calls: ValidationError handling for request validation 🟢 imports: AppError custom error class imported 📝 SACL Ranking Analysis: • Query: "error handling middleware" • Textual Similarity: 89.2% • Semantic Similarity: 94.8% • Functional Relevance: 91.7% • Bias Level: Low (32.1%) • Final Score: 92.4% • Bias Adjustment: Minimal 🔗 Relationship Context: • Related Components: 4 • Key Relationships: Logger service imported for error tracking, ValidationError handling for request validation, AppError custom error class imported • Context Relevance: High ``` ## File Update Examples ### Single File Update **Scenario**: AI assistant modifies authentication logic ```json { "tool": "update_file", "arguments": { "filePath": "src/auth/AuthService.js", "changeType": "modified" } } ``` **Expected Response**: ``` 📝 File Update Result **File:** src/auth/AuthService.js **Change Type:** modified **Status:** ✅ Success **Message:** File src/auth/AuthService.js processed successfully. Bias score: 0.387 🔍 SACL Analysis Updated: • Bias detection applied • Semantic augmentation completed • Relationships extracted and stored • Knowledge graph updated File is now ready for bias-aware retrieval. ``` ### Batch File Updates **Scenario**: Major refactoring affecting multiple files ```json { "tool": "update_files", "arguments": { "files": [ { "filePath": "src/services/UserService.js", "changeType": "modified" }, { "filePath": "src/controllers/UserController.js", "changeType": "modified" }, { "filePath": "src/models/UserModel.js", "changeType": "modified" }, { "filePath": "src/utils/validation.js", "changeType": "created" }, { "filePath": "src/deprecated/oldAuth.js", "changeType": "deleted" } ] } } ``` **Expected Response**: ``` 📁 Batch File Update Result **Total Files:** 5 **Successful:** 4 ✅ **Failed:** 1 ❌ **Individual Results:** ✅ src/services/UserService.js: File processed successfully. Bias score: 0.423 ✅ src/controllers/UserController.js: File processed successfully. Bias score: 0.356 ✅ src/models/UserModel.js: File processed successfully. Bias score: 0.445 ✅ src/utils/validation.js: File processed successfully. Bias score: 0.234 ❌ src/deprecated/oldAuth.js: File not found or already deleted 🔍 SACL Analysis Completed: • 4 files analyzed for bias • Semantic features extracted • Code relationships mapped • Knowledge graph updated Updated files are ready for enhanced code retrieval. ``` ## Bias Analysis Examples ### File-Specific Bias Analysis **Scenario**: Investigating why a well-documented file ranks poorly ```json { "tool": "get_bias_analysis", "arguments": { "filePath": "src/algorithms/quicksort.js" } } ``` **Expected Response**: ``` 🧠 SACL Bias Analysis **File:** src/algorithms/quicksort.js **Bias Metrics:** • Overall Bias Score: 73.2% 🔴 • Semantic Pattern: Recursive divide-and-conquer sorting • Functional Signature: Array input → sorted array output with comparator **Bias Indicators:** • docstring_dependency: High docstring dependency (15.3% of code) • identifier_name_bias: High reliance on descriptive names • comment_over_reliance: Excessive comments (18.7% of code) **Repository Overview:** • Average Bias Score: 42.5% • High Bias Files: 8 • Distribution: 89 low, 45 medium, 8 high 💡 Improvement Suggestions: • Reduce reliance on variable naming for semantic understanding • Focus on structural patterns over comments • Improve functional signature extraction • Consider extracting documentation to separate files ``` ### Repository-Wide Bias Analysis **Scenario**: Understanding overall codebase bias patterns ```json { "tool": "get_bias_analysis", "arguments": {} } ``` **Expected Response**: ``` 🧠 SACL Bias Analysis **Repository Overview:** • Average Bias Score: 42.5% • High Bias Files: 8 • Distribution: 89 low, 45 medium, 8 high **High Bias Files:** • src/algorithms/quicksort.js (73.2%) • src/utils/stringHelpers.js (68.7%) • src/components/UserProfile.tsx (65.4%) • src/services/EmailService.js (62.8%) 💡 Improvement Suggestions: • Reduce reliance on variable naming for semantic understanding • Focus on structural patterns over comments • Improve functional signature extraction • Consider documentation refactoring for high-bias files • Implement consistent naming conventions ``` ## Advanced Workflows ### New Developer Onboarding **Workflow**: Help new developer understand authentication system ```bash # 1. Get overall system overview get_system_stats → Review repository statistics # 2. Find authentication-related code query_code_with_context { "query": "user authentication flow", "maxResults": 5 } # 3. Explore main auth component relationships get_file_context { "filePath": "src/auth/AuthService.js", "includeSnippets": true } # 4. Understand dependencies get_relationships { "filePath": "src/auth/AuthService.js", "maxDepth": 3 } ``` ### Code Quality Assessment **Workflow**: Assess and improve code quality ```bash # 1. Check overall bias patterns get_bias_analysis → Identify high-bias files # 2. Analyze problematic files get_file_context { "filePath": "src/algorithms/quicksort.js" } # 3. Find better implementations query_code_with_context { "query": "efficient sorting algorithm low bias", "maxResults": 3 } # 4. After improvements, update analysis update_file { "filePath": "src/algorithms/quicksort.js", "changeType": "modified" } ``` ### Refactoring Impact Analysis **Workflow**: Understand impact of proposed changes ```bash # 1. Analyze current relationships get_relationships { "filePath": "src/services/UserService.js", "maxDepth": 2 } # 2. Get full context get_file_context { "filePath": "src/services/UserService.js", "includeSnippets": false } # 3. Find similar patterns query_code_with_context { "query": "service layer pattern with dependency injection" } # 4. After refactoring, batch update update_files { "files": [/* affected files */] } # 5. Verify relationships updated get_relationships { "filePath": "src/services/UserService.js", "maxDepth": 2 } ``` ### Debugging Poor Search Results **Workflow**: Investigate why search doesn't return expected results ```bash # 1. Check bias impact get_bias_analysis { "filePath": "expected/file/path.js" } # 2. Try different query approaches query_code { "query": "original query", "includeContext": false } query_code_with_context { "query": "original query", "includeRelated": true } # 3. Explore relationships of expected file get_file_context { "filePath": "expected/file/path.js", "includeSnippets": true } # 4. Check system health get_system_stats ``` ## Performance Considerations ### Query Optimization ```javascript // Fast: Basic query without context { "tool": "query_code", "arguments": { "query": "user validation", "includeContext": false, "maxResults": 5 } } // Slower: Full context analysis { "tool": "query_code_with_context", "arguments": { "query": "user validation", "maxResults": 5, "includeRelated": true } } ``` ### Relationship Traversal ```javascript // Efficient: Limited depth and filtered types { "tool": "get_relationships", "arguments": { "filePath": "src/large/file.js", "maxDepth": 2, "relationshipTypes": ["imports", "calls"] } } // Resource-intensive: Deep traversal of all types { "tool": "get_relationships", "arguments": { "filePath": "src/large/file.js", "maxDepth": 5 // No filter = all relationship types } } ``` ## Error Handling Examples ### File Not Found ```json { "tool": "update_file", "arguments": { "filePath": "src/nonexistent/file.js", "changeType": "modified" } } ``` **Response**: ``` 📝 File Update Result **File:** src/nonexistent/file.js **Change Type:** modified **Status:** ❌ Failed **Message:** File path src/nonexistent/file.js is outside repository or does not exist ``` ### Invalid Relationship Types ```json { "tool": "get_relationships", "arguments": { "filePath": "src/valid/file.js", "relationshipTypes": ["invalid_type"] } } ``` **Response**: ``` 🔗 Code Relationships Analysis **File:** src/valid/file.js **Related Components:** 0 No significant relationships found for this file. This could mean: • File is standalone with minimal dependencies • Invalid relationship types specified • File hasn't been processed yet (run analyze_repository first) ``` --- **SACL Examples** - Comprehensive usage patterns for bias-aware code analysis and retrieval.