jCodeMunch-MCP

Servidor MCP eficiente em tokens para exploração de código-fonte do GitHub via parsing de AST com tree-sitter

GitHub
2.7k
Experimente este MCPPatrocinado

Documentação

jCodeMunch MCP

O servidor MCP mais eficiente em tokens para recuperação precisa de código-fonte via parsing AST com tree-sitter. Reduza os custos de tokens de IA em 86-99% na exploração de código (média de 96%, benchmark com 28,3x menos tokens que um agente grep-and-read) e pare de queimar sua janela de contexto lendo arquivos inteiros.

Resultados reais, ao vivo da produção 838B+ tokens economizados · 136.000+ instalações reportadas · US$ 4,2M+ em gastos de IA evitados · 100.000+ kg de CO₂ evitados Números contadores em 2026-08-17, avaliados na taxa de entrada de US$ 5/MTok do Claude Opus. Todos os quatro só crescem, então leia-os como mínimos. Ao vivo em jcodemunch.com.

Funciona com Claude Code, Cursor, VS Code, Codex CLI, Windsurf, Continue e qualquer cliente compatível com MCP.

Instalar agora · Início rápido · Veja as evidências · Preços

PyPI version PyPI - Python Version License MCP Local-first Issues closed DOI

Grátis para uso pessoal. Use para ganhar dinheiro, e o Tio J. fica com uma parte. Justo? Licenças comerciais abaixo. Nossa garantia: se o jCodeMunch não se pagar, você não paga pelo jCodeMunch.

Por que jCodeMunch?

A maioria dos agentes de IA explora repositórios da maneira cara: abrem arquivos inteiros, examinam milhares de linhas irrelevantes, repetem. Isso não é "um pouco ineficiente". Isso é um incinerador de tokens.

O jCodeMunch indexa um codebase uma vez e permite que agentes recuperem apenas o código exato de que precisam: funções, classes, métodos, constantes, contornos e pacotes de contexto bem delimitados, com precisão de nível de byte. Ele analisa o código-fonte com tree-sitter, armazena metadados estruturados de símbolos (assinatura, tipo, nome qualificado, resumo, deslocamentos de byte) junto com o conteúdo bruto do arquivo em um índice local, e busca implementações exatas sob demanda em vez de reler arquivos repetidamente.

TarefaAbordagem tradicionalCom jCodeMunch
Encontrar uma funçãoAbrir e examinar arquivos grandesBuscar símbolo, buscar implementação exata
Entender um móduloLer regiões amplas do arquivoPuxar apenas símbolos e imports relevantes
Explorar estrutura do repoPercorrer arquivo após arquivoConsultar contornos, árvores e pacotes direcionados
"O que quebra se eu mudar X?"Não é possívelget_blast_radius

Indexe uma vez. Consulte barato. Continue em frente. Contexto de precisão vence contexto de força bruta.

Evidências

Benchmark reproduzível de eficiência de tokens

Medido com tiktoken cl100k_base em três repositórios públicos fixados em commits upstream, executado em 2026-09-03 na v1.108.316. Fluxo de trabalho: search_symbols (top 5) + get_symbol_source × 3 por consulta. Duas linhas de base, mesma execução, mesmo corpus, mesmo leitor de arquivos:

  • Grep-top-3: rg -l os termos da consulta, classifica arquivos por contagem de correspondências, abre os 3 primeiros inteiros. Isso é o que um agente competente sem a ferramenta realmente faz, e é o número a citar.
  • Read-all: todos os arquivos-fonte indexados concatenados. Um teto que ninguém paga; mantido para continuidade com números publicados anteriormente.
RepositórioArquivosSímbolosLinha de base Grep-top-3jCodeMunchvs grepvs read-all
expressjs/express18645515.724 média1.007 média15,6x153,5x
fastapi/fastapi1.18613.24085.296 média2.149 média39,7x384,1x
gin-gonic/gin981.45131.975 média1.537 média20,8x98,8x
Total geral (15 execuções de tarefas)664.97523.46728,3x241,1x

Contra um agente grep-and-read: redução de 96,5%, 28,3x menos tokens. Nenhum múltiplo único descreve cada consulta; as linhas por repositório acima mostram a variação. Contra read-all, o número é 99,6%, mas ninguém paga esse teto. A codificação compacta de transmissão MUNCH então reduz uma mediana de 45,5% a mais de bytes nas respostas.

Metodologia completa, commits fixados, harness e limitações conhecidas: benchmarks/METHODOLOGY.md · Reproduza você mesmo · TOKEN_SAVINGS.md

Teste A/B independente em um codebase de produção

Teste A/B de 50 iterações em um codebase real de produção Vue 3 + Firebase, jCodeMunch vs ferramentas nativas (Grep/Glob/Read), Claude Sonnet 4.6, sessão nova por iteração: taxa de sucesso 80% vs 72%, taxa de timeout 32% vs 40%, criação média de cache reduzida em 10,5%. Economias na camada de ferramentas isoladas da sobrecarga fixa: 15-25%. Uma categoria de descoberta apareceu exclusivamente na variante jCodeMunch: detecção de arquivos órfãos via find_importers, uma consulta estrutural que ferramentas nativas não conseguem responder sem scripts. Relatório completo: benchmarks/ab-test-naming-audit-2026-03-18.md

Mencionado por

Página completa de reconhecimentos →

Instalação

Instalações com um clique

Install in VS Code Install in VS Code Insiders Install in Cursor

Recomendado: um comando

uv tool install jcodemunch-mcp
jcodemunch-mcp init

Sem virtualenv para gerenciar, nada escrito no Python do sistema, e funciona como está em distros PEP 668 (Ubuntu 24.04+, Debian 12+) onde pip install puro é recusado. Ainda não tem uv?

init detecta automaticamente seus clientes MCP (Claude Code, Claude Desktop, Cursor, Windsurf, Continue), escreve as entradas de configuração deles, instala a política de prompt CLAUDE.md para que seu agente realmente use o jCodeMunch, opcionalmente instala hooks de aplicação, opcionalmente indexa seu projeto e audita seus arquivos de configuração de agente em busca de desperdício de tokens.

Outros caminhos de instalação
ComandoUse quando
uvx jcodemunch-mcpInstalação zero. Executa a partir de um ambiente efêmero — nada fica permanentemente no disco. As entradas de cliente que init escreve já invocam o servidor dessa forma, então para a maioria das configurações isso é tudo que é executado. ⚠ Os hooks de aplicação são a exceção: eles são gerados por um subshell com PATH mínimo e resolvem o executável pelo nome, então precisam de uv tool install (ou pipx/pip) para funcionar.
pipx install jcodemunch-mcpVocê já padroniza com pipx
pip install jcodemunch-mcpDentro de um virtualenv que você gerencia

Verifique:

jcodemunch-mcp --version

Configuração manual do Claude Code

claude mcp add -s user jcodemunch -- uvx jcodemunch-mcp

Sem etapa de instalação — uvx busca e executa o servidor sob demanda. Prefere no seu PATH (e necessário para hooks de aplicação)? uv tool install jcodemunch-mcp, depois claude mcp add -s user jcodemunch jcodemunch-mcp.

Depois diga ao agente para preferir as ferramentas. Isso importa mais do que as pessoas pensam; a instalação disponibiliza as ferramentas, mas não quebra o hábito de leitura bruta do agente. Uma linha no seu CLAUDE.md resolve:

Call the jcodemunch_guide tool and strictly follow its instructions.

Usando Cursor, Windsurf, Codex CLI, Antigravity, Gemini CLI, Qwen Code, Kiro, Cline, Zed, Goose, Hermes, Odysseus ou Paperclip? Toda configuração de cliente testada está em CLIENTS.md. Extras opcionais (busca semântica local, resumos de IA por provedor) estão em QUICKSTART.md; os sistemas que cada extra puxa são documentados em SECURITY.md.

Início rápido

Passo a passo completo: QUICKSTART.md. A versão de dois minutos, dentro do seu agente após init:

  1. Pergunte: "Indexe este repo com jcodemunch."
  2. Pergunte: "Usando jcodemunch, encontre a função que lida com autenticação e mostre-me o código-fonte dela."

O agente deve responder via search_symbols e get_symbol_source, retornando dezenas de linhas em vez de arquivos inteiros. Confirme com get_session_stats: ele reporta tokens servidos e economias para a sessão. É daí que vêm os números no medidor.

Quer pular a indexação inicial para frameworks populares? Pacotes iniciais pré-construídos: jcodemunch-mcp install-pack --list (pacotes gratuitos não precisam de licença).

O que você pode fazer

  • Recupere um símbolo em vez de carregar um arquivo. get_symbol_source retorna o corpo exato da função, com precisão de byte, para a maioria das edições que tocam uma função em um arquivo de 700 linhas (~95% de economia nessa leitura).
  • Monte o contexto de uma tarefa inteira em uma chamada. assemble_task_context classifica a intenção da tarefa, extrai símbolos âncora e executa a sequência certa de ferramentas sob um orçamento de tokens. plan_turn roteia o turno antes da primeira leitura.
  • Faça perguntas estruturais que o grep não consegue responder. find_importers, get_blast_radius, get_call_hierarchy, find_dead_code, get_changed_symbols, get_hotspots, search_ast varreduras de anti-padrões e mais. Dois deles soam parecidos e não são: check_references responde onde um nome é usado (locais de importação mais todo arquivo cujo conteúdo o menciona), find_references responde quem o importa, apenas sobre o grafo de importação, então um local de chamada é invisível para ele.
  • Pré-valide mudanças arriscadas e saiba quando parar. check_edit_safe, check_delete_safe, get_pr_risk_profile e plan_refactoring com blocos {old_text, new_text} prontos para edição. As duas verificações de segurança retornam stop_rule.terminal: true significa que nenhuma chamada adicional ao jcodemunch muda o veredito, então reexecutar find_importers ou check_references para ter certeza é trabalho desperdiçado. Significa final, não seguro. check_rename_safe responde safe: null em vez de true quando o grafo de importação não conseguiu alcançar o arquivo do símbolo, então os arquivos que o usam nunca foram verificados, e get_pr_risk_profile responde risk_score: null com unmeasurable_axes quando não conseguiu medir o eixo de impacto; um gate de CI deve falhar em null. Entregue ao servidor a própria saída do seu verificador de tipos (jcodemunch-mcp import-trace --diagnostics <file>: mypy --output json, pyright --outputjson, tsc --pretty false, ruff --output-format json) e check_edit_safe, get_changed_symbols, get_pr_risk_profile e get_symbol_provenance dizem quais símbolos o verificador já sinaliza, a partir de qual commit. Nada executa um verificador por você. False nomeia a coisa específica que mudaria a resposta.
  • Confie nas respostas. Pontuações de confiança calibradas, sinalizadores de atualização, contratos de cobertura em alegações de ausência, referências verificadas por compilador via importação SCIP e redação automática de segredos antes que qualquer coisa chegue ao LLM.
  • Mantenha o índice atualizado automaticamente. Modos de observação, hooks de agente e uma extensão do VS Code fecham a lacuna de desatualização.

Esse é o resumo dos destaques. O tour completo das 90+ ferramentas, o formato compacto de transmissão MUNCH, recibos de evidências, anotação de trabalho descarregável e a instrumentação de economia de sessão estão em CAPABILITIES.md, com detalhes internos em UNDER_THE_HOOD.md.

O que há de novo

  • v1.108.318 (2026-09-11) — o processo é código que não pode pular uma etapa, e o campo é medido a partir de arquivos de resultado
  • v1.108.317 (2026-09-04) — CI executa o harness em cada mudança; a publicação é um workflow despachado
  • v1.108.316 (2026-09-02) — Uma preferência de exibição editou os dados que estava exibindo

Quando ajuda (e quando não ajuda)?

CenárioFerramenta nativajCodeMunchEconomia
Editar uma função (arquivo de 700 linhas)Read → 700 linhasget_symbol_source → 30 linhas~95%
Entender a estrutura de um arquivoRead → conteúdo completoget_file_outline → nomes + assinaturas~80%
Descobrir qual arquivo editarGrep muitos arquivossearch_symbols → correspondência exatacomparável
Edição exige contexto do arquivo inteiroRead → conteúdo completoget_file_content → conteúdo completo~0%
"O que quebra se eu mudar X?"não é possívelget_blast_radiuscapacidade exclusiva

Ele ajuda mais em edições direcionadas (uma função, um método, uma classe), que são a maioria do trabalho real de edição. Edições que realmente exigem o arquivo inteiro (reestruturar estado no nível do arquivo, reordenar lógica que abrange centenas de linhas) não veem vantagem. Melhor se aplica a: repositórios grandes, bases de código desconhecidas, exploração orientada por agentes, refatoração e análise de impacto, e equipes que cortam custos de tokens de IA sem tornar os agentes menos inteligentes.

Idiomas: mais de 70 via tree-sitter, incluindo Python, JavaScript/TypeScript, Go, Rust, Java, C/C++, C#, PHP, Ruby, Swift e Kotlin. Matriz completa: LANGUAGE_SUPPORT.md. Monorepos: sim; indexação incremental, detecção de membros do workspace, escopo por subcaminho.

Adiando os esquemas de ferramentas (busca de ferramentas da Anthropic)

Se você acessar o jCodeMunch por meio do conector MCP em um modelo que suporta busca de ferramentas, você pode manter nossos esquemas fora do prefixo de contexto inteiramente e deixar o Claude carregar apenas as duas ou três ferramentas que uma solicitação precisa. Você não define defer_loading por ferramenta — defina uma vez para o servidor inteiro:

{
  "mcp_servers": [
    { "type": "url", "url": "https://your-host/mcp", "name": "jcodemunch" }
  ],
  "tools": [
    { "type": "tool_search_tool_bm25_20251119", "name": "tool_search_tool_bm25" },
    {
      "type": "mcp_toolset",
      "mcp_server_name": "jcodemunch",
      "default_config": { "defer_loading": true },
      "configs": {
        "resolve_repo":       { "defer_loading": false },
        "search_symbols":     { "defer_loading": false },
        "get_ranked_context": { "defer_loading": false }
      }
    }
  ]
}

Envie com o cabeçalho beta mcp-client-2025-11-20. Ambas as partes são obrigatórias — mcp_servers sozinho é um erro de validação, e mcp_toolset sem o mcp_server_name correspondente também é.

⚠ O conector MCP aceita uma URL, então isso se aplica ao jCodeMunch servido via sse ou streamable-http (jcodemunch-mcp serve --transport streamable-http), não à configuração padrão local via stdio. No stdio, se os esquemas são adiados depende do seu cliente, e tool_surface: "counter" abaixo é a alavanca que você controla.

O bloco configs acima segue o próprio conselho da Anthropic — mantenha suas 3–5 ferramentas mais usadas residentes para que solicitações comuns evitem a ida e volta da busca — e configs por ferramenta substitui default_config.

Definições adiadas são excluídas do prefixo do prompt do sistema e anexadas inline como blocos tool_reference quando o Claude as descobre, então o cache de prompt é preservado — este não é o tipo de lista de ferramentas dinâmica que invalida o cache. Pelo menos uma ferramenta na solicitação deve permanecer não adiada, ou a API retorna um 400.

⚠ Este é um mecanismo diferente do nosso próprio tool_surface: "counter", e você não precisa de ambos. A busca de ferramentas é do lado do host e funciona em todos os servidores MCP que você tem conectados; o Contador é do lado do servidor, funciona em qualquer host, incluindo aqueles sem suporte a busca de ferramentas, e é o que init configura em uma primeira instalação. Escolha o que seu host suporta — veja CONFIGURATION.md para o Contador e jcodemunch-mcp surface para o que sua instalação realmente anuncia.

Segurança, privacidade e comportamento em segundo plano

Local-primeiro por design: os índices ficam em ~/.code-index/, e o único comportamento de rede padrão do pacote base é um contador de economia anônimo (ID aleatório mais contagens agregadas de tokens, sem código, sem caminhos, sem PII; opte por sair com share_savings: false). Tudo o que o servidor faz além de responder a uma chamada de ferramenta (observação de arquivos, serviço de login opcional, validação de licença, downloads de modelos, relatórios de organização) é opt-in ou opt-out, visível e reversível, e cada item está enumerado em SECURITY.md junto com os controles de travessia de caminho, symlink e redação de segredos.

Substituição do pacote de gramáticas (#608). A dependência tree-sitter-language-pack está fixada em <1.0.0 porque as wheels 0.x incluem todas as gramáticas e a análise permanece local. F# é a única exceção: é analisado pela wheel fixada tree-sitter-fsharp, que também compila sua gramática, então a análise de F# permanece local em qualquer pacote (#848). Você pode substituí-la com pip install -U tree-sitter-language-pack após a instalação; nada no código a recusa. O que você aceita, medido contra 1.17.0 em 2026-09-11: o pacote 1.x não inclui gramáticas e busca cada uma pela rede em seu diretório de cache (medido no Windows: %LOCALAPPDATA%\tree-sitter-language-pack\v<version>\libs; jcodemunch-mcp install-status imprime o caminho em qualquer plataforma) na primeira vez que um idioma é analisado, então uma instalação sem rede não analisa nada, e a gramática nim mudou upstream, então arquivos nim não produzem símbolos (o manifesto também carece de autohotkey, ejs e verse, o que não custa nada aqui: esses três são analisados pelos próprios extratores do jCodeMunch, não pelo tree-sitter). Uma instalação em um pacote 1.x diz isso: cada resultado index_folder carrega um bloco grammar_pack e um aviso nomeando a versão, o diretório de cache e cada idioma cuja gramática falhou, e jcodemunch-mcp install-status imprime o mesmo. Remover a fixação é uma decisão separada que precisa da história offline primeiro.

Configuração por projeto

A maioria das configurações fica no ~/.code-index/config.jsonc global, mas qualquer uma delas pode ser substituída para um único repositório colocando um .jcodemunch.jsonc em sua raiz. É uma sobreposição: chaves que declara vencem, chaves que omite caem para o global e depois para o padrão embutido, então só precisa conter o que difere.

// <your-repo>/.jcodemunch.jsonc
{
  "max_file_size": 1048576,
  "languages": ["python", "typescript", "racket"]
}

Declarando formas de definição do Racket

Projetos Racket rotineiramente definem suas próprias formas de definição com define-syntax, e um analisador estático não pode saber o que elas vinculam — (defstep (check-admin) ...) é indistinguível de uma chamada de função. Declará-las torna seus vínculos pesquisáveis:

{
  "racket_definition_forms": {
    "defstep":  "function",
    "defstudy": "constant",
    "defvar":   "constant",
    "define-schema": "class"
  }
}

Cada entrada mapeia um nome de forma para o que ela vincula: function, constant, class ou type. Onde o nome fica é lido da fonte em vez de declarado — (defstep (check-admin) ...) pega o cabeçalho da lista de parâmetros, (defstudy consent ...) pega o símbolo puro — então uma forma que aparece em ambas as formas funciona de qualquer maneira.

⚠ Isso é uma afirmação, não algo que o jCodeMunch pode verificar. Uma declaração errada coloca um nome no índice que o Racket não vincula de fato. Declarações também são correspondidas apenas após cada forma embutida, então declarar define ou struct não tem efeito — o tratamento embutido vence.

Declarando como é um #lang do Racket

Uma linha #lang nomeia um leitor, e o analisador Racket do jCodeMunch lê expressões S. Os langs da distribuição são embutidos (racket/*, typed/racket*, s-exp, info, at-exp …, e os langs de documento scribble/*, pollen, punct, markdown …), mas o lang de um projeto próprio é desconhecido para ele e é tratado como um documento — sem símbolos, ainda pesquisável por texto — até você dizer qual é sua sintaxe:

{
  "racket_langs": {
    "conscript": "at-exp",
    "mylang": "sexp"
  }
}

sexp é expressões S puras; at-exp é corpos de texto at-exp sobre Racket (lidos com @ como o caractere de comando, exatamente como #lang at-exp os lê, então prosa contendo ; " # ou | é prosa); text é um idioma de documento que nunca é percorrido. Uma chave também cobre seus sub-idiomas (conscript corresponde a conscript/with-require), e um projeto pode rebaixar um idioma bem como promover um. Um idioma at-exp cujo leitor usa outro caractere de comando o declara com a forma de objeto — "mylang": {"tier": "at-exp", "command_char": "◊"} — da maneira que o make-at-readtable do Racket aceita #:command-char.

Ambas as chaves mudam o que o analisador emite para arquivos inalterados, então uma mudança em qualquer uma é carimbada no índice e força uma reanálise completa na próxima indexação (rebuild_reason: "racket_config_changed"); você não precisa tocar nos arquivos ou limpar o índice. Um índice contendo arquivos Racket construído antes deste carimbo existir reanalisa uma vez da mesma maneira (rebuild_reason: "racket_index_predates_gate").

Documentação

DocO que cobre
QUICKSTART.mdDo zero ao indexado em três passos
CLIENTS.mdConfiguração testada para cada cliente MCP
USER_GUIDE.mdReferência completa de ferramentas, fluxos de trabalho e melhores práticas
CAPABILITIES.mdA referência completa de capacidades além do resumo
CONFIGURATION.mdReferência do arquivo de configuração, alavancas de controle de tokens, hierarquia de ferramentas, o Contador
UNDER_THE_HOOD.mdO manual técnico: veredictos, internals de classificação, contratos de proveniência
ARCHITECTURE.mdDesign interno, modelo de armazenamento e pontos de extensão
GROQ.mdGroq Remote MCP, o CLI gcm, GitHub Action speedreview
HEADLESS.mdUsando jCodeMunch com claude -p
AGENT_HOOKS.mdGanchos de agente e políticas de prompt
LANGUAGE_SUPPORT.mdIdiomas suportados e detalhes de análise
SECURITY.mdControles de segurança, movimento de dados, comportamento em segundo plano
TROUBLESHOOTING.mdProblemas comuns e correções
CHANGELOG.md · ROADMAP.mdHistórico de versões e o que vem a seguir

Licenciamento e uso comercial

jCodeMunch-MCP é lançado sob a Licença de Uso Dual jCodeMunch-MCP (termos completos). Grátis para uso não comercial. Uso comercial requer uma licença paga, única, vendida pela jMunch LLC via Stripe:

Somente jCodeMunch: Builder, $79 (1 desenvolvedor) · Studio, $349 (até 5) · Platform, $1,999 (implantação interna em toda a organização)

Suíte completa jMunch (código + docs + dados): Trio Builder, $99 · Trio Studio, $449 · Trio Platform, $2,499

Não tem certeza se vale a pena? Faça suas próprias contas com a calculadora de ROI, ou encaminhe a versão para o time de finanças para quem aprova. A garantia permanece: se o jCodeMunch não se pagar, você não paga pelo jCodeMunch.

Condições em todos os usos: mantenha o aviso de direitos autorais, marque claramente modificações e mantenha o nome do autor original intacto (ele é meio vaidoso), e inclua um aviso de modificação proeminente em redistribuições de fonte. O Software não pode ser renomeado, re-marcado ou publicado em qualquer registro público de pacotes, e é fornecido "COMO ESTÁ" sem garantia. LICENSE controla.

FAQ

Quanto posso economizar em tokens do Claude / Opus? Em fluxos de trabalho pesados de recuperação, tokens de leitura de código tipicamente caem 86-99%, medidos em média de 96,5% (28,3x) contra um agente de grep-e-leitura em 15 tarefas e 3 repositórios. Resultados por consulta variam de 7,6x a 81,2x. Metodologia: TOKEN_SAVINGS.md e benchmarks/.

Como isso é diferente de ferramentas baseadas em RAG ou grep? jCodeMunch recupera no nível de símbolo com precisão de byte (funções, classes, importadores, raio de explosão, hierarquias) em vez de pedaços difusos (RAG) ou correspondências de linha bruta (grep) que o agente ainda precisa ler e raciocinar.

É grátis para uso pessoal? Sim. Uso comercial precisa de licença; veja acima.

Onde está o mergulho profundo em X? Capacidades: CAPABILITIES.md. Config: CONFIGURATION.md. Clientes: CLIENTS.md. Internals: UNDER_THE_HOOD.md. Ou o fluxo completo: jcodemunch.com.

Extras: Observatório de saúde de código OSS (capturas semanais em seis eixos de Express, FastAPI, Gin, Django e afins) · Radar de Custo de Tokens (inteligência diária de custo de tokens de IA) · Console jMunch (GUI MIT gratuita para atualizações com um clique)