Next.js Architecture MCP

Servidor MCP para bases de código Next.js

Tu agente deja de adivinar dónde vive el código.

Lee tu proyecto Next.js una vez, aprende las convenciones que tu código ya sigue, y responde "¿qué archivo es dueño de esto?" en una sola llamada — en lugar de seis greps y un archivo de instrucciones de 11,000 tokens en cada prompt.

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

o agrégalo al proyecto

npm i -D nextjs-mcp-architecture

Pro: análisis de impacto, el panel y más →

cwd, sin variables de entornoPlan gratuito para siempreNode 20+

dependencias de módulos

ciclo de dos vías

arrastra un módulo · haz clic para inspeccionar

0 ms

índice en frío, 2,100 archivos

0 ms

inicio en caliente

0.0 ms

consulta de búsqueda

0

paquetes instalados

La versión corta

Lo que esto ahorra, en una sola sesión.

El costo de encontrar un archivo de la manera habitual, las cuatro líneas que lo reemplazan, y la respuesta que devuelve.

Cada cifra en pantalla es la medición publicada en el benchmark a continuación, tomada en dub — un producto Next.js de código abierto con 3,659 archivos que cualquiera puede clonar.

Una ejecución, un repositorio público

Lo que encontró en Dub.

Dub es un producto Next.js de código abierto con 3,620 archivos. Esta es una ejecución sin modificar contra él — archivo, línea y redacción tomadas del informe, para que puedas clonar el repositorio y verificar cada una.

Dos componentes de cliente importan el crypto de Node.

El módulo no existe en un navegador, por lo que el componente falla donde se ejecuta, no donde está escrito.

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

Tres variables de entorno solo de servidor se leen en código que llega al navegador.

Next.js no las filtra — las reemplaza con undefined. Así, una integración SSO se ejecuta sin ID de cliente y no se genera ningún error en ningún lugar.

• 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

Un 'use client' está debajo de los imports.

La directiva solo cuenta al inicio de un archivo. Escrita así no hace nada, y el archivo se trata como un componente de servidor.

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

3,620

archivos fuente escaneados

lib → ui

ciclo de dependencias

7

grupos casi duplicados

~538

líneas que podrían eliminar

Ninguno de estos falla una verificación de tipos. Ninguno falla una regla de lint. Se encuentran donde el código se ejecuta — en un navegador, para un usuario — que es el lugar más caro para encontrar cualquier cosa.

Lee el informe completo →

Medido, no estimado

Encontrar un archivo cuesta 16,372 tokens. Debería costar 293.

Ocho prompts que un desarrollador escribiría realmente, ejecutados contra dub — un producto Next.js de código abierto con 3,593 archivos que cualquiera puede clonar. Una vez como un agente busca hoy, una vez a través de este servidor. Mismo repositorio, mismas tareas, misma puntuación.

16,372

tokens para encontrarlo buscando

293

tokens en el plan gratuito

56×

menos contexto por tarea

6/8

archivo correcto encontrado en Free — buscar obtuvo 6/8

Un prompt, ambas formas

tú

Describe la tarea…

Lo que el desarrollador preguntó	Buscando	Free	Pro
¿Dónde cambio el botón que copia un enlace corto?	3,120	307	240
Arregla el error donde el modal de código QR descarga el tamaño incorrecto	21,197	267	224
El selector de rango de fechas de analítica se reinicia cuando cambio de pestaña	30,706	287	241
Agrega una columna a la tabla de enlaces	27,782	313	248
¿Dónde está implementado el flujo de verificación de dominio personalizado?	4,156	286	234
El botón de plan de actualización en la página de facturación no hace nada	35,172	294	241
¿Dónde edito los colores que puede tener una etiqueta?	4,621	301	240
El formulario de invitar compañeros no muestra un error cuando el correo ya está invitado	4,221	286	230

devolvió el archivo dueño de la tareano lo hizoLa longitud de la barra es lo que buscando gastó, contra la fila más ancha.

dónde van los tokens

"El botón de plan de actualización en la página de facturación no hace nada"

• glob *button*755
• grep "upgrade plan button" + "billing upgrade"0
• grep palabras individuales (la frase no encontró nada)25,496
• leer 3 archivos8,921
• resolve_task_context294

Buscar la propia frase del desarrollador no devuelve nada — la gente describe comportamiento, el código nombra cosas. Así que el agente recurre a buscar las palabras una a la vez, y palabras comunes como estas coinciden con una gran parte de la base de código. Ese recurso es donde se va el contexto.

qué cambian los dos niveles

3,593 archivos fuente en el proyecto del benchmark

Cada archivo está en el índice en todos los niveles, bajo su nombre y ruta — un archivo que el índice nunca ha oído no puede devolverse a ningún precio, así que eso no es lo que venden los niveles de pago.

Lo que un nivel aumenta es cuántos archivos se leen internamente: el nivel gratuito lee 1,500 de ellos, distribuidos por todo el árbol, y lo dice en su respuesta. En este proyecto eso vale una tarea en 8 — Free encuentra 6, Pro 7 — y Pro responde en 237 tokens en lugar de 293, porque ha leído el archivo en lugar de solo conocer su nombre.

12 tareas de agente al día, veintiún días laborables

Solo descubrimiento. Los precios de modelos cambian y los tuyos pueden diferir — los conteos de tokens son la medición; los dólares son esa medición valorada a las tarifas de entrada de Claude Opus 5 ($5.00 por millón) el día en que se ejecutó. Un proyecto con un archivo de instrucciones grande paga eso además, en cada prompt.

$20.63

$0.37

Cómo se construyó la línea base. Glob por los sustantivos en la solicitud, grep la redacción del desarrollador, grep las palabras por separado cuando la frase falla, luego leer los tres archivos más prometedores — cada paso realmente ejecutado y su salida real medida, con candidatos clasificados como una persona elige qué abrir. Una comparación solo vale la pena publicarla si al otro lado se le dio su mejor oportunidad, así que la precisión aquí es un empate: 6 de 8 en ambos casos, en tareas parcialmente diferentes. Lo que cambia es lo que cuesta preguntar.

Mide el contexto requerido para responder la pregunta — no lo que cualquier agente individual gastó en cualquier día individual, que no sería reproducible. Método completo, cada tarea y las advertencias — o ejecuta npm run benchmark contra tu propio proyecto.

En menos de medio minuto

Míralo encontrar el archivo.

Un informe de error real, una base de código real de 3,659 archivos, y sin cortes. Grep devuelve 86 archivos. Una llamada devuelve el correcto.

Grabado contra dub, un producto Next.js de código abierto que cualquiera puede clonar. Los conteos de archivos provienen de ejecutar grep en él; la respuesta proviene de este servidor a través del Protocolo de Contexto de Modelo, mediante el inspector oficial de MCP en lugar de un cliente nuestro; las cifras de tokens son las mismas mediciones que el benchmark a continuación publica.

No es una captura de pantalla

Todo lo que aprende, en una página local.

El panel se ejecuta en tu máquina y lee el mismo índice que consulta tu agente. El gráfico anterior es ese renderizador, en vivo.

El proyecto a continuación es inventado, y también lo es todo lo que reporta — los nombres de módulos y dependencias de un cliente real no son nuestros para publicar. Tiene la forma de una aplicación de comercio de tamaño mediano para que los hallazgos se vean como los que obtendrías.

hallazgos

• errorsrc/components/PriceTag.tsx:14 process.env.STRIPE_SECRET_KEY no está definido en el navegador. Solo las variables NEXT_PUBLIC_* llegan al código de cliente.
• warningsrc/app/account/OrderList.tsx:22 useState necesita 'use client'. Ningún importador de este archivo declara la directiva, por lo que parece un Componente de Servidor.

convenciones

• aplicada97% de los archivos de página y layout (61) son componentes de servidor. excepción: src/app/blog/preview/page.tsx
• aplicada94% de los archivos de hooks (49) se nombran use*. excepción: src/hooks/cartStore.ts
• observada71% de los archivos de componentes (218) son PascalCase, como Button.tsx.

casi duplicados

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

Míralo en vivo, en una base de código real

El panel completo de Pro, ejecutándose contra el proyecto de código abierto Dub (3,620 archivos). Tu propio código nunca sale de tu máquina.

Abre la demo en vivo →

Cómo funciona

Aprende tu proyecto. No impone el nuestro.

Los linters genéricos traen las convenciones de otra persona y aciertan sobre una base de código que nunca han visto aproximadamente tan a menudo como el azar. Lo que hace que una regla valga la pena es la evidencia de tu propio repositorio, con el conteo adjunto para que puedas verificarlo.

01

Encuentra el proyecto

Nueve señales ordenadas, cada una puntuada contra evidencia real de una aplicación Next.js. Los monorepos se resuelven a la aplicación correcta, y una biblioteca de UI que lista next como peer no se considera correctamente una.

02

Lo lee una vez

Un índice de TypeScript puro con BM25 ponderado por campo — sin dependencia nativa, así que npx no puede fallar en un paso de compilación. También aprende tu vocabulario de dominio de tus propios archivos de traducción, que es cómo una búsqueda de "invoice" encuentra un módulo llamado fin/ar.

03

Solo afirma lo que puede probar

Las convenciones se controlan con un límite de confianza de Wilson. Las reglas de corrección del framework siempre se aplican, porque son hechos sobre Next.js en lugar de opiniones sobre tu estilo.

Un hallazgo se ve así

94% de los archivos de hooks (47 de 50) en este proyecto se nombran use*.ts y viven bajo src/hooks. src/utils/fetchUser.ts declara un hook y se desvía. Ejemplo conforme: src/hooks/useOrders.ts

El conteo hace que la afirmación sea verificable. El ejemplo conforme permite que el agente copie el patrón en lugar de discutir con la regla.

Qué pasa después de que lo pegues

Una caminata, y conoce el proyecto.

Seis pasos, en el orden en que el código los ejecuta, con las cifras que un índice en frío del proyecto del benchmark realmente produjo. Nada aquí se ejecuta en segundo plano y nada sale de tu máquina.

De la instalación al índice

npx extrae el paquete

01

npx extrae el paquete

$

02

Determina qué proyecto está mirando

9 señales, puntuadas contra evidencia de una aplicación Next.js real

• config del agente0
• directorio de trabajo0
• prefijo npm0
• ruta que mencionaste0

03

Camina el árbol una vez

0

archivos fuente

0

omitidos

solo stat — nada abierto aún

04

Lee y pondera lo que encontró

BillingDetailPanel

nombre ×5 · ruta ×5 · cuerpo ×1

05

Aprende qué hace este proyecto

06

Listo

697 ms

compilación en frío

83 ms

cada inicio posterior

0.22 ms

por consulta

Todo local. Nada salió de la máquina.

El segundo pegado

Dile a tu agente que ya no tiene que buscar.

Instalar el servidor no cambia los hábitos de un agente. Uno que ya sabe usar grep seguirá usando grep a menos que sus instrucciones digan que hay algo mejor — la diferencia entre pagar por el descubrimiento una vez y pagar por él en 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.

Pega esto junto con el fragmento de instalación y el benchmark anterior se convierte en el comportamiento que realmente obtienes.

Deliberadamente corto: estos archivos se cargan en cada prompt, así que una página de prosa aquí gastaría más contexto del que el servidor ahorra.

Va en AGENTS.md, CLAUDE.md o .github/copilot-instructions.md.

Lee la documentación completa →

Cuánto vale

Pon tus propios números.

Los controles deslizantes comienzan donde aterrizó el benchmark. Muévelos a tu proyecto — el resultado es una estimación, y está etiquetada como tal.

sin él, por mes

6,141,744

con él

174,636

alrededor de 5,967,108 tokens menos

Medido en un proyecto de 3,593 archivos, aplicado al tuyo — así que esto es una estimación para tu base de código, no una medición de ella. El archivo de instrucciones se cuenta completo aquí; el caché de prompts recupera parte de eso en la práctica.

Precios

El plan gratuito es genuinamente útil por sí solo.

Lo que pagas es por medir y gestionar la arquitectura, no por encontrar archivos. Si todo lo que quieres es un agente que deje de adivinar, quédate en Free.

2 meses gratis

Free

$0para siempre

Todo lo que un agente necesita para dejar de adivinar.

• Detección de proyecto sin configuración
• Convenciones aprendidas con evidencia
• Nueve herramientas de descubrimiento y verificación
• Verificaciones de corrección de Next.js
• Cada archivo indexado, 500 leídos completos

Instalar

Basic

$5por mes

Ve la arquitectura, no solo consúltala.

• Todo en Free
• Panel de dependencias local
• 3,000 archivos leídos completos
• Convenciones aplicadas, no solo observadas

Pro

$10por mes

Mide y gestiona.

• Todo lo de Basic
• Análisis de impacto antes de cambiar código compartido
• Auditoría de ciclos de dependencia y acoplamiento
• Detección de casi duplicados
• Exportación de informes en Markdown y HTML
• Sin límite de lectura, uso en CI incluido

Preguntas

Respuestas, antes de que lo instales.

¿Ralentiza a mi agente?+

Un arranque en caliente es de 53 ms y una consulta es una fracción de milisegundo. La indexación nunca se ejecuta durante el protocolo de enlace de MCP: ocurre en la primera llamada a una herramienta que la necesite, por lo que un proyecto grande no puede detener el inicio de tu cliente. Después, el índice es incremental: un recorrido solo con stat decide que nada cambió, y solo se vuelven a leer los archivos cuyo mtime, tamaño y hash de contenido difieren todos.

¿Cuánto tarda la primera indexación y qué tamaño tiene?+

Medido en un proyecto de 3,593 archivos: aproximadamente 1.4 segundos en frío y 3.3 MB en disco leídos por completo. Un proyecto de 2,100 archivos se indexa en 412 ms. No hay demonio ni nada que se ejecute en segundo plano: el trabajo ocurre cuando una herramienta lo solicita y luego se detiene.

¿Dónde almacena el índice?+

En el directorio de caché de tu sistema operativo, nunca en tu repositorio: ~/Library/Caches/nextjs-mcp-architecture en macOS, %LOCALAPPDATA%\nextjs-mcp-architecture en Windows y $XDG_CACHE_HOME/nextjs-mcp-architecture (generalmente ~/.cache) en Linux. Cada proyecto obtiene un subdirectorio con el nombre de un hash de su ruta absoluta, por lo que dos proyectos en una misma máquina no pueden leer el índice del otro, y nada aparece nunca en tu git status ni en tu contexto de compilación de Docker. Eliminar ese directorio es seguro; la siguiente llamada a una herramienta lo reconstruye.

¿Se limpia solo?+

Sí. Los directorios de caché de proyectos que no has abierto en 30 días se eliminan, y se conservan los 50 más recientes. La limpieza se programa unos segundos después de la primera llamada a una herramienta en lugar de ejecutarse en línea, por lo que nunca se interpone ante una respuesta que estás esperando.

¿Todo mi proyecto es buscable en el nivel gratuito?+

Sí. Cada archivo está en el índice en todos los niveles, por su nombre y su ruta: un archivo que el índice nunca haya visto no podría devolverse a ningún precio, y eso no es lo que venden los niveles de pago. Lo que un nivel aumenta es cuántos archivos se leen internamente: el gratuito lee 500 de ellos, elegidos en todo el árbol en lugar de los primeros encontrados, y cada respuesta lo indica.

¿Qué le pasa a mi índice si mi suscripción termina?+

Nada de lo tuyo se toca y nada queda varado. El índice vive en la caché de tu sistema operativo, no en tu repositorio, por lo que tu código fuente nunca está involucrado. En la siguiente llamada a una herramienta se reconstruye con el presupuesto gratuito: cada archivo sigue siendo localizable por nombre y ruta, los contenidos de archivos sobrantes se descartan y el archivo de caché se vuelve más pequeño en lugar de más grande: en un proyecto de 3,593 archivos pasa de 3.3 MB a 1.7 MB. Renovar reconstruye el índice profundo de la misma manera.

¿De verdad no necesita configuración?+

Sin cwd, sin variable de entorno, sin archivo de configuración. Resuelve el proyecto a partir de nueve señales en orden: una ruta que mencionaste, las raíces del cliente MCP, el prefijo propio de npm, el directorio de trabajo—y puntúa cada una contra la evidencia de una aplicación Next.js real en lugar de tomar la primera. Cuando realmente no puede determinarlo, lo dice y ofrece la solución en lugar de responder sobre el proyecto equivocado.

¿Hará cumplir convenciones que no tengo?+

Solo establece una regla cuando tu propio código la respalda: el límite inferior de la puntuación de Wilson debe alcanzar 0.80, lo que significa aproximadamente 16 archivos conformes sin excepciones, o 25 con como máximo una. Los patrones más débiles se informan como observaciones y nunca generan un hallazgo. Un proyecto demasiado nuevo para tener convenciones no recibe ninguna inventada.

¿Qué envía a algún lugar?+

Nada. La indexación, el aprendizaje y la verificación se ejecutan localmente. La verificación de licencia es una comprobación de firma sin conexión contra una clave integrada en el paquete, por lo que funciona sin red alguna.

¿Con qué editores y agentes funciona?+

Con cualquier cosa que hable MCP sobre stdio: Claude Code, Cursor, VS Code, Windsurf y Zed. El fragmento de instalación es idéntico para todos.

Un pegado, y tu agente conoce el código base.

Gratis para siempre, sin cuenta, nada que configurar. Añade un nivel de pago más tarde si quieres ver la arquitectura además de consultarla.

npx -y nextjs-mcp-architecture@latest