使用说明

Informe Técnico – MCP Calculator Server

1. Introducción

El presente informe técnico documenta el desarrollo del MCP Calculator Server, una API construida con Node.js, TypeScript y Fastify. El objetivo del proyecto es exponer un endpoint que permita realizar operaciones aritméticas básicas con validación estricta de parámetros y documentación automática mediante OpenAPI 3.0.

El sistema fue diseñado siguiendo buenas prácticas de desarrollo backend, con énfasis en validación de datos, manejo de errores y claridad en la documentación técnica.

2. Descripción del Tool

Nombre: calculator Descripción: Realiza operaciones aritméticas básicas (suma, resta, multiplicación y división) con dos números.

Operaciones soportadas

add: Suma
subtract: Resta
multiply: Multiplicación
divide: División

3. Tecnologías utilizadas

Node.js
TypeScript
Fastify
AJV (JSON Schema Validator)
@fastify/swagger
@fastify/swagger-ui

4. Estructura del proyecto

MCP-CALCULATOR-SERVER/
│
├── src/
├   ├──routes/
│   │      └── calculator.routes.ts
│   ├──tools/
│   │      └──calculetor.tools.json
│   └── index.ts
│
├── fotos/
├── node_modules/
├── package.json
├── package-lock.json
├── tsconfig.json
└── README.md

5. Instalación

Ubicar el proyecto en el sistema local.
Abrir una terminal en el directorio raíz del proyecto.
Instalar las dependencias.

npm install

6. Ejecución del servidor

Para iniciar el servidor en modo desarrollo:

npm run dev

El servicio quedará disponible en:

http://localhost:3000

7. Documentación OpenAPI

La documentación OpenAPI 3.0 se genera automáticamente utilizando Swagger y se encuentra disponible en:

http://localhost:3000/docs

Desde esta interfaz se puede consultar la definición del endpoint, los esquemas de entrada y salida, y ejecutar pruebas directamente sobre la API.

(Evidencia: capturas de pantalla almacenadas en la carpeta "fotos")

8. Endpoint implementado

POST /tools/calculator

8.1 Parámetros de entrada

{
  "operation": "add",
  "a": 10,
  "b": 5
}

Validaciones

operation: obligatorio, tipo string, valores permitidos: add, subtract, multiply, divide
a: obligatorio, tipo number
b: obligatorio, tipo number
No se permiten propiedades adicionales

La validación es realizada automáticamente por Fastify mediante JSON Schema.

9. Respuestas

9.1 Respuesta exitosa (200)

{
  "result": 15,
  "operation": "add"
}

9.2 Error por parámetros inválidos (400)

{
  "operation": "power",
  "a": 2,
  "b": 3
}

Respuesta:

{

  "error": "Operacion desconocida",

}

9.3 Error por división entre cero (400)

{
  "operation": "divide",
  "a": 10,
  "b": 0
}

Respuesta:

{
  "error": "División por cero no permitida"
}

9.4 Error interno del servidor (500)

{
  "error": "Error interno del servidor"
}

10. Pruebas realizadas

El endpoint fue probado utilizando herramientas de cliente HTTP como Thunder Client y Postman, verificando casos válidos e inválidos.

Ejemplo de prueba con curl:

curl -X POST http://localhost:3000/tools/calculator \
-H "Content-Type: application/json" \
-d '{"operation":"multiply","a":4,"b":6}'

Operacion Suma:

Operacion Resta:

Operacion Multiplicacion:

Operacion Division:

Operacion Division entre cero (400)

Error por parámetros inválidos (400)

11. Conclusiones

El MCP Calculator Server cumple con los requisitos técnicos establecidos, proporcionando un endpoint funcional con validación automática, manejo adecuado de errores HTTP y documentación clara mediante OpenAPI. El proyecto demuestra una implementación correcta de Fastify con TypeScript y una estructura adecuada para servicios backend.