# nextjs-mcp-architecture

An MCP server that learns **your** Next.js project's own architecture, so your
coding agent finds the right file in one call instead of six greps.

No configuration. No absolute paths in your MCP config. No rules to write.

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

That is the whole setup. There is no `cwd` and no `env` block on purpose.

## Why

Two things quietly dominate what an agent costs you on a real codebase:

1. **Discovery.** The agent does not know where anything lives, so it greps,
   globs and reads its way to the file it needed, several tool calls before the
   actual work starts.
2. **The architecture document.** A mature project's `CLAUDE.md` or
   `copilot-instructions.md` runs to tens of kilobytes and is loaded into
   context on *every* prompt, whether or not that prompt needs it.

This server attacks both: it answers discovery questions from a local index in
one call, and it serves your conventions on demand in ~300-token slices
instead of as a permanent wall of text.

## Measured

Eight prompts a developer would actually type, run against
[dubinc/dub](https://github.com/dubinc/dub) — an open-source Next.js product of
3,593 files — once the way an agent searches today, once through this server.

| | Searching | This server |
| --- | ---: | ---: |
| Tokens to find the owning file | **16,372** | **293** |
| Right file found | 6/8 | 6/8 |

**56× less context per task**, at the same accuracy. dub was chosen
knowing it is a hard case for us: everything in it is named in plain English,
so grep works about as well as grep can work.

The harness ships with this package and the run is deterministic — no model
call, no network — so you can clone dub and reproduce every figure, or point it
at your own project. See `BENCHMARK.md`, included in this package.

## It learns your project, it does not impose ours

Generic linters ship someone else's conventions. This does not. On first use
it reads your project and derives the rules **your** code already follows,
with a measured confidence for each:

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

A convention is only enforced when the evidence supports it: the Wilson score
lower bound must reach 0.80, which in practice means at least 16 conforming
files with no exceptions, or 25 with at most one. Weaker patterns are reported
as observations and improve search ranking, but never produce a finding — and
a project too young to have conventions gets none invented for it.

Alongside that, a short list of Next.js **correctness** rules always applies,
because those are framework facts rather than opinions: a Node built-in
imported into the client bundle, a private environment variable read in the
browser, `next/headers` in a client component. The client boundary is followed
through the import graph, so a component whose parent declares `'use client'`
is not reported for lacking its own directive.

It also reads whatever you already have — `AGENTS.md`, `CLAUDE.md`,
`.github/copilot-instructions.md`, `.github/instructions`, `.github/skills`,
`.cursor/rules`, `components.json`. Those sources are commonly duplicated
between `.github/` and `.claude/`, so they are deduplicated and distilled to
the actual directives — on the order of 1,300 tokens — with the full text of
any section available on request rather than loaded up front.

## Make your agent reach for it

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.

Paste this into your `AGENTS.md`, `CLAUDE.md` or
`.github/copilot-instructions.md`:

```md
## 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.
```

Deliberately short: that file loads on every prompt, so a page of prose here
would spend more context than the server saves.

## Tools

| Tool | What it answers |
| --- | --- |
| `resolve_task_context` | Given a task in plain language: the few files that own it, the conventions that apply, and the commands that verify it |
| `find_symbol` | Where a component, hook or type is declared, and which files use it |
| `get_route_context` | Which page serves a URL, which layouts wrap it, where the client boundary is |
| `get_project_profile` | The actual stack: version, router, aliases, styling, data, forms, ORM, tests |
| `get_project_conventions` | What this project's own code does, with the evidence — and what its docs say |
| `check_conventions` | Framework correctness and convention drift in the files you just changed |
| `get_project_context` | Which project was resolved and how, and which apps it contains |
| `list_projects` | Every candidate project root visible on this machine |
| `set_project_root` | Pin the project for the rest of the session |

Measured on a 2,100-file project: the whole tool surface costs about 1,550 tokens
of permanent context, and a typical answer is 70–310 tokens.

## Paid add-on

Subscribers install `@nextjs-mcp/pro` alongside this package. It
adds `impact_analysis`, `audit_architecture` and `find_duplicates`, plus a local
dashboard (`npx nextjs-mcp-dashboard`) showing the module dependency graph,
findings, learned conventions and near-duplicates, with the report downloadable
as Markdown or HTML.

The add-on is registered only when a valid licence is present. Without one its
tools are not advertised at all, so a free user never pays context for them.

The free tier is genuinely useful on its own. What the add-on adds is measuring
and managing the architecture, not finding files — every file in your project
is in the index either way, because a file the index has never heard of could
not be returned at all.

Current plans and prices are on the website; putting them in a README is how
they end up out of date in a copy nobody remembers to edit.

## How fast

Measured against a real 2,100-file Next.js application:

| | |
| --- | --- |
| Cold index build | 412 ms |
| Warm start (nothing changed) | 53 ms |
| Search query | 0.2 ms |
| Project profile, cached | 0.16 ms |
| Index on disk | 1.5 MB, in your OS cache directory |

## Requirements

Node.js 20 or newer. No native dependencies — nothing to compile, so `npx`
cannot fail on a node-gyp build. Three packages total, about one second to
install.

## Where the index lives

Your operating system's cache directory, never your repository:

| | |
| --- | --- |
| macOS | `~/Library/Caches/nextjs-mcp-architecture` |
| Windows | `%LOCALAPPDATA%\nextjs-mcp-architecture` |
| Linux | `$XDG_CACHE_HOME/nextjs-mcp-architecture` (usually `~/.cache`) |

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 appears
in your `git status` or Docker build context. Deleting the directory is safe —
the next tool call rebuilds it.

Directories for projects untouched for 30 days are deleted automatically, and
the 50 most recent are kept. The sweep is scheduled a few seconds after the
first tool call, so it never sits in front of an answer you are waiting for.

**If a subscription lapses**, nothing of yours is touched and nothing is
stranded. The index is rebuilt at the free budget on the next call: every file
stays findable by name and path, surplus file contents are dropped, and the
cache file gets *smaller* — on a 3,593-file project, 3.3 MB to 1.7 MB. Renewing
rebuilds the deep index the same way.

## Privacy

Everything runs locally. Your source, file names and prompts are not
transmitted anywhere. Licence verification is an offline signature check
against a key embedded in the package.

## Licence

Commercial, source-available. Free-tier use is perpetual and permitted
commercially. See the `LICENSE` file included in this package.