Next.js Architecture MCP

MCP server for Next.js codebases

Your agent stops guessing where the code lives.

It reads your Next.js project once, learns the conventions your code already follows, and answers “which file owns this” in a single call — instead of six greps and an 11,000-token instructions file on every prompt.

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

or add it to the project

npm i -D nextjs-mcp-architecture

Pro: impact analysis, the dashboard & more →

cwd, no env varsFree forever tierNode 20+

module dependencies

two-waycycle

drag a module · click to inspect

0 ms

cold index, 2,100 files

0 ms

warm start

0.0 ms

search query

0

packages installed

The short version

What this saves, in one sitting.

The cost of finding one file the usual way, the four lines that replace it, and the answer it gives back.

Every figure on screen is the measurement published in the benchmark below, taken on dub — an open-source Next.js product of 3,659 files that anyone can clone.

One run, a public repository

What it found in Dub.

Dub is an open-source Next.js product of 3,620 files. This is one unmodified run against it — file, line and wording taken from the report, so you can clone the repository and check every one.

Two client components import Node’s crypto.

The module does not exist in a browser, so the component fails where it runs, not where it is written.

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

Three server-only environment variables are read in code that reaches the browser.

Next.js does not leak them — it replaces them with undefined. So an SSO integration runs with no client id and no error is raised anywhere.

• 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

One ‘use client’ sits below the imports.

The directive only counts at the top of a file. Written this way it does nothing, and the file is treated as a server component.

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

3,620

source files scanned

lib → ui

dependency cycle

7

near-duplicate groups

~538

lines they could shed

None of these fail a type check. None of them fail a lint rule. They are found where the code runs — in a browser, for a user — which is the most expensive place to find anything.

Read the full report →

Measured, not estimated

Finding one file costs 16,372 tokens. It should cost 293.

Eight prompts a developer would actually type, run against dub — an open-source Next.js product of 3,593 files that anyone can clone. Once the way an agent searches today, once through this server. Same repository, same tasks, same scoring.

16,372

tokens to find it by searching

293

tokens on the free tier

56×

less context per task

6/8

right file found on Free — searching got 6/8

One prompt, both ways

you

Describe the task…

What the developer asked	Searching	Free	Pro
Where do I change the button that copies a short link?	3,120	307	240
Fix the bug where the QR code modal downloads the wrong size	21,197	267	224
The analytics date range picker resets when I switch tabs	30,706	287	241
Add a column to the links table	27,782	313	248
Where is the custom domain verification flow implemented?	4,156	286	234
The upgrade plan button on the billing page does nothing	35,172	294	241
Where do I edit the colours a tag can have?	4,621	301	240
The invite teammates form does not show an error when the email is already invited	4,221	286	230

returned the file that owns the taskdid notBar length is what searching spent, against the widest row.

where the tokens go

“The upgrade plan button on the billing page does nothing”

• glob *button*755
• grep "upgrade plan button" + "billing upgrade"0
• grep individual words (phrase found nothing)25,496
• read 3 files8,921
• resolve_task_context294

Searching the developer’s own phrase returns nothing — people describe behaviour, code names things. So the agent falls back to searching the words one at a time, and ordinary words like these match a large share of the codebase. That fallback is where the context goes.

what the two tiers change

3,593 source files in the benchmarked project

Every file is in the index at every tier, under its name and path — a file the index has never heard of cannot be returned at any price, so that is not what the paid tiers sell.

What a tier raises is how many files are read inside: the free tier reads 1,500 of them, spread across the whole tree, and says so in its answer. On this project that is worth one task in 8 — free finds 6, Pro 7 — and Pro answers in 237 tokens instead of 293, because it has read the file rather than only knowing its name.

12 agent tasks a day, twenty-one working days

Discovery only. Model prices change and yours may differ — the token counts are the measurement; the dollars are that measurement priced at Claude Opus 5 input rates ($5.00 per million) on the day it ran. A project with a large instructions file pays that on top, every prompt.

$20.63

$0.37

How the baseline was built. Glob by the nouns in the request, grep the developer's phrasing, grep the words separately when the phrase misses, then read the three most promising files — each step genuinely executed and its real output measured, with candidates ranked the way a person picks what to open. A comparison is only worth publishing if the other side was given its best shot, so accuracy here is a tie: 6 of 8 either way, on partly different tasks. What changes is what it costs to ask.

It measures the context required to answer the question — not what any single agent spent on any single day, which would not be reproducible. Full method, every task and the caveats — or run npm run benchmark against your own project.

Under half a minute

Watch it find the file.

A real bug report, a real 3,659-file codebase, and no cuts. Grep returns 86 files. One call returns the right one.

Recorded against dub, an open-source Next.js product anyone can clone. The file counts come from running grep on it; the answer comes from this server over the Model Context Protocol, through the official MCP inspector rather than a client of ours; the token figures are the same measurements the benchmark below publishes.

Not a screenshot

Everything it learns, in one local page.

The dashboard runs on your machine and reads the same index your agent queries. The graph above is that renderer, live.

The project below is invented, and so is everything it reports — a real customer’s module names and dependencies are not ours to publish. It is shaped like a mid-size commerce app so the findings look like the ones you would get.

findings

• errorsrc/components/PriceTag.tsx:14 process.env.STRIPE_SECRET_KEY is undefined in the browser. Only NEXT_PUBLIC_* variables reach client code.
• warningsrc/app/account/OrderList.tsx:22 useState needs 'use client'. No importer of this file declares the directive, so it looks like a Server Component.

conventions

• enforced97% of page and layout files (61) are server components. exception: src/app/blog/preview/page.tsx
• enforced94% of hook files (49) are named use*. exception: src/hooks/cartStore.ts
• observed71% of component files (218) are PascalCase, like Button.tsx.

near-duplicates

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

See it live, on a real codebase

The full Pro dashboard, running against the open-source Dub project (3,620 files). Your own code never leaves your machine.

Open the live demo →

How it works

It learns your project. It does not impose ours.

Generic linters ship someone else’s conventions and are right about a codebase they have never seen roughly as often as chance. What makes a rule worth stating is evidence from your own repository, with the count attached so you can check it.

01

Finds the project

Nine ordered signals, each scored against real evidence of a Next.js app. Monorepos resolve to the right app, and a UI library that lists next as a peer is correctly not one.

02

Reads it once

A pure-TypeScript index with field-weighted BM25 — no native dependency, so npx cannot fail on a build step. It also learns your domain vocabulary from your own translation files, which is how a search for “invoice” finds a module named fin/ar.

03

States only what it can prove

Conventions are gated on a Wilson confidence bound. Framework correctness rules always apply, because those are facts about Next.js rather than opinions about your style.

A finding looks like this

94% of hook files (47 of 50) in this project are named use*.ts and live under src/hooks. src/utils/fetchUser.ts declares a hook and deviates. Conforming example: src/hooks/useOrders.ts

The count makes the claim checkable. The conforming example lets the agent copy the pattern instead of arguing with the rule.

What happens after you paste it

One walk, and it knows the project.

Six steps, in the order the code runs them, with the figures a cold index of the benchmarked project actually produced. Nothing here runs in the background and nothing leaves your machine.

From install to indexed

npx pulls the package

01

npx pulls the package

$

02

It works out which project it is looking at

9 signals, scored against evidence of a real Next.js app

• agent config0
• working directory0
• npm prefix0
• path you mentioned0

03

It walks the tree once

0

source files

0

skipped

stat only — nothing opened yet

04

It reads and weighs what it found

BillingDetailPanel

name ×5 · path ×5 · body ×1

05

It learns what this project does

06

Ready

697 ms

cold build

83 ms

every start after

0.22 ms

per query

All local. Nothing left the machine.

The second paste

Tell your agent it no longer has to search.

Installing the server does not change an agent’s habits. One that already knows how to grep will keep grepping unless its instructions say there is something better — the difference between paying for discovery once and paying for it on every 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.

Paste this alongside the install snippet and the benchmark above becomes the behaviour you actually get.

Deliberately short: these files load on every prompt, so a page of prose here would spend more context than the server saves.

Goes in AGENTS.md, CLAUDE.md or.github/copilot-instructions.md.

Read the full documentation →

What it is worth

Put your own numbers in.

The sliders start where the benchmark landed. Move them to your project — the result is an estimate, and it is labelled as one.

without it, per month

6,141,744

with it

174,636

about 5,967,108 fewer tokens

Measured on a 3,593-file project, applied to yours — so this is an estimate for your codebase, not a measurement of it. The instructions file is counted in full here; prompt caching recovers part of that in practice.

Pricing

The free tier is genuinely useful on its own.

What you pay for is measuring and managing the architecture, not finding files. If all you want is an agent that stops guessing, stay on Free.

2 months free

Free

$0forever

Everything an agent needs to stop guessing.

• Zero-config project detection
• Learned conventions with evidence
• Nine discovery and verification tools
• Next.js correctness checks
• Every file indexed, 500 read in full

Install

Basic

$5per month

See the architecture, not just query it.

• Everything in Free
• Local dependency dashboard
• 3,000 files read in full
• Conventions enforced, not just observed

Pro

$10per month

Measure and manage it.

• Everything in Basic
• Impact analysis before you change shared code
• Dependency cycles and coupling audit
• Near-duplicate detection
• Markdown and HTML report export
• No read ceiling, CI use included

Questions

Answers, before you install it.

Does it slow my agent down?+

A warm start is 53 ms and a query is a fraction of a millisecond. Indexing never runs during the MCP handshake — it happens on the first tool call that needs it, so a large project cannot stall your client’s startup. After that the index is incremental: a stat-only walk decides nothing changed, and only files whose mtime, size and content hash all differ are re-read.

How long does the first index take, and how big is it?+

Measured on a 3,593-file project: about 1.4 seconds cold, and 3.3 MB on disk read in full. A 2,100-file project indexes in 412 ms. There is no daemon and nothing runs in the background — the work happens when a tool asks for it and then stops.

Where does it store the index?+

In your operating system’s cache directory, never in your repository: ~/Library/Caches/nextjs-mcp-architecture on macOS, %LOCALAPPDATA%\nextjs-mcp-architecture on Windows, and $XDG_CACHE_HOME/nextjs-mcp-architecture (usually ~/.cache) on Linux. Each project gets a sub-directory named after a hash of its absolute path, so two projects on one machine cannot read each other’s index, and nothing ever appears in your git status or your Docker build context. Deleting that directory is safe; the next tool call rebuilds it.

Does it clean up after itself?+

Yes. Cache directories for projects you have not opened in 30 days are deleted, and the 50 most recent are kept. The sweep is scheduled a few seconds after the first tool call rather than run inline, so it never sits in front of an answer you are waiting for.

Is my whole project searchable on the free tier?+

Yes. Every file is in the index at every tier, under its name and its path — a file the index has never heard of could not be returned at any price, and that is not what the paid tiers sell. What a tier raises is how many files are read inside: free reads 500 of them, chosen across the whole tree rather than the first ones found, and every answer says so.

What happens to my index if my subscription ends?+

Nothing of yours is touched, and nothing is stranded. The index lives in your OS cache, not your repository, so your source is never involved. On the next tool call it is rebuilt at the free budget: every file stays findable by name and path, the surplus file contents are dropped, and the cache file gets smaller rather than larger — on a 3,593-file project it goes from 3.3 MB to 1.7 MB. Renewing rebuilds the deep index the same way.

Does it really need no configuration?+

No cwd, no environment variable, no config file. It resolves the project from nine signals in order — a path you mentioned, the MCP client’s roots, npm’s own prefix, the working directory — and scores each against the evidence of an actual Next.js app rather than taking the first one. When it genuinely cannot tell, it says so and offers the fix instead of answering about the wrong project.

Will it enforce conventions I do not have?+

It only states a rule when your own code supports it: the Wilson score lower bound has to reach 0.80, which means roughly 16 conforming files with no exceptions, or 25 with at most one. Weaker patterns are reported as observations and never produce a finding. A project too new to have conventions gets none invented for it.

What does it send anywhere?+

Nothing. Indexing, learning and checking all run locally. Licence verification is an offline signature check against a key embedded in the package, so it works with no network at all.

Which editors and agents does it work with?+

Anything that speaks MCP over stdio: Claude Code, Cursor, VS Code, Windsurf and Zed. The install snippet is identical for all of them.

One paste, and your agent knows the codebase.

Free forever, no account, nothing to configure. Add a paid tier later if you want to see the architecture as well as query it.

npx -y nextjs-mcp-architecture@latest