mcp-server-plus

Введение

mcp-server-plus — это набор инструментов для MCP-серверов: небольшой TypeScript-фреймворк для создания серверов Model Context Protocol без повторения шаблонного кода.

Примечание о названии пакета: mcp-server-toolkit уже занято на npm, поэтому этот пакет публикуется как mcp-server-plus.

Related MCP server: MCP Framework

Зачем существует этот пакет

Разработчики, начинающие создавать MCP-серверы, снова и снова реализуют регистрацию инструментов, подсказки, ресурсы, аутентификацию, логирование и тесты. Популярные библиотеки, такие как Express и Hono, успешны, потому что делают очевидный путь очевидным. mcp-server-plus стремится к такому же DX поверх официального @modelcontextprotocol/sdk.

Установка

npm install mcp-server-plus zod

Требуется Node.js 18+.

Возможности

• Регистрация инструментов

• Реестр подсказок

• Ресурсы

• Аутентификация / авторизация

• Логирование

• Метрики

• Потоковая передача (через MCP stdio transport)

• Middleware

• CLI-генератор каркаса

• Вспомогательные средства для тестирования

Быстрый старт

import { z } from "zod";
import { createServer, toolResult } from "mcp-server-plus";

const weatherTool = {
  description: "Get weather",
  inputSchema: { city: z.string() },
  async handler({ city }: { city: string }) {
    return toolResult(`Weather in ${city}: sunny`);
  },
};

const server = createServer({
  name: "demo",
  version: "1.0.0",
});

server.tool("weather", weatherTool);

await server.start(); // stdio

CLI

npx mcp-server-plus init my-weather-server
cd my-weather-server
npm install
npm start

Справочник API

createServer(options) / createMcpServer(options)

Создаёт McpKitServer.

server.tool(name, definition)

Регистрирует инструмент (также подключается к MCP SDK).

server.prompt(name, definition)

Регистрирует шаблон подсказки.

server.resource(uri, definition)

Регистрирует ресурс.

server.use(middleware)

Добавляет middleware вокруг вызовов инструментов.

server.start()

Подключает MCP stdio transport (потоковая передача обрабатывается SDK).

server.invokeTool(name, args, meta?)

Вызов в процессе для тестов/скриптов.

Вспомогательные средства для тестирования

import { callTool, expectText } from "mcp-server-plus/testing";

Примеры

server.tool("weather", weatherTool);
server.prompt("greet", {
  description: "Greeting",
  arguments: [{ name: "name", required: true }],
  handler: async ({ name }) => ({
    messages: [
      { role: "user", content: { type: "text", text: `Hello ${name}` } },
    ],
  }),
});
server.resource("memo://hello", {
  mimeType: "text/plain",
  handler: async (uri) => ({
    contents: [{ uri: uri.href, text: "Hello", mimeType: "text/plain" }],
  }),
});

Расширенные примеры

Аутентификация + RBAC

const server = createServer({
  name: "secure",
  version: "1.0.0",
  // MCP_API_KEY is the expected secret only. Callers must still send meta.apiKey.
  auth: { apiKey: process.env.MCP_API_KEY, required: true },
});

server.tool("deploy", {
  roles: ["admin"],
  scopes: ["deploy"],
  handler: async () => toolResult("deployed"),
});

Middleware + метрики

server.use(async (ctx, next) => {
  const started = Date.now();
  try {
    return await next();
  } finally {
    ctx.log.info("tool timing", ctx.toolName, Date.now() - started);
  }
});

console.log(server.metricsSnapshot());

Интеграция с фреймворками

Работает с любым MCP-хостом, поддерживающим stdio-серверы. Укажите хосту ваш процесс node dist/index.js (или npm start).

Пример конфигурации MCP-хоста:

{
  "mcpServers": {
    "demo": {
      "command": "node",
      "args": ["/path/to/server/src/index.js"]
    }
  }
}

Использование TypeScript

Полноценная поддержка TypeScript. Аргументы инструментов выводятся из Zod inputSchema, если вы явно типизируете обработчик. Включите strict для лучших результатов.

Обработка ошибок

Типизированные ошибки: McpKitError, AuthError, ForbiddenError.
Сбои инструментов возвращают { isError: true, content: [...] }, чтобы хосты могли безопасно их отображать.

Производительность

• Тонкая обёртка над официальным SDK (без дополнительных сетевых переходов)

• Middleware только при вызовах инструментов

• Метрики используют простые счётчики (низкие накладные расходы)

Лучшие практики

• Держите инструменты небольшими и учитывайте побочные эффекты

• Проверяйте входные данные с помощью Zod-схем

• Используйте optional аутентификацию для локальной/разработки, required для общих хостов

• Предпочитайте invokeTool в модульных тестах; используйте stdio для интеграционных

FAQ

Это официальный SDK?
Нет — он построен на @modelcontextprotocol/sdk с улучшенным DX.

Поддерживает ли потоковую передачу?
Да, через MCP stdio transport, используемый server.start().

CJS или ESM?
Двойная публикация; ESM в приоритете.

Руководство по миграции

С сырого SDK McpServer

Замените шаблонный код registerTool на server.tool(name, definition) и сохраните Zod-схемы. Вызывайте server.start() вместо ручного подключения StdioServerTransport.

SemVer

Критические изменения выходят в мажорных версиях и документируются в CHANGELOG.md.

Устранение неполадок

Вклад

См. CONTRIBUTING.md.

Лицензия

MIT