MCP TypeScript Starter

MCP Typescript Starter — это ориентированная на production основа для создания сервера Model Context Protocol на TypeScript. Он включает один типизированный пример инструмента, транспорты stdio и Streamable HTTP, строгую валидацию, тесты, защищённый контейнер и автоматическую публикацию в GHCR.

Склонируйте репозиторий, замените пример домена и сохраните инфраструктуру, котораая нужна настоящим серверам MCP.

Навигация

• Использование этого стартера

• О проекте

• Возможности

• MCP-инстроменты

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

• Установка

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

• Настройка MCP-клиента

• Кастомизация стартера

• Проверка

• Ограничения

• Вклад в проек

• Лицензия

Related MCP server: mcp-server-http-streamable

Использование этого стартера

Нажмите Use his template на GitHub, чтобы создать новый MCP-сервер с независимой историей Git. После создания замените пример инструмента и обновите идентичность проека, следуя разделу Кастомизация стартера.

Сделайте форк этого репозитория, если хотите вернуть улучшения через pull request. Прежде чем отправить изменения, ознакомьтесь с разделом Вклад в проект.

Если этот стартер вам помог, поставьте звёздочку репозиторию. Это помогает другим TypeScript-разработчикам найти проек.

О проекте

Стартер демонстрирует полный путь от проверенного определения MCP-инструмента до видимого клиенту структурированного результата. Сервер использует теущий модульный MCP TypeScript SDK и веб-стандартную HTTP-модель Hono, а не собственный серверный фреймворк.

Транспорт stdio по умолчанию предназначен для локальных клиенов, котореые заускают сервер как дочерний процес. Streamable HTTP не сохраняет состояние и создаёт новый экземпляр MCP-сервера для кажого запроса, поэтоме его можно реплицировать без общего хранилища сессий.

Пример выполняется ограниченную работу в памяти. Здесь нет телеметрии, прикладной базы данных, постоянного хранилища, аутентификации или зависимости от внешних сервисов.

Возможности

• Регистрирует инструменты со строгими входными и выходными схемами Zod.

• Возвращает и человекочитаемый контент, и типизированный струкурированный контент.

• Включает корректые аннотации безопасности MCP.

• Поддерживает stdio и Stateless Streamable HTTP.

• Использует Hono с валидацией Host и Origin против DNS rebinding.

• Привязывает HTTP к loopback по умолчанию и требует список разрешённых для других интерфейсов.

• Ограничивает входные данные инструментов и тела HTTP-запросов.

• В режиме stdio сохраняет stdout исключительно для сообщений протокола MCP.

• Обрабатывает SIGINT и SIGTERM с идемпотентным безопасным завершением работы.

• Работает как не-root контейнер с поддержкой read-only-root-filesystem.

• Тестирует конфигурацию, подклчение stdio, поведение MCP, маршруты Hono и реаьный HTTP-трафик.

• Публикует мультиархитектурные образы только после усешного прохождения проверок качестка.

MCP-инструменты

echo

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

Пример ввода:

{
  "message": "Hello, MCP!",
  "metadata": {
    "source": "example-client"
  }
}

Пример струкурированного вывода:

{
  "message": "Hello, MCP!",
  "metadata": {
    "source": "example-client"
  }
}

Сообщения ограничены 10 000 символами. Медаданные принимают не более 20 записей; ключи ограничены 64 симолами, значения — 1 024 симолами.

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

• Node.js 24+

• TypeScript со строгими правилами проека

• Model Context Protocol TypeScript SDK 2

• Hono

• Zod

• Vitest

• pnpm

• Docker

Установка

Предварительные требования

• Node.js 24+ и pnpm 11 для локальной разработки.

• Docker и Docker Compose для развёртывания в контейнере.

Docker Compose

Рекомендованное HTTP-развёртывание использует опубликованный мультиархитектурный образ:

ghcr.io/lukegskw/mcp-typescript-starter:latest

Скачайте пример Compose и укажите hostname, который будут использовать клиенты:

curl -O https://raw.githubusercontent.com/lukegskw/mcp-typescript-starter/main/compose.example.yaml
export MCP_ALLOWED_HOSTS='mcp.example.internal'
docker compose -f compose.example.yaml up -d

Эндпоинты Streamable HTTP и health будут доступны по адресу:

http://<host>:3000/mcp
http://<host>:3000/healthz

Чтобы опубликовать другой порт хоста, задайте MCP_PUBLISHED_PORT. Приложение по-прежнему использует порт 3000 внутри контейнера.

Тег latest сооствутствует последней усешной сборке из ветки по умолчанию. Используйте тег версии или неизменяемый тег sha-* для контролируемого развёртывания и отката.

Docker run

docker run -d \
  --name mcp-typescript-starter \
  --restart unless-stopped \
  --read-only \
  --user 10001:10001 \
  --cap-drop ALL \
  --security-opt no-new-privileges:true \
  --tmpfs /tmp:size=16m,mode=1777 \
  -e MCP_TRANSPORT=streamable-http \
  -e MCP_HOST=0.0.0.0 \
  -e MCP_ALLOWED_HOSTS=127.0.0.1,localhost,mcp.example.internal \
  -p 3000:3000 \
  ghcr.io/lukegskw/mcp-typescript-starter:latest

Сборка контейнера из исходников

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
docker buildx build --load -t mcp-typescript-starter:local .

Локальная установка Node.js

git clone https://github.com/lukegskw/mcp-typescript-starter.git
cd mcp-typescript-starter
pnpm install --frozen-lockfile
pnpm build
pnpm start -- --transport stdio

Для локальной разработки со Streamable HTTP:

MCP_TRANSPORT=streamable-http pnpm dev

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

Параметр командной строки --trаnsport переопределяет MCP_TRANSPORT. MCP_ALLOWED_HOS содежит имеа хостов, а не URL; включите все имеа хостов, которые используют легитимные клиенты и проверки состоня.

В примере конфигурации сервера нет секретов. Добавляйте учётные данные предмедной облати через платформу развёртывания или окружение, но никогда как аргументы MCP-инструментов или в файлах, попадающих в репозиторий.

Настройка MCP-клиента

Для клиента, который принимает определени сервера Streamable HTTP:

mcp_servers:
  starter:
    url: http://127.0.0.1:3000/mcp

Для клиента, который заускает локальный stdio-сервер:

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

Чтобы локальный клиент мог заускать контейнер через stdio, используйте docker run -i --rm и передавайте --transport stdio после имен образ. Параметр -i обязателен, чтобы клиент мог обмениваться MCP-сообщениями через стандатный ввод и вывод.

Форматы конфигурации клиенов различаются. Обратитесь к документации клиента за точной схемой и перезаустите или перезагрузите клиента после изменения определени сервера.

Кастомизация стартеа

Основные точки расширения намеренно просты:

1. Скопируйте или замените src/tools/echo.ts.

2. Определите строгие входные и выходные схемы перед написанием обработчика.

3. Зарегистрируйте инструмент в src/server.ts.

4. Добавьте тесты поведени MCP и любые интеграционные тесты предмедной облати.

5. Замените имя пакета, идентичность сервера, ссылки на образы и содержимое README.

Оставляйте модули инструментов ответственными за свои схемы и обработчики. Держите транспортные модули независимыми от доменных инструментов. Вводите сервисы или постоянное хранилище только тогда, когда этого требует реальное поведение.

Проверка

Запустите полный набор проверок репозитория:

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test:unit
pnpm test:integration
pnpm build

Для изменений контейнера:

docker buildx build --load -t mcp-typescript-starter:test .

Наконец, подключите MCP-клиент и убедитесь, что echo отображается в списке и возвращает и текст, и структурированный контент. В HTTP-режиме убедитесь, что /healthz возвращает {"status":"ok"}.

Ограничения

• Пример предоставляет один инструмент и не содежит ресурсов или промптов.

• Streamable HTTP не имеет аутентификации. Ограничьте его loopback-интерфейсом, доверенной локальной сетью, VPN, частной контейнерной сетью или аутентифицирующим обратным прокси.

• Списки разрешённых Hos и Origin предотвращают определённые классы атак DNS rebinding, но не аутентифицируют вызывающих.

• HTTP-сервер не сохраняет состояние и не содежит общего постоянного хранилища или распределённой координации.

• Ограничение частоты запросов, трассировка, метрики и доменное логирование не включены.

• Репозиторий — это стартер из исходного кода, а не опубликованная npm-библиотека.

Изучите SECURITY.md прежде чем открывать HTTP-транспорт или сообщать о проблеме безопасности.

Вклад в проект

Вклад привествуется. Перед открытием pull request:

pnpm install --frozen-lockfile
pnpm format:check
pnpm lint
pnpm typecheck
pnpm test
pnpm build
docker buildx build --load -t mcp-typescript-starter:test .

Изменени должны сохранть строгую типизацию, ограниченную валидацию, структурированные результаты MCP, чистоту протокола stdout, безопасные HTTP-настройки по умолчанию, детерминированные тесты и докуменатцию для видимого пользователю поведени. Не добавляйте абстракции без конкретного сценари их использоани.

Лицензия

MIT. См. LICENSE.