nextjs-mcp-kit: Instructions file for Claude Code

nextjs-mcp-kit

A standalone Next.js (App Router) package: an MCP server, an MCP client, and a provider-agnostic chat UI.

Published to the npm registry as nextjs-mcp-kit — a library other people install. Two consumer modes, both verified end to end:

• npm i nextjs-mcp-kit into an existing Next.js app, then npx nextjs-mcp-kit init
• an empty directory with only npm init run — init scaffolds a whole app

(The name nextjs-mcp was already taken on npm. See docs/PUBLISH.md.)

This repository is self-contained. It has no dependency on, and must not reference, any other project on this machine.

Two surfaces, deliberately separate:

Route	What it is
/	MCP prompt chat — prompts served by this app's own MCP server
/chat	Plain chat — pick a provider + model, set instructions, talk. No tools.
/add-tool	Make a tool: by form, by .md/.txt upload, or from a skill
/mcp-dashboard	What the MCP server serves, and the mcp.json to point a client at it
/personal-chat	Instructions + tools + a streamed reply, with the trace named
/smart-chat	Does a tool fit this prompt? It decides, in the open

---

Non-negotiables

These are the constraints this was built under. Do not quietly relax them.

1. No tools in /chat. /chat sends messages and nothing else, and src/api/chat.ts stays a plain conversation forever. Tool calling lives on its own route, /api/agent-chat, which calls the provider registry directly. It does not wrap /api/chat — asking a model to pick a tool by making a second call to a chat endpoint is a cheap imitation of the tool machinery every provider already has. See docs/PLAN_NOT_CHEAP.md.
2. Nothing prebuilt or scaffolded "for later." No placeholder tool registries, no dead abstractions. Add a thing when it is used. Two routes (/api/models/capabilities, /api/models/pull) were deleted for exactly this reason — they were tool-calling groundwork nothing called.
3. Simplicity over cleverness — but reusable. The provider seam exists because it removes branching everywhere else, not because it is grand.
4. This repository is independent. Everything it needs lives here.
5. Context is only what this app needs. Two slices: agent and instruction — no speculative slices carried in from elsewhere.
6. It is on npm. Favour clear public seams and no machine-specific assumptions; a consumer installs this, they do not clone your setup.
7. What is advertised must be served. The MCP catalogue and the MCP server derive from one list. See "The drift rule" below — this is not a style preference, it is the bug that shipped last time.
8. One tool record is the truth. A tool is stored once, neutrally, and each provider's dialect is derived from it (src/tools/dialects/). Two hand-kept per-provider lists is rule 7's bug wearing a new hat.
9. Never silently answer without a tool that was asked for. A provider that cannot tool-call, or a model without the capability, is reported before Send — the same contract isAvailable() follows. A quiet downgrade to plain chat is worse than an error, because nobody is told.
10. Never split tool results across messages. All results from one assistant turn go back in exactly one user message. Anthropic does not error on this; it just stops making parallel calls, which is a silent degradation.