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"]
}
}
}cwd, no env varsFree forever tierNode 20+
- 0 ms
- cold index, 2,100 files
- 0 ms
- warm start
- 0.0 ms
- search query
- 0
- packages installed
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
Describe the task…
⏎- glob *button*+755
- grep "upgrade plan button" + "billing upgrade"no match
- grep individual words (phrase found nothing)+25,496
- read 3 files+8,921
- resolve_task_context+294
| 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 |
“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.
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.
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.
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.
- 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.
- 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.
- 89% similarsrc/app/shop/_components/ProductFilterBar.tsxsrc/app/admin/_components/CatalogFilterBar.tsx
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.
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.
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.
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.
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.
npx pulls the package
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
It walks the tree once
It reads and weighs what it found
It learns what this project does
Ready
- 697 ms
- cold build
- 83 ms
- every start after
- 0.22 ms
- per query
All local. Nothing left the machine.
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 →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.
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.
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.
Free
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, 1,500 read in full
Basic
Most pickedor $50 a year
See the architecture, not just query it.
- Everything in Free
- Local dependency dashboard
- Markdown and HTML reports
- 15,000 files read in full
- Conventions enforced, not just observed
Pro
or $100 a year
Measure and manage it.
- Everything in Basic
- Impact analysis before you change shared code
- Dependency cycles and coupling audit
- Near-duplicate detection
- No read ceiling, CI use included
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 1,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