Template MCP Server

Una plantilla de línea de comandos para iniciar rápidamente un servidor MCP con FastMCP, compatible con transporte stdio y HTTP.

GitHub
76
Prueba este MCPPatrocinado

Documentación

@mcpdotdirect/template-mcp-server

License: MIT TypeScript

Una herramienta CLI para comenzar rápidamente a crear tu propio servidor MCP (Model Context Protocol) usando FastMCP

📋 Uso

# with npx
npx @mcpdotdirect/create-mcp-server

# Or with npm
npm init @mcpdotdirect/mcp-server

🔭 Qué Incluye

La plantilla incluye:

  • Configuración básica del servidor con opciones de transporte stdio y HTTP usando FastMCP
  • Estructura para definir herramientas, recursos y prompts de MCP
  • Configuración de TypeScript
  • Scripts de desarrollo y configuración

✨ Características

  • FastMCP: Construido con el framework FastMCP para una implementación más sencilla
  • Soporte de Doble Transporte: Ejecuta tu servidor MCP sobre stdio o HTTP
  • TypeScript: Soporte completo de TypeScript para seguridad de tipos
  • Extensible: Fácil de agregar herramientas, recursos y prompts personalizados

🚀 Primeros Pasos

Después de crear tu proyecto:

  1. Instala las dependencias usando tu gestor de paquetes preferido:

    # Using npm
npm install

# Using yarn
yarn

# Using pnpm
pnpm install

# Using bun
bun install

  2. Inicia el servidor:

    # Start the stdio server
npm start

# Or start the HTTP server
npm run start:http

  3. Para desarrollo con recarga automática:

    # Development mode with stdio
npm run dev

# Development mode with HTTP
npm run dev:http

Nota: Los scripts predeterminados en package.json usan Bun como runtime (por ejemplo, bun run src/index.ts). Si prefieres usar un gestor de paquetes o runtime diferente, puedes modificar estos scripts en tu archivo package.json para usar Node.js u otro runtime de tu elección.

📖 Uso Detallado

Métodos de Transporte

El servidor MCP soporta dos métodos de transporte:

  1. Transporte stdio (Modo Línea de Comandos):

    • Se ejecuta en tu máquina local
    • Gestionado automáticamente por Cursor
    • Se comunica directamente vía stdout
    • Solo accesible por ti localmente
    • Ideal para desarrollo personal y herramientas

  2. Transporte SSE (Modo Web HTTP):

    • Puede ejecutarse local o remotamente
    • Gestionado y ejecutado por ti
    • Se comunica a través de la red
    • Puede compartirse entre máquinas
    • Ideal para colaboración en equipo y herramientas compartidas

Ejecutando el Servidor Localmente

Transporte stdio (Modo CLI)

Inicia el servidor en modo stdio para herramientas CLI:

# Start the stdio server
npm start
# or with other package managers
yarn start
pnpm start
bun start

# Start the server in development mode with auto-reload
npm run dev
# or
yarn dev
pnpm dev
bun dev

Transporte HTTP (Modo Web)

Inicia el servidor en modo HTTP para aplicaciones web:

# Start the HTTP server
npm run start:http
# or
yarn start:http
pnpm start:http
bun start:http

# Start the HTTP server in development mode with auto-reload
npm run dev:http
# or
yarn dev:http
pnpm dev:http
bun dev:http

Por defecto, el servidor HTTP se ejecuta en el puerto 3001. Puedes cambiar esto configurando la variable de entorno PORT:

# Start the HTTP server on a custom port
PORT=8080 npm run start:http

Conectándose al Servidor

Conectándose desde Cursor

Para conectar tu servidor MCP desde Cursor:

  1. Abre Cursor y ve a Configuración (icono de engranaje en la esquina inferior izquierda)
  2. Haz clic en "Features" en la barra lateral izquierda
  3. Desplázate hacia abajo hasta la sección "MCP Servers"
  4. Haz clic en "Add new MCP server"
  5. Ingresa los siguientes detalles:
    • Nombre del servidor: my-mcp-server (o cualquier nombre que prefieras)
    • Para modo stdio:
      • Tipo: command
      • Comando: La ruta al ejecutable de tu servidor, por ejemplo, npm start
    • Para modo SSE:
      • Tipo: url
      • URL: http://localhost:3001/sse
  6. Haz clic en "Save"

Usando mcp.json con Cursor

Para una configuración más portable, crea un archivo .cursor/mcp.json en el directorio raíz de tu proyecto:

{
  "mcpServers": {
    "my-mcp-stdio": {
      "command": "npm",
      "args": [
        "start"
      ],
      "env": {
        "NODE_ENV": "development"
      }
    },
    "my-mcp-sse": {
      "url": "http://localhost:3001/sse"
    }
  }
}

También puedes crear una configuración global en ~/.cursor/mcp.json para que tus servidores MCP estén disponibles en todos tus espacios de trabajo de Cursor.

Nota:

  • Las entradas de tipo command ejecutan el servidor en modo stdio
  • La entrada de tipo url se conecta al servidor HTTP usando transporte SSE
  • Puedes proporcionar variables de entorno usando el campo env
  • Al conectarte vía SSE con FastMCP, usa la URL completa incluyendo la ruta /sse: http://localhost:3001/sse

Probando tu Servidor con Herramientas CLI

FastMCP proporciona herramientas integradas para probar tu servidor:

# Test with mcp-cli
npx fastmcp dev server.js

# Inspect with MCP Inspector
npx fastmcp inspect server.ts

Usando Variables de Entorno

Puedes personalizar el servidor usando variables de entorno:

# Change the HTTP port (default is 3001)
PORT=8080 npm run start:http

# Change the host binding (default is 0.0.0.0)
HOST=127.0.0.1 npm run start:http

🛠️ Agregando Herramientas y Recursos Personalizados

Al agregar herramientas, recursos o prompts personalizados a tu servidor FastMCP:

Herramientas

server.addTool({
  name: "hello_world",
  description: "A simple hello world tool",
  parameters: z.object({
    name: z.string().describe("Name to greet")
  }),
  execute: async (params) => {
    return `Hello, ${params.name}!`;
  }
});

Recursos

server.addResourceTemplate({
  uriTemplate: "example://{id}",
  name: "Example Resource",
  mimeType: "text/plain",
  arguments: [
    {
      name: "id",
      description: "Resource ID",
      required: true,
    },
  ],
  async load({ id }) {
    return {
      text: `This is an example resource with ID: ${id}`
    };
  }
});

Prompts

server.addPrompt({
  name: "greeting",
  description: "A simple greeting prompt",
  arguments: [
    {
      name: "name",
      description: "Name to greet",
      required: true,
    },
  ],
  load: async ({ name }) => {
    return `Hello, ${name}! How can I help you today?`;
  }
});

📚 Documentación

Para más información sobre FastMCP, visita Repositorio de GitHub de FastMCP.

Para más información sobre el Model Context Protocol, visita la Documentación de MCP.

📄 Licencia

Este proyecto está licenciado bajo la Licencia MIT - consulta el archivo LICENSE para más detalles.