AI导哈

MCP模板服务器

MCP模板服务器是一个用于管理和配置MCP（Model Context Protocol）服务的工具，支持多种传输协议和日志配置。

  • by Elolawyn
  • Python
  • 本地部署
  • 更新于
在 GitHub 查看 Elolawyn/mcp-template

使用说明

mcp-template

Plantilla para MCPs.

Changelog

Para ver la lista de cambios, acceder a CHANGELOG.md.

Instalación

# Rama main
uv tool install git+https://github.com/Elolawyn/mcp-template

# Otra rama
uv tool install git+https://github.com/Elolawyn/mcp-template@rama

Ejecución

MCP_LOG_MODE="console"
MCP_LOG_LEVEL="debug"
mcp-template-server --transport streamable-http --host 127.0.0.1 --port 8000

Desinstalación

uv tool uninstall mcp-template

Conexión con el servidor MCP

Configuración JSON de Claude (apuntando a proyecto local con STDIO)

Hay que modificar el fichero ~/.config/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "server_name": {
      "command": "uv",
      "args": [
        "--directory",
        "/home/username/code/mcp-template",
        "run",
        "mcp-template-server"
      ],
      "transport": "stdio",
      "env": {
        "MCP_LOG_MODE": "both",
        "MCP_LOG_LEVEL": "debug",
        "MCP_LOG_PATH": "/home/username/code/proyecto/logs/mcp-template.log"
      }
    }
  }
}

Configuración JSON de Windsurf (apuntando a proyecto local con streamable-http)

{
  "mcpServers": {
    "mcpTemplate": {
      "serverUrl": "http://localhost:puerto/mcp"
    }
  }
}

Fichero JSON de cliente de langchain-mcp-adapters (ejecutando con STDIO una rama de github)

langchain-mcp-adapters.

{
  "server_name": {
    "command": "uvx",
    "args": [
      "--from",
      "git+https://github.com/Elolawyn/mcp-template@rama",
      "mcp-template-server"
    ],
    "transport": "stdio",
    "env": {
      "MCP_LOG_MODE": "both",
      "MCP_LOG_LEVEL": "debug",
      "MCP_LOG_PATH": "/home/username/code/proyecto/logs/mcp-template.log"
    }
  }
}

Hay que mejorar esta forma de hacerlo, no debe ir el token de github tal cual es el fichero de configuración. Se debería insertar a posteriori.

Fichero JSON de cliente de langchain-mcp-adapters (apuntando a proyecto local con STDIO)

langchain-mcp-adapters.

{
  "server_name": {
    "command": "uv",
    "args": [
      "--directory",
      "/home/username/code/mcp-template",
      "run",
      "mcp-template-server"
    ],
    "transport": "stdio",
    "env": {
      "MCP_LOG_MODE": "both",
      "MCP_LOG_LEVEL": "debug",
      "MCP_LOG_PATH": "/home/username/code/proyecto/logs/mcp-template.log"
    }
  }
}

En este caso, el cliente es el que ejecuta el servidor MCP como un subproceso y se le pueden indicar variables de entorno. Al detener el cliente, se detiene el subproceso del servidor MCP.

Fichero JSON de cliente de langchain-mcp-adapters (apuntando a proyecto local con streamable-http)

langchain-mcp-adapters.

{
  "server_name": {
    "url": "http://localhost:puerto/mcp",
    "transport": "streamable_http"
  }
}

En este caso, se debe ejecutar el servidor MCP antes en otra consola y se le pueden indicar variables de entorno al lanzarlo en ese momento. Para cerrar con éxito los servidores, primero se debe cerrar el cliente, y el servidor MCP después.

Fichero JSON de cliente de langchain-mcp-adapters (apuntando a proyecto local con SSE)

langchain-mcp-adapters.

{
  "server_name": {
    "url": "http://localhost:puerto/sse",
    "transport": "sse"
  }
}

En este caso, se debe ejecutar el servidor MCP antes en otra consola y se le pueden indicar variables de entorno al lanzarlo en ese momento. Para cerrar con éxito los servidores, primero se debe cerrar el cliente, y el servidor MCP después.

Documentación

Variables de entorno

  • MCP_LOG_MODE: Modo de logging. Puede ser both, console, file o none. Por defecto es both.
  • MCP_LOG_LEVEL: Nivel de logging. Puede ser debug, info, warning, error o critical. Por defecto es debug.
  • MCP_LOG_PATH: Ruta del archivo de logging. Por defecto es workingdir/logs/mcp.log.
  • MCP_MAX_REQUESTS_PER_SECOND: Máximo de peticiones por segundo. Por defecto es 50.

Configurar componentes

Por defecto se registran para ser accesibles todos los prompts, resources y tools (enabled = True) de forma recursiva en sus correspondientes carpetas. Se pueden dejar de registrar si tienen asignado los tags internal o deprecated o se indica enabled = False. Por defecto se cachean todas las peticiones a prompts, resources y tools pero se pueden excluir las tools que tienen el tag nocache.

Middlewares

El orden de ejecución de los middlewares importa.

  • ErrorHandlingMiddleware: Gestión de errores. Loggea errores con traza.
  • RateLimitingMiddleware: Limitación de peticiones. Utiliza la variable de entorno MCP_MAX_REQUESTS_PER_SECOND. Limita el máximo de peticiones que se pueden recibir.
  • TimingMiddleware: Tiempo total de ejecución de petición.
  • ResponseCachingMiddleware: Cacheo de respuestas. Por defecto, cachea peticiones iguales en memoria a diversos endpoint, como llamadas de tools, listar tools, listar prompts, listar resources, etc... Si logra acceder a la caché, no se ejecutan el resto de middlewares ni la petición real. Las tools con el tag nocache no se cachean.
  • DetailedTimingMiddleware: Tiempo de ejecución por componentes.
  • LoggingMiddleware: Logging.

Dependiendo del proyecto, se pueden añadir middlewares adicionales, personalizar los existentes o eliminarlos.

Ciclo de vida

El ciclo de vida del servidor se gestiona mediante la función lifespan en la que se puede ejecutar código al arrancar y detener el MCP.

Desarrollo

Instalar python (uv)

Revisar repositorio de uv.

uv python install 3.13.7

Instalar nodejs (asdf)

Revisar documentación de asdf.

Clonar repositorio

git clone git@github.com:Elolawyn/mcp-template.git

Git flow

Instalar git-flow.

Instalar dependencias (modo desarrollo)

Ejecutar tarea 📦 Instalar o el comando:

uv sync --extra dev && npm install -g @modelcontextprotocol/inspector

Las dependencias utilizan el operador ~= para especificar una versión segura (se harán actualizaciones menores pero no importantes).

Añadir depedencias de desarrollo

  • Añadir dependencia a pyproject.toml, en la sección [project.optional-dependencies].dev.
  • Ejecutar instalación de dependencias en modo desarrollo.

Añadir depedencias de producción

  • Añadir dependencia a pyproject.toml, en la sección [project].dependencies.
  • Ejecutar instalación de dependencias en modo desarrollo.

Comprobar estilo y tipado

Ejecutar tarea 🔍 Estilo y tipado o el comando:

uv run ruff check src tests && uv run pyright src tests

Comprobar vulnerabilidades en paquetes

Ejecutar tarea 🕵️‍♂️ Audit o el comando:

uv run pip-audit --skip-editable

Ejecutar tests

Ejecutar tarea 🧪 Tests o el comando:

uv run pytest

Comprobar cobertura del código

Ejecutar tarea 📊 Cobertura o el comando:

cmd /c start ${workspaceFolder}\\htmlcov\\index.html # Windows
firefox ${workspaceFolder}/htmlcov/index.html # Linux
open ${workspaceFolder}/htmlcov/index.html # MacOS

Lanzar el servidor en modo streamable-http

Ejecutar tarea ▶️ streamable-http o el comando:

uv run python -m src.mcp_template.server --transport streamable-http --host 127.0.0.1 --port 8000

Dentro del inspector de MCP, hay que seleccionar Streamable HTTP como capa de transporte y apuntar a http://127.0.0.1:8000/mcp.

Lanzar el servidor en modo sse (legacy)

Ejecutar tarea ▶️ sse o el comando:

uv run python -m src.mcp_template.server --transport sse --host 127.0.0.1 --port 8000

Dentro del inspector de MCP, hay que seleccionar SSE como capa de transporte y apuntar a http://127.0.0.1:8000/sse.

Esto es por compatibilidad, siempre se recomienda usar streamable-http.

Lanzar el inspector de MCP

Ejecutar tarea 🔍 Inspector MCP o el comando:

npx @modelcontextprotocol/inspector

Se recomienda lanzar el MCP como streamable-http para inspeccionarlo con el inspector.

相关 MCP