nextjs-mcp-kit

MCP-сервер, MCP-клиент и не зависящий от провайдера чат-интерфейс для Next.js App Router — в виде route-обработчиков, компонентов и типизированного состояния, которые можно установить.

Дайте вашему приложению небольшой чат, который действительно знает что-то о вашем приложении.

Умный чат — ответы, которые вы написали, документы, которые вы загрузили

• инструменты, которые вы добавляете Вы добавляете ответы через форму в браузере, чтобы создать инструмент. Никакого переобучения, векторной базы данных или повторного деплоя.

Он намеренно не умный. Это маленький чат, который здоровается и знает ваши часы работы, и чтобы получить такой, нужна примерно минута.

npm i nextjs-mcp-kit && npx nextjs-mcp-kit init

nextjs-mcp-kit — параметры скаффолдера

npx nextjs-mcp-kit init // создать в текущей директории

npx nextjs-mcp-kit init --force // перезаписать существующие файлы

npx nextjs-mcp-kit init --dir web // создать в ./web

Затем переходите к разделу Ваш первый инструмент за 60 секунд.

Шесть интерфейсов, намеренно раздельных:

Добавьте инструмент из браузера — и он сразу станет доступен в чате, а также будет отдаваться по MCP любому клиенту, направленному на ваше приложение, включая чужой клиент.

Related MCP server: Example Next.js MCP Server

Ваш первый инструмент за 60 секунд

Никакого API, никаких ключей, никакого кода. Запустите npm run dev, откройте /add-tool и оставьте первый параметр на «Возвращает текст, который я пишу»:

Оставьте параметры пустыми. Нажмите Добавить инструмент.

Теперь откройте /personal-chat, отметьте opening_hours и спросите: «вы открыты в субботу?»

Модель отвечает «нет — по выходным закрыто», и под ответом написано, что выполнился opening_hours, и показано, что именно вернул инструмент. Она этого не знала. Вы сказали ей это тридцать секунд назад через форму.

Это весь цикл. Всё остальное в этом README — тот же цикл с дополнительными вариантами.

Почему описание важнее, чем кажется

Описание — это не документация, а то, как модель решает, вызывать ли инструмент вообще. "opening hours" игнорируется в половине случаев. "The shop opening hours. Call this when asked when we are open." — вызывается. Расплывчатое описание означает инструмент, который зарегистрирован, но никогда не выбирается.

Для чего это нужно

Крошечный чат для ваших посетителей. Не настолько умный, чтобы быть агентом поддержки, и не пытается им быть. Достаточно умный, чтобы поприветствовать человека и ответить на шесть вопросов, которые действительно задают вашему приложению, — ответами, которые вы написали. Каждый такой ответ — это инструмент skill: имя, описание и возвращаемый текст.

Ответы, основанные на том, что вы ему сказали. Когда инструмент подходит под вопрос, модель вызывает его и отвечает на основе полученного результата, а не на основе того, что она смутно помнит о магазинах в целом. Вопрос, который покрывают ваши инструменты, получает ответ от ваших инструментов.

Вы всегда видите, что произошло. Каждый ответ, использовавший инструмент, называет его и показывает, что он вернул. Если ответ пришёл из вашего текста, вы можете это доказать; если модель ответила сама, трассировка пуста, и вы тоже это видите. Не нужно гадать, какой вариант вы получили.

Никаких тихих запасных вариантов. Если провайдер не умеет вызывать инструменты или модели Ollama не хватает этой возможности, вы получите 503 с причиной до начала хода — и никогда не получите ответ, который молча проигнорировал отмеченные вами инструменты.

Бесплатно в работе. Ollama работает локально, поэтому чат для посетителей ничего не стоит за сообщение, и данные не покидают машину. Переключитесь на Claude для более качественного чата с теми же инструментами — в селекторе 💳 означает платный ход, 🖥️ — локальный.

Это также MCP-сервер. Те же инструменты, которые вы добавили из браузера, отдаются по MCP, так что Claude Desktop — или клиент любого другого человека — может указать на ваше развёрнутое приложение и использовать их. См. Подключение MCP-клиента.

Какую страницу дать вашим посетителям

/smart-chat — та, на которую стоит их направить. Один вопрос на входе, один ответ на выходе: он проверяет все зарегистрированные вами инструменты, использует подходящий и сообщает, какой именно выполнился. Никакого диалога для поддержания, никакой истории для хранения, ничего настраивать посетителю не нужно.

// app/ask/page.tsx — your public "ask us anything" page
export { SmartChatPage as default } from 'nextjs-mcp-kit/pages';

Или вставьте только компонент на свою страницу:

import { SmartChat } from 'nextjs-mcp-kit/components';

/personal-chat — для вас: полный диалог, инструкции и список инструментов, которые этот диалог может использовать. Здесь вы пробуете новый инструмент, прежде чем подпустить к нему кого-то ещё.

/add-tool и /mcp-dashboard тоже ваши, а не ваших посетителей. Ни на одном из них нет аутентификации — либо поместите их за свою, либо вообще не включайте их в публичное приложение.

Работает с Ollama (локально, бесплатно) и Claude (Anthropic). Добавление третьего провайдера — это один файл и одна запись в массиве.

Установка

Требуются Next.js 16+ и Node 20.9+. Диапазон peer-зависимостей намеренно равен >=16.0.0, а не >=15.0.0: 16 — единственный мажорный релиз, с которым это собрано и протестировано, а диапазон peer-зависимостей должен описывать то, что действительно проверено, а не то, что, возможно, заработает. На Next 15 npm i сообщит о peer-конфликте — это ожидаемый сигнал, а не баг.

В существующее приложение Next.js

npm i nextjs-mcp-kit
npx nextjs-mcp-kit init

init создаёт обработчики маршрутов и /chat. Он не трогает ваш корневой layout — добавьте две строки самостоятельно:

// app/layout.tsx
import { GlobalProvider } from 'nextjs-mcp-kit/context';
import 'nextjs-mcp-kit/styles.css';

export default function RootLayout({ children }: { children: React.ReactNode }) {
  return (
    <html lang="en">
      <body>
        <GlobalProvider>{children}</GlobalProvider>
      </body>
    </html>
  );
}

Затем выполните cp env.local.example .env.local и npm run dev.

Импорт компонента: то, на чём спотыкаются

Компоненты не экспортируются из корня пакета. Так не работает:

import { AgentChat } from 'nextjs-mcp-kit';
// The export AgentChat was not found in module .../dist/index.js [app-rsc]
// Did you mean to import initialAgent?

А так работает:

import { AgentChat } from 'nextjs-mcp-kit/components';

Корневая точка входа намеренно безопасна для сервера — см. Экспорт. Эмпирическое правило: если что-то рендерится, его нет в корне.

Исправить импорт необходимо, но недостаточно: AgentChat требует, чтобы в вашем приложении существовали /api/providers, /api/chat и /api/instructions, а над ним — GlobalProvider. npx nextjs-mcp-kit init создаёт маршруты; layout — ваш. Полностью рабочее приложение — плюс список проблем в порядке, в котором они действительно возникают — находится в examples branch.

Автономно, из пустой директории

mkdir my-app && cd my-app
npm init -y
npm i nextjs-mcp-kit
npx nextjs-mcp-kit init          # detects the empty dir, writes a whole app
npm i next react react-dom
npm i -D typescript@^5 @types/node @types/react @types/react-dom
cp env.local.example .env.local
npm run dev

typescript@^5 закреплён намеренно. Голый npm i -D typescript сейчас разрешается в TypeScript 7, чью реструктурированную lib/ Next 16 не обнаруживает — он сообщает "you do not have the required package(s) installed", хотя пакет установлен, и сборка падает.

Конфигурация

OLLAMA_API_URL=http://localhost:11434   # 11434 is Ollama's default port
ANTHROPIC_API_KEY=                      # empty is fine — runs local-only
NEXTJS_MCP_DATA_DIR=                    # defaults to ./.data

Оставить ANTHROPIC_API_KEY пустым — это поддерживаемый режим, а не поломка: селектор показывает Claude как недоступного с указанием причины, а Ollama продолжает работать. В этом смысл isAvailable() — отсутствующий ключ это нормальное состояние, о котором сообщается заранее, а не исключение, выбрасываемое при нажатии «Отправить».

На серверless-хостингах задайте NEXTJS_MCP_DATA_DIR=/tmp/nextjs-mcp-kit; их файловая система бандла доступна только для чтения, кроме /tmp. См. Постоянное хранение.

Маршруты

Коды состояния несут смысл: 503 — когда провайдер просто недоступен (запрос был корректным), 400 — при неверном вводе, 500 — при настоящем сбое.

curl -X POST localhost:3000/api/chat -H 'content-type: application/json' -d '{
  "provider": "ollama",
  "model": "llama3.1:8b",
  "system": "Answer in one word.",
  "messages": [{ "role": "user", "content": "Capital of France?" }]
}'
# {"answer":"Paris","provider":"ollama","model":"llama3.1:8b","billed":false}

Инструменты

/api/chat не имеет инструментов и никогда не будет. Вызов инструментов — это отдельный маршрут, который обращается к реестру провайдеров напрямую — он не оборачивает /api/chat.

curl -X POST localhost:3000/api/agent-chat -H 'content-type: application/json' -d '{
  "provider": "anthropic",
  "model": "claude-haiku-4-5-20251001",
  "messages": [{ "role": "user", "content": "What is the refund window?" }],
  "tools": ["refund_policy"]
}'
# {"answer":"…","provider":"anthropic","model":"…","billed":true,
#  "trace":[{"name":"refund_policy","result":"…","isError":false,"ms":2}]}

trace — ради этого всё и затевается: ответ, использовавший инструмент, может это доказать.

Добавьте "stream": true для NDJSON — по одному JSON-объекту на строку, {"type":"token"} … {"type":"done"}. Читайте его с помощью streamAgentChat из nextjs-mcp-kit/client, а не разбирайте самостоятельно.

Какие инструменты выполняются, полностью выбирает вызывающая сторона: отсутствие tools[] означает обычный ход. Ничто никогда не отбрасывается молча — провайдер, который не умеет вызывать инструменты, или модель Ollama без этой возможности получает 503 с причиной вместо ответа, который тихо проигнорировал то, что вы просили.

Конфигурация сегмента маршрута

Каждый сгенерированный маршрут объявляет собственный runtime:

export { POST } from 'nextjs-mcp-kit/api/chat';

export const runtime = 'nodejs';
export const maxDuration = 120;

Это не шаблонный код, который можно выбросить. Next читает конфигурацию сегмента статически из самого модуля маршрута, поэтому повторно экспортированный runtime молча игнорируется, и обработчик выполняется на неправильном.

Добавление провайдера

Слой провайдера — единственное место, которое знает о бэкендах моделей. Два шага:

1. Напишите ChatProvider:

import type { ChatProvider } from 'nextjs-mcp-kit/types';

export const myProvider: ChatProvider = {
  id: 'mine',
  label: 'My backend',
  defaultModel: 'some-model',
  billed: false,
  dynamicModels: false,

  // Never throws. A missing key or a down daemon is a normal state.
  async isAvailable() {
    return process.env.MY_KEY
      ? { available: true }
      : { available: false, reason: 'MY_KEY is not set' };
  },

  async listModels() {
    return [{ id: 'some-model', label: 'Some model' }];
  },

  // `system` arrives separately: Anthropic takes it as a top-level field,
  // Ollama as a message role. That difference is absorbed here, per provider.
  async chat({ model, system, messages }) {
    return { text: '…', model };
  },
};

2. Добавьте его в реестр.

Больше ничего не меняется. Ни маршрут, ни редьюсер, ни селектор, ни объединение типов — ProviderId намеренно является string. /api/providers и ProviderModelPicker управляются реестром, поэтому новый провайдер появляется в обоих выпадающих списках без единого изменения на клиенте.

billed управляет значком 💳/🖥️. Платный ход никогда не должен быть сюрпризом.

Чтобы ваш провайдер мог вызывать инструменты, добавьте опциональный chatWithTools. Он остаётся опциональным, поэтому провайдер без него остаётся полностью работоспособным — и сообщается как не умеющий работать с инструментами, а не тихо отвечает без запрошенных инструментов:

async chatWithTools({ model, system, messages, tools, run, onToken }) {
  // `tools` is neutral — translate it with your dialect:
  //   import { DIALECTS } from 'nextjs-mcp-kit/tools';
  //   const declared = DIALECTS.openai.toTools(tools);
  // Then loop: ask, ingestToolCalls(raw), await run(call), feed results back.
  return { text: '…', model, trace: [] };
}

Большинство новых бэкендов совместимы с OpenAI, и DIALECTS.openai уже существует — так что новый провайдер обычно вообще не добавляет диалект.

Как инструменты работают внутри

Инструмент хранится один раз, в одной нейтральной форме. Вариант каждого провайдера выводится из неё:

import { deriveByProvider } from 'nextjs-mcp-kit/tools';

deriveByProvider(tools).anthropic; // [{ name, description, input_schema }]
deriveByProvider(tools).ollama;    // [{ type:'function', function:{ … } }]

Это важно, потому что Anthropic и Ollama расходятся на каждом шагу — ключ схемы, содержат ли вызовы id и как возвращаются результаты. Два списка, поддерживаемых вручную, разошлись бы при первом же редактировании одного из них.

Два вида, оба вызываемые с первого дня:

skill — это способ, которым документ или тело в форме SKILL.md становится инструментом без файловой системы. Текст — это поле в записи.

Проблема id и её решение. Anthropic присваивает каждому вызову инструмента id и сопоставляет результаты по tool_use_id; нативный API Ollama не отправляет id вообще и сопоставляет по порядку. Единый цикл, предполагающий любой из этих вариантов, ломается на другом. Поэтому ни одно из этих предположений не делается за пределами одного файла: ingestToolCalls() сохраняет id там, где он есть, создаёт name#index там, где его нет, и нормализует аргументы, пришедшие в виде JSON-строки. После приёма два провайдера неразличимы, и каждый по-прежнему возвращает результаты так, как требует его собственный API.

React-компоненты находятся за собственными подпутями, поэтому их импорт не может затащить встроенные модули Node — или ANTHROPIC_API_KEY — в клиентский бандл. Если что-то рендерится, его нет в корне.

Подпути разрешаются через карту exports в package.json, для чего в вашем tsconfig.json требуется "moduleResolution": "bundler". create-next-app уже устанавливает это; при устаревшей настройке "node" каждый подпуть не разрешается с ошибкой Cannot find module 'nextjs-mcp-kit/components'.

Состояние

Контекст с разделёнными значениями: { state, actions }, потребляемый через useContextState() / useContextActions(). Компоненты, которые только диспатчат, не перерендериваются при изменении несвязанного состояния.

'use client';
import { useContextState, useContextActions } from 'nextjs-mcp-kit/context';

function MyChat() {
  const { agent, instruction } = useContextState();
  const { sendChat, selectProvider } = useContextActions();
  // agent.chat, agent.provider, agent.model, agent.routing …
}

Два слайса, agent и instruction. Действия читают текущее состояние через ref, а не через замыкание, что сохраняет идентичность каждого действия стабильной на всё время жизни провайдера — без этого sendChat пересоздавался бы при каждом нажатии клавиши.

Пресеты и systemText

Это две разные вещи, и смешивать их было бы ошибкой:

• presets — сохранённый, персистентный список.

• systemText — редактируемый текст, который фактически отправляется со следующим ходом.

Выбор пресета заполняет systemText. Последующее редактирование не изменяет сохранённый пресет. Пресет — это отправная точка, а не клетка. Сохранение с существующим именем редактирует этот пресет (id выводится из имени), а не накапливает почти дубликаты.

Темизация

Все цвета берутся из CSS-кастомных свойств. Переопределите любое из них после импорта — вот и вся история с темизацией:

:root {
  --mcp-bubble-user: #dcfce7;
  --mcp-border: #cbd5e1;
}

Светлая и тёмная темы обе определяются через prefers-color-scheme.

Персистентность

Пресеты инструкций и инструменты хранятся в виде JSON в каталоге NEXTJS_MCP_DATA_DIR (по умолчанию ./.data) — это минимальная вещь, которая переживает перезапуск. Добавьте .data/ в ваш .gitignore.

.data/
  instructions.json
  tools.json

Это файловое хранилище, поэтому на серверлесе оно существует на каждый инстанс и является временным — файловая система бандла доступна только для чтения, кроме /tmp, который очищается между вызовами. Если вам нужно долговременное хранение, замените два файла: src/store/instructions.ts и src/store/tools.ts — это единственные места, которые маршруты читают или в которые пишут.

Тело навыка — это поле в записи инструмента, а не файл на диске. Загрузка документа не создаёт SKILL.md нигде, и ничто в этом пакете никогда не пишет в дерево исходников вашего приложения.

Подключение MCP-клиента

{
  "mcpServers": {
    "nextjs-mcp-kit-local": {
      "type": "http",
      "url": "http://localhost:3000/api/mcpserver/mcp"
    }
  }
}

Обратите внимание на суффикс /mcp — маршрут представляет собой динамический сегмент [transport], поэтому направление клиента на /api/mcpserver само по себе не подключит его.

Эта конечная точка — публичная поверхность, а не приватная дверь. Разверните своё приложение, и любой сможет направить свой MCP-клиент на https://your-app.example.com/api/mcpserver/mcp со своей моделью и своим ключом — им нечего у вас забирать. Они получают все промпты и все инструменты, которые вы добавили, а /mcp-dashboard показывает, что именно это такое.

Что это намеренно не делает

• Нет инструментов в /chat. Этот маршрут намеренно отправляет только сообщения и ничего больше. Инструменты находятся на /api/agent-chat и на четырёх страницах выше.

• Нет стриминга на /api/chat. Его ответы приходят целиком, и его формат не менялся. /api/agent-chat стримит.

• Нет авторизации. Разместите эти маршруты за своей собственной. Обратите внимание, что /api/mcpserver/mcp публичен по замыслу — на него предполагается направлять клиентов.

• Нет загрузки .docx или .pdf. Только .md и .txt, потому что их поддержка добавляет ноль зависимостей в устанавливаемый пакет. Добавление формата — это одна ветка в src/server/extractText.ts.

• Нет базы данных. Инструменты и пресеты — это JSON-файлы. На серверлесе это на каждый инстанс и временно — замените два файла хранилища.

• Ничего предсобранного «на потом». Никаких заглушек-реестров, никаких мёртвых абстракций.

Требования

Next.js ≥ 16 (App Router), React ≥ 18.3, Node ≥ 20.9. Протестировано с Next 16.2 и React 19.2.

Примечание

Архитектура nextjs-mcp-kit реализует строгую границу, разделяющую публичные клиентские компоненты и безопасное серверное исполнение. Клиентский слой на React координирует интерактивные состояния и чат-интерфейсы, но полностью слеп к чувствительным переменным окружения и сторонним учётным данным. Безопасность обеспечивается тем, что все ключи API, локальные выполнения инструментов и прямые вызовы LLM находятся исключительно за Next.js Route Handlers в безопасной среде выполнения Node.js. Взаимодействие между этими границами строится на стандартных HTTP POST-запросах для событий, инициированных пользователем, и Server-Sent Events (SSE) для однонаправленной потоковой передачи данных в реальном времени. Такая схема гарантирует, что сложные многоагентные рабочие процессы остаются высокоотзывчивыми, соответствуя строгим современным корпоративным стандартам безопасности.

Архитектура nextjs-mcp-kit реализует строгую границу, разделяющую публичные клиентские компоненты и безопасное серверное исполнение. Клиентский слой на React координирует интерактивные состояния и чат-интерфейсы, но полностью слеп к чувствительным переменным окружения и сторонним учётным данным. Безопасность обеспечивается тем, что все ключи API, локальные выполнения инструментов и прямые вызовы LLM находятся исключительно за Next.js Route Handlers в безопасной среде выполнения Node.js. Взаимодействие между этими границами строится на стандартных HTTP POST-запросах для событий, инициированных пользователем, и Server-Sent Events (SSE) для однонаправленной потоковой передачи данных в реальном времени. Такая схема гарантирует, что сложные многоагентные рабочие процессы остаются высокоотзывчивыми, соответствуя строгим современным корпоративным стандартам безопасности.

Самое интересное в этом пакете — как мало вашего времени он требует.

Всё, что обычно составляет работу — провайдерский шов, цикл вызова инструментов, два провайдера, которые расходятся в том, как объявляются инструменты и как возвращаются результаты, стриминг, MCP-сервер, персистентность — уже сделано. Устанавливается, а не копируется. Оно остаётся сделанным, когда вы выполняете npm update, и ни одна из этих частей не является кодом, который вам нужно читать, поддерживать или считать своим.

То, что остаётся вам, — это единственная часть, которая всегда по-настоящему была вашей: решение, что должен знать ваш чат. Это имя, предложение, описывающее, когда его использовать, и ответ. Заполняется в форме, в браузере, меньше чем за минуту. Десять таких — и у вас чат, который знает ваше приложение лучше, чем когда-либо будет знать любой универсальный ассистент, — потому что ни у кого больше нет ваших часов работы, вашего окна возврата или ваших правил доставки.

Поэтому форма работы необычна: полдня, и большая часть этого времени уходит на размышления о том, о чём на самом деле спрашивают ваши посетители, а не о схемах инструментов и API провайдеров. Демо быстро собирается и непропорционально хорошо смотрится, потому что то, что впечатляет людей — оно знало это о вашем приложении — происходит из части, которая заняла у вас минуту, а не из той, что заняла месяцы.

Две вещи, которые стоит знать перед началом, чтобы ничего здесь не было преувеличено. Это узкоспециализированный чат по замыслу: он очень хорошо отвечает на основе того, что вы ему дали, и не пытается быть универсальным ассистентом. И в этом пакете нет авторизации нигде — /add-tool и /mcp-dashboard ваши, а не ваших посетителей. Поместите их за свою авторизацию или вообще не монтируйте их в публичном приложении.

А теперь идите и создайте что-нибудь с его помощью. Он был написан, чтобы его расширяли, а не просто восхищались им: новый провайдер — это один файл и одна запись в массиве, новый вид инструмента — одна ветка, а хранилище — это два файла, которые можно заменить на настоящую базу данных. Если вы создадите что-то с его помощью, мне искренне хотелось бы это увидеть.

Благодарности ❤️

Этот набор — тонкая прослойка поверх основательной работы других людей.

Ollama ❤️ — за то, что делает локальные модели по-настоящему простыми. Без аккаунта, без ключа, без счетов: скачайте модель — и она отвечает. Именно поэтому nextjs-mcp-kit может быть полезен сразу после установки, и именно поэтому провайдер по умолчанию — локальный.

Claude и Anthropic ❤️ — за модели и за Model Context Protocol. MCP — это то, на чём построен маршрут /, и он был отдан как открытая спецификация, а не удержан как ров. Этот пакет не существовал бы в таком виде без него.

Оба провайдера здесь намеренно полноправные. Один — локальный и бесплатный, другой — облачный и отличный, и провайдерский шов существует, чтобы ни одному не пришлось побеждать.

Лицензия

MIT