生产就绪的 MCP 样板

科克斯巴扎尔 AI 行程 MCP 服务器

一个模型上下文协议 (MCP) 服务器，为孟加拉国科克斯巴扎尔提供旅行规划工具和天气信息。基于 FastMCP 构建，并由 uv 管理。

功能特性

天气资源：温度预报和详细的天气信息
行程工具：AI 驱动的旅行行程生成
旅行提示词：用于旅行规划的预配置提示词
身份验证支持：通过 Clerk 进行可选的身份验证（可通过环境变量配置）
速率限制：内置速率限制中间件
Docker 就绪：包含生产环境 Dockerfile
代码检查与格式化：Ruff + pre-commit 钩子（参见 _docs/lint-formatting.md）

要求

Python 3.13+
uv (包管理器)
Node.js 20+ (仅用于 MCP Inspector)

入门指南

# Install dependencies
uv sync

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

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

CLI 命令

所有命令均在 pyproject.toml 中注册，可通过 uv run 使用：

命令	描述
`uv run mcp-server`	启动 MCP 服务器
`uv run mcp-server-dev`	以开发模式启动 MCP 服务器（自动重载）
`uv run mcp-inspector`	启动 MCP Inspector UI（需要 Node.js 20+）
`uv run lint`	在所有文件上运行 pre-commit 钩子（检查 + 格式化）
`uv run pre-commit-install`	将 pre-commit 钩子安装到 git 仓库

开发服务器

通过 watchdog 启动带有自动重载功能的 MCP 服务器：

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

MCP Inspector

启动交互式 MCP Inspector UI 以测试工具、资源和提示词：

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

代码检查与格式化

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

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

有关完整配置详情，请参阅 _docs/lint-formatting.md。

测试

./scripts/test.sh

有关测试约定和固件，请参阅 _docs/testing.md。

Docker

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

服务器通过容器内的 uv run mcp-server 运行。传输方式和端口可通过环境变量（TRANSPORT_NAME, SERVER_PORT, SERVER_HOST）进行配置。

项目结构

.
├── 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

文档

文档	描述
`_docs/lint-formatting.md`	Ruff 和 pre-commit 配置
`_docs/testing.md`	测试设置、固件和约定
`_docs/httpx-client.md`	异步 HTTP 客户端使用
`_docs/auth-provider-auth0.md`	身份验证提供程序集成
`_docs/remote-mcp-connect.md`	远程 MCP 连接指南
`_docs/adr/`	架构决策记录

许可证

MIT

Cox's Bazar AI Itinerary MCP Server