SACL MCP Server

A framework for bias-aware code retrieval using semantic-augmented reranking and localization.

Semantic-Augmented Reranking and Localization for Code Retrieval

A Model Context Protocol (MCP) server that implements the SACL research framework to provide bias-aware code retrieval for AI coding assistants like Claude Code, Cursor, and other MCP-enabled tools.

SACL addresses the critical problem oftextual biasin code retrieval systems. Traditional systems over-rely on surface-level features like docstrings, comments, and variable names, leading to biased results that favor well-documented code regardless of functional relevance.

- 🧠 Bias Detection: Identifies over-reliance on textual features
- 🔍 Semantic Augmentation: Enriches code understanding beyond surface text
- 📊 Intelligent Reranking: Prioritizes functional relevance over documentation
- 🎯 Code Localization: Pinpoints functionally relevant code segments
- 🔗 Relationship Analysis: Maps code dependencies and relationships
- 🎨 Context-Aware Retrieval: Returns results with related components
- 🚀 Agent-Controlled Updates: Explicit file updates for Docker compatibility
- 🗄️ Knowledge Graph: Persistent semantic storage with Graphiti/Neo4j
- 🔧 MCP Integration: Works with Claude Code, Cursor, and other AI tools

┌─────────────────┐ ┌─────────────────┐ ┌─────────────────┐ │ AI Assistant │────│ SACL MCP Server │────│ Graphiti/Neo4j │ │ (Claude, Cursor)│ │ │ │ Knowledge Graph │ └─────────────────┘ └─────────────────┘ └─────────────────┘ │ ┌─────────────────┐ │ SACL Framework │ │ │ │ • Bias Detection│ │ • Semantic Aug. │ │ • Reranking │ │ • Localization │ │ • Relationships │ │ • Context-Aware │ └─────────────────┘

- Node.js 18+
- Neo4j database
- OpenAI API key

# Clone the repository git clone <repository-url> cd sacl # Install dependencies npm install # Copy environment configuration cp .env.example .env # Edit .env with your settings OPENAI_API_KEY=your_key_here NEO4J_URI=bolt://localhost:7687 NEO4J_USER=neo4j NEO4J_PASSWORD=your_password

# Start Neo4j and SACL server docker-compose up -d # Check logs docker-compose logs -f sacl-mcp-server

# Build the project npm run build # Start the server npm start

The SACL server provides comprehensive MCP tools for bias-aware code analysis:

Performs full SACL analysis of a repository:

{ "repositoryPath": "/path/to/repo", "incremental": false }

Bias-aware code search with optional context:

{ "query": "function that sorts arrays efficiently", "repositoryPath": "/path/to/repo", "maxResults": 10, "includeContext": false // Set true for relationship context }

Enhanced search with relationship context and related components:

{ "query": "authentication middleware", "repositoryPath": "/path/to/repo", "maxResults": 10, "includeRelated": true }

Explicitly update single file analysis when changes are made:

{ "filePath": "src/services/auth.js", "changeType": "modified" // "created", "modified", or "deleted" }

{ "files": [ { "filePath": "src/index.js", "changeType": "modified" }, { "filePath": "src/utils/new.js", "changeType": "created" } ] }

Analyze code relationships and dependencies:

{ "filePath": "src/controllers/UserController.js", "maxDepth": 3, "relationshipTypes": ["imports", "calls", "extends"] // Optional filter }

{ "filePath": "src/models/User.js", "includeSnippets": true // Include code previews }

{ "filePath": "src/utils/sort.js" // Optional }

Add to yourclaude_desktop_config.json:

{ "mcpServers": { "sacl": { "command": "node", "args": ["/path/to/sacl/dist/index.js"], "env": { "OPENAI_API_KEY": "your-key", "NEO4J_URI": "bolt://localhost:7687", "NEO4J_USER": "neo4j", "NEO4J_PASSWORD": "password" } } } }

Configure in your Cursor settings to connect to the SACL MCP server.

- Docstring Dependency: Over-reliance on documentation
- Identifier Name Bias: Focusing on variable/function names
- Comment Over-reliance: Prioritizing commented code

- Functional Signatures: What the code actually does
- Behavior Patterns: Computational patterns (iteration, recursion, etc.)
- Structural Features: Complexity metrics, AST analysis
- Augmented Embeddings: Bias-adjusted semantic vectors

- Bias-Aware Ranking: Reduces textual weight based on bias score
- Code Localization: Identifies functionally relevant segments
- Semantic Similarity: Uses augmented embeddings
- Functional Relevance: Considers computational patterns

Maps code relationships and dependencies:

- Import/Export Analysis: Module dependencies and exports
- Function Call Mapping: Call graphs and method invocations
- Class Inheritance: Extends/implements relationships
- Dependency Tracking: External and internal dependencies
- Context-Aware Results: Related components with each query result

AI Assistant → analyze_repository → SACL processes all files → Knowledge graph populated

AI Assistant → query_code_with_context("authentication") → SACL retrieval → Context-aware results

AI modifies code → update_file("src/auth.js", "modified") → SACL re-analyzes → Relationships updated

AI Assistant → get_relationships("UserController.js") → Dependency graph → Related components

- Original textual similarity score
- Semantic similarity score
- Bias-adjusted final score
- Localized code regions
- Related components and dependencies
- Context explanation with relationship importance
- Explanation of ranking decisions

- 12.8%improvement in Recall@1 on HumanEval
- 9.4%improvement on MBPP
- 7.0%improvement on SWE-Bench-Lite
- P95 latency: <300ms for retrieval operations

🧠 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 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) 💡 Improvement Suggestions: • Reduce reliance on variable naming for semantic understanding • Focus on structural patterns over comments • Improve functional signature extraction

src/ ├── core/ # SACL framework implementation │ ├── BiasDetector.ts # Textual bias detection │ ├── SemanticAugmenter.ts # Semantic enhancement │ ├── SACLReranker.ts # Reranking and localization with context │ └── SACLProcessor.ts # Main orchestrator with relationship support ├── mcp/ # MCP server implementation │ └── SACLMCPServer.ts # MCP protocol handlers (9 tools) ├── graphiti/ # Knowledge graph integration │ └── GraphitiClient.ts # Graphiti/Neo4j interface with relationships ├── utils/ # Utility modules │ └── CodeAnalyzer.ts # AST analysis and relationship extraction ├── types/ # TypeScript type definitions │ ├── index.ts # Core types and interfaces │ └── relationships.ts # Relationship type definitions └── index.ts # Application entry point

npm run build # Build TypeScript npm run dev # Development with auto-reload npm run lint # Code linting npm run format # Code formatting npm test # Run tests

- Fork the repository
- Create a feature branch
- Implement changes following SACL methodology
- Add tests for new functionality
- Submit a pull request

This implementation is based on the research paper:

"SACL: Understanding and Combating Textual Bias in Code Retrieval with Semantic-Augmented Reranking and Localization"

- Authors: Dhruv Gupta, Gayathri Ganesh Lakshmy, Yiqing Xie
- arXiv: 2506.20081v2
- Systematic Bias Detection: Identifies textual bias through feature masking
- Semantic Augmentation: Enhances code understanding beyond text
- Bias-Aware Ranking: Reduces surface-level feature dependency
- Localization: Pinpoints functionally relevant code regions

- Claude Code: Direct MCP integration
- Cursor: MCP server connection
- VS Code Extensions: Via MCP protocol
- Custom Tools: Any MCP-compatible client

-

JavaScript/TypeScript: Full AST analysis with relationship extraction

- Import/export tracking
- Function call analysis
- Class inheritance detection
- Dynamic imports support

- Import statement parsing
- Class inheritance detection
- Function call patterns

Other Languages(Java, C++, C#, Go, Rust): Basic analysis

- Import/include statements
- Class declarations
- Function definitions

Extensible: Easy to add new language analyzers

MIT License - see LICENSE file for details.

- Issues: GitHub Issues
- Documentation: See/docsdirectory
- Research Paper:arXiv:2506.20081v2

AI-to-AI code review platform — Claude, Codex, and Gemini cross-check each other via MCP, REST API, and CLI for consensus-based results.