template-mcp

Шаблон сервера MCP (Model Context Protocol) на TypeScript с валидацией Zod и поддержкой двойного транспорта (stdio/HTTP). Совместим с любым клиентом MCP: Claude Code, Claude Desktop, Cursor, VS Code Copilot, Windsurf, Cline и другими.

Возможности

• Двойной транспорт: stdio (локальный) и Streamable HTTP (удаленный)

• Строгий TypeScript с модулями ESM

• Валидация Zod для схем входных данных инструментов

• Валидация окружения Joi (быстрый отказ при запуске)

• Логирование Pino в stderr (безопасно для stdio)

• Модульная архитектура: инструменты, ресурсы и промпты как отдельные модули

• Паттерн «Фабрика»: createServer() для тестируемости

• Полный набор тестов с использованием in-memory транспорта SDK MCP

• Качественный инструментарий: ESLint + Prettier + Husky + lint-staged

• Готовность к Docker: многоэтапная сборка

• CI/CD: конвейер GitHub Actions

Related MCP server: xmcp Application

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

pnpm install
pnpm dev

Скрипты

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

Скопируйте .env.example в .env и настройте:

Структура проекта

src/
├── main.ts              # Entrypoint: transport selection
├── server.ts            # createServer() factory
├── config/              # Env validation + constants
├── common/              # Logger, error helpers, types
├── tools/               # MCP tools (callable by LLMs)
├── resources/           # MCP resources (read-only data)
└── prompts/             # MCP prompts (reusable templates)

Добавление нового инструмента

1. Создайте src/tools/my-tool.tool.ts:

import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
import { z } from 'zod';

export function registerMyTool(server: McpServer): void {
  server.registerTool(
    'my_tool',
    {
      title: 'My Tool',
      description: 'What this tool does',
      inputSchema: {
        param: z.string().describe('Parameter description'),
      },
      annotations: {
        readOnlyHint: true,
        destructiveHint: false,
        idempotentHint: true,
        openWorldHint: false,
      },
    },
    async ({ param }) => ({
      content: [{ type: 'text', text: `Result: ${param}` }],
    }),
  );
}

2. Зарегистрируйте в src/tools/index.ts:

import { registerMyTool } from './my-tool.tool.js';

export function registerTools(server: McpServer): void {
  registerGreetTool(server);
  registerMyTool(server); // add here
}

3. Добавьте тесты в src/tools/__tests__/my-tool.tool.spec.ts

Конфигурация клиента

Claude Code

Добавьте в .claude/settings.json:

{
  "mcpServers": {
    "template-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/template-mcp/dist/main.js"]
    }
  }
}

Claude Desktop

Добавьте в claude_desktop_config.json:

{
  "mcpServers": {
    "template-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/template-mcp/dist/main.js"]
    }
  }
}

Cursor

Добавьте в Cursor Settings > MCP Servers:

{
  "mcpServers": {
    "template-mcp": {
      "command": "node",
      "args": ["/absolute/path/to/template-mcp/dist/main.js"]
    }
  }
}

VS Code (Copilot)

Добавьте в .vscode/settings.json:

{
  "mcp": {
    "servers": {
      "template-mcp": {
        "command": "node",
        "args": ["/absolute/path/to/template-mcp/dist/main.js"]
      }
    }
  }
}

Docker

# Build
docker build -t template-mcp .

# Run (HTTP mode, used for remote access)
docker run -p 3000:3000 template-mcp

Технологический стек

• Node.js 22 + TypeScript (строгий, ESM)

• MCP SDK v1 (@modelcontextprotocol/sdk)

• Zod (валидация входных данных инструментов)

• Joi (валидация окружения)

• Pino (логирование в stderr)

• Vitest (тестирование)

• ESLint + Prettier + Husky

Проверка

Все нижеперечисленное проверено и работает на 100%.

Качество кода

Модульные тесты (11/11)

pnpm test

Без сети и портов — используется InMemoryTransport из SDK.

Runtime — транспорт stdio (режим по умолчанию)

echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' \
  | MCP_TRANSPORT=stdio node dist/main.js

Ответ JSON-RPC в stdout, логи в stderr.

Runtime — транспорт HTTP

MCP_TRANSPORT=http PORT=3100 node dist/main.js &
# Initialize → capturar Mcp-Session-Id del header
# tools/list, resources/list, prompts/list, tools/call greet, resources/read info://server

Docker

docker build -t template-mcp .  # multi-stage: base → deps → build → production
docker run -p 3000:3000 template-mcp  # arranca en HTTP mode

CI (GitHub Actions)

pnpm install → pnpm lint → pnpm build → pnpm test Запускается при каждом push и PR в main/master.

Конвейер коммитов (локальный)

git commit → husky → lint-staged → eslint --fix + prettier --write (только для staged-файлов)

Известные пробелы

• HTTP-транспорт без автоматических тестов (средний): модульные тесты используют InMemoryTransport; HTTP-транспорт (StreamableHTTPServerTransport) был проверен только вручную через curl. Для удаленного продакшена добавьте интеграционные тесты с реальной сессией

• Интеграция с клиентом MCP (средний): проверьте вручную, добавив в .claude/settings.json или Cursor, и убедитесь, что инструменты/ресурсы/промпты отображаются в клиенте

• Экстремальные входные данные инструментов (низкий): очень длинные строки, некорректный unicode — Zod их отклоняет, но ответ об ошибке не протестирован через HTTP

• Параллельные сессии (низкий): вне области действия шаблона