enriquetecfan11/myfirstmcpserver

My First SSE MCP Server

Servidor de ejemplo basado en Model Context Protocol (MCP) que expone herramientas sobre HTTP + Server-Sent Events (SSE) para interactuar con una API local de usuarios y de estado.

Este repo está pensado como plantilla/boilerplate para crear más MCP servers en Node basados en Express + SSE. La idea es clonar este proyecto, cambiar el nombre y adaptar las tools de ejemplo a tu propio dominio y APIs.

Índice / Table of Contents

• 🇪🇸 Documentación en Español
• 🇬🇧 English Documentation

🇪🇸 Documentación en Español

Descripción

myfirstmcpserver es un servidor MCP que:

• Expone un endpoint SSE (GET /sse) y uno HTTP (POST /messages) usando Express.
• Usa el SDK oficial @modelcontextprotocol/sdk para registrar herramientas MCP.
• Se conecta a una API HTTP externa (por defecto http://localhost:3001) para operaciones de red y de usuarios.

Para más detalle técnico, consulta la spec interna en docs/spec.md.

Características principales

• Transporte SSE: integración basada en SSEServerTransport del SDK MCP.
• Agrupación por dominio:
  • networkTools: herramientas relacionadas con conectividad y estado de una API.
  • userTools: herramientas para listar y crear usuarios vía API externa.
• Diseño extensible: fácil añadir nuevos grupos de tools o nuevas operaciones.

Nota: aunque el nombre del repo haga referencia a STDIO, esta plantilla está basada en Express + SSE, no en STDIO puro.

Cómo usar esta plantilla

1. Clona este repositorio o úsalo como template en GitHub.
2. Cambia el nombre del paquete y la descripción en package.json si lo deseas.
3. Opcionalmente, cambia el name del McpServer en src/config/server.js.
4. Adapta o elimina las tools de ejemplo en:
   • src/tools/networkTools.js
   • src/tools/userTools.js Crea nuevos módulos initializeXTools siguiendo el mismo patrón para tu dominio.
5. Configura la variable de entorno API_BASE_URL para apuntar a tu API real.
6. Ajusta la documentación del README.md y de docs/spec.md para tu nuevo proyecto.

Requisitos

• Node.js ≥ 18 (se usa fetch nativo de Node).
• npm (gestor de paquetes).

Instalación

Desde la raíz del proyecto:

npm install

Ejecución

• Modo desarrollo (con nodemon):

npm run dev

• Modo normal:

npm start

Por defecto el servidor se levanta en http://localhost:3000. El endpoint SSE es:

• GET http://localhost:3000/sse

Y el endpoint de mensajes MCP es:

• POST http://localhost:3000/messages

Uso con un cliente MCP

Este servidor está pensado para ser consumido por un cliente MCP que soporte el transporte SSE definido en el SDK (SSEServerTransport).

De forma general, el cliente debe:

• Abrir una conexión SSE contra GET /sse.
• Enviar peticiones MCP (tools) en formato JSON a POST /messages.

Consulta la documentación del cliente MCP que estés usando para ver cómo configurar un endpoint SSE externo.

Herramientas MCP disponibles

Las tools se registran en la instancia de McpServer y se describen con más detalle en docs/spec.md. Resumen rápido:

• 🔗 Network Tools (src/tools/networkTools.js):
  • ping({ url }): hace un fetch(url) y devuelve el código de estado o un error.
  • apiStatus(): llama a http://localhost:3001/status y devuelve el JSON de estado.
• 👤 User Tools (src/tools/userTools.js):
  • getUsers(): obtiene la lista de usuarios desde http://localhost:3001/users.
  • createUser({ name, email }): crea un usuario nuevo separando nombre y apellidos y haciendo POST a http://localhost:3001/users.

API externa

Este proyecto no incluye la implementación de la API externa en http://localhost:3001, solo la consume. Se espera que exista un servicio con al menos:

• GET /status — Devuelve información de estado.
• GET /users — Devuelve un array de usuarios.
• POST /users — Crea un nuevo usuario con el body JSON adecuado.

Consulta docs/spec.md para ver ejemplos de estructuras de datos.

🇬🇧 English Documentation

Overview

myfirstmcpserver is a Model Context Protocol (MCP) server that:

• Exposes an SSE endpoint (GET /sse) and an HTTP endpoint (POST /messages) using Express.
• Uses the official @modelcontextprotocol/sdk to register MCP tools.
• Connects to an external HTTP API (by default http://localhost:3001) for network and user-related operations.

For a deeper technical description, check the internal spec in docs/spec.md.

Features

• SSE transport using the SDK SSEServerTransport.
• Domain-based tools grouping:
  • networkTools: connectivity and API health checks.
  • userTools: listing and creating users through the external API.
• Extensible design: easy to add new tool groups or operations.

Note: even if the repo name mentions STDIO, this template is built on Express + SSE, not on pure STDIO transport.

How to use this template

1. Clone this repository or use it as a template on GitHub.
2. Update the package name and description in package.json if needed.
3. Optionally change the name of the McpServer in src/config/server.js.
4. Adapt or remove the example tools in:
   • src/tools/networkTools.js
   • src/tools/userTools.js and create new initializeXTools modules following the same pattern.
5. Configure the API_BASE_URL environment variable to point to your real API.
6. Adjust this README.md and docs/spec.md to describe your concrete project.

Requirements

• Node.js ≥ 18 (uses Node’s built-in fetch).
• npm as package manager.

Setup

From the project root:

npm install

Running

• Development mode (with nodemon):

npm run dev

• Normal mode:

npm start

By default the server listens on http://localhost:3000. Main endpoints:

• GET http://localhost:3000/sse — SSE endpoint for MCP.
• POST http://localhost:3000/messages — MCP messages endpoint.

Using it from an MCP client

This server is intended to be used by an MCP client supporting SSE transport as implemented by the SDK.

In general, the client should:

• Open an SSE connection to GET /sse.
• Send MCP tool requests as JSON to POST /messages.

Please refer to your MCP client documentation for the exact configuration format to point it at an external SSE MCP server.

Available MCP tools

Tools are registered on the McpServer instance. See docs/spec.md for full details. Quick summary:

• 🔗 Network Tools (src/tools/networkTools.js):
  • ping({ url }): performs fetch(url) and returns the HTTP status code or an error.
  • apiStatus(): calls http://localhost:3001/status and returns the status JSON.
• 👤 User Tools (src/tools/userTools.js):
  • getUsers(): gets the user list from http://localhost:3001/users.
  • createUser({ name, email }): creates a new user splitting full name into first/last and sending a POST to http://localhost:3001/users.

External API

This project does not include the implementation of the external API at http://localhost:3001; it just consumes it. It expects at least:

• GET /status — Returns general status information.
• GET /users — Returns an array of users.
• POST /users — Creates a new user with the appropriate JSON body.

You can find example payloads in docs/spec.md.

Made by Enrique Rodriguez Vela