Boilerplate de MCP listo para producción

Servidor MCP de itinerario de IA para Cox's Bazar

Un servidor del Protocolo de Contexto de Modelo (MCP) que proporciona herramientas de planificación de viajes e información meteorológica para Cox's Bazar, Bangladés. Construido con FastMCP y gestionado por uv.

Características

Recursos meteorológicos: Pronósticos de temperatura e información meteorológica detallada
Herramientas de itinerario: Generación de itinerarios de viaje mediante IA
Prompts de viaje: Prompts preconfigurados para la planificación de viajes
Soporte de autenticación: Autenticación opcional a través de Clerk (configurable mediante variables de entorno)
Limitación de tasa: Middleware de limitación de tasa integrado
Listo para Docker: Dockerfile de producción incluido
Linting y formato: Ruff + hooks de pre-commit (ver _docs/lint-formatting.md)

Requisitos

Python 3.13+
uv (gestor de paquetes)
Node.js 20+ (solo para el Inspector MCP)

Primeros pasos

# Install dependencies
uv sync

# Copy environment variables and configure
cp .env.example .env

# (Optional) Install pre-commit git hooks
uv run pre-commit-install

Comandos de la CLI

Todos los comandos están registrados en pyproject.toml y disponibles a través de uv run:

Comando	Descripción
`uv run mcp-server`	Iniciar el servidor MCP
`uv run mcp-server-dev`	Iniciar el servidor MCP en modo desarrollo (recarga automática)
`uv run mcp-inspector`	Iniciar la interfaz de usuario del Inspector MCP (requiere Node.js 20+)
`uv run lint`	Ejecutar hooks de pre-commit (lint + formato) en todos los archivos
`uv run pre-commit-install`	Instalar hooks de pre-commit en el repositorio git

Servidor de desarrollo

Inicie el servidor MCP con recarga automática a través de watchdog:

uv run mcp-server-dev
# or
./scripts/run-mcp-server.sh

Inspector MCP

Inicie la interfaz de usuario interactiva del Inspector MCP para probar herramientas, recursos y prompts:

uv run mcp-inspector
# or
./scripts/run-inspector.sh

Linting y formato

# Run lint + format via pre-commit
uv run lint

# Or run individually
./scripts/lint.sh       # ruff check . --fix
./scripts/format.sh     # ruff format .

Consulte _docs/lint-formatting.md para obtener detalles completos de configuración.

Pruebas

./scripts/test.sh

Consulte _docs/testing.md para conocer las convenciones y fixtures de prueba.

Docker

docker build -t mcp-server .
docker run mcp-server

El servidor se ejecuta mediante uv run mcp-server dentro del contenedor. El transporte y el puerto son configurables a través de variables de entorno (TRANSPORT_NAME, SERVER_PORT, SERVER_HOST).

Estructura del proyecto

.
├── src/mcp_server/
│   ├── server.py                  # Main server entry point
│   ├── mcp_instance.py            # FastMCP instance & auth config
│   ├── cli.py                     # CLI command definitions
│   ├── config/
│   │   ├── auth_provider.py       # Auth provider factory
│   │   └── custom_routes.py       # Custom HTTP routes
│   ├── handlers/                  # MCP handler registrations (auto-discovered)
│   │   ├── tools/
│   │   │   ├── auth_additional.py
│   │   │   └── itinerary.py
│   │   ├── resources/
│   │   │   └── weather.py
│   │   └── prompts/
│   │       └── travel_prompts.py
│   ├── models/
│   │   └── itinerary_models.py    # Pydantic models & schemas
│   ├── services/
│   │   └── itenerary_service.py   # Business logic
│   ├── lib/
│   │   ├── clerk_auth_provider.py # Clerk OAuth provider
│   │   └── httpx_client.py        # Async HTTP client wrapper
│   ├── prompt_templates/
│   │   └── travel.py              # Prompt text builders
│   └── utils/
│       ├── elicitation.py
│       ├── get_weather_forecast.py
│       ├── helpers.py
│       └── http.py
├── tests/
│   ├── conftest.py
│   ├── fixtures/
│   │   ├── context.py
│   │   └── weather.py
│   ├── unit/
│   │   ├── test_auth_additional_tools.py
│   │   ├── test_auth_provider.py
│   │   ├── test_elicitation.py
│   │   ├── test_helpers.py
│   │   ├── test_itinerary_service_extra.py
│   │   ├── test_itinerary_tool_handler.py
│   │   ├── test_models.py
│   │   ├── test_server.py
│   │   ├── test_travel_prompts.py
│   │   ├── test_travel_prompts_handler.py
│   │   ├── test_weather_forecast.py
│   │   └── test_weather_resource.py
│   └── integration/
│       ├── test_itinerary_tool.py
│       └── test_weather_api.py
├── scripts/
│   ├── run-mcp-server.sh          # Dev server with auto-reload
│   ├── run-inspector.sh           # MCP Inspector launcher
│   ├── test.sh                    # Test runner
│   ├── lint.sh                    # Ruff lint --fix
│   ├── format.sh                  # Ruff format
│   └── generate-secrets.sh        # Secret key generator
├── _docs/                         # Documentation & ADRs
│   ├── adr/
│   │   ├── 001-choose-fastmcp.md
│   │   ├── 002-choose-httpx.md
│   │   └── ADR-template.md
│   ├── auth-provider-auth0.md
│   ├── httpx-client.md
│   ├── lint-formatting.md
│   ├── remote-mcp-connect.md
│   └── testing.md
├── .env.example                   # Environment variables template
├── .pre-commit-config.yaml        # Pre-commit hook config
├── Dockerfile                     # Production Docker image
├── pyproject.toml                 # Project config & dependencies
├── ruff.toml                      # Ruff linter/formatter config
├── pytest.ini                     # Pytest configuration
├── glama.json                     # Glama registry config
└── LICENSE                        # MIT License

Documentación

Documento	Descripción
`_docs/lint-formatting.md`	Configuración de Ruff y pre-commit
`_docs/testing.md`	Configuración de pruebas, fixtures y convenciones
`_docs/httpx-client.md`	Uso del cliente HTTP asíncrono
`_docs/auth-provider-auth0.md`	Integración del proveedor de autenticación
`_docs/remote-mcp-connect.md`	Guía de conexión remota MCP
`_docs/adr/`	Registros de decisiones de arquitectura

Licencia

MIT

Cox's Bazar AI Itinerary MCP Server