Documentation

A stdio MCP server that indexes a Next.js project locally and answers structural questions about it. Node 20 or newer. No native dependencies.

Install

Add this to your MCP client’s configuration — .mcp.json for Claude Code, .cursor/mcp.json for Cursor, .vscode/mcp.json for VS Code. The snippet is identical everywhere.

.mcp.json

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

There is deliberately no cwd and no env. The server works out which project it is looking at from the signals the client already gives it.

How it finds your project

Nine signals, in order of trust: an absolute path in a tool argument, a pinned root, an explicit environment variable, the MCP client’s roots, npm’s own resolved prefix, the working directory, INIT_CWD, PWD, and finally your agent’s own MCP registration.

Each candidate is scored against real evidence of a Next.js application rather than accepted on the spot, so a high-trust but wrong signal loses to a lower-trust verified one. In a monorepo it resolves to the app containing the path you mentioned; when several apps are equally plausible it says so and lists them instead of guessing.

If it ever resolves the wrong project, pass projectRoot to any tool, or call set_project_root once.

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 tell it there is something better — which is 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. It is deliberately short: those files load on every prompt, so a page of prose here would spend more context than the server saves.

AGENTS.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.

Tools

Available on every tier:

resolve_task_context: Give it a task in plain language. Returns the few files that own it, the conventions that apply, and the commands that verify it. This should be the first call for any implementation, bug-fix or refactor.
find_symbol: Where a component, hook, function or type is declared, and which files use it — without reading whole files.
get_route_context: For a URL path: the page that serves it, the layout, loading and error files that wrap it, and which parts are client components.
get_project_profile: The actual stack — Next version, router, path aliases, styling, UI kit, data and form libraries, ORM, i18n, test runners.
get_project_conventions: The conventions this project follows, each with the evidence behind it, plus whatever its own instruction files declare.
check_conventions: Checks the files you changed for framework errors and convention drift. Call it before reporting work done.
get_project_context: Which project was resolved and how, and which applications it contains.
list_projects: Every candidate project root visible on this machine, with the evidence for each.
set_project_root: Pins the project for the rest of the session.

Added by nextjs-mcp-architecture-pro with a Basic or Pro licence. Without one they are not registered at all, so they cost nothing in context:

impact_analysis: Which files and modules depend on one file, how far the effect reaches, which routes it touches, and how risky the change is.
audit_architecture: Module sizes and coupling, dependency cycles, files nothing imports, the most depended-on files, outstanding framework errors.
find_duplicates: Files that are near-copies of each other, ignoring imports, comments and string contents.

Paid tiers

The add-on is an ordinary npm package. Anyone can download it; without a licence key it registers no tools at all, so there is nothing to gain by having the files.

Install it in the project and set your licence key:

shell

npm install --save-dev nextjs-mcp-architecture-pro
export NEXTJS_MCP_LICENSE="your-key"

The key can also live in ~/.config/nextjs-mcp/license, which is usually better for a laptop. It is verified offline against a key embedded in the package, so this works with no network. Nothing in your MCP configuration changes.

Or put it in the MCP configuration itself, if you would rather keep everything in one file:

.mcp.json

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

The licence key is the only credential. The config file above is often committed to a repository — prefer ~/.config/nextjs-mcp/license unless you are sure yours is not.

Dashboard

shell

npx nextjs-mcp-dashboard

Binds 127.0.0.1 only, refuses any request whose Host header is not a loopback name, answers nothing but GET, and never writes to your project. Flags: --project, --port, --host, --no-open.

What leaves your machine

Nothing. Indexing, convention learning and checking all run locally. Derived data is written to your operating system’s cache directory, keyed by a hash of the project path — never inside your repository and never to the working directory. Licence verification is an offline signature check.

Troubleshooting

It answered about the wrong project: Call get_project_context to see which project it resolved and from which signal, then set_project_root to pin the right one.
A tool says only some files were read: Every file is in the index at every tier, under its name and path. What a tier limits is how many files have their contents read — 500 on the free tier, spread across the whole tree. A match that depends on what is written inside a file can be missed; a file cannot be invisible.
The paid tools are missing: They are only registered with a valid licence. Start the server and check stderr: an installed add-on with no licence says so in one line.
A convention looks wrong: Every rule carries its sample size and a counterexample. If the numbers do not match your repository, the file classification is likely off — the role is inferred from content, so a file that does something unusual can be counted under the wrong role.