Code Understanding

Analisa repositórios GitHub locais e remotos para fornecer compreensão de código e geração de contexto, incluindo análise de estrutura, identificação de arquivos e mapeamento semântico.

GitHub

Experimente este MCPPatrocinado

Documentação

⚠️ Aviso de Suporte de Plataforma

Este servidor MCP foi testado no macOS e Linux. O suporte para Windows ainda não foi verificado (ainda não testado).

Se você testar no Windows e encontrar problemas, por favor abra uma issue para que possamos melhorar o suporte multiplataforma.

Servidor MCP Code Understanding

Um servidor MCP (Model Context Protocol) projetado para entender bases de código e fornecer contexto inteligente para assistentes de codificação com IA. Este servidor lida com repositórios GitHub locais e remotos e suporta operações padrão compatíveis com MCP.

🤖 Instalação com Assistente de IA

Peça a um assistente de codificação com IA para ajudá-lo a instalar este servidor! Copie e cole o conteúdo do nosso Prompt do Assistente de Configuração para o seu assistente de IA (Claude, ChatGPT, Cursor, etc.) e ele o guiará por todo o processo de instalação.

Recursos

Clonar e analisar repositórios GitHub ou bases de código locais
Obter estrutura do repositório e organização de arquivos
Identificar arquivos críticos com base em métricas de complexidade e estrutura de código
Gerar mapas detalhados do repositório mostrando:
- Assinaturas de funções e relacionamentos
- Definições de classes e hierarquias
- Estrutura de código e dependências
Recuperar e analisar documentação do repositório
Análise direcionada a arquivos ou diretórios específicos
Manter a análise atualizada com mudanças no repositório via atualização

Início Rápido: Configuração do Cliente MCP

Pré-requisitos

Obrigatório: Instalação do uv

Este servidor requer uv, um gerenciador de pacotes Python moderno. Se você ainda não tem o uv instalado:

# Install UV (macOS/Linux)
curl -sSf https://astral.sh/uv/install.sh | sh

# Install UV (Windows PowerShell)
irm https://astral.sh/uv/install.ps1 | iex

Para mais opções de instalação, visite o guia oficial de instalação do uv em astral.sh/uv.

Métodos de Instalação

Método 1: Execução direta com uvx (Recomendado)

# Run directly without installing a global binary
uvx code-understanding-mcp-server

Isso inicia o servidor em um ambiente isolado gerenciado pelo UV a cada execução.

Método 2: Instalação em ambiente virtual (Opcional)

Se você preferir um binário persistente dentro de um ambiente virtual dedicado:

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package into the venv
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

Verificar Instalação

Dependendo do método escolhido:

# Method 1 (uvx): runs via uvx; no persistent binary is installed
uvx --version

# Method 2 (venv install): verify the binary inside your venv
which code-understanding-mcp-server
# Expected output example: /Users/username/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server

Configurar Seu Cliente MCP

Use uma das seguintes configurações para o seu cliente MCP:

{
  "mcpServers": {
    "code-understanding": {
      "command": "uvx",
      "args": [
        "code-understanding-mcp-server"
      ]
    }
  }
}

Alternativamente, se você instalou em um ambiente virtual, aponte diretamente para o binário nesse ambiente:

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/.venvs/mcp-code-understanding/bin/code-understanding-mcp-server",
      "args": []
    }
  }
}

Por que Usar Este Servidor MCP?

Servidor MCP Code Understanding

Proposta de Valor

O Servidor MCP Code Understanding capacita assistentes de IA com capacidades abrangentes de compreensão de código, permitindo que eles forneçam assistência mais precisa, contextual e prática com tarefas de desenvolvimento de software. Ao criar uma ponte semântica entre repositórios e sistemas de IA, este servidor reduz drasticamente o tempo e o atrito envolvidos na exploração, análise e orientação de implementação de código.

Casos de Uso Comuns

Análise de Repositório de Referência

Examinar repositórios externos (bibliotecas, dependências, etc.) para informar o desenvolvimento atual
Encontrar padrões de implementação e exemplos em projetos de código aberto
Entender como bibliotecas específicas funcionam internamente quando a documentação é insuficiente
Comparar abordagens de implementação entre projetos semelhantes
Identificar melhores práticas de bases de código de alta qualidade

Extração de Conhecimento e Documentação

Gerar documentação abrangente para bases de código mal documentadas
Criar visões gerais arquiteturais e diagramas de relacionamento de componentes
Desenvolver caminhos de aprendizado progressivos para integração de desenvolvedores
Extrair lógica de negócios e conhecimento de domínio embutidos no código
Identificar e documentar pontos de integração do sistema e dependências

Avaliação e Melhoria da Base de Código

Analisar dívida técnica e priorizar esforços de refatoração
Identificar vulnerabilidades de segurança e problemas de conformidade
Avaliar cobertura e qualidade de testes
Detectar código morto, lógica duplicada e oportunidades de otimização
Avaliar a implementação em relação a padrões de design e princípios arquiteturais

Compreensão de Sistemas Legados

Recuperar conhecimento de sistemas com documentação mínima
Apoiar o planejamento de migração entendendo os limites do sistema
Analisar dependências complexas antes de fazer alterações
Rastrear implementações de recursos em múltiplos componentes
Entender decisões de design históricas e suas justificativas

Transferência de Conhecimento Entre Projetos

Aplicar padrões de um projeto para outro
Preencher lacunas de conhecimento entre equipes que trabalham em sistemas relacionados
Identificar componentes reutilizáveis em múltiplos projetos
Entender diferenças nas abordagens de implementação entre equipes
Facilitar o compartilhamento de conhecimento em ambientes de desenvolvimento distribuídos

Para exemplos detalhados de como o Servidor MCP Code Understanding pode ser usado em cenários do mundo real, consulte nosso documento de Cenários de Exemplo. Ele inclui orientações passo a passo sobre:

Acelerar a integração de desenvolvedores em uma base de código complexa
Planejar e executar migrações de API
Conduzir avaliações de vulnerabilidades de segurança

Como Funciona

O Servidor MCP Code Understanding processa repositórios através de uma série de etapas de análise:

Clonagem do Repositório: O servidor clona o repositório alvo em seu cache
Análise de Estrutura: Análise de diretórios, arquivos e sua organização
Identificação de Arquivos Críticos: Determinação de componentes estruturalmente significativos
Recuperação de Documentação: Coleta de todos os arquivos de documentação
Mapeamento Semântico: Criação de um mapa detalhado mostrando relacionamentos entre componentes
Análise de Conteúdo: Exame de arquivos específicos conforme necessário para compreensão mais profunda

Assistentes de IA integram-se ao servidor fazendo solicitações direcionadas para cada etapa analítica, construindo uma compreensão abrangente da base de código que pode ser usada para abordar perguntas e necessidades específicas dos usuários.

Fluxo de Trabalho Recomendado para Assistentes de IA

Ao trabalhar com repositórios, os assistentes de IA devem seguir este fluxo de trabalho para obter resultados ideais:

Verificar Cache Primeiro: Use list_cached_repository_branches para ver se o repositório já está em cache
- Se estiver em cache: Pule para a etapa 3 (atualização)
- Se não estiver em cache: Continue para a etapa 2
Descobrir Nomes de Branches: Muitos repositórios usam "master", "develop" ou outros nomes em vez de "main"
- Use list_remote_branches para descobrir branches disponíveis
- Identifique o branch padrão correto antes de clonar
Atualizar Antes da Análise: Repositórios em cache ficam desatualizados com o tempo
- Use refresh_repo para puxar as alterações mais recentes antes de qualquer análise
- Isso garante que a análise seja baseada no código atual, não no cache desatualizado
Realizar Análise: Uma vez que o repositório esteja atualizado, use as ferramentas de análise
- get_source_repo_map para estrutura de código
- get_repo_critical_files para identificar componentes-chave
- get_repo_documentation para descoberta de documentação

Este fluxo de trabalho previne problemas comuns como falhas de clonagem devido a nomes de branches incorretos, tentativas redundantes de clonagem e análise baseada em dados de cache desatualizados.

Considerações de Design para Bases de Código Grandes

O servidor emprega várias estratégias para manter desempenho e usabilidade mesmo com repositórios de escala empresarial:

Processamento Assíncrono: Clonagem e análise de repositórios ocorrem em threads em segundo plano, fornecendo feedback imediato enquanto a análise mais profunda continua
Análise Progressiva: Análise inicial rápida permite interação imediata, com compreensão mais detalhada construída ao longo do tempo
Controle de Escopo: Parâmetros para max_tokens, files e directories permitem análise direcionada de áreas específicas de interesse
Gerenciamento de Limites: Detecção automática do tamanho do repositório com orientação apropriada para estratégias de análise
Compreensão Hierárquica: A estrutura do repositório é analisada primeiro, permitindo priorização inteligente de componentes críticos para análise semântica mais profunda

Essas escolhas de design garantem que os desenvolvedores possam começar a trabalhar imediatamente com bases de código grandes enquanto o sistema constrói uma compreensão progressivamente mais profunda em segundo plano, alcançando um equilíbrio ideal entre profundidade de análise e capacidade de resposta.

Autenticação GitHub (Opcional)

Se você precisar acessar repositórios privados ou quiser evitar limites de taxa da API do GitHub, adicione seu token do GitHub à configuração:

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/code-understanding-mcp-server",
      "args": [],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    }
  }
}

Opções Avançadas de Configuração

Para usuários avançados, o servidor suporta várias opções de configuração:

{
  "mcpServers": {
    "code-understanding": {
      "command": "/path/to/code-understanding-mcp-server",
      "args": [
        "--cache-dir", "~/custom-cache-dir",     // Override repository cache location
        "--max-cached-repos", "20",              // Override maximum number of cached repos
        "--transport", "stdio",                  // Transport type (stdio or sse)
        "--port", "3001"                         // Port for SSE transport (only used with sse)
      ],
      "env": {
        "GITHUB_PERSONAL_ACCESS_TOKEN": "your-github-token-here"
      }
    }
  }
}

Opções disponíveis:

--cache-dir: Substituir o local do diretório de cache do repositório (padrão: ~/.cache/mcp-code-understanding)
--max-cached-repos: Definir o número máximo de repositórios em cache (padrão: 10)
--transport: Escolher o tipo de transporte (stdio ou sse, padrão: stdio)
--port: Definir a porta para transporte SSE (padrão: 3001, usado apenas com transporte sse)

Notas Específicas por Plataforma

macOS

Com uvx, nenhum binário persistente é instalado; nenhuma alteração de PATH é necessária
Com um ambiente virtual, certifique-se de ativá-lo ou referencie o caminho completo para o binário do venv

Linux

Com uvx, nenhum binário persistente é instalado; nenhuma alteração de PATH é necessária
Com um ambiente virtual, você pode preferir adicionar um alias de ajuda ou ativar o venv antes do uso

Windows

Atualmente não suportado - O suporte para Windows está planejado para uma versão futura
O trabalho de desenvolvimento está em andamento para habilitar a compatibilidade com Windows

Solução de Problemas

Conflitos de Dependência

Se você encontrar conflitos de dependência ao usar uvx, crie um ambiente isolado e instale o pacote lá:

# Create a dedicated virtual environment
uv venv ~/.venvs/mcp-code-understanding

# Activate it (macOS/Linux)
source ~/.venvs/mcp-code-understanding/bin/activate

# Install the package
uv pip install code-understanding-mcp-server

# Run the server
code-understanding-mcp-server

Binário Não Encontrado

Se o binário instalado não for encontrado:

Verifique o local de instalação:

# macOS/Linux
find ~/.local -name "code-understanding-mcp-server" 2>/dev/null

Adicione ao PATH se necessário:

# Add to ~/.bashrc, ~/.zshrc, or appropriate shell config
export PATH="$HOME/.local/bin:$PATH"

Use o caminho absoluto para o binário do seu venv na configuração MCP se não estiver ativando o venv

Configuração do Servidor

O servidor usa um arquivo config.yaml para configuração base. Este arquivo é criado automaticamente no diretório de configuração padrão (~/.config/mcp-code-understanding/config.yaml) quando o servidor é executado pela primeira vez. Você também pode colocar um arquivo config.yaml no seu diretório atual para substituir a configuração padrão.

Aqui está a estrutura de configuração padrão:

name: "Code Understanding Server"
log_level: "debug"

repository:
  cache_dir: "~/.cache/mcp-code-understanding"
  max_cached_repos: 10

documentation:
  include_tags:
    - markdown
    - rst
    - adoc
  include_extensions:
    - .md
    - .markdown
    - .rst
    - .txt
    - .adoc
    - .ipynb
  format_mapping:
    tag:markdown: markdown
    tag:rst: restructuredtext
    tag:adoc: asciidoc
    ext:.md: markdown
    ext:.markdown: markdown
    ext:.rst: restructuredtext
    ext:.txt: plaintext
    ext:.adoc: asciidoc
    ext:.ipynb: jupyter
  category_patterns:
    readme: 
      - readme
    api: 
      - api
    documentation:
      - docs
      - documentation
    examples:
      - examples
      - sample

Para Desenvolvedores

Pré-requisitos

Python 3.11 ou 3.12: Necessário tanto para desenvolvimento quanto para uso
```
# Verify your Python version
python --version
# or
python3 --version
```
Gerenciador de Pacotes UV: O instalador de pacotes Python moderno
```
# Install UV
curl -sSf https://astral.sh/uv/install.sh | sh
```

Configuração de Desenvolvimento

Para contribuir ou executar este projeto localmente:

# 1. Clone the repository
git clone https://github.com/yourusername/mcp-code-understanding.git
cd mcp-code-understanding

# 2. Create virtual environment
uv venv

# 3. Activate the virtual environment
#    Choose the command appropriate for your operating system and shell:

#    Linux/macOS (bash/zsh):
source .venv/bin/activate

#    Windows (Command Prompt - cmd.exe):
.venv\\Scripts\\activate.bat

#    Windows (PowerShell):
#    Note: You might need to adjust your execution policy first.
#    Run: Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope Process
.venv\\Scripts\\Activate.ps1

# 4. Install dependencies (editable mode with dev extras)
#    (Ensure your virtual environment is activated first!)
uv pip install -e ".[dev]"

# 5. Set up pre-commit hooks
pre-commit install

# 6. Run tests
uv run pytest

# 7. Test the server using MCP inspector
# Without GitHub authentication:
uv run mcp dev src/code_understanding/mcp/server/app.py

# With GitHub authentication (for testing private repos):
GITHUB_PERSONAL_ACCESS_TOKEN=your_token_here uv run mcp dev src/code_understanding/mcp/server/app.py

Isso iniciará um console interativo onde você pode testar todos os endpoints do servidor MCP diretamente.

Ferramentas de Desenvolvimento

As seguintes ferramentas de desenvolvimento estão disponíveis após a instalação com extras de desenvolvimento (.[dev]):

Executar testes com cobertura:

uv run pytest

Formatar código (usando black e isort):

# Format with black
uv run black .

# Sort imports
uv run isort .

Verificação de tipos com mypy:

uv run mypy .

Todas as ferramentas são configuradas via pyproject.toml com configurações otimizadas para este projeto.

Publicação no PyPI

Quando estiver pronto para publicar uma nova versão no PyPI, siga estes passos:

Atualize o número da versão em pyproject.toml:

# Edit pyproject.toml and change the version field
# For example: version = "0.1.1"

Limpe artefatos de build anteriores:

# Remove previous distribution packages and build directories
rm -rf dist/ 2>/dev/null || true
rm -rf build/ 2>/dev/null || true
rm -rf src/*.egg-info/ 2>/dev/null || true

Construa os pacotes de distribuição:
```
uv run python -m build
```
Verifique os pacotes construídos:
```
ls dist/
```

Envie para o PyPI (use TestPyPI primeiro se não tiver certeza):

# Install twine if you haven't already
uv pip install twine

# For PyPI release:
uv run python -m twine upload dist/*

Você precisará de credenciais do PyPI configuradas ou será solicitado a inseri-las durante o envio.

Histórico de Versões

v0.1.6 (Mais Recente)

Correção de Dependência: configargparse==1.7 explicitamente fixado para resolver problemas de instalação causados pela versão removida no PyPI
Isso garante instalação limpa com uvx e outros gerenciadores de pacotes, prevenindo falhas de resolução de dependências
Nenhuma mudança funcional nas capacidades do servidor

Licença

MIT