MCP TypeScript Starter

MCP TypeScript Starter es una base orientada a producción para crear un servidor de Model Context Protocol con TypeScript. Incluye una herramienta de ejemplo tipada, transportes stdio y Streamable HTTP, validación estricta, pruebas, un contenedor endurecido y publicación automatizada en GHCR.

Clónalo, sustituye el dominio de ejemplo y conserva la infraestructura que los servidores MCP reales necesitan.

Navegación

• Usar esta plantilla inicial

• Acerca de

• Características

• Herramientas MCP

• Pila tecnológica

• Instalación

• Configuración

• Configuración del cliente MCP

• Personalizar la plantilla inicial

• Verificación

• Limitaciones

• Contribuciones

• Licencia

Related MCP server: mcp-server-http-streamable

Usar esta plantilla inicial

Haz clic en Usar esta plantilla en GitHub para crear un nuevo servidor MCP con un historial de Git independiente. Después de crearlo, sustituye la herramienta de ejemplo y actualiza la identidad del proyecto siguiendo Personalizar la plantilla inicial.

Haz un fork de este repositorio si quieres aportar mejoras mediante una pull request. Consulta Contribuciones antes de enviar cambios.

Si esta plantilla inicial te ha resultado útil, considera darle una estrella al repositorio. Así ayudas a que otros desarrolladores de TypeScript descubran el proyecto.

Acerca de

La plantilla inicial demuestra el recorrido completo desde una definición validada de herramienta MCP hasta un resultado estructurado visible para el cliente. El servidor utiliza el actual MCP TypeScript SDK modular y el modelo HTTP estándar web de Hono en lugar de un framework de servidor personalizado.

El transporte stdio predeterminado está pensado para clientes locales que inician el servidor como un proceso hijo. Streamable HTTP no tiene estado y crea un nuevo servidor MCP para cada solicitud, por lo que puede replicarse sin almacenamiento de sesión compartido.

El ejemplo realiza un trabajo acotado en memoria. No hay telemetría, base de datos de aplicación, almacenamiento persistente, autenticación ni dependencia de servicios externos.

Características

• Registra herramientas con esquemas estrictos de entrada y salida en Zod.

• Devuelve tanto contenido legible por humanos como contenido estructurado tipado.

• Incluye anotaciones de seguridad MCP precisas.

• Admite stdio y Streamable HTTP sin estado.

• Usa Hono con validación de Host y Origin contra el rebinding de DNS.

• Vincula HTTP al loopback por defecto y exige una lista de permitidos para otras interfaces.

• Limita las entradas de las herramientas y los cuerpos de las solicitudes HTTP.

• Mantiene stdout exclusivamente para los mensajes del protocolo MCP en modo stdio.

• Gestiona SIGINT y SIGTERM con un apagado elegante idempotente.

• Se ejecuta como un contenedor no root con soporte para un sistema de archivos raíz de solo lectura.

• Prueba la configuración, el cableado de stdio, el comportamiento de MCP, las rutas de Hono y el tráfico HTTP real.

• Publica imágenes multiarquitectura solo después de que pasen las comprobaciones de calidad.

Herramientas MCP

echo

Devuelve un mensaje validado y metadatos de cadena opcionales. Es deliberadamente simple para que el repositorio enseñe esquemas, registro, anotaciones y resultados de MCP sin inventar un dominio de negocio.

Ejemplo de entrada:

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

Ejemplo de salida estructurada:

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

Los mensajes están limitados a 10 000 caracteres. Los metadatos aceptan como máximo 20 entradas; las claves están limitadas a 64 caracteres y los valores a 1 024 caracteres.

Pila tecnológica

• Node.js 24+

• TypeScript con reglas de proyecto estrictas

• Model Context Protocol TypeScript SDK 2

• Hono

• Zod

• Vitest

• pnpm

• Docker

Instalación

Requisitos previos

• Node.js 24+ y pnpm 11 para el desarrollo local.

• Docker y Docker Compose para el despliegue en contenedores.

Docker Compose

El despliegue HTTP recomendado utiliza la imagen multiarquitectura publicada:

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

Descarga el ejemplo de Compose y proporciona el nombre de host que usarán los clientes:

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

Los endpoints de Streamable HTTP y de salud estarán disponibles en:

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

Para publicar un puerto de host diferente, establece MCP_PUBLISHED_PORT. La aplicación sigue usando el puerto 3000 dentro del contenedor.

La etiqueta latest sigue la compilación exitosa más reciente de la rama predeterminada. Usa una etiqueta de versión o una etiqueta inmutable sha-* para un despliegue y una reversión controlados.

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

Compilar el contenedor desde el código fuente

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

Instalación local de 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

Para el desarrollo local con Streamable HTTP:

MCP_TRANSPORT=streamable-http pnpm dev

Configuración

La opción de línea de comandos --transport anula MCP_TRANSPORT. MCP_ALLOWED_HOSTS contiene nombres de host, no URLs; incluye todos los nombres de host que usen los clientes legítimos y las comprobaciones de salud.

El servidor no tiene secretos en su configuración de ejemplo. Añade las credenciales del dominio a través de la plataforma de despliegue o del entorno, nunca como argumentos de herramientas MCP ni en archivos confirmados.

Configuración del cliente MCP

Para un cliente que acepte definiciones de servidor Streamable HTTP:

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

Para un cliente que inicie un servidor stdio local:

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

Para permitir que un cliente local inicie el contenedor a través de stdio, usa docker run -i --rm y pasa --transport stdio después del nombre de la imagen. -i es necesario para que el cliente pueda intercambiar mensajes MCP a través de la entrada y salida estándar.

Los formatos de configuración de los clientes difieren. Consulta la documentación del cliente para conocer su esquema exacto y reinicia o recarga el cliente después de cambiar la definición de su servidor.

Personalizar la plantilla inicial

Los principales puntos de extensión son deliberadamente directos:

1. Copia o sustituye src/tools/echo.ts.

2. Define esquemas estrictos de entrada y salida antes de escribir el controlador.

3. Registra la herramienta en src/server.ts.

4. Añade pruebas de comportamiento de MCP y cualquier prueba de integración del dominio.

5. Sustituye el nombre del paquete, la identidad del servidor, las referencias a la imagen y el contenido del README.

Mantén los módulos de herramientas responsables de sus propios esquemas y controladores. Mantén los módulos de transporte independientes de las herramientas de dominio. Introduce servicios o persistencia solo cuando el comportamiento real lo requiera.

Verificación

Ejecuta la suite completa del repositorio:

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

Para cambios en el contenedor:

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

Por último, conecta un cliente MCP y confirma que echo aparece listado y devuelve tanto texto como contenido estructurado. En modo HTTP, confirma que /healthz devuelve {"status":"ok"}.

Limitaciones

• El ejemplo expone una herramienta y ningún recurso o prompt.

• Streamable HTTP no tiene autenticación. Limítalo a loopback, una LAN de confianza, una VPN, una red privada de contenedores o un proxy inverso autenticado.

• Las listas de permitidos de Host y Origin previenen clases de ataques de rebinding de DNS, pero no autentican a los llamantes.

• El servidor HTTP no tiene estado y no contiene persistencia compartida ni coordinación distribuida.

• No se incluyen limitación de tasa, trazado, métricas ni registro específico del dominio.

• El repositorio es una plantilla inicial de código fuente, no una librería npm publicada.

Revisa SECURITY.md antes de exponer el transporte HTTP o de informar de un problema de seguridad.

Contribuciones

Las contribuciones son bienvenidas. Antes de abrir una 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 .

Los cambios deben preservar el tipado estricto, la validación acotada, los resultados estructurados de MCP, la pureza del protocolo en stdout, los valores predeterminados seguros de HTTP, las pruebas deterministas y la documentación del comportamiento visible para el usuario. No añadas abstracciones sin un caso de uso concreto para ellas.

Licencia

MIT. Consulta LICENSE.