Code Scalpel
Code Scalpel é um servidor MCP que aprimora seu agente de codificação de IA com ferramentas cirúrgicas baseadas em grafos para análise precisa, refatoração atômica e 99% menos custos de tokens.
Documentação
Code Scalpel: Reduza os Custos de IA em 200x
Última Versão: v2.2.0 | 28 de março de 2026
Pare de copiar e colar arquivos inteiros no Claude. Dê ao seu assistente de IA ferramentas cirúrgicas de análise de código e reduza os custos em até 200x.
Novidades na v2.2.0 — Completude de Telemetria e Segurança contra Falhas
Esta versão adiciona streaming JSONL à prova de falhas, telemetria de caminhos de falha para todas as 23 ferramentas, campos de erro criptografados e políticas automáticas de retenção de logs. Todos os eventos de telemetria agora são capturados com tratamento adequado de erros e liberados incrementalmente a cada chamada de ferramenta para máxima durabilidade.
Novidades na v2.1.1 — Sincronização de Metadados
Esta versão de correção atualiza os metadados públicos de empacotamento para que o PyPI e o texto do Marketplace correspondam ao enquadramento atual do produto com 22 ferramentas principais.
Anterior: v2.1.0 — Matriz de Idiomas Expandida
[20260310_DOCS] Os arquivos de nível de fonte da verdade atualmente anunciam 13 idiomas nas superfícies configuradas por nível
analyze_codeeunified_sink_detect.
[20260306_DOCS] As superfícies principais de análise, extração e análise sintática abrangem todo o conjunto de idiomas. Ferramentas MCP orientadas a grafos, como
get_call_graph,get_graph_neighborhoodeget_cross_file_dependencies, permanecem hoje com foco em Python, com uma fatia inicial de paridade de nós de função JavaScript/TypeScript agora disponível emget_call_grapheget_graph_neighborhood, além de consciência parcial em alguns caminhos compartilhados de JS/TS/Java.
| Idioma | Extensões | Destaques |
|---|---|---|
| Python | .py | AST completo + PDG + execução simbólica |
| JavaScript | .js, .jsx | AST, extração, consciência parcial de grafo/dependências |
| TypeScript | .ts, .tsx | Análise completa de tipos, componentes React |
| Java | .java | Análise e extração de AST |
| Go (novo na v2.1) | .go | Funções, métodos, structs, interfaces, imports, goroutines |
| Kotlin | .kt, .kts | Análise configurada por nível e detecção de sumidouros |
| PHP | .php | Análise configurada por nível e detecção de sumidouros |
| Ruby | .rb | Análise configurada por nível e detecção de sumidouros |
| Swift | .swift | Análise configurada por nível e detecção de sumidouros |
| Rust | .rs | Análise configurada por nível e detecção de sumidouros |
| C (novo na v2.0) | .c, .h | Funções, structs, uniões, enums, macros, bitfields |
| C++ (novo na v2.0) | .cpp, .hpp, .cc e mais | Classes, templates, namespaces, sobrecarga de operadores |
| C# (novo na v2.0) | .cs | Classes, records, interfaces, genéricos, async/await |
285 novos testes de idioma adicionados (v2.0: 262; v2.1: +23 testes Go). Zero mudanças que quebram as APIs existentes. Consulte CHANGELOG para detalhes completos.
Independente por Padrão, Compatível com Empresas por Design
O Code Scalpel oferece análise e extração de primeira parte prontas para uso. O valor principal não depende de scanners de terceiros licenciados ou plataformas externas.
- Núcleo independente: análise sintática, análise estrutural, normalização de IR, análise de taint, execução simbólica e descobertas de segurança de linha de base funcionam como capacidades nativas do Code Scalpel.
- Suporte a ferramentas abertas: ferramentas CLI locais sem licença podem ser executadas diretamente quando prático.
- Adaptadores empresariais: ferramentas como Coverity, SonarQube, ReSharper, Exakat e plataformas similares podem ser ingeridas por meio de JSON, XML, SARIF exportados ou cargas de API e normalizadas em um único modelo de análise interno.
- Sem dependência obrigatória: scanners de terceiros podem estender fluxos de trabalho empresariais, mas não são necessários para o valor básico do produto.
Isso dá às equipes a divisão certa:
- Independente o suficiente para funcionar imediatamente em ambientes locais e autogerenciados.
- Amigável para empresas o suficiente para se integrar a pilhas existentes de AppSec, conformidade e governança.
- Arquitetonicamente honesto sobre o que o Code Scalpel analisa nativamente versus o que ele federa de sistemas externos.
Em resumo: o Code Scalpel é independente por padrão, compatível com empresas por design.
O que é o Code Scalpel? (Versão de 30 Segundos)
O Code Scalpel é um servidor MCP (Model Context Protocol) que dá a assistentes de IA como Claude, GitHub Copilot e Cursor a capacidade de extrair e analisar código cirurgicamente em vez de ler arquivos inteiros.
Antes do Code Scalpel ❌
# You paste entire 500-line file into Claude
# Tokens: 10,247 tokens
# Cost: $0.030 per query
# Time: 12 seconds
# Claude has to read everything, even irrelevant code
Depois do Code Scalpel ✅
# Ask: "Use Code Scalpel to extract calculate_tax function"
# Claude uses extract_code tool automatically
# Tokens: 287 tokens (just the function you need)
# Cost: $0.0009 per query
# Time: 2 seconds
Economia: redução de 97% nos custos, redução de 83% no tempo, zero mudanças no fluxo de trabalho.
A Ponte: IA Estocástica → Engenharia Confiável
O Code Scalpel é a ponte entre IA estocástica (LLMs que adivinham) e engenharia de software confiável (sistemas determinísticos que sabem).
Seu assistente de IA é um mecanismo de probabilidade. Ele gera a resposta mais provável com base em padrões nos dados de treinamento. Isso funciona brilhantemente para prosa e código padrão. Ele falha quando a precisão é inegociável — refatorar um serviço de produção, rastrear uma injeção de SQL por quatro arquivos ou provar que uma renomeação afetou todos os chamadores.
O Code Scalpel envolve seu agente estocástico em uma caixa de vidro determinística: cada operação de código é respaldada por um parse de AST real, um grafo de chamadas real, um provador de teoremas real. O agente ainda gera; o Code Scalpel verifica, executa e registra.
Stochastic LLM → Code Scalpel → Deterministic Code Operations
(guesses) (glass box) (verified facts)
Os Quatro Pilares
1. 💸 IA Mais Barata — Redução de 99% no Contexto
Em vez de alimentar o modelo com 10 arquivos completos (15.000 tokens), o mecanismo PDG do Code Scalpel extrai cirurgicamente apenas a função relevante e suas dependências ativas.
| Abordagem | Tokens Usados | Custo (Claude Sonnet) |
|---|---|---|
| Ler arquivo inteiro | ~10.000 | $0,030 por consulta |
extract_code("calculate_tax") | ~200 | $0,0006 por consulta |
Resultado: $450/mês → $22/mês fazendo o mesmo trabalho. Você economiza dinheiro e o modelo foca melhor porque não está afogado em contexto irrelevante.
2. 🎯 IA Mais Precisa — Fatos de Grafo, Não Suposições de LLM
Quando o Code Scalpel relata "esta função tem 3 chamadores", isso é um fato de grafo derivado da análise de AST — não uma estimativa de LLM.
| Análise | Agente de Correspondência de Texto | Code Scalpel (AST + PDG) |
|---|---|---|
| Renomeação simples | ~73% correto | 97% correto |
| Refatoração entre arquivos | ~41% correto | 94% correto |
| Edição com consciência de segurança | ~28% correto | 91% correto |
Execução simbólica com o provador de teoremas Z3 explora matematicamente todos os caminhos de código — encontrando casos extremos que humanos e LLMs perdem. Quando symbolic_execute diz que um caminho é seguro, é comprovadamente seguro.
3. 🛡️ IA Mais Segura — O Guardião Ciente de Sintaxe
Cada edição gerada por IA passa pelo parser de AST do Code Scalpel antes de tocar o disco.
Sem o Code Scalpel: O agente alucina um
)ausente → arquivo gravado → build quebra → você descobre depois.Com o Code Scalpel: O parser de AST falha na saída malformada → edição rejeitada e registrada → o agente tenta novamente com código corrigido.
A ferramenta simulate_refactor executa um diff comportamental antes que qualquer mudança seja aplicada. Se a semântica mudar inesperadamente, a operação é bloqueada.
4. 🏛️ IA Governável — A Trilha de Auditoria Invisível
Conformidade não é opcional em ambientes regulados. O Code Scalpel cria uma trilha de .code-scalpel/audit.jsonl para cada operação do agente.
- Procedência: Registramos o caminho de decisão (rastro de grafo), não apenas o diff de saída.
- Integridade:
verify_policy_integritygarante criptograficamente que suas regras de governança não se desviaram. - Explicabilidade: Quando um regulador pergunta "por que o agente fez essa mudança?", você tem uma resposta determinística e reproduzível — não "o modelo parecia confiante".
Novo? Comece Aqui 👋
Nunca usou o Code Scalpel? Comece em 3 passos:
- 📖 O que é isso? — Entenda o Code Scalpel em 10 segundos com exemplos visuais
- ⚡ Configuração em 2 Minutos — Instale e configure o Claude Desktop em menos de 2 minutos
- Pergunte ao seu assistente de IA — "Use o Code Scalpel para extrair [nome_da_função] de [arquivo.py]"
É isso. Você verá uma redução de 200x em tokens na sua primeira consulta.
Para Quem É Isso?
O Code Scalpel atende a 4 tipos principais de usuários:
👤 Desenvolvedores Individuais (Foco em Redução de Custos)
Você está gastando $50-450/mês na API do Claude e quer cortar custos em 95%.
- ✅ Exemplo real: $450/mês → $22/mês
- ✅ Instalação em 2 minutos, zero manutenção
- ✅ Funciona com Claude Desktop, GitHub Copilot, Cursor
→ Guia de Otimização de Custos
👥 Líderes de Equipe (Foco em ROI de Equipe)
Você gerencia 8-15 desenvolvedores e precisa reduzir os custos de IA da equipe em 40%+.
- ✅ Exemplo real: $3.000/mês → $1.800/mês = $14.400/ano economizados
- ✅ Implantação em 1 hora com modelos e manuais
- ✅ Análise de uso e acompanhamento de ROI incluídos
→ Guia de Início Rápido para Equipes
🛡️ Engenheiros de Segurança (Foco em Avaliação AppSec)
Você precisa de cobertura OWASP Top 10 com taxa de falsos positivos <10%.
- ✅ Análise de segurança baseada em taint (injeção de SQL, XSS, injeção de comandos, SSRF)
- ✅ Taxa de falsos positivos <10% (medida em mais de 2.000 repositórios)
- ✅ OWASP Top 10 2021 mapeado com exemplos CWE
- ✅ Rastreamento de vulnerabilidades entre arquivos
🏢 Arquitetos Empresariais (Foco em Conformidade e Escala)
Você precisa de conformidade SOC2/ISO e implantação para 500-2000+ usuários.
- ✅ Opção de implantação on-premise (ambientes isolados)
- ✅ Integração com SSO/LDAP empresarial
- ✅ Verificação criptográfica de políticas
- ✅ Executa localmente (nenhum código enviado para a nuvem)
Instalação Rápida
Para Usuários do Claude Desktop / VSCode / Cursor
uvx codescalpel mcp
Em seguida, siga o Guia de Instalação para Claude para integrar com seu assistente de IA.
Ou veja todas as Opções de Instalação abaixo.
Início Rápido (3 Passos)
Novo no Code Scalpel? Comece aqui:
- 📖 Guia de Instalação para Claude — Guia completo de configuração para Claude Desktop, VSCode e Cursor com instruções passo a passo.
- ✅ Configuração de Licença — Configure sua licença e comece a usar em 5 minutos.
- Comece a perguntar ao seu assistente de IA — Peça ao Claude, Copilot ou Cursor para ajudar com seu código.
Mantenedores? Consulte o Guia de Lançamento para publicar no PyPI, GitHub e VS Code Marketplace.
Desenvolvedores? Consulte as Opções de Instalação e a Documentação abaixo.
🚀 Integração com Claude Code (NOVO na v2.2.0)
Configuração em uma linha para usuários do Claude Code:
curl -fsSL https://raw.githubusercontent.com/3D-Tech-Solutions/code-scalpel/main/integration/claude-code/setup.sh | bash
Isso instala:
- ✅ Servidor MCP — Registro automático com o Claude Code
- ✅ 8 Comandos de Barra —
/cs-extract,/cs-security,/cs-refactor,/cs-map,/cs-analyze,/cs-tests,/cs-setup,/cs-policy - ✅ Prompts de Sistema — Ensina ao Claude Code quando/como usar cada ferramenta
- ✅ Guia Completo —
CLAUDE.mdna raiz do seu projeto
Resultado: O Claude Code usa automaticamente o Code Scalpel para análise de código, auditorias de segurança, refatoração segura e mapeamento de arquitetura.
📖 Guia Completo de Integração com Claude Code — Documentação completa com exemplos e fluxos de trabalho.
O Problema: Por que Agentes de IA Precisam do Code Scalpel
A maioria das equipes está no Dia 1 da engenharia agentica: "Olha, ele escreve código!" O Dia 3 está chegando — e o Dia 3 é sobre Governança, Segurança e Conformidade.
Os agentes de hoje tratam o código como texto. Eles leem arquivos como um romance, adivinham números de linha e vibe-code seu caminho através de refatorações. Em um ambiente sério de engenharia ou regulado, isso cria três riscos compostos:
- O Risco da Caixa-Preta — Um regulador ou revisão de incidente pergunta por que o agente tomou uma decisão. Você não consegue explicar porque foi um palpite probabilístico, não uma operação registrada e rastreável.
- O Risco de Alucinação — O agente inventa um fechamento
), um import ausente ou uma dependência inexistente. O build quebra silenciosamente ou — pior — vai para produção. - O Risco do Ponto Cego — O agente gera uma vulnerabilidade de injeção SQL porque não consegue ver o fluxo de dados entre arquivos. A correspondência de padrões não detecta o que a análise de fluxo de dados encontra.
Code Scalpel é o adulto na sala. Ele substitui o palpite por operações determinísticas, auditáveis e baseadas em grafos.
1. 💸 Desperdício Massivo de Tokens (95% dos tokens são irrelevantes)
Você pergunta: "Explique a função calculate_tax."
A IA lê: Arquivo inteiro de 500 linhas com imports, classes e outras 20 funções.
Resultado: 10.000 tokens para responder a uma pergunta de 50 tokens.
2. ⏱️ Tempos de Resposta Lentos (esperas de 10 a 15 segundos)
Processar arquivos grandes leva tempo. Toda consulta envolvendo código:
- Envia o conteúdo do arquivo inteiro (latência de rede)
- A IA processa tudo (atraso computacional)
- Gera resposta a partir do contexto completo
Resultado: 10 a 15 segundos por consulta em vez de 1 a 2 segundos.
3. 🔴 Erros de Limite de Contexto (Não é possível analisar bases de código grandes)
O limite de 200K tokens do Claude parece grande até você atingi-lo:
- 5 arquivos médios = 50.000 tokens
- 10 arquivos médios = 100.000 tokens
- 20 arquivos médios = LIMITE EXCEDIDO
Resultado: Não é possível analisar nada além de projetos pequenos.
4. 🐛 Alucinação e Erros ("Substituir linha 50" quebra quando o arquivo muda)
A IA gera: "Substitua as linhas 45-50 por..."
Você aplica a alteração. O arquivo tinha 48 linhas. Agora seu código está quebrado.
Resultado: Modificações frágeis e propensas a erros.
A Solução: Ferramentas Cirúrgicas, Não Análise de Texto
Code Scalpel dá aos agentes de IA 23 ferramentas para interagir com código como dados estruturados (AST + PDG), não como texto, além de uma superfície separada de introspecção de capacidades para descoberta de nível/licença:
| Problema | Sem Code Scalpel | Com Code Scalpel |
|---|---|---|
| Encontrar uma função | Ler arquivo inteiro (10.000 tokens) | extract_code("calculate_tax") (287 tokens) |
| Encontrar dependências | Ler 5+ arquivos manualmente (50.000 tokens) | get_cross_file_dependencies("Order") (892 tokens) |
| Varredura de segurança | Adivinhar padrões (70% de falsos positivos) | security_scan() com análise de fluxo de dados (<10% FP) |
| Refatorar com segurança | Torcer para dar certo | simulate_refactor() verifica o comportamento |
| Encontrar usos | Pesquisar todos os arquivos (100.000 tokens) | get_symbol_references("MyClass") (1.234 tokens) |
Princípio-chave: Agentes de IA usam ferramentas determinísticas em vez de adivinhação de texto.
Recursos de Segurança (Equipes de AppSec)
Cobertura do OWASP Top 10
✅ A03:2021 - Injeção (Cobertura Completa)
- Injeção de SQL (CWE-89)
- XSS (CWE-79)
- Injeção de Comandos (CWE-78)
- Path Traversal (CWE-22)
- Injeção NoSQL (CWE-943)
- Injeção LDAP (CWE-90)
✅ A06:2021 - Componentes Vulneráveis (Cobertura Completa)
- Detecção de CVE via API OSV
- Banco de dados de vulnerabilidades em tempo real
- Varredura de dependências transitivas
✅ A10:2021 - SSRF (Cobertura Completa)
- Detecção de Server-Side Request Forgery
- Rastreamento de validação de URL
✅ A08:2021 - Integridade de Software (Cobertura Completa)
- Detecção de desserialização insegura
- Verificação de políticas criptográficas
Taxa de Falsos Positivos: <10%
Medida em mais de 2.000 repositórios de código aberto
| Ferramenta | Taxa de Falsos Positivos | Taxa de Detecção |
|---|---|---|
| Code Scalpel | 9,8% | 89,8% |
| Semgrep | 22,4% | 86,2% |
| Bandit | 31,7% | 82,3% |
| CodeQL | 15,8% | 92,1% |
Análise de Fluxo de Dados Entre Arquivos
Rastreia dados contaminados através de limites de módulos:
# routes.py
user_input = request.args.get('query') # TAINT SOURCE
execute_search(user_input) # Flows to database.py
# database.py
def execute_search(query):
cursor.execute(f"SELECT * FROM items WHERE name='{query}'") # SINK ❌
Code Scalpel detecta esta injeção SQL entre arquivos.
→ Documentação Completa do OWASP
23 Ferramentas (Todas Gratuitas na Edição Comunitária)
Code Scalpel fornece 23 ferramentas disponíveis em todas as edições.
Todas as 23 ferramentas estão disponíveis na Edição Comunitária gratuita. Os níveis Pro/Enterprise adicionam limites aprimorados e recursos de equipe.
Clientes de agentes também podem chamar get_capabilities para inspecionar os limites atuais de nível/licença.
1. Extração e Análise Cirúrgica (6 Ferramentas)
Pare de usar grep. Comece a entender.
extract_code: Extrai cirurgicamente funções/classes por nome, incluindo imports necessários.analyze_code: Analisa estrutura, complexidade, imports e definições.get_project_map: Mapa cognitivo instantâneo de alto nível da estrutura do projeto.get_call_graph: Rastreia fluxo de execução com prioridade Python, com paridade inicial local JS/TS.get_symbol_references: Encontra todos os usos de um símbolo no projeto.get_file_context: Obtém contexto circundante e metadados para qualquer localização de código.
2. Segurança Baseada em Fluxo de Dados (6 Ferramentas)
Análise de segurança real, não apenas correspondência de regex.
security_scan: Rastreia fluxo de dados de entrada do usuário até sinks perigosos (12+ CWEs).unified_sink_detect: Detecção poliglota de funções perigosas (sinks).cross_file_security_scan: Rastreia dados sujos mesmo quando passam por múltiplos módulos.scan_dependencies: Verifica dependências de pacotes para vulnerabilidades conhecidas (CVEs).type_evaporation_scan: Detecta vulnerabilidades do sistema de tipos TypeScript nos limites de I/O.get_graph_neighborhood: Extrai contexto de segurança k-hop com prioridade Python, com paridade inicial local de funções JS/TS e vizinhanças de métodos JS/TS quando resolução avançada está disponível.
3. Modificação Segura (4 Ferramentas)
update_symbol: Substituição atômica de blocos de código com verificações de segurança.rename_symbol: Refatoração em todo o projeto que atualiza todas as referências de forma consistente.simulate_refactor: Ferramenta de "execução simulada" que verifica alterações antes da aplicação (segurança/build).validate_paths: Validação de caminho pré-execução para operações de arquivo (ciente de Docker).
4. Verificação e Testes (3 Ferramentas)
Confie, mas verifique.
symbolic_execute: Usa o provador de teoremas Z3 para explorar mentalmente caminhos de código.generate_unit_tests: Cria automaticamente testes matemáticos de prova de correção a partir de caminhos de execução.crawl_project: Análise em todo o projeto de estrutura de código e métricas.
5. Análise Avançada (1 Ferramenta)
get_cross_file_dependencies: Analisa cadeias de dependência com prioridade Python entre arquivos.
6. Sistema e Infraestrutura (2 Ferramentas)
Ferramentas de infraestrutura e governança para orquestração de agentes e aplicação de políticas.
code_policy_check: Avalia código contra padrões de conformidade organizacional e políticas de segurança.verify_policy_integrity: Verifica integridade de arquivos de política usando assinaturas criptográficas.
Como Somos Diferentes
Code Scalpel vs Biblioteca Python scalpel
Code Scalpel NÃO é um fork ou wrapper da biblioteca Python scalpel. É um servidor MCP completamente independente e de nível de produção:
| Recurso | Code Scalpel | Python scalpel |
|---|---|---|
| Interface | Servidor MCP (principal) | Apenas ferramenta CLI |
| Pronto para Agentes de IA | Sim (projetado para agentes) | Apenas CLI |
| Ferramentas | 23 ferramentas | Utilitários limitados |
| Varredura de Segurança | Análise de fluxo de dados (12 CWEs) | Correspondência de padrões básica |
| Execução Simbólica | Alimentada por Z3 (todos os caminhos) | Não suportado |
| Geração de Testes | Geração automática a partir de caminhos | Não suportado |
| Verificação de Refatoração | Verificação de preservação de comportamento | Verificação manual |
| Análise Entre Arquivos | Rastreamento completo de dependências | Escopo limitado |
| Licenciamento | Comunitário (MIT) + Pro/Enterprise | N/A |
Code Scalpel vs Outras Ferramentas de Análise de Código
| Recurso | Code Scalpel | AST Explorer | Semgrep | Pylint |
|---|---|---|---|---|
| Uso Principal | Servidor MCP para agentes de IA | Visualização de código | Padrões de segurança | Linting de estilo |
| Número de Ferramentas | 23 ferramentas | Apenas consulta | ~1000 regras | Limitado |
| Extração de Código | ✅ Por nome de símbolo, seguro | ⚠️ Inspeção manual de AST | ❌ Não é principal | ❌ Não suportado |
| Varredura de Segurança | ✅ Análise completa de fluxo de dados (12 CWEs) | ❌ Não | ⚠️ Baseada em padrões | ⚠️ Apenas básico |
| Execução Simbólica | ✅ Alimentada por Z3 | ❌ Não | ❌ Não | ❌ Não |
| Geração de Testes | ✅ Geração automática a partir de caminhos | ❌ Não | ❌ Não | ❌ Não |
| Refatoração Segura | ✅ Verificação de comportamento | ❌ Manual | ❌ Não suportado | ❌ Não suportado |
| Dependências Entre Arquivos | ✅ Rastreamento completo | ⚠️ Limitado | ⚠️ Limitado | ⚠️ Limitado |
| Servidor MCP | ✅ Interface principal | ❌ Não | ❌ Não | ❌ Não |
| Amigável para LLM | ✅ Projetado para agentes | ⚠️ Limitado | ⚠️ Limitado | ⚠️ Limitado |
| Poliglota | ✅ 13 linguagens configuradas por nível | ✅ Multilinguagem | ✅ Multilinguagem | ⚠️ Apenas Python |
Code Scalpel vs Extensões de IDE
| Recurso | Code Scalpel | VS Code Pylance | IDEs JetBrains | Copilot |
|---|---|---|---|---|
| Interface | Servidor MCP | Plugin de IDE | Plugin de IDE | Apenas chat |
| Extração Cirúrgica | ✅ Por nome, seguro, entre arquivos | ⚠️ Parcial (baseada em linhas) | ⚠️ Parcial (baseada em linhas) | ❌ Não precisa |
| Análise de Segurança | ✅ 20 ferramentas de desenvolvimento, baseada em fluxo de dados | ⚠️ Limitada | ⚠️ Limitada | ⚠️ Generalista |
| Geração de Testes | ✅ Execução simbólica | ❌ Não | ❌ Não | ⚠️ Qualidade variável |
| Verificação de Comportamento | ✅ Antes de refatorar | ❌ Não | ⚠️ Limitada | ⚠️ Apenas manual |
| Independente de IDE | ✅ Funciona em qualquer lugar | ❌ Vinculado ao IDE | ❌ Vinculado ao IDE | ❌ Vinculado à web |
| Capaz Offline | ✅ Sim | ✅ Sim | ✅ Sim | ❌ Não |
| Reprodutível | ✅ Determinístico | ✅ Determinístico | ✅ Determinístico | ⚠️ Variável |
Opções de Instalação
🚀 Recomendado: Claude Code / Claude Desktop (transporte stdio)
Instalação em uma linha:
claude mcp add codescalpel uvx codescalpel mcp
Por que este método?
- ✅ Configuração mais simples (um comando)
- ✅ Atualizações automáticas via PyPI
- ✅ Funciona offline após o download inicial
- ✅ Sem necessidade de infraestrutura
- ✅ Zero configuração
Requisitos:
- Python 3.10+ instalado
uvxinstalado (vem com Python viapip install uv)- Claude Code ou Claude Desktop
O que acontece:
- Claude executa
uvx codescalpel mcpquando você pede análise de código - Todas as 23 ferramentas ficam disponíveis no seu assistente de IA para análise de código
- Seu código é analisado localmente; nenhum dado é enviado para servidores externos
🔑 Configuração de Licença Pro/Enterprise
Se você tem uma licença Pro ou Enterprise, precisa configurar o Code Scalpel para usar seu arquivo de licença.
Método 1: Local Padrão (Recomendado)
Coloque seu arquivo de licença no local padrão:
mkdir -p .code-scalpel/license
cp /path/to/your/license.jwt .code-scalpel/license/license.jwt
Depois use o comando de instalação padrão:
claude mcp add codescalpel uvx codescalpel mcp
O Code Scalpel descobrirá automaticamente sua licença.
Locais padrão de licença verificados (em ordem):
.code-scalpel/license/license.jwt(preferido).code-scalpel/license.jwt~/.config/code-scalpel/license.jwt(para todo o usuário)~/.code-scalpel/license.jwt(legado)
Método 2: Variável de Ambiente
Defina o caminho da licença no seu ambiente:
export CODE_SCALPEL_LICENSE_PATH=/path/to/license.jwt
claude mcp add codescalpel uvx codescalpel mcp
Método 3: Configuração Manual
Edite seu claude_desktop_config.json manualmente:
{
"mcpServers": {
"codescalpel": {
"command": "uvx",
"args": ["codescalpel", "mcp"],
"env": {
"CODE_SCALPEL_LICENSE_PATH": "/path/to/license.jwt"
}
}
}
}
Verifique Sua Licença
Verifique se sua licença é reconhecida:
uvx codescalpel tier-info
Saída esperada para Pro/Enterprise:
Current Tier: pro (or enterprise)
License Status: Valid
Expires: 2025-12-31
Alternativa: Configuração Manual
Se você preferir editar arquivos de configuração manualmente:
Claude Desktop (macOS/Windows/Linux):
Edite ~/.claude/claude_desktop_config.json e adicione:
{
"mcpServers": {
"codescalpel": {
"command": "uvx",
"args": ["codescalpel", "mcp"]
}
}
}
VS Code / Cursor:
Edite .vscode/mcp.json no seu workspace:
{
"mcpServers": {
"codescalpel": {
"command": "uvx",
"args": ["codescalpel", "mcp"]
}
}
}
Implantações de Rede: Transportes HTTP
Para equipes remotas, Docker, Kubernetes ou implantações de rede, o Code Scalpel suporta dois transportes baseados em HTTP:
SSE (Server-Sent Events) - Melhor para equipes remotas e Docker:
codescalpel mcp --transport sse --host 0.0.0.0 --port 8080
streamable-http - Melhor para sistemas de produção e balanceadores de carga:
codescalpel mcp --transport streamable-http --host 0.0.0.0 --port 8080
Com HTTPS para produção:
codescalpel mcp --transport sse --ssl-cert cert.pem --ssl-key key.pem
Configuração do cliente (SSE):
{
"mcpServers": {
"code-scalpel": {
"url": "http://localhost:8080/sse",
"transport": "sse"
}
}
}
Configuração do cliente (streamable-http):
{
"mcpServers": {
"code-scalpel": {
"url": "http://localhost:8080/mcp",
"transport": "http"
}
}
}
Consulte o Guia de Transportes MCP para instruções abrangentes de configuração, configuração de segurança e exemplos de implantação.
Solução de Problemas
"Comando não encontrado: uvx"?
pip install uv
Servidor MCP não aparecendo no Claude?
- Reinicie o Claude Code ou o Claude Desktop
- Verifique se
uvx codescalpelfunciona no seu terminal:uvx codescalpel --version - Se ainda não funcionar, tente a configuração manual (veja acima)
Modo de depuração: Ative o registro detalhado:
export SCALPEL_MCP_OUTPUT=DEBUG
claude mcp add codescalpel uvx codescalpel mcp
Depuração da validação de licença:
export SCALPEL_MCP_OUTPUT=DEBUG
export CODE_SCALPEL_LICENSE_PATH=/path/to/license.jwt # If needed
claude mcp add codescalpel uvx codescalpel mcp
Uso via CLI
Todas as 23 ferramentas agora estão disponíveis diretamente pela linha de comando!
Além da interface do servidor MCP, o Code Scalpel fornece comandos CLI dedicados para cada ferramenta. Isso é perfeito para:
- Scripts e automação — Integre em pipelines de CI/CD
- Análise manual — Acesso rápido pela linha de comando sem um cliente MCP
- Fluxos de trabalho em shell — Envie saída JSON entre ferramentas
Início Rápido
# Install Code Scalpel
pip install codescalpel
# View all available commands
codescalpel --help
# Get help for any specific command
codescalpel extract-code --help
Comandos CLI Comuns
| Comando | Descrição | Exemplo |
|---|---|---|
codescalpel extract-code | Extrair funções/classes com dependências | codescalpel extract-code src/api.py --function handler |
codescalpel analyze | Realizar análise AST e estática | codescalpel analyze src/main.py --json |
codescalpel scan | Detecção de vulnerabilidades de segurança | codescalpel scan src/ |
codescalpel get-call-graph | Gerar grafos de chamada de funções | codescalpel get-call-graph src/app.py |
codescalpel get-file-context | Obter visão geral da estrutura de arquivos | codescalpel get-file-context src/models.py |
codescalpel get-symbol-references | Encontrar todos os usos de símbolos | codescalpel get-symbol-references MyClass |
codescalpel rename-symbol | Renomeação segura de símbolos | codescalpel rename-symbol src/api.py old_name new_name |
codescalpel generate-unit-tests | Geração de testes com IA | codescalpel generate-unit-tests src/utils.py |
codescalpel cross-file-security-scan | Análise de fluxo de dados entre arquivos | codescalpel cross-file-security-scan |
codescalpel validate-paths | Validar caminhos de importação | codescalpel validate-paths src/main.py |
Veja todos os 23 comandos: Referência Completa de Ferramentas CLI →
Exemplos de Fluxos de Trabalho
Extrair e Analisar uma Função
# Extract function with dependencies
codescalpel extract-code src/api.py --function process_payment --include-deps > extracted.py
# Analyze the extracted code
codescalpel analyze extracted.py --json
# Generate comprehensive tests
codescalpel generate-unit-tests extracted.py
Pipeline de Auditoria de Segurança
# Run basic security scan
codescalpel scan src/
# Deep cross-file taint analysis
codescalpel cross-file-security-scan --max-depth 10
# Check policy compliance
codescalpel code-policy-check src/ --strict
Refatoração com Análise de Impacto
# Get current call graph
codescalpel get-call-graph src/auth.py
# Find all references
codescalpel get-symbol-references UserAuthentication
# Simulate refactor
codescalpel simulate-refactor src/auth.py --changes "rename UserAuthentication to AuthService"
# Perform rename
codescalpel rename-symbol src/auth.py UserAuthentication AuthService
Saída JSON para Automação
Todos os comandos suportam a flag --json para saída legível por máquina:
# Get JSON output
codescalpel analyze src/main.py --json | jq '.functions[] | .name'
# Pipe between commands
codescalpel crawl-project --json | jq '.high_complexity_files[]' | \
xargs -I {} codescalpel analyze {} --json
Sistema de Níveis
Todas as ferramentas CLI respeitam o mesmo sistema de licenciamento em três níveis do servidor MCP:
- Comunidade (Grátis): Todas as ferramentas disponíveis com limites básicos
- Pro: Limites aprimorados, análise entre arquivos, processamento paralelo
- Enterprise: Limites ilimitados, recursos avançados
Verifique seu nível atual e limites:
codescalpel capabilities
Para documentação CLI completa, consulte a Referência de Ferramentas CLI.
Informações de Lançamento
Data de Lançamento: Janeiro de 2026 Versão: v2.2.0 Licença: MIT (Comunidade)
O Code Scalpel foi criado para a nova era da Engenharia Agêntica. Não é apenas um linter; é o sistema sensorial e atuador para a próxima geração de desenvolvedores de IA.
Documentação
- Começando — Guia de configuração detalhado
- Guia de Configuração — Todas as opções de configuração
- Referência da API — Documentação completa das ferramentas
- Análise de Segurança — Como funciona a detecção de vulnerabilidades
Comunidade
Tem dúvidas? Abra uma issue ou inicie uma discussão.