SACL MCP Server

Servidor SACL MCP

Reclassificação e Localização Aumentadas por Semântica para Recuperação de Código

Um servidor Model Context Protocol (MCP) que implementa o framework de pesquisa SACL para fornecer recuperação de código consciente de viés para assistentes de codificação de IA, como Claude Code, Cursor e outras ferramentas habilitadas para MCP.

🎯 Visão Geral

O SACL aborda o problema crítico do viés textual em sistemas de recuperação de código. Sistemas tradicionais dependem excessivamente de características superficiais, como docstrings, comentários e nomes de variáveis, levando a resultados tendenciosos que favorecem código bem documentado, independentemente da relevância funcional.

Principais Recursos

• 🧠 Detecção de Viés: Identifica dependência excessiva de características textuais
• 🔍 Aumento Semântico: Enriquece a compreensão do código além do texto superficial
• 📊 Reclassificação Inteligente: Prioriza relevância funcional sobre documentação
• 🎯 Localização de Código: Identifica segmentos de código funcionalmente relevantes
• 🔗 Análise de Relacionamentos: Mapeia dependências e relacionamentos de código
• 🎨 Recuperação Consciente de Contexto: Retorna resultados com componentes relacionados
• 🚀 Atualizações Controladas por Agente: Atualizações explícitas de arquivos para compatibilidade com Docker
• 🗄️ Grafo de Conhecimento: Armazenamento semântico persistente com Graphiti/Neo4j
• 🔧 Integração MCP: Funciona com Claude Code, Cursor e outras ferramentas de IA

🏗️ Arquitetura

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

🚀 Início Rápido

Pré-requisitos

• Node.js 18+
• Banco de dados Neo4j
• Chave da API OpenAI

Instalação

# 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

Configuração Manual

# Build the project
npm run build

# Start the server
npm start

🔧 Configuração

Variáveis de Ambiente

Variável	Descrição	Padrão
OPENAI_API_KEY	Chave da API OpenAI (obrigatória)	-
SACL_REPO_PATH	Repositório a ser analisado	Diretório atual
SACL_NAMESPACE	Namespace exclusivo	Gerado automaticamente
SACL_LLM_MODEL	Modelo LLM para análise	gpt-4
SACL_EMBEDDING_MODEL	Modelo de incorporação	text-embedding-3-small
SACL_BIAS_THRESHOLD	Sensibilidade de detecção de viés (0-1)	0.5
SACL_MAX_RESULTS	Número máximo de resultados de pesquisa	10
SACL_CACHE_ENABLED	Habilitar cache de incorporação	true
NEO4J_URI	URI de conexão Neo4j	bolt://localhost:7687
NEO4J_USER	Nome de usuário Neo4j	neo4j
NEO4J_PASSWORD	Senha Neo4j	password

🎮 Uso

Ferramentas MCP

O servidor SACL fornece ferramentas MCP abrangentes para análise de código consciente de viés:

1. analyze_repository

Executa análise SACL completa de um repositório:

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

2. query_code

Pesquisa de código consciente de viés com 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 🆕

Pesquisa aprimorada com contexto de relacionamento e componentes relacionados:

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

4. update_file 🆕

Atualiza explicitamente a análise de um único arquivo quando alterações são feitas:

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

5. update_files 🆕

Atualização em lote de múltiplos arquivos:

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

6. get_relationships 🆕

Analisa relacionamentos e dependências de código:

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

7. get_file_context 🆕

Obtém contexto abrangente para um arquivo:

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

8. get_bias_analysis

Métricas detalhadas de viés e depuração:

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

9. get_system_stats

Desempenho do sistema e estatísticas:

{}

Configuração do Cliente MCP

Claude Desktop

Adicione ao seu 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"
      }
    }
  }
}

IDE Cursor

Configure nas configurações do Cursor para conectar ao servidor MCP SACL.

📊 Framework SACL

Estágio 1: Detecção de Viés

Identifica três tipos de viés textual:

• Dependência de Docstring: Dependência excessiva de documentação
• Viés de Nome de Identificador: Foco em nomes de variáveis/funções
• Dependência Excessiva de Comentários: Priorização de código comentado

Estágio 2: Aumento Semântico

Enriquece representações de código com:

• Assinaturas Funcionais: O que o código realmente faz
• Padrões de Comportamento: Padrões computacionais (iteração, recursão, etc.)
• Características Estruturais: Métricas de complexidade, análise AST
• Incorporações Aumentadas: Vetores semânticos ajustados para viés

Estágio 3: Reclassificação e Localização

• Classificação Consciente de Viés: Reduz peso textual com base na pontuação de viés
• Localização de Código: Identifica segmentos funcionalmente relevantes
• Similaridade Semântica: Usa incorporações aumentadas
• Relevância Funcional: Considera padrões computacionais

Estágio 4: Análise de Relacionamentos 🆕

Mapeia relacionamentos e dependências de código:

• Análise de Import/Export: Dependências e exportações de módulos
• Mapeamento de Chamadas de Função: Grafos de chamadas e invocações de métodos
• Herança de Classes: Relacionamentos extends/implements
• Rastreamento de Dependências: Dependências externas e internas
• Resultados Conscientes de Contexto: Componentes relacionados com cada resultado de consulta

🧪 Fluxo de Trabalho de Exemplo

1. Análise de Repositório:

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

2. Consulta de Código com Contexto:

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

3. Atualizações de Arquivos:

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

4. Exploração de Relacionamentos:

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

5. Os Resultados Incluem:

   • Pontuação original de similaridade textual
   • Pontuação de similaridade semântica
   • Pontuação final ajustada para viés
   • Regiões de código localizadas
   • Componentes relacionados e dependências
   • Explicação de contexto com importância de relacionamento
   • Explicação das decisões de classificação

📈 Desempenho

Com base em benchmarks de pesquisa SACL:

• 12,8% de melhoria em Recall@1 no HumanEval
• 9,4% de melhoria no MBPP
• 7,0% de melhoria no SWE-Bench-Lite
• Latência P95: <300ms para operações de recuperação

🔍 Exemplo de Análise de Viés

🧠 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

🛠️ Desenvolvimento

Estrutura do Projeto

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

Compilação

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

Contribuindo

1. Faça um fork do repositório
2. Crie um branch de funcionalidade
3. Implemente alterações seguindo a metodologia SACL
4. Adicione testes para novas funcionalidades
5. Envie um pull request

📚 Contexto de Pesquisa

Esta implementação é baseada no artigo de pesquisa:

"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

Principais Contribuições de Pesquisa

1. Detecção Sistemática de Viés: Identifica viés textual através de mascaramento de características
2. Aumento Semântico: Melhora a compreensão do código além do texto
3. Classificação Consciente de Viés: Reduz dependência de características superficiais
4. Localização: Identifica regiões de código funcionalmente relevantes

🔗 Integração

Ferramentas de IA Suportadas

• Claude Code: Integração MCP direta
• Cursor: Conexão com servidor MCP
• Extensões VS Code: Via protocolo MCP
• Ferramentas Personalizadas: Qualquer cliente compatível com MCP

Suporte a Linguagens

• JavaScript/TypeScript: Análise AST completa com extração de relacionamentos

  • Rastreamento de import/export
  • Análise de chamadas de função
  • Detecção de herança de classes
  • Suporte a imports dinâmicos

• Python: Análise baseada em regex

  • Análise de declarações de import
  • Detecção de herança de classes
  • Padrões de chamadas de função

• Outras Linguagens (Java, C++, C#, Go, Rust): Análise básica

  • Declarações de import/include
  • Declarações de classes
  • Definições de funções

• Extensível: Fácil adicionar novos analisadores de linguagem

📄 Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

🆘 Suporte

• Problemas: GitHub Issues
• Documentação: Consulte o diretório /docs
• Artigo de Pesquisa: arXiv:2506.20081v2

🔮 Melhorias Futuras

• Análise AST multilíngue para todas as linguagens suportadas
• Integração Graphiti em tempo real (atualmente usa métodos simulados)
• Detecção de relacionamentos semânticos além da análise sintática
• Grafos de relacionamentos visuais em respostas MCP
• Configuração de limite de viés personalizado por projeto
• Integração com Language Server Protocol (LSP)
• Algoritmos avançados de localização com aprendizado de máquina
• Otimizações de desempenho para grandes bases de código (>10k arquivos)
• Notificações de viés em tempo real durante a escrita de código
• Definições de tipos de relacionamento personalizados

---

Servidor SACL MCP - Trazendo recuperação de código consciente de viés baseada em pesquisa para assistentes de codificação de IA.