Loads environment variables from .env files for server configuration, enabling customization of transport types, HTTP settings, authentication, and logging options.
Provides HTTP request utilities through the 'serviceRequest' function in httpUtils.ts, supporting authenticated API requests with OAuth2 or API key authentication, retries, and response validation.
Implements the HTTP transport layer using Express to handle POST requests to the /mcp endpoint, process JSON-RPC messages, and support stateless request handling.
Bienvenido a MCP-SERVER-TEMPLATE , un proyecto de plantilla para implementar un servidor de Protocolo de Contexto de Modelo (MCP) con el SDK oficial de TypeScript. Este proyecto proporciona una base para crear servidores MCP con y sin estado, compatibles con diferentes mecanismos de transporte como HTTP y E/S estándar (stdio).
Este proyecto, MCP-SERVER-TEMPLATE , es una plantilla de inicio basada en TypeScript para crear servidores MCP (Protocolo de Contexto de Modelo) con el SDK oficial. El servidor actúa como interfaz entre las consultas del usuario y la ejecución de la herramienta, permitiendo que los asistentes de IA y los sistemas externos invoquen herramientas dinámicamente, interpreten indicaciones y gestionen recursos de forma modular y extensible.
execute para manejar la lógica empresarial.env y de tiempo de ejecución para:Esta plantilla es ideal para:
Ya sea que esté creando un prototipo de una cadena de herramientas LLM, integrándola con sistemas propietarios o preparando un backend asistente MCP de producción escalable, este proyecto ofrece una solución lista para extender y completamente estructurada.
@modelcontextprotocol/sdk , express , axios ) como las dependencias de desarrollo (por ejemplo, typescript , ts-node , jest ) como se define en package.json .@modelcontextprotocol/sdk (versión ^1.10.1 ) esté instalado, ya que es la dependencia principal para la funcionalidad de MCP.El proyecto utiliza un sistema de configuración gestionado mediante variables de entorno y dos archivos clave en src/core/config/ . La configuración se define en ConfigService y runtimeConfig , lo que permite personalizar los tipos de transporte, el registro y las integraciones con API externas.
dotenv en runtimeConfig.ts ):TRANSPORT_TYPE : Establece el mecanismo de transporte ( 'http' o 'stdio' , predeterminado: 'stdio' ).HTTP_PORT : Puerto para el servidor HTTP (predeterminado: 3000 ).HTTP_HOST : Host para el servidor HTTP (predeterminado: localhost ).SESSION_SUPPORT : habilita o deshabilita el soporte de sesión (valor predeterminado: 'true' ).LOG_LEVEL : Nivel de registro (por ejemplo, 'info' , 'debug' , predeterminado: 'info' ).MCP_INSPECTOR_PORT : Puerto para el inspector MCP (predeterminado: 6274 ).Establecer variables de entorno en un archivo .env :
El servidor se inicia a través del punto de entrada src/index.ts , que orquesta el proceso de inicialización y arranque mediante inyección de dependencia y configuraciones.
index.ts carga variables de entorno utilizando dotenv para garantizar que las configuraciones (por ejemplo, TRANSPORT_TYPE , HTTP_PORT ) estén disponibles.createDependencies para configurar dependencias compartidas como el registrador y ConfigService .HttpTransport o StdioTransport ) se configura a través de runtimeConfig en función de la configuración TRANSPORT_TYPE .MCPServer con el transporte y las dependencias configuradas.tsc para generar la carpeta dist/ con archivos JavaScript compilados.node dist/index.js para ejecutar el servidor compilado.http , el servidor escucha en http://localhost:3000/mcp (puerto y host configurables a través de HTTP_PORT y HTTP_HOST ).stdio , el servidor lee y escribe en la consola.ts-node :ts-node src/index.ts , lo que permite una iteración más rápida sin un paso de compilación.runtimeConfig estén configuradas correctamente antes de iniciar el servidor.LOG_LEVEL ) para verificar que el servidor se inició correctamente.El proyecto incluye varios scripts para probar el servidor, depurar su comportamiento y verificar la funcionalidad mediante pruebas automatizadas y el Inspector MCP.
Ejecute pruebas unitarias usando Jest para verificar la funcionalidad de componentes individuales:
Esto ejecuta jest y ejecuta todas las pruebas definidas en el proyecto (p. ej., herramientas de prueba, utilidades o lógica del servidor). Asegúrate de que los archivos de prueba estén configurados con Jest y ts-jest para compatibilidad con TypeScript.
Se proporciona un script de prueba para el transporte HTTP para verificar la funcionalidad básica del servidor MCP.
src/scripts/testHttpTransport.js )tools/list JSON-RPC al servidor y validando la respuesta.axios para enviar solicitudes HTTP POST al servidor.http://localhost:3000/mcp con method: 'tools/list' , id: 1 y los encabezados apropiados.jsonrpc: '2.0' ).id de respuesta coincide con la solicitud ( id: 1 ).result con la clave tools esperada.TRANSPORT_TYPE configurado en 'http' :ts-node src/scripts/testHttpTransport.ts .Para iniciar el servidor y ejecutar la prueba HTTP en un solo comando:
Esto ejecuta npm run start & npm run test:http , iniciando el servidor en segundo plano y ejecutando inmediatamente el script de prueba HTTP.
http://localhost:3000/mcp . Ajuste el endpoint en el script si HTTP_PORT o HTTP_HOST son diferentes.CalculatorTool estén registradas para verlas en la respuesta de tools/list .El Inspector MCP es una herramienta poderosa para depurar y monitorear el servidor MCP, proporcionando una interfaz web para inspeccionar el estado y las interacciones del servidor.
src/scripts/mcpInspectorScript.ts )child_process para generar el proceso mcp-inspector y ejecutar comandos de apertura del navegador.axios para comprobar si se puede acceder a la interfaz web de MCP Inspector.createDependencies() para acceder a ConfigService para la configuración del puerto.mcp-inspector usando npx mcp-inspector node dist/index.js y heredando stdio para la salida de la consola.waitUntilInspectorIsReady para sondear la interfaz de usuario web (puerto predeterminado: 6274 , configurable a través de MCP_INSPECTOR_PORT ) con reintentos (20 intentos, retraso de 500 ms).openstartxdg-openhttp://localhost:6274 (o puerto configurado)http://localhost:6277npm run build para generar dist/index.js ).ts-node src/scripts/start-mcp-inspector.ts .Para construir el proyecto y ejecutar el Inspector MCP en un solo comando:
Esto ejecuta npm run build && npm run mcp:inspector , lo que garantiza que el proyecto esté compilado antes de iniciar el inspector.
MCP_INSPECTOR_PORT no esté siendo utilizado por otro servicio.El proyecto utiliza Prettier para mantener un formato de código consistente en todos los archivos.
Para formatear todos los archivos del proyecto:
Esto ejecuta prettier --write . , formateando automáticamente todos los archivos compatibles (por ejemplo, .ts , .js , .json ).
Para comprobar si todos los archivos cumplen las reglas de formato de Prettier:
Esto ejecuta prettier --check . , informando cualquier archivo que no se ajuste a las reglas de formato sin modificarlos.
src/core/config/configService.ts : Implementa ConfigService , una clase para administrar la configuración del servidor. Carga la configuración de las variables de entorno con valores predeterminados para el tipo de transporte, la configuración del servidor HTTP, el nivel de registro, las URL de la API (p. ej., MealDB), las credenciales de autenticación y el puerto del inspector de MCP.runtimeConfig.ts : Define la configuración del entorno de ejecución mediante dotenv para cargar las variables de entorno. Establece la configuración de transporte ( transportType , puerto) y la estrategia de autenticación ( authStrategy , tokenSecret , username , password ).src/core/dependencies/dependencies.ts : Implementa la inyección de dependencias con la interfaz Dependencies , proporcionando un logger (mediante Winston) y una instancia ConfigService . La función createDependencies configura dinámicamente los transportes de registro según transportType (stderr para stdio , stdout para otros, además de un archivo de registro combined.log ) y exporta un logger singleton para uso global.src/core/server/transports/http/server.ts : Implementa HttpTransport , un transporte HTTP sin estado que utiliza Express. Gestiona solicitudes POST /mcp , procesa mensajes JSON-RPC con autenticación opcional mediante token de portador, almacena las respuestas en un ResponseMap y admite el envío asíncrono de respuestas. Se basa en Dependencies inyectadas para el registro y la configuración.stdio/server.ts : Implementa StdioTransport , un transporte que utiliza StdioServerTransport del SDK. Gestiona la comunicación stdin/stdout, inicia y cierra el transporte, y gestiona el envío de mensajes con registro de errores mediante Dependencies (dependencias) inyectadas en las dependencias.baseTransport.ts : Define la interfaz BaseTransport y la clase abstracta AbstractTransport , extendiendo la interfaz Transport del SDK. Especifica métodos ( start , send , close , isRunning ) y controladores de eventos ( onmessage , onerror , onclose ) para las implementaciones de transporte, proporcionando un contrato común para HttpTransport y StdioTransport .transportFactory.ts : Implementa TransportFactory , una clase estática que crea instancias de HttpTransport o StdioTransport según el tipo de TransportConfig (p. ej., 'http' o 'stdio' ). Utiliza la inyección de dependencias con Dependencies para proporcionar registro y configuración, generando un error para los tipos de transporte no compatibles.mcpServer.ts : Implementa MCPServer , la clase principal del servidor que integra el Server del SDK de MCP con un transporte ( HttpTransport o StdioTransport ). Inicializa el servidor, configura un RequestHandler con un ToolRegistry , conecta el transporte y gestiona el paso de mensajes, errores y respuestas mediante Dependencies inyectadas para el registro.requestHandler.ts : Implementa RequestHandler , que registra los controladores para las solicitudes tools/list y tools/call mediante el SDK de MCP. Enumera las herramientas disponibles y ejecuta llamadas a herramientas con argumentos validados (mediante Zod), admite tokens de autenticación y genera errores para herramientas ( ToolNotFoundError ) o argumentos ( ValidationError ) no válidos. Utiliza Dependencies inyectadas para el registro.src/core/toolManagement/toolFactory.ts : Implementa ToolFactory , una clase que crea instancias de herramientas (p. ej., calculatorTool ) mediante inyección de dependencias con Dependencies . Define un tipo genérico ToolConstructor y gestiona los errores de instanciación mediante registro.toolRegistry.ts : Implementa ToolRegistry , una clase que gestiona el registro y la recuperación de herramientas. Utiliza ToolFactory para instanciar herramientas desde toolClasses , las almacena en un Map y proporciona métodos para registrar, obtener y listar herramientas con sus metadatos (nombre, descripción, esquema de entrada). Registra el estado de carga y los errores mediante Dependencies inyectadas por dependencias.errors.ts : define clases de error personalizadas para la gestión de herramientas, incluyendo ToolNotFoundError (se lanza cuando una herramienta solicitada no está registrada) y ValidationError (se lanza cuando los argumentos de la herramienta no pasan la validación, por ejemplo, a través de Zod).types.ts : Define tipos de TypeScript para configuraciones de transporte y autenticación. Incluye TransportType ( 'stdio' , 'sse' , 'http' ), TransportConfig (con opciones para SSE o HTTP y autenticación), SSETransportConfig (puerto, CORS, autenticación), HttpStreamTransportConfig (puerto, modo de respuesta, CORS, sesión, reanudabilidad, autenticación) y AuthConfig (estrategia, credenciales).src/prompts/ : Directorio para plantillas de indicaciones (actualmente vacío, reservado para una futura implementación).src/resources/ : Directorio para la gestión de recursos (actualmente vacío, reservado para futuras implementaciones).src/scripts/testHttpTransport.js : script de prueba para el transporte HTTP para verificar la funcionalidad básica enviando una solicitud tools/list y validando la respuesta.mcpInspectorScript.ts : Script para iniciar el Inspector MCP, esperar a que su interfaz web esté lista y abrirlo en un navegador para depurar el servidor MCP. Utiliza inyección de dependencias para acceder ConfigService y configurar los puertos, y gestiona la apertura del navegador según la plataforma.src/tools/types/ITool.ts : Define la interfaz ITool para las herramientas, especificando name , description , schema (tipo Zod), jsonSchema y el método execute para procesar CallToolRequest JSON-RPC. Exporta Dependencies para las implementaciones de herramientas.baseTool.ts : implementa una clase BaseTool abstracta que reduce el código repetitivo, maneja la inyección de dependencia con Dependencies y convierte automáticamente los esquemas Zod en esquemas JSON usando zod-to-json-schema para introspección, documentación y generación de UI.index.ts : exporta toolClasses como una matriz de constructores de herramientas (por ejemplo, CalculatorTool ) para carga dinámica por parte de ToolRegistry , lo que permite una fácil extensión con nuevas herramientas.calculatorTool.ts : Implementa CalculatorTool , una herramienta concreta que realiza operaciones aritméticas básicas ( add , subtract , multiply , divide ) con validación de entrada a través de Zod, manejo de errores (por ejemplo, división por cero usando HttpError ) y registro a través de Dependencies inyectadas por dependencia.utils/httpUtils.ts : Proporciona funciones de utilidad para operaciones HTTP, incluyendo serviceRequest para realizar solicitudes HTTP autenticadas (OAuth2 o clave API) con reintentos y gestión de tiempos de espera, getAuthToken para obtener y almacenar en caché tokens OAuth2, buildQueryString para crear cadenas de consulta y validateResponse para la validación de respuestas. Se integra con ConfigService para la configuración.index.ts : Exporta funciones de utilidad para su uso en herramientas y otros componentes.src/index.ts : Punto de entrada para iniciar el servidor MCP. Carga variables de entorno mediante dotenv , inicializa dependencias con createDependencies , crea una instancia MCPServer con el transporte de runtimeConfig e inicia el servidor asincrónicamente, gestionando errores fatales mediante registro y cierre.MCPServer (a través de RequestHandler ).MCPServer con administración de sesiones si es necesario, pero realice pruebas exhaustivas..env o se pasen directamente al proceso.ConfigService para verificar las configuraciones cargadas si fallan las integraciones de API externas (por ejemplo, MealDB, OMDB).LOG_LEVEL coincida con los niveles esperados (por ejemplo, 'info' , 'debug' ).stdio , asegúrese de que los registros se dirijan a stderr según lo previsto; verifique combined.log para ver los registros basados en archivos.HttpTransport , asegúrese de que el puerto esté disponible y que no se estén ejecutando servicios conflictivos.StdioTransport , verifique la disponibilidad de stdin/stdout si no se procesan mensajes.TransportFactory falla, verifique que TRANSPORT_TYPE coincida con un tipo admitido ( 'http' o 'stdio' ) en la configuración.tools/list o las solicitudes tools/call fallan, verifique ToolRegistry para ver las herramientas registradas.CallToolRequestSchema para evitar ValidationError .toolClasses en src/tools/index.ts incluya implementaciones de herramientas válidas.ToolFactory para detectar errores de instanciación y asegurarse de que Dependencies se inyecten correctamente.MCP_INSPECTOR_PORT (predeterminado: 6274 ) no esté en uso.dist/index.js exista ejecutando npm run build antes de iniciar el script.serviceRequest falla, verifique las configuraciones authType , authEndpoint , clientId , clientSecret o apiKey en ConfigService .validateResponse .testHttpTransport.js falla, asegúrese de que el servidor esté ejecutándose con TRANSPORT_TYPE='http' y escuchando en http://localhost:3000/mcp .endpoint del script (ajuste si HTTP_PORT o HTTP_HOST son diferentes).ToolRegistry ; una matriz tools vacía puede indicar un problema de carga de herramientas.npm test falla, asegúrese de que Jest esté configurado correctamente con ts-jest para compatibilidad con TypeScript y verifique que existan los archivos de prueba.npm run mcp:inspector o npm run mcp:dev falla, verifique que @modelcontextprotocol/inspector esté instalado y que el servidor esté compilado ( dist/index.js existe).npm run format:check informa problemas, ejecute npm run format para corregir el formato automáticamente o ajuste manualmente los archivos para que coincidan con las reglas de Prettier.No dudes en enviar incidencias o solicitudes de incorporación de cambios en el repositorio de GitHub. ¡Agradecemos cualquier contribución para mejorar la implementación del servidor, añadir nuevas funciones u optimizar el rendimiento!
Este proyecto está licenciado bajo la licencia ISC. Consulte el archivo LICENSE para más detalles.
@modelcontextprotocol/sdkThis server cannot be installed
Una plantilla de inicio basada en TypeScript para crear servidores de protocolo de contexto de modelo que permite a los asistentes de IA llamar dinámicamente a herramientas, interpretar indicaciones y administrar recursos a través de una arquitectura modular con soporte para múltiples métodos de transporte.