SACL MCP Server

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.

🎯 Overview

SACL addresses the critical problem of textual bias in 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.

Key Features

• 🧠 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

🏗️ Architecture

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

🚀 Quick Start

Prerequisites

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

Installation

# Clone the repository
git clone 
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

Using Docker (Recommended)

# Start Neo4j and SACL server
docker-compose up -d

# Check logs
docker-compose logs -f sacl-mcp-server

Manual Setup

# Build the project
npm run build

# Start the server
npm start

🔧 Configuration

Environment Variables

🎮 Usage

MCP Tools

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

1. `analyze_repository`

Performs full SACL analysis of a repository:

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

2. `query_code`

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
}

3. `query_code_with_context` 🆕

Enhanced search with relationship context and related components:

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

4. `update_file` 🆕

Explicitly update single file analysis when changes are made:

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

5. `update_files` 🆕

Batch update multiple files:

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

6. `get_relationships` 🆕

Analyze code relationships and dependencies:

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

7. `get_file_context` 🆕

Get comprehensive context for a file:

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

8. `get_bias_analysis`

Detailed bias metrics and debugging:

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

9. `get_system_stats`

System performance and statistics:

{}

MCP Client Configuration

Claude Desktop

Add to your `claude_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"
      }
    }
  }
}

Cursor IDE

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

📊 SACL Framework

Stage 1: Bias Detection

Identifies three types of textual bias:

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

Stage 2: Semantic Augmentation

Enriches code representations with:

• 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

Stage 3: Reranking & Localization

• 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

Stage 4: Relationship Analysis 🆕

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

🧪 Example Workflow

1. Repository Analysis:

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

2. Code Query with Context:

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

3. File Updates:

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

4. Relationship Exploration:

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

5. Results Include:

📈 Performance

Based on SACL research benchmarks:

• 12.8% improvement in Recall@1 on HumanEval
• 9.4% improvement on MBPP
• 7.0% improvement on SWE-Bench-Lite
• P95 latency: 10k files)
• [ ] Real-time bias notifications during code writing
• [ ] Custom relationship type definitions

SACL MCP Server - Bringing research-backed bias-aware code retrieval to AI coding assistants.