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.

Free Forever Setup Time Local Execution Core Tools Languages

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_code e unified_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_neighborhood e get_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 em get_call_graph e get_graph_neighborhood, além de consciência parcial em alguns caminhos compartilhados de JS/TS/Java.

IdiomaExtensõesDestaques
Python.pyAST completo + PDG + execução simbólica
JavaScript.js, .jsxAST, extração, consciência parcial de grafo/dependências
TypeScript.ts, .tsxAnálise completa de tipos, componentes React
Java.javaAnálise e extração de AST
Go (novo na v2.1).goFunções, métodos, structs, interfaces, imports, goroutines
Kotlin.kt, .ktsAnálise configurada por nível e detecção de sumidouros
PHP.phpAnálise configurada por nível e detecção de sumidouros
Ruby.rbAnálise configurada por nível e detecção de sumidouros
Swift.swiftAnálise configurada por nível e detecção de sumidouros
Rust.rsAnálise configurada por nível e detecção de sumidouros
C (novo na v2.0).c, .hFunções, structs, uniões, enums, macros, bitfields
C++ (novo na v2.0).cpp, .hpp, .cc e maisClasses, templates, namespaces, sobrecarga de operadores
C# (novo na v2.0).csClasses, 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.

AbordagemTokens UsadosCusto (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áliseAgente de Correspondência de TextoCode Scalpel (AST + PDG)
Renomeação simples~73% correto97% correto
Refatoração entre arquivos~41% correto94% correto
Edição com consciência de segurança~28% correto91% 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_integrity garante 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:

  1. 📖 O que é isso? — Entenda o Code Scalpel em 10 segundos com exemplos visuais
  2. ⚡ Configuração em 2 Minutos — Instale e configure o Claude Desktop em menos de 2 minutos
  3. 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

→ Cobertura OWASP Top 10

🏢 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)

→ Guia Empresarial


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:

  1. 📖 Guia de Instalação para Claude — Guia completo de configuração para Claude Desktop, VSCode e Cursor com instruções passo a passo.
  2. ✅ Configuração de Licença — Configure sua licença e comece a usar em 5 minutos.
  3. 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.md na 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:

ProblemaSem Code ScalpelCom Code Scalpel
Encontrar uma funçãoLer arquivo inteiro (10.000 tokens)extract_code("calculate_tax") (287 tokens)
Encontrar dependênciasLer 5+ arquivos manualmente (50.000 tokens)get_cross_file_dependencies("Order") (892 tokens)
Varredura de segurançaAdivinhar padrões (70% de falsos positivos)security_scan() com análise de fluxo de dados (<10% FP)
Refatorar com segurançaTorcer para dar certosimulate_refactor() verifica o comportamento
Encontrar usosPesquisar 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

FerramentaTaxa de Falsos PositivosTaxa de Detecção
Code Scalpel9,8%89,8%
Semgrep22,4%86,2%
Bandit31,7%82,3%
CodeQL15,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:

RecursoCode ScalpelPython scalpel
InterfaceServidor MCP (principal)Apenas ferramenta CLI
Pronto para Agentes de IASim (projetado para agentes)Apenas CLI
Ferramentas23 ferramentasUtilitários limitados
Varredura de SegurançaAnálise de fluxo de dados (12 CWEs)Correspondência de padrões básica
Execução SimbólicaAlimentada por Z3 (todos os caminhos)Não suportado
Geração de TestesGeração automática a partir de caminhosNão suportado
Verificação de RefatoraçãoVerificação de preservação de comportamentoVerificação manual
Análise Entre ArquivosRastreamento completo de dependênciasEscopo limitado
LicenciamentoComunitário (MIT) + Pro/EnterpriseN/A

Code Scalpel vs Outras Ferramentas de Análise de Código

RecursoCode ScalpelAST ExplorerSemgrepPylint
Uso PrincipalServidor MCP para agentes de IAVisualização de códigoPadrões de segurançaLinting de estilo
Número de Ferramentas23 ferramentasApenas consulta~1000 regrasLimitado
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

RecursoCode ScalpelVS Code PylanceIDEs JetBrainsCopilot
InterfaceServidor MCPPlugin de IDEPlugin de IDEApenas 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
  • uvx instalado (vem com Python via pip install uv)
  • Claude Code ou Claude Desktop

O que acontece:

  1. Claude executa uvx codescalpel mcp quando você pede análise de código
  2. Todas as 23 ferramentas ficam disponíveis no seu assistente de IA para análise de código
  3. 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?

  1. Reinicie o Claude Code ou o Claude Desktop
  2. Verifique se uvx codescalpel funciona no seu terminal:
    uvx codescalpel --version
    
  3. 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

ComandoDescriçãoExemplo
codescalpel extract-codeExtrair funções/classes com dependênciascodescalpel extract-code src/api.py --function handler
codescalpel analyzeRealizar análise AST e estáticacodescalpel analyze src/main.py --json
codescalpel scanDetecção de vulnerabilidades de segurançacodescalpel scan src/
codescalpel get-call-graphGerar grafos de chamada de funçõescodescalpel get-call-graph src/app.py
codescalpel get-file-contextObter visão geral da estrutura de arquivoscodescalpel get-file-context src/models.py
codescalpel get-symbol-referencesEncontrar todos os usos de símboloscodescalpel get-symbol-references MyClass
codescalpel rename-symbolRenomeação segura de símboloscodescalpel rename-symbol src/api.py old_name new_name
codescalpel generate-unit-testsGeração de testes com IAcodescalpel generate-unit-tests src/utils.py
codescalpel cross-file-security-scanAnálise de fluxo de dados entre arquivoscodescalpel cross-file-security-scan
codescalpel validate-pathsValidar caminhos de importaçãocodescalpel 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

Comunidade

Tem dúvidas? Abra uma issue ou inicie uma discussão.