mishrole/first-mcp-server

Primer Servidor MCP

Este es un servidor MCP simple construido con TypeScript y el SDK de Model Context Protocol (MCP).

MCP (Model Context Protocol) es un protocolo que permite a los modelos de lenguaje interactuar con herramientas externas y servicios web para ampliar sus capacidades, facilitando su integración con APIs, bases de datos y otras herramientas para brindarles contexto y acceso en tiempo real a determinados recursos.

Este ejemplo proporciona datos de pronóstico del tiempo para una ciudad determinada utilizando la API de Open-Meteo.

Pre-requisitos

Este proyecto sólo ha sido probado en Windows 11.

Asegúrate de tener instaladas las siguientes herramientas:

• Node.js (v18.18.0 o superior)
• Pnpm (v9.11.0 o superior)
• Claude Desktop
• Visual Studio Code
• Git

Instalación

1. Clona el repositorio.

git clone https://github.com/mishrole/first-mcp-server.git

2. Ve al directorio del proyecto.

cd first-mcp-server

3. Instala las dependencias.

pnpm install

A medida que avances, recuerda modificar las rutas de los archivos según tu sistema operativo y estructura de carpetas.

Problemas comunes

1. PUERTO DEL INSPECTOR O PROXY MCP EN USO Si ves un error indicando que un puerto MCP ya está en uso, puedes detener los procesos que están usando los puertos del Proxy y del Inspector MCP o cambiar los puertos en la configuración del Inspector MCP.
2. EL INSPECTOR MCP NO SE ABRE Si el Inspector MCP no se abre automáticamente, puedes abrir manualmente tu navegador web y navegar a http://localhost:6274 (o el puerto que hayas configurado) para acceder a la interfaz del Inspector MCP.
3. LA HERRAMIENTA NO APARECE EN CLAUDE DESKTOP Asegúrate de que la configuración en claude_desktop_config.json sea correcta y que hayas reiniciado Claude Desktop después de hacer cambios en la configuración.

Si el problema no se encuentra listado, considera consultar la documentación oficial de MCP para Visual Studio Code o abrir un issue en el repositorio de GitHub, a veces dos cabezas piensan mejor que una. 😸

Cómo usar la herramienta fetch-weather en Claude Desktop

1. Abre Claude Desktop y ve a la configuración (Settings).

2. Ve a la sección "Developer" y haz click en "Edit Configuration".

1. Añade la configuración de la herramienta MCP a tu archivo claude_desktop_config.json. Asegúrate de modificar la ruta de main.ts en los argumentos y añadir la ruta correcta de acuerdo a tu sistema.

Una copia del archivo claude_desktop_config.json se encuentra en la raíz de este repositorio para referencia.

{
  "mcpServers": {
    "fetch-weather": {
      "command": "npx",
      "args": ["-y", "tsx", "C:\\Users\\YOUR_USER\\first-mcp-server\\main.ts"]
    }
  }
}

4. Reinicia Claude Desktop para que los cambios surtan efecto. Esto es esencial para que Claude Desktop reconozca la nueva configuración del servidor MCP, ya que no detecta automáticamente los cambios en el archivo de configuración. Para reiniciar, asegúrate de cerrar completamente el proceso de Claude Desktop y luego vuelve a abrir la aplicación.

5. Abre una nueva conversación en Claude Desktop y asegúrate de que la herramienta "fetch-weather" esté disponible para su uso.

6. Ahora puedes usar la herramienta "fetch-weather" en tus conversaciones con Claude.

Cómo usar la herramienta fetch-weather en Visual Studio Code

1. Asegúrate de tener activadas las opciones de Agente y Discovery habilitadas.

2. Abre el chat y cambia el modo a "Agent".

3. Selecciona "Configure Tools" y verifica que la herramienta "fetch-weather" de Claude y/o la herramienta "fetch-weather-vscode" esté disponible para su uso.

La configuración de la herramienta "fetch-weather-vscode" se encuentra en el archivo .vscode/mcp.json en la raíz del proyecto.

Asegúrate de modificar la ruta de main.ts en los argumentos y añadir la ruta correcta de acuerdo a tu sistema.

{
  "servers": {
    "fetch-weather-vscode": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "tsx", "C:\\Users\\YOUR_USER\\first-mcp-server\\main.ts"]
    }
  },
  "inputs": []
}

La herramienta "fetch-weather-vscode" sólo está disponible para este Workspace. Nos servirá en caso el Discovery no encuentre la versión configurada en el archivo de Claude. También es posible configurarlo de manera global para usarlo en otros proyectos. Para más información, consulta la documentación oficial de MCP para Visual Studio Code.

4. Ahora puedes usar la herramienta "fetch-weather" en tus conversaciones desde el Chat de Visual Studio Code. Por ejemplo puedes preguntar: ¿Cuál es el tiempo en Lima?

5. Después de correr la herramienta, verás los datos del pronóstico del tiempo en el chat.

Cómo usar MCP Inspector para validar respuestas del servidor MCP

1. Ejecuta el Inspector MCP.

pnpm start

2. El Inspector MCP se abrirá en tu navegador web predeterminado. Puedes interactuar con el servidor a través de la interfaz del Inspector MCP.

3. Ve al Inspector MCP en tu navegador web y haz clic en el botón "Connect".

4. Selecciona el botón "List Tools" para ver las herramientas disponibles.

5. Selecciona la herramienta "fetch-weather".

6. Ingresa el nombre de la ciudad para la cual quieres obtener el pronóstico del tiempo.

7. Haz clic en el botón "Run Tool". Los datos del pronóstico del tiempo se mostrarán en el Inspector MCP.

Pruebas

Este proyecto utiliza Vitest para las pruebas. Para ejecutar los tests, usa el siguiente comando:

pnpm test