Next.js Architecture MCP

Servidor MCP para codebases Next.js

Seu agente para de adivinhar onde o código está.

Ele lê seu projeto Next.js uma vez, aprende as convenções que seu código já segue e responde "qual arquivo é dono disso" em uma única chamada — em vez de seis greps e um arquivo de instruções de 11.000 tokens a cada prompt.

{
  "mcpServers": {
    "nextjs-mcp-architecture": {
      "command": "npx",
      "args": ["-y", "nextjs-mcp-architecture@latest"]
    }
  }
}

ou adicione-o ao projeto

npm i -D nextjs-mcp-architecture

Pro: análise de impacto, o dashboard e mais →

cwd, sem variáveis de ambienteGrátis para sempreNode 20+

dependências de módulos

ciclo de duas vias

arraste um módulo · clique para inspecionar

0 ms

índice frio, 2.100 arquivos

0 ms

inicialização quente

0.0 ms

consulta de busca

0

pacotes instalados

A versão resumida

O que isso economiza, em uma única sessão.

O custo de encontrar um arquivo do jeito usual, as quatro linhas que o substituem e a resposta que ele devolve.

Cada número na tela é a medição publicada no benchmark abaixo, feita no dub — um produto Next.js de código aberto com 3.659 arquivos que qualquer um pode clonar.

Uma execução, um repositório público

O que ele encontrou no Dub.

Dub é um produto Next.js de código aberto com 3.620 arquivos. Esta é uma execução não modificada contra ele — arquivo, linha e texto retirados do relatório, para que você possa clonar o repositório e verificar cada um.

Dois componentes client importam o crypto do Node.

O módulo não existe em um navegador, então o componente falha onde é executado, não onde é escrito.

• lib/api/create-id.ts:2
• lib/api/rewards/custom-reward-utils.ts:7

Três variáveis de ambiente somente servidor são lidas em código que chega ao navegador.

Next.js não as vaza — ele as substitui por undefined. Então uma integração SSO roda sem client id e nenhum erro é levantado em lugar algum.

• lib/auth/sso-login-programs.ts:8 — FRAMER_CLIENT_ID
• lib/auth/sso-login-programs.ts:9 — FRAMER_CLIENT_SECRET
• lib/auth/sso-login-programs.ts:22 — BEEHIIV_CLIENT_ID

Um 'use client' está abaixo dos imports.

A diretiva só conta no topo de um arquivo. Escrita assim, ela não faz nada, e o arquivo é tratado como um componente servidor.

• lib/swr/use-workspace-preferences.ts:3

3.620

arquivos de origem escaneados

lib → ui

ciclo de dependência

7

grupos quase duplicados

~538

linhas que poderiam ser removidas

Nenhum desses falha em uma verificação de tipo. Nenhum deles falha em uma regra de lint. Eles são encontrados onde o código roda — em um navegador, para um usuário — que é o lugar mais caro para encontrar qualquer coisa.

Leia o relatório completo →

Medido, não estimado

Encontrar um arquivo custa 16.372 tokens. Deveria custar 293.

Oito prompts que um desenvolvedor realmente digitaria, executados contra o dub — um produto Next.js de código aberto com 3.593 arquivos que qualquer um pode clonar. Uma vez do jeito que um agente busca hoje, uma vez através deste servidor. Mesmo repositório, mesmas tarefas, mesma pontuação.

16.372

tokens para encontrar por busca

293

tokens no plano gratuito

56×

menos contexto por tarefa

6/8

arquivo certo encontrado no Free — a busca obteve 6/8

Um prompt, dos dois jeitos

você

Descreva a tarefa…

O que o desenvolvedor perguntou	Buscando	Free	Pro
Onde mudo o botão que copia um link curto?	3.120	307	240
Corrija o bug onde o modal de QR code baixa o tamanho errado	21.197	267	224
O seletor de intervalo de datas da análise redefine quando troco de aba	30.706	287	241
Adicione uma coluna à tabela de links	27.782	313	248
Onde o fluxo de verificação de domínio personalizado é implementado?	4.156	286	234
O botão de upgrade de plano na página de cobrança não faz nada	35.172	294	241
Onde edito as cores que uma tag pode ter?	4.621	301	240
O formulário de convite de colegas não mostra erro quando o email já foi convidado	4.221	286	230

retornou o arquivo dono da tarefanão retornouO comprimento da barra é o que a busca gastou, contra a linha mais larga.

para onde vão os tokens

"O botão de upgrade de plano na página de cobrança não faz nada"

• glob *button*755
• grep "upgrade plan button" + "billing upgrade"0
• grep de palavras individuais (a frase não encontrou nada)25.496
• leitura de 3 arquivos8.921
• resolve_task_context294

Buscar a própria frase do desenvolvedor não retorna nada — pessoas descrevem comportamento, código nomeia coisas. Então o agente recorre a buscar as palavras uma a uma, e palavras comuns como essas correspondem a uma grande parte do codebase. Esse recurso é para onde o contexto vai.

o que os dois planos mudam

3.593 arquivos de origem no projeto do benchmark

Todo arquivo está no índice em todos os planos, sob seu nome e caminho — um arquivo que o índice nunca viu não pode ser retornado a nenhum preço, então não é isso que os planos pagos vendem.

O que um plano aumenta é quantos arquivos são lidos internamente: o plano gratuito lê 1.500 deles, espalhados por toda a árvore, e diz isso em sua resposta. Neste projeto, isso vale uma tarefa em 8 — o Free encontra 6, o Pro 7 — e o Pro responde em 237 tokens em vez de 293, porque leu o arquivo em vez de apenas saber seu nome.

12 tarefas de agente por dia, vinte e um dias úteis

Somente descoberta. Os preços de modelo mudam e os seus podem diferir — as contagens de tokens são a medição; os dólares são essa medição precificada nas taxas de entrada do Claude Opus 5 ($5,00 por milhão) no dia em que foi executado. Um projeto com um arquivo de instruções grande paga isso por cima, a cada prompt.

$20,63

$0,37

Como a linha de base foi construída. Glob pelos substantivos na solicitação, grep pela frase do desenvolvedor, grep pelas palavras separadamente quando a frase falha, depois leia os três arquivos mais promissores — cada etapa genuinamente executada e seu resultado real medido, com candidatos classificados do jeito que uma pessoa escolhe o que abrir. Uma comparação só vale a pena publicar se o outro lado recebeu sua melhor chance, então a precisão aqui é um empate: 6 de 8 em ambos os casos, em tarefas parcialmente diferentes. O que muda é o custo de perguntar.

Mede o contexto necessário para responder à pergunta — não o que qualquer agente individual gastou em qualquer dia individual, o que não seria reproduzível. Método completo, cada tarefa e as ressalvas — ou execute npm run benchmark contra seu próprio projeto.

Em menos de meio minuto

Veja-o encontrar o arquivo.

Um relatório de bug real, um codebase real de 3.659 arquivos e sem cortes. Grep retorna 86 arquivos. Uma chamada retorna o certo.

Gravado contra o dub, um produto Next.js de código aberto que qualquer um pode clonar. As contagens de arquivos vêm de executar grep nele; a resposta vem deste servidor através do Model Context Protocol, pelo inspetor MCP oficial em vez de um cliente nosso; os números de tokens são as mesmas medições que o benchmark abaixo publica.

Não é uma captura de tela

Tudo o que ele aprende, em uma página local.

O dashboard roda na sua máquina e lê o mesmo índice que seu agente consulta. O gráfico acima é esse renderizador, ao vivo.

O projeto abaixo é inventado, e tudo o que ele relata também é — os nomes de módulos e dependências de um cliente real não são nossos para publicar. Ele é moldado como um aplicativo de comércio de médio porte para que os achados pareçam com os que você obteria.

achados

• errorsrc/components/PriceTag.tsx:14 process.env.STRIPE_SECRET_KEY é undefined no navegador. Apenas variáveis NEXT_PUBLIC_* alcançam o código do cliente.
• warningsrc/app/account/OrderList.tsx:22 useState precisa de 'use client'. Nenhum importador deste arquivo declara a diretiva, então ele parece um Componente Servidor.

convenções

• aplicada97% dos arquivos de página e layout (61) são componentes servidor. exceção: src/app/blog/preview/page.tsx
• aplicada94% dos arquivos de hook (49) são nomeados use*. exceção: src/hooks/cartStore.ts
• observada71% dos arquivos de componente (218) são PascalCase, como Button.tsx.

quase duplicados

• 89% semelhantes src/app/shop/_components/ProductFilterBar.tsx src/app/admin/_components/CatalogFilterBar.tsx

Veja ao vivo, em um codebase real

O dashboard Pro completo, rodando contra o projeto de código aberto Dub (3.620 arquivos). Seu próprio código nunca sai da sua máquina.

Abra a demonstração ao vivo →

Como funciona

Ele aprende seu projeto. Ele não impõe o nosso.

Linters genéricos enviam as convenções de outra pessoa e estão certos sobre um codebase que nunca viram aproximadamente com a mesma frequência do acaso. O que torna uma regra digna de ser declarada é a evidência do seu próprio repositório, com a contagem anexada para que você possa verificar.

01

Encontra o projeto

Nove sinais ordenados, cada um pontuado contra evidência real de um app Next.js. Monorepos resolvem para o app certo, e uma biblioteca de UI que lista next como peer corretamente não é um.

02

Lê uma vez

Um índice puro em TypeScript com BM25 ponderado por campo — sem dependência nativa, então npx não pode falhar em uma etapa de build. Ele também aprende seu vocabulário de domínio a partir dos seus próprios arquivos de tradução, que é como uma busca por "invoice" encontra um módulo chamado fin/ar.

03

Declara apenas o que pode provar

Convenções são limitadas por um limite de confiança de Wilson. Regras de correção do framework sempre se aplicam, porque são fatos sobre Next.js em vez de opiniões sobre seu estilo.

Um achado se parece com isso

94% dos arquivos de hook (47 de 50) neste projeto são nomeados use*.ts e vivem sob src/hooks. src/utils/fetchUser.ts declara um hook e se desvia. Exemplo conforme: src/hooks/useOrders.ts

A contagem torna a afirmação verificável. O exemplo conforme permite que o agente copie o padrão em vez de discutir com a regra.

O que acontece depois que você cola

Uma caminhada, e ele conhece o projeto.

Seis etapas, na ordem em que o código as executa, com os números que um índice frio do projeto do benchmark realmente produziu. Nada aqui roda em segundo plano e nada sai da sua máquina.

Da instalação ao índice

npx puxa o pacote

01

npx puxa o pacote

$

02

Ele descobre qual projeto está olhando

9 sinais, pontuados contra evidência de um app Next.js real

• config do agente0
• diretório de trabalho0
• prefixo npm0
• caminho que você mencionou0

03

Ele percorre a árvore uma vez

0

arquivos de origem

0

pulados

somente stat — nada aberto ainda

04

Ele lê e pesa o que encontrou

BillingDetailPanel

nome ×5 · caminho ×5 · corpo ×1

05

Ele aprende o que este projeto faz

06

Pronto

697 ms

build frio

83 ms

cada início depois

0,22 ms

por consulta

Tudo local. Nada saiu da máquina.

A segunda colagem

Diga ao seu agente que ele não precisa mais buscar.

Instalar o servidor não muda os hábitos de um agente. Um que já sabe usar grep continuará usando grep, a menos que suas instruções digam que há algo melhor — a diferença entre pagar pela descoberta uma vez e pagar por ela a cada prompt.

## Finding code

Call \`resolve_task_context\` with the task in plain language **before** reading
or searching for anything. It returns the files that own the task, the
conventions that apply to them, and the command that verifies the change.

- Do not glob or grep to locate a feature. That is the cost this server exists
  to remove.
- Use \`find_symbol\` rather than opening files to find where something is
  declared.
- Use \`get_route_context\` for anything addressed by a URL.
- Call \`check_conventions\` on the files you changed before reporting done.

Fall back to grep only when a tool's answer includes \`degradations\` saying the
index is partial, or when you already know the exact file.

Cole isso junto com o trecho de instalação e o benchmark acima se torna o comportamento que você realmente obtém.

Deliberadamente curto: esses arquivos carregam a cada prompt, então uma página de prosa aqui gastaria mais contexto do que o servidor economiza.

Vai em AGENTS.md, CLAUDE.md ou .github/copilot-instructions.md.

Leia a documentação completa →

Quanto vale

Coloque seus próprios números.

Os controles deslizantes começam onde o benchmark parou. Mova-os para o seu projeto — o resultado é uma estimativa, e é rotulado como tal.

sem ele, por mês

6.141.744

com ele

174.636

cerca de 5.967.108 tokens a menos

Medido em um projeto de 3.593 arquivos, aplicado ao seu — então esta é uma estimativa para o seu codebase, não uma medição dele. O arquivo de instruções é contado integralmente aqui; o cache de prompt recupera parte disso na prática.

Preços

O plano gratuito é genuinamente útil por si só.

O que você paga é por medir e gerenciar a arquitetura, não por encontrar arquivos. Se tudo o que você quer é um agente que pare de adivinhar, fique no Free.

2 meses grátis

Free

$0para sempre

Tudo o que um agente precisa para parar de adivinhar.

• Detecção de projeto sem configuração
• Convenções aprendidas com evidência
• Nove ferramentas de descoberta e verificação
• Verificações de correção do Next.js
• Todo arquivo indexado, 500 lidos integralmente

Instalar

Basic

$5por mês

Veja a arquitetura, não apenas consulte-a.

• Tudo no Free
• Dashboard de dependências local
• 3.000 arquivos lidos integralmente
• Convenções aplicadas, não apenas observadas

Pro

$10por mês

Meça e gerencie.

• Tudo do Básico
• Análise de impacto antes de você alterar código compartilhado
• Auditoria de ciclos de dependência e acoplamento
• Detecção de quase-duplicatas
• Exportação de relatórios em Markdown e HTML
• Sem limite de leitura, uso em CI incluído

Perguntas

Respostas, antes de você instalar.

Isso deixa meu agente mais lento?+

Uma inicialização a quente leva 53 ms e uma consulta é uma fração de milissegundo. A indexação nunca roda durante o handshake do MCP — ela acontece na primeira chamada de ferramenta que precisa dela, então um projeto grande não pode travar a inicialização do seu cliente. Depois disso, o índice é incremental: uma varredura apenas de stat decide que nada mudou, e somente arquivos cujo mtime, tamanho e hash de conteúdo diferem são relidos.

Quanto tempo leva a primeira indexação e qual o tamanho dela?+

Medido em um projeto com 3.593 arquivos: cerca de 1,4 segundos a frio, e 3,3 MB em disco lidos por completo. Um projeto com 2.100 arquivos indexa em 412 ms. Não há daemon e nada roda em segundo plano — o trabalho acontece quando uma ferramenta pede e então para.

Onde ele armazena o índice?+

No diretório de cache do seu sistema operacional, nunca no seu repositório: ~/Library/Caches/nextjs-mcp-architecture no macOS, %LOCALAPPDATA%\nextjs-mcp-architecture no Windows, e $XDG_CACHE_HOME/nextjs-mcp-architecture (geralmente ~/.cache) no Linux. Cada projeto recebe um subdiretório nomeado a partir de um hash do seu caminho absoluto, então dois projetos em uma mesma máquina não podem ler o índice um do outro, e nada aparece no seu git status ou no contexto de build do Docker. Excluir esse diretório é seguro; a próxima chamada de ferramenta o reconstrói.

Ele se limpa sozinho?+

Sim. Diretórios de cache de projetos que você não abriu em 30 dias são excluídos, e os 50 mais recentes são mantidos. A varredura é agendada alguns segundos após a primeira chamada de ferramenta, em vez de rodar inline, então ela nunca fica na frente de uma resposta que você está esperando.

Meu projeto inteiro é pesquisável no plano gratuito?+

Sim. Todo arquivo está no índice em todos os planos, pelo nome e pelo caminho — um arquivo que o índice nunca viu não poderia ser retornado a nenhum preço, e não é isso que os planos pagos vendem. O que um plano aumenta é quantos arquivos são lidos internamente: o gratuito lê 500 deles, escolhidos em toda a árvore em vez dos primeiros encontrados, e toda resposta diz isso.

O que acontece com meu índice se minha assinatura terminar?+

Nada seu é tocado, e nada fica órfão. O índice vive no cache do seu SO, não no seu repositório, então seu código-fonte nunca é envolvido. Na próxima chamada de ferramenta, ele é reconstruído com o orçamento gratuito: todo arquivo continua encontrável por nome e caminho, o conteúdo excedente dos arquivos é descartado, e o arquivo de cache fica menor em vez de maior — em um projeto com 3.593 arquivos, ele vai de 3,3 MB para 1,7 MB. Renovar reconstrói o índice profundo da mesma forma.

Ele realmente não precisa de configuração?+

Sem cwd, sem variável de ambiente, sem arquivo de configuração. Ele resolve o projeto a partir de nove sinais em ordem — um caminho que você mencionou, as raízes do cliente MCP, o prefixo do npm, o diretório de trabalho — e pontua cada um contra a evidência de um app Next.js real, em vez de pegar o primeiro. Quando ele realmente não consegue distinguir, ele diz isso e oferece a correção em vez de responder sobre o projeto errado.

Ele vai impor convenções que eu não tenho?+

Ele só declara uma regra quando seu próprio código a suporta: o limite inferior do escore de Wilson precisa chegar a 0,80, o que significa cerca de 16 arquivos conformes sem exceções, ou 25 com no máximo uma. Padrões mais fracos são relatados como observações e nunca geram um achado. Um projeto novo demais para ter convenções não ganha nenhuma inventada.

O que ele envia para algum lugar?+

Nada. Indexação, aprendizado e verificação rodam todos localmente. A verificação de licença é uma checagem de assinatura offline contra uma chave embutida no pacote, então funciona sem rede alguma.

Com quais editores e agentes ele funciona?+

Qualquer coisa que fale MCP via stdio: Claude Code, Cursor, VS Code, Windsurf e Zed. O trecho de instalação é idêntico para todos.

Uma colagem, e seu agente conhece o código.

Grátis para sempre, sem conta, nada para configurar. Adicione um plano pago depois se quiser ver a arquitetura além de consultá-la.

npx -y nextjs-mcp-architecture@latest