MCP Server Zez Quality

🚀 Servidor MCP para Análise de Código e Geração de Testes

Um servidor MCP (Model Context Protocol) completo desenvolvido em Python usando FastMCP, projetado para análise estática de código, resumo de fluxo de execução e geração automática de prompts para criação de testes unitários.

📋 Índice

• Características
• Instalação
• Configuração
• Ferramentas Disponíveis
• Exemplos de Uso
• Integração com IDEs
• API Reference
• Troubleshooting

✨ Características

🔍 Analisador Estático

• Extração completa de assinatura de funções
• Análise de parâmetros com tipos e valores padrão
• Detecção de tipos de entrada e saída
• Mapeamento de dependências internas e externas
• Suporte a decoradores Python

🌊 Resumidor de Fluxo

• Análise de estruturas de controle (if/else, loops)
• Detecção de tratamento de exceções
• Mapeamento de pontos de retorno
• Cálculo de complexidade ciclomática
• Geração de resumo textual minimalista

📝 Gerador de Prompt Minimalista

• Combinação inteligente de análises estática e de fluxo
• Templates específicos por linguagem (Python, Java, JavaScript)
• Frameworks suportados: pytest, JUnit, Jest
• Estrutura de saída fixa e otimizada
• Estimativa automática de número de testes

🛠️ Instalação

Pré-requisitos

Python >= 3.8
pip >= 21.0

Instalação Rápida

# Clonar ou baixar os arquivos do servidor
git clone 
cd mcp-code-analyzer

# Instalar dependências
pip install -r requirements.txt

# Ou instalar manualmente
pip install fastmcp ast-tools

Instalação para Desenvolvimento

# Criar ambiente virtual
python -m venv venv
source venv/bin/activate  # Linux/Mac
# ou
venv\Scripts\activate  # Windows

# Instalar dependências de desenvolvimento
pip install -r requirements.txt
pip install pytest pytest-cov black flake8

⚙️ Configuração

1. Configuração Básica do Servidor

# mcp_server.py - Executar o servidor
if __name__ == "__main__":
    mcp.run(debug=True, host="localhost", port=8000)

2. Configuração para Claude Desktop

Adicione ao arquivo ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "code-analyzer": {
      "command": "python",
      "args": ["/caminho/completo/para/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/caminho/para/projeto"
      }
    }
  }
}

3. Configuração para VS Code

Instale a extensão MCP e adicione ao settings.json:

{
  "mcp.servers": {
    "code-analysis": {
      "command": "python",
      "args": ["/caminho/para/mcp_server.py"],
      "env": {
        "PYTHONPATH": "/caminho/para/projeto"
      }
    }
  }
}

🛠️ Ferramentas Disponíveis

1. analyze_function_static

Descrição: Extrai informações estruturais de uma função

Parâmetros:

• code (string): Código fonte da função

Retorna:

{
  "signature": "function_name(params) -> return_type",
  "parameters": [
    {
      "name": "param_name",
      "type": "param_type",
      "has_default": false,
      "default_value": null
    }
  ],
  "return_type": "return_type",
  "dependencies": {
    "imports": ["module1", "module2"],
    "internal_calls": ["func1", "func2"]
  },
  "decorators": ["@decorator1", "@decorator2"]
}

2. summarize_function_flow

Descrição: Analisa fluxo de controle da função

Parâmetros:

• code (string): Código fonte da função

Retorna:

{
  "flow_map": [
    {
      "type": "conditional",
      "condition": "x > 0",
      "has_else": true,
      "nested_flow": [...]
    }
  ],
  "complexity_score": 3,
  "summary": "IF(x > 0) -> LOOP(item in items) -> RETURN(result)"
}

3. generate_test_prompt

Descrição: Gera prompt otimizado para criação de testes

Parâmetros:

• code (string): Código fonte da função
• language (string, opcional): "python", "java", "javascript" (padrão: "python")
• test_framework (string, opcional): "pytest", "junit", "jest", "auto" (padrão: "pytest")

Retorna:

{
  "prompt": "Prompt otimizado para LLM...",
  "metadata": {
    "language": "python",
    "framework": "pytest",
    "complexity_score": 3,
    "estimated_tests": 8
  }
}

4. analyze_and_generate_complete

Descrição: Executa análise completa e gera prompt em uma única chamada

Parâmetros:

• code (string): Código fonte da função
• language (string, opcional): Linguagem de programação
• test_framework (string, opcional): Framework de teste

Retorna: Combinação de todas as análises anteriores com resumo consolidado

💡 Exemplos de Uso

Exemplo Básico - Python

# Código de exemplo
code = """
def calcular_media(numeros: List[float], ignorar_zeros: bool = False) -> float:
    if not numeros:
        raise ValueError("Lista não pode estar vazia")
    
    if ignorar_zeros:
        numeros = [n for n in numeros if n != 0]
    
    if not numeros:
        return 0.0
    
    return sum(numeros) / len(numeros)
"""

# Análise estática
resultado_estatico = analyze_function_static(code)
print(f"Assinatura: {resultado_estatico['signature']}")

# Análise de fluxo
resultado_fluxo = summarize_function_flow(code)
print(f"Complexidade: {resultado_fluxo['complexity_score']}")

# Geração de prompt
prompt_resultado = generate_test_prompt(code, "python", "pytest")
print("Prompt gerado:")
print(prompt_resultado["prompt"])

Exemplo Java

codigo_java = """
public List filterActiveUsers(List users, String department) 
    throws UserException {
    
    if (users == null || users.isEmpty()) {
        throw new IllegalArgumentException("Users list cannot be null or empty");
    }
    
    List result = new ArrayList<>();
    
    for (User user : users) {
        try {
            if (!user.isActive()) {
                continue;
            }
            
            if (department != null && !department.equals(user.getDepartment())) {
                continue;
            }
            
            result.add(user);
            
        } catch (Exception e) {
            logger.warn("Error processing user: " + user.getId(), e);
        }
    }
    
    return result;
}
"""

# Gerar prompt para JUnit
prompt_java = generate_test_prompt(codigo_java, "java", "junit")

Exemplo JavaScript

codigo_js = """
async function fetchUserData(userId, options = {}) {
    const { includeProfile = true, timeout = 5000 } = options;
    
    if (!userId || typeof userId !== 'string') {
        throw new Error('Invalid user ID');
    }
    
    try {
        const controller = new AbortController();
        const timeoutId = setTimeout(() => controller.abort(), timeout);
        
        const response = await fetch(`/api/users/${userId}`, {
            signal: controller.signal,
            headers: { 'Content-Type': 'application/json' }
        });
        
        clearTimeout(timeoutId);
        
        if (!response.ok) {
            throw new Error(`HTTP ${response.status}: ${response.statusText}`);
        }
        
        const userData = await response.json();
        
        if (includeProfile) {
            userData.profile = await fetchUserProfile(userId);
        }
        
        return userData;
        
    } catch (error) {
        if (error.name === 'AbortError') {
            throw new Error('Request timeout');
        }
        throw error;
    }
}
"""

# Gerar prompt para Jest
prompt_js = generate_test_prompt(codigo_js, "javascript", "jest")

🔧 Integração com IDEs

VS Code

1. Instalação da Extensão MCP

code --install-extension anthropic.mcp-client

1. Configuração

{
  "mcp.servers": {
    "code-analyzer": {
      "command": "python",
      "args": ["C:\\path\\to\\mcp_server.py"]
    }
  }
}

1. Uso

• Selecione uma função no editor
• Pressione Ctrl+Shift+P (Windows/Linux) ou Cmd+Shift+P (Mac)
• Digite "MCP: Analyze Function"
• Escolha a ferramenta desejada

Claude Desktop

1. Configuração (arquivo de configuração já mostrado acima)

1. Uso

@code-analyzer analyze_function_static

GitHub Copilot

1. Configuração via Plugin

{
  "github.copilot.chat.mcp.servers": [
    {
      "name": "code-analyzer",
      "command": "python",
      "args": ["/path/to/mcp_server.py"]
    }
  ]
}

1. Uso no Chat

@code-analyzer Analise esta função e gere testes

📊 API Reference

Classes Principais

StaticAnalyzer

Responsável pela análise estática de código.

Métodos:

• analyze_function(code: str) -> Dict[str, Any]
• _extract_signature(node: ast.FunctionDef) -> str
• _extract_parameters(node: ast.FunctionDef) -> List[Dict[str, Any]]
• _extract_return_type(node: ast.FunctionDef) -> str
• _extract_dependencies(tree: ast.AST) -> Dict[str, List[str]]

FlowSummarizer

Analisa fluxo de controle e complexidade.

Métodos:

• summarize_flow(code: str) -> Dict[str, Any]
• _analyze_flow(body: List[ast.stmt]) -> List[Dict[str, Any]]
• _calculate_complexity(flow_map: List[Dict[str, Any]]) -> int
• _generate_flow_summary(flow_map: List[Dict[str, Any]]) -> str

PromptGenerator

Gera prompts otimizados para LLMs.

Métodos:

• generate_test_prompt(static_analysis, flow_analysis, language, framework) -> Dict[str, Any]
• _build_prompt_sections(static_analysis, flow_analysis) -> Dict[str, str]
• _get_output_structure(language: str, framework: str) -> str
• _estimate_test_count(flow_analysis: Dict[str, Any]) -> int

Tipos de Dados

Resultado da Análise Estática

{
    "signature": str,           # Assinatura completa da função
    "parameters": List[{        # Lista de parâmetros
        "name": str,            # Nome do parâmetro
        "type": str,            # Tipo do parâmetro
        "has_default": bool,    # Tem valor padrão?
        "default_value": str    # Valor padrão (se houver)
    }],
    "return_type": str,         # Tipo de retorno
    "dependencies": {           # Dependências
        "imports": List[str],   # Módulos importados
        "internal_calls": List[str]  # Chamadas internas
    },
    "decorators": List[str]     # Decoradores aplicados
}

Resultado da Análise de Fluxo

{
    "flow_map": List[{          # Mapa do fluxo de execução
        "type": str,            # Tipo do elemento (conditional, loop_for, etc.)
        "condition": str,       # Condição (para if/while)
        "nested_flow": List     # Fluxo aninhado
    }],
    "complexity_score": int,    # Complexidade ciclomática
    "summary": str             # Resumo textual do fluxo
}

🚨 Troubleshooting

Problemas Comuns

1. Erro: "Nenhuma função encontrada no código"

Causa: O código não contém uma definição de função válida.

Solução:

# ❌ Incorreto
code = "x = 1 + 2"

# ✅ Correto  
code = "def minha_funcao(): return 1 + 2"

2. Erro de parsing AST

Causa: Código com sintaxe inválida.

Solução:

• Verifique a sintaxe do código
• Certifique-se de que a indentação está correta
• Teste o código em um interpretador Python primeiro

3. Servidor MCP não responde

Causa: Problemas de comunicação ou configuração.

Soluções:

# Testar servidor localmente
python mcp_server.py

# Verificar logs
python mcp_server.py --debug

# Verificar porta
netstat -an | grep 8000

4. Dependências não encontradas

Causa: FastMCP ou ast-tools não instalados.

Solução:

pip install --upgrade fastmcp
pip install ast-tools

Logs e Debugging

Habilitar Logs Detalhados

import logging
logging.basicConfig(level=logging.DEBUG)

# No servidor
mcp.run(debug=True, log_level="DEBUG")

Testar Ferramentas Individualmente

# Teste análise estática
from mcp_server import analyze_function_static

code = "def test(): pass"
result = analyze_function_static(code)
print(json.dumps(result, indent=2))

Validar Configuração MCP

# Verificar se o servidor responde
curl -X POST http://localhost:8000/mcp \
  -H "Content-Type: application/json" \
  -d '{"method": "tools/list"}'

🔬 Testes

Executar Testes

# Executar todos os testes
pytest test_mcp_server.py -v

# Executar com cobertura
pytest test_mcp_server.py --cov=mcp_server --cov-report=html

# Executar testes específicos
pytest test_mcp_server.py::TestStaticAnalyzer::test_analyze_simple_function -v

Estrutura de Testes

tests/
├── test_static_analyzer.py
├── test_flow_summarizer.py  
├── test_prompt_generator.py
├── test_integration.py
└── fixtures/
    ├── sample_functions.py
    └── expected_results.json

🚀 Performance e Otimização

Métricas de Performance

Dicas de Otimização

1. Cache de Resultados

from functools import lru_cache

@lru_cache(maxsize=1000)
def analyze_cached(code_hash):
    return analyze_function_static(code)

1. Processamento Assíncrono

import asyncio

async def analyze_multiple_functions(functions):
    tasks = [analyze_function_async(code) for code in functions]
    return await asyncio.gather(*tasks)

1. Limitação de Recursos

# Limitar tamanho do código
MAX_CODE_SIZE = 10000  # caracteres

if len(code) > MAX_CODE_SIZE:
    raise ValueError("Código muito grande")

🤝 Contribuição

Como Contribuir

1. Fork o repositório
2. Crie uma branch para sua feature (git checkout -b feature/AmazingFeature)
3. Commit suas mudanças (git commit -m 'Add some AmazingFeature')
4. Push para a branch (git push origin feature/AmazingFeature)
5. Abra um Pull Request

Padrões de Código

# Formatting
black mcp_server.py

# Linting  
flake8 mcp_server.py

# Type checking
mypy mcp_server.py

Roadmap

• [ ] Suporte a mais linguagens (C#, Go, Rust)
• [ ] Análise de múltiplos arquivos
• [ ] Interface web para visualização
• [ ] Plugin para JetBrains IDEs
• [ ] Métricas avançadas de qualidade de código
• [ ] Integração com CI/CD pipelines

📄 Licença

Este projeto está licenciado sob a MIT License - veja o arquivo LICENSE para detalhes.

🙏 Agradecimentos

• FastMCP - Framework MCP para Python
• AST Tools - Análise sintática Python
• Comunidade MCP - Protocolo e especificações

🎯 Pronto para usar! Este servidor MCP está pronto para integração com Claude, VS Code, GitHub Copilot e outros clientes MCP. Comece analisando suas funções e gerando testes de alta qualidade automaticamente!