프로덕션 준비 완료 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`	git 저장소에 pre-commit 훅 설치

개발 서버

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