SACL MCP Server

Un marco para la recuperación de código consciente de sesgos mediante reranking y localización con aumento semántico.

Documentación

SACL MCP Server

Reordenamiento y Localización con Aumento Semántico para la Recuperación de Código

Un servidor de Protocolo de Contexto de Modelo (MCP) que implementa el marco de investigación SACL para proporcionar recuperación de código consciente del sesgo para asistentes de codificación de IA como Claude Code, Cursor y otras herramientas habilitadas para MCP.

🎯 Resumen

SACL aborda el problema crítico del sesgo textual en los sistemas de recuperación de código. Los sistemas tradicionales dependen en exceso de características superficiales como docstrings, comentarios y nombres de variables, lo que produce resultados sesgados que favorecen código bien documentado independientemente de su relevancia funcional.

Características Principales

🧠 Detección de Sesgo: Identifica la dependencia excesiva de características textuales
🔍 Aumento Semántico: Enriquece la comprensión del código más allá del texto superficial
📊 Reordenamiento Inteligente: Prioriza la relevancia funcional sobre la documentación
🎯 Localización de Código: Identifica con precisión segmentos de código funcionalmente relevantes
🔗 Análisis de Relaciones: Mapea dependencias y relaciones del código
🎨 Recuperación Contextual: Devuelve resultados con componentes relacionados
🚀 Actualizaciones Controladas por Agente: Actualizaciones explícitas de archivos para compatibilidad con Docker
🗄️ Grafo de Conocimiento: Almacenamiento semántico persistente con Graphiti/Neo4j
🔧 Integración MCP: Funciona con Claude Code, Cursor y otras herramientas de IA

🏗️ Arquitectura

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

🚀 Inicio Rápido

Requisitos Previos

Node.js 18+
Base de datos Neo4j
Clave API de OpenAI

Instalación

# 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

Usando Docker (Recomendado)

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

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

Configuración Manual

# Build the project
npm run build

# Start the server
npm start

🔧 Configuración

Variables de Entorno

Variable	Descripción	Valor por Defecto
`OPENAI_API_KEY`	Clave API de OpenAI (requerida)	-
`SACL_REPO_PATH`	Repositorio a analizar	Directorio actual
`SACL_NAMESPACE`	Espacio de nombres único	Generado automáticamente
`SACL_LLM_MODEL`	Modelo LLM para análisis	`gpt-4`
`SACL_EMBEDDING_MODEL`	Modelo de embeddings	`text-embedding-3-small`
`SACL_BIAS_THRESHOLD`	Sensibilidad de detección de sesgo (0-1)	`0.5`
`SACL_MAX_RESULTS`	Máximo de resultados de búsqueda	`10`
`SACL_CACHE_ENABLED`	Habilitar caché de embeddings	`true`
`NEO4J_URI`	URI de conexión a Neo4j	`bolt://localhost:7687`
`NEO4J_USER`	Usuario de Neo4j	`neo4j`
`NEO4J_PASSWORD`	Contraseña de Neo4j	`password`

🎮 Uso

Herramientas MCP

El servidor SACL proporciona herramientas MCP completas para el análisis de código consciente del sesgo:

1. `analyze_repository`

Realiza un análisis SACL completo de un repositorio:

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

2. `query_code`

Búsqueda de código consciente del sesgo con contexto opcional:

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

3. `query_code_with_context` 🆕

Búsqueda mejorada con contexto de relaciones y componentes relacionados:

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

4. `update_file` 🆕

Actualiza explícitamente el análisis de un solo archivo cuando se realizan cambios:

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

5. `update_files` 🆕

Actualización por lotes de múltiples archivos:

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

6. `get_relationships` 🆕

Analiza relaciones y dependencias del código:

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

7. `get_file_context` 🆕

Obtén contexto completo para un archivo:

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

8. `get_bias_analysis`

Métricas detalladas de sesgo y depuración:

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

9. `get_system_stats`

Rendimiento del sistema y estadísticas:

{}

Configuración del Cliente MCP

Claude Desktop

Añade a tu 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

Configura en los ajustes de Cursor para conectarte al servidor MCP de SACL.

📊 Marco SACL

Etapa 1: Detección de Sesgo

Identifica tres tipos de sesgo textual:

Dependencia de Docstrings: Dependencia excesiva de la documentación
Sesgo de Nombres de Identificadores: Enfoque en nombres de variables/funciones
Dependencia Excesiva de Comentarios: Priorización de código comentado

Etapa 2: Aumento Semántico

Enriquece las representaciones del código con:

Firmas Funcionales: Lo que el código realmente hace
Patrones de Comportamiento: Patrones computacionales (iteración, recursión, etc.)
Características Estructurales: Métricas de complejidad, análisis AST
Embeddings Aumentados: Vectores semánticos ajustados por sesgo

Etapa 3: Reordenamiento y Localización

Clasificación Consciente del Sesgo: Reduce el peso textual según la puntuación de sesgo
Localización de Código: Identifica segmentos funcionalmente relevantes
Similitud Semántica: Utiliza embeddings aumentados
Relevancia Funcional: Considera patrones computacionales

Etapa 4: Análisis de Relaciones 🆕

Mapea relaciones y dependencias del código:

Análisis de Importación/Exportación: Dependencias y exportaciones de módulos
Mapeo de Llamadas a Funciones: Grafos de llamadas e invocaciones de métodos
Herencia de Clases: Relaciones de extensión/implementación
Seguimiento de Dependencias: Dependencias externas e internas
Resultados Contextuales: Componentes relacionados con cada resultado de consulta

🧪 Flujo de Trabajo de Ejemplo

Análisis de Repositorio:

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

Consulta de Código con Contexto:

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

Actualizaciones de Archivos:

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

Exploración de Relaciones:

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

Los Resultados Incluyen:
- Puntuación original de similitud textual
- Puntuación de similitud semántica
- Puntuación final ajustada por sesgo
- Regiones de código localizadas
- Componentes y dependencias relacionados
- Explicación del contexto con importancia de las relaciones
- Explicación de las decisiones de clasificación

📈 Rendimiento

Basado en los benchmarks de investigación de SACL:

Mejora del 12.8% en Recall@1 en HumanEval
Mejora del 9.4% en MBPP
Mejora del 7.0% en SWE-Bench-Lite
Latencia P95: <300ms para operaciones de recuperación

🔍 Ejemplo de Análisis de Sesgo

🧠 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

🛠️ Desarrollo

Estructura del Proyecto

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

Compilación

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

Contribuciones

Haz un fork del repositorio
Crea una rama de características
Implementa cambios siguiendo la metodología SACL
Añade pruebas para la nueva funcionalidad
Envía un pull request

📚 Antecedentes de Investigación

Esta implementación se basa en el artículo de investigación:

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

Autores: Dhruv Gupta, Gayathri Ganesh Lakshmy, Yiqing Xie
arXiv: 2506.20081v2

Contribuciones Clave de la Investigación

Detección Sistemática de Sesgo: Identifica el sesgo textual mediante enmascaramiento de características
Aumento Semántico: Mejora la comprensión del código más allá del texto
Clasificación Consciente del Sesgo: Reduce la dependencia de características superficiales
Localización: Identifica con precisión regiones de código funcionalmente relevantes

🔗 Integración

Herramientas de IA Compatibles

Claude Code: Integración directa con MCP
Cursor: Conexión al servidor MCP
Extensiones de VS Code: Mediante el protocolo MCP
Herramientas Personalizadas: Cualquier cliente compatible con MCP

Soporte de Lenguajes

JavaScript/TypeScript: Análisis AST completo con extracción de relaciones
- Seguimiento de importaciones/exportaciones
- Análisis de llamadas a funciones
- Detección de herencia de clases
- Soporte de importaciones dinámicas
Python: Análisis basado en expresiones regulares
- Análisis de sentencias de importación
- Detección de herencia de clases
- Patrones de llamadas a funciones
Otros Lenguajes (Java, C++, C#, Go, Rust): Análisis básico
- Sentencias de importación/inclusión
- Declaraciones de clases
- Definiciones de funciones
Extensible: Fácil de añadir nuevos analizadores de lenguajes

📄 Licencia

Licencia MIT: consulta el archivo LICENSE para más detalles.

🆘 Soporte

Problemas: GitHub Issues
Documentación: Consulta el directorio /docs
Artículo de Investigación: arXiv:2506.20081v2

🔮 Mejoras Futuras

SACL MCP Server - Llevando la recuperación de código consciente del sesgo respaldada por investigación a los asistentes de codificación de IA.

SACL MCP Server

Documentación

SACL MCP Server

🎯 Resumen

Características Principales

🏗️ Arquitectura

🚀 Inicio Rápido

Requisitos Previos

Instalación

Usando Docker (Recomendado)

Configuración Manual

🔧 Configuración

Variables de Entorno

🎮 Uso

Herramientas MCP

1. analyze_repository

2. query_code

3. query_code_with_context 🆕

4. update_file 🆕

5. update_files 🆕

6. get_relationships 🆕

7. get_file_context 🆕

8. get_bias_analysis

9. get_system_stats

Configuración del Cliente MCP

Claude Desktop

Cursor IDE

📊 Marco SACL

Etapa 1: Detección de Sesgo

Etapa 2: Aumento Semántico

Etapa 3: Reordenamiento y Localización

Etapa 4: Análisis de Relaciones 🆕

🧪 Flujo de Trabajo de Ejemplo

📈 Rendimiento

🔍 Ejemplo de Análisis de Sesgo

🛠️ Desarrollo

Estructura del Proyecto

Compilación

Contribuciones

📚 Antecedentes de Investigación

Contribuciones Clave de la Investigación

🔗 Integración

Herramientas de IA Compatibles

Soporte de Lenguajes

📄 Licencia

🆘 Soporte

🔮 Mejoras Futuras

1. `analyze_repository`

2. `query_code`

3. `query_code_with_context` 🆕

4. `update_file` 🆕

5. `update_files` 🆕

6. `get_relationships` 🆕

7. `get_file_context` 🆕

8. `get_bias_analysis`

9. `get_system_stats`