mcp-template
Plantilla para MCPs.
Changelog
Para ver la lista de cambios, acceder a CHANGELOG.md.
Instalación```shell
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```shell
MCP_LOG_MODE="console"
MCP_LOG_LEVEL="debug"
mcp-template-server --transport streamable-http --host 127.0.0.1 --port 8000
Desinstalación```shell
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`:```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)```json
{
"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.```json
{
"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.```json
{
"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.```json
{
"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.```json
{
"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.```shell
uv python install 3.13.7
Instalar nodejs (asdf)
Revisar documentación de asdf.
Clonar repositorio```shell
git clone git@github.com:Elolawyn/mcp-template.git
### Git flow
Instalar git-flow.
### Instalar dependencias (modo desarrollo)
Ejecutar tarea `📦 Instalar` o el comando:```shell
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:```shell
uv run ruff check src tests && uv run pyright src tests
### Comprobar vulnerabilidades en paquetes
Ejecutar tarea `🕵️♂️ Audit` o el comando:```shell
uv run pip-audit --skip-editable
Ejecutar tests
Ejecutar tarea 🧪 Tests o el comando:```shell
uv run pytest
### Comprobar cobertura del código
Ejecutar tarea `📊 Cobertura` o el comando:```shell
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:```shell
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:```shell
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:shell
npx @modelcontextprotocol/inspector
> Se recomienda lanzar el MCP como streamable-http para inspeccionarlo con el inspector.