MCP Node.js Boilerplate

Boilerplate для создания MCP client и MCP server на Node.js + TypeScript. На стороне HTTP используется Express. Поддерживаются:

• stdio — клиент запускает сервер как дочерний процесс, подходит для MCP host, работающих локально

• Streamable HTTP — endpoint находится по адресу /mcp и может быть опубликован через HTTPS с помощью Cloudflare Tunnel

• mock tools для CRUD users

• статический resource users://all и resource template users://{id}

• prompt summarize-users

• CLI client для discovery, вызова tools, чтения resources и запроса prompts

Исходные данные находятся в src/data/users.json и загружаются в память при запуске сервера. Изменения через CRUD не перезаписывают файл и сбрасываются при перезапуске процесса.

Requirements

• Node.js 20 и выше

• npm

• cloudflared только для случаев, когда нужен HTTPS tunnel

Related MCP server: MCP TypeScript Starter

Установка

npm install

Проверка сборки и тестов:

npm run check

Важная структура

src/
├── client/
│   └── client.ts          # MCP CLI client ใช้ได้ทั้ง stdio และ HTTP
├── data/
│   └── users.json         # mock seed data
├── lib/
│   └── api-client.ts      # shared Axios instance สำหรับ upstream APIs
├── services/
│   └── user-service.ts    # business logic กลางสำหรับ MCP capabilities
└── server/
    ├── mcp.ts             # ประกอบ server และ capability registrations
    ├── tools/
    │   └── user-tools.ts
    ├── resources/
    │   └── user-resources.ts
    ├── prompts/
    │   └── user-prompts.ts
    ├── schemas/
    │   └── user.ts        # shared MCP output schema
    ├── repository.ts      # in-memory CRUD repository
    ├── stdio.ts           # stdio entry point
    └── http.ts            # Express + Streamable HTTP entry point
scripts/
└── build.mjs              # compile TypeScript และ copy mock JSON ไป dist

Factory в mcp.ts используется совместно обоими транспортами, поэтому возможности сервера не отличаются. Tools, Resources и Prompts обращаются к общему UserService вместо прямой привязки к repository.

Вызов External API с помощью Axios

В проекте есть общий экземпляр Axios в src/lib/api-client.ts с base URL, timeout и опциональным Bearer token. Его можно импортировать и использовать в tool или service:

import { apiClient } from "../../lib/api-client.js";

const response = await apiClient.get("/users");
console.log(response.data);

Настройка при запуске сервера:

API_BASE_URL=https://api.example.com \
API_TIMEOUT_MS=10000 \
API_TOKEN=your-token \
npm run server:http

Пример использования в MCP tool:

server.registerTool(
  "list-upstream-users",
  {
    description: "List users from the configured upstream API",
    inputSchema: z.object({}),
  },
  async () => {
    const { data } = await apiClient.get("/users");
    return {
      content: [{ type: "text", text: JSON.stringify(data, null, 2) }],
      structuredContent: { users: data },
    };
  },
);

Если API_BASE_URL не задан, можно передавать абсолютный URL напрямую в Axios. Избегайте логирования API_TOKEN и храните токен в secret manager при production-развёртывании.

Запуск в режиме stdio

Обычно не нужно запускать stdio server отдельно, потому что клиент или MCP host запускают процесс сами.

Запуск demo client, который открывает сервер, выполняет discovery capabilities, вызывает tools, читает resources и запрашивает prompt:

npm run client:stdio -- demo

Запуск сервера напрямую для ожидания MCP host:

npm run server:stdio

Важно: stdio использует stdout как канал для JSON-RPC, поэтому логи сервера должны записываться только через stderr, например console.error.

Пример конфигурации для MCP host, замените /absolute/path/to/mcp-boilerplate на реальный путь:

{
  "mcpServers": {
    "mock-users": {
      "command": "node",
      "args": [
        "--import",
        "tsx",
        "/absolute/path/to/mcp-boilerplate/src/server/stdio.ts"
      ],
      "cwd": "/absolute/path/to/mcp-boilerplate"
    }
  }
}

Или соберите заранее и используйте JavaScript без зависимости от tsx во время выполнения:

npm run build
npm run start:stdio

Конфигурация после сборки:

{
  "mcpServers": {
    "mock-users": {
      "command": "node",
      "args": [
        "/absolute/path/to/mcp-boilerplate/dist/server/stdio.js"
      ],
      "cwd": "/absolute/path/to/mcp-boilerplate"
    }
  }
}

Запуск в режиме Express HTTP

Terminal 1 — запуск сервера:

npm run server:http

Значения по умолчанию:

• MCP endpoint: http://127.0.0.1:3000/mcp

• health check: http://127.0.0.1:3000/health

Terminal 2 — запуск HTTP client:

npm run client:http -- demo

Порт или host можно изменить с помощью environment variables:

HOST=127.0.0.1 PORT=4000 npm run server:http
MCP_URL=http://127.0.0.1:4000/mcp npm run client:http -- demo

Для production build:

npm run build
npm run start:http

Включение HTTPS с помощью Cloudflare Tunnel

HTTPS в этом примере завершается на Cloudflare, а Express server продолжает слушать HTTP только локально.

Установка cloudflared на macOS:

brew install cloudflared

Terminal 1 — запуск MCP HTTP server:

npm run server:http

Terminal 2 — запуск Quick Tunnel:

cloudflared tunnel --url http://127.0.0.1:3000

cloudflared покажет временный URL, например:

https://random-words.trycloudflare.com

Внешний MCP endpoint будет таким:

https://random-words.trycloudflare.com/mcp

Terminal 3 — тестирование через HTTPS tunnel:

MCP_URL=https://random-words.trycloudflare.com/mcp npm run client:http -- demo

Quick Tunnel подходит только для разработки, и Cloudflare указывает, что SSE не поддерживается. Поэтому в этом boilerplate режим ответа установлен на auto: обычные команды CRUD/discovery отвечают JSON, но не следует использовать Quick Tunnel для тестирования функций, требующих стриминга, например долгосрочных подписок. Для production используйте named tunnel, собственный hostname, authentication и authorization.

При использовании custom hostname добавьте его в allowlist:

ALLOWED_HOSTS=mcp.example.com npm run server:http

Несколько hostname через запятую:

ALLOWED_HOSTS=mcp.example.com,mcp-staging.example.com npm run server:http

localhost, 127.0.0.1, ::1 и *.trycloudflare.com уже разрешены для разработки.

Команды MCP client

Используется одинаковый формат для client:stdio и client:http — отличается только имя скрипта.

Просмотр tools:

npm run client:stdio -- list-tools
npm run client:http -- list-tools

Просмотр resources или prompts:

npm run client:stdio -- list-resources
npm run client:stdio -- list-prompts

Вызов CRUD tools:

npm run client:stdio -- call list-users '{}'
npm run client:stdio -- call get-user '{"id":"1"}'
npm run client:stdio -- call create-user '{"name":"Margaret Hamilton","email":"margaret@example.com","role":"developer"}'
npm run client:stdio -- call update-user '{"id":"1","role":"viewer"}'
npm run client:stdio -- call delete-user '{"id":"3"}'

Чтение resources:

npm run client:stdio -- read users://all
npm run client:stdio -- read users://1

Запрос prompt:

npm run client:stdio -- prompt summarize-users '{"tone":"detailed"}'

Для другого HTTP URL задайте MCP_URL:

MCP_URL=https://mcp.example.com/mcp npm run client:http -- call list-users '{}'

Примечание для stdio: каждая команда CLI запускает новый процесс сервера, поэтому данные всегда начинаются с исходных mock-данных. Если нужно, чтобы CRUD-операции были последовательными, используйте MCP host, который сохраняет одно соединение, или запустите HTTP server и обращайтесь через client:http.

Доступные tools, resources и prompt

Environment variables

Примеры значений находятся в .env.example. Проект не загружает файл .env автоматически; экспортируйте переменные или указывайте их перед командой, как в примерах выше.

Security notes

• В этом примере нет authentication и authorization — не открывайте публичный endpoint с реальными данными.

• Проверка Host и Origin разрешает только localhost, TryCloudflare и значения из ALLOWED_HOSTS.

• Mock repository находится в памяти и намеренно не сохраняет данные.

• Для production добавьте auth, rate limiting, audit logging, persistent database и конфигурацию TLS/trust-proxy, подходящую для реальной системы.

Все скрипты

npm run dev:stdio       # stdio server พร้อม watch mode
npm run dev:http        # Express HTTP server พร้อม watch mode
npm run server:stdio    # stdio server จาก TypeScript
npm run server:http     # Express HTTP server จาก TypeScript
npm run client:stdio -- demo
npm run client:http -- demo
npm run build
npm run start:stdio     # รัน dist หลัง build
npm run start:http      # รัน dist หลัง build
npm test
npm run check

Ссылки: MCP TypeScript SDK, Cloudflare Quick Tunnels