.PHONY: help setup install install-dev run dev test test-cov lint format clean docker
# ============================================================================
# 預設目標：顯示幫助訊息
# ============================================================================
help:
@echo "════════════════════════════════════════════════════════════"
@echo " MCP-MAF - Microsoft Agent Framework with MCP Protocol"
@echo "════════════════════════════════════════════════════════════"
@echo ""
@echo " Setup & Installation:"
@echo " make setup - 初始環境設置（安裝 uv，建立虛擬環境）"
@echo " make install - 安裝專案依賴"
@echo " make install-dev - 安裝開發依賴（含測試、linting）"
@echo ""
@echo " Development:"
@echo " make dev - 啟動開發伺服器（熱重載）"
@echo " make run - 啟動生產伺服器"
@echo " make run-bg - 背景執行伺服器"
@echo " make stop - 停止背景伺服器"
@echo ""
@echo " Testing & Quality:"
@echo " make test - 執行所有測試"
@echo " make test-cov - 執行測試並生成覆蓋率報告"
@echo " make lint - 執行程式碼檢查（ruff + mypy）"
@echo " make format - 格式化程式碼"
@echo ""
@echo " Examples:"
@echo " make example-standalone - 執行獨立 Agent 範例"
@echo " make example-sse - 執行 SSE 客戶端範例"
@echo ""
@echo " Quick Tool Testing:"
@echo " make demo-tools - 展示所有工具資訊"
@echo " make demo-weather - 快速測試天氣工具"
@echo " make demo-calc - 快速測試計算器工具"
@echo " make demo-stock - 快速測試股票查詢工具"
@echo " make demo-all - 測試所有功能（health + 三個工具）"
@echo ""
@echo " Docker:"
@echo " make docker-build - 建置 Docker 映像"
@echo " make docker-run - 執行 Docker 容器"
@echo " make docker-up - 啟動 Docker Compose"
@echo " make docker-down - 停止 Docker Compose"
@echo ""
@echo " Utilities:"
@echo " make health - 健康檢查"
@echo " make test-sse - 測試 SSE 連接"
@echo " make logs - 查看伺服器日誌"
@echo " make clean - 清理暫存檔案"
@echo ""
@echo " Quick Start:"
@echo " make quickstart - 完整設置並啟動（setup + install + run）"
@echo ""
@echo "════════════════════════════════════════════════════════════"
# ============================================================================
# 環境設置
# ============================================================================
setup:
@echo "📦 Setting up MCP-MAF development environment..."
@echo ""
@# 檢查並安裝 uv
@if ! command -v uv &> /dev/null; then \
echo "🔧 Installing uv..."; \
curl -LsSf https://astral.sh/uv/install.sh | sh; \
echo ""; \
else \
echo "✅ uv already installed"; \
fi
@# 建立虛擬環境
@echo "🐍 Creating virtual environment..."
@uv venv
@echo ""
@echo "✅ Setup complete!"
@echo ""
@echo "💡 Next steps:"
@echo " 1. Activate virtual environment:"
@echo " source .venv/bin/activate"
@echo " 2. Install dependencies:"
@echo " make install"
@echo " 3. Start server:"
@echo " make run"
@echo ""
install:
@echo "📦 Installing MCP-MAF dependencies..."
@uv pip install -e .
@echo "✅ Dependencies installed successfully!"
@echo ""
@echo "💡 To install development dependencies, run: make install-dev"
@echo ""
install-dev: install
@echo "📦 Installing development dependencies..."
@uv pip install -e ".[dev]"
@echo "✅ Development dependencies installed!"
@echo ""
# ============================================================================
# 伺服器運行
# ============================================================================
run:
@echo "🚀 Starting MCP-MAF SSE Server..."
@echo ""
@echo "📍 Endpoints:"
@echo " SSE: http://localhost:8000/sse"
@echo " Messages: http://localhost:8000/messages"
@echo " Health: http://localhost:8000/health"
@echo " Docs: http://localhost:8000/docs"
@echo ""
@echo "🛑 Press Ctrl+C to stop"
@echo ""
@uv run uvicorn mcp_maf.server:app --host 0.0.0.0 --port 8000
dev:
@echo "🚀 Starting development server with hot reload..."
@echo ""
@echo "📝 Hot reload enabled - edit files and see changes instantly"
@echo ""
@uv run uvicorn mcp_maf.server:app --host 0.0.0.0 --port 8000 --reload
run-bg:
@echo "🚀 Starting server in background..."
@mkdir -p logs
@nohup uv run uvicorn mcp_maf.server:app --host 0.0.0.0 --port 8000 > logs/server.log 2>&1 &
@echo "✅ Server started in background"
@echo "📝 Logs: logs/server.log"
@echo "🛑 To stop: make stop"
@echo ""
stop:
@echo "🛑 Stopping MCP-MAF server..."
@pkill -f "uvicorn mcp_maf.server:app" || true
@echo "✅ Server stopped"
# ============================================================================
# 測試與品質檢查
# ============================================================================
test:
@echo "🧪 Running tests..."
@uv run pytest tests/ -v
test-cov:
@echo "🧪 Running tests with coverage..."
@uv run pytest tests/ -v --cov=mcp_maf --cov-report=html --cov-report=term
@echo ""
@echo "📊 Coverage report generated:"
@echo " HTML: htmlcov/index.html"
@echo " Terminal output above"
@echo ""
test-watch:
@echo "👀 Running tests in watch mode..."
@uv run pytest-watch tests/
lint:
@echo "🔍 Linting code..."
@echo ""
@echo "Running ruff..."
@uv run ruff check src/ tests/
@echo ""
@echo "Running mypy..."
@uv run mypy src/
@echo ""
@echo "✅ Linting complete!"
format:
@echo "🎨 Formatting code..."
@uv run ruff format src/ tests/ examples/
@echo "✅ Code formatted!"
# ============================================================================
# 範例執行
# ============================================================================
example-standalone:
@echo "🎯 Running standalone agent example..."
@echo ""
@uv run python examples/standalone_agent.py
example-sse:
@echo "🎯 Running SSE client example..."
@echo ""
@uv run python examples/sse_client.py
example-tools:
@echo "🎯 Running tools demo..."
@echo ""
@uv run python examples/tools_demo.py
# ============================================================================
# 快速工具測試 | Quick Tool Testing
# ============================================================================
demo-tools:
@echo "═══════════════════════════════════════════════════════"
@echo " Lucy Server - 工具展示 | Tools Demo"
@echo "═══════════════════════════════════════════════════════"
@echo ""
@.venv/bin/python examples/tools_demo.py
demo-weather:
@echo "🌤️ 測試天氣工具 | Testing Weather Tool"
@echo "───────────────────────────────────────────────────────"
@.venv/bin/python -c "import asyncio, json; from mcp_maf.tools import WeatherTool; tool = WeatherTool(); result = asyncio.run(tool.execute(location='Taipei')); print(json.dumps(result, indent=2, ensure_ascii=False))"
@echo ""
@echo "✅ 天氣工具測試完成 | Weather tool test completed"
demo-calc:
@echo "🧮 測試計算器工具 | Testing Calculator Tool"
@echo "───────────────────────────────────────────────────────"
@.venv/bin/python -c "import asyncio, json; from mcp_maf.tools import CalculatorTool; tool = CalculatorTool(); result = asyncio.run(tool.execute(expression='123 * 456')); print(json.dumps(result, indent=2, ensure_ascii=False))"
@echo ""
@echo "✅ 計算器工具測試完成 | Calculator tool test completed"
demo-stock:
@echo "📊 測試股票查詢工具 | Testing Stock Price Tool"
@echo "───────────────────────────────────────────────────────"
@.venv/bin/python -c "import asyncio, json; from mcp_maf.tools import StockPriceTool; tool = StockPriceTool(); result = asyncio.run(tool.execute(stock_code='2330')); print(json.dumps(result, indent=2, ensure_ascii=False))"
@echo ""
@echo "✅ 股票工具測試完成 | Stock tool test completed"
demo-all: health demo-weather demo-calc demo-stock
@echo ""
@echo "═══════════════════════════════════════════════════════"
@echo " ✅ 所有工具測試完成 | All tools tested successfully"
@echo "═══════════════════════════════════════════════════════"
# ============================================================================
# Docker
# ============================================================================
docker-build:
@echo "🐳 Building Docker image..."
@docker build -t mcp-maf:latest -f docker/Dockerfile .
@echo "✅ Docker image built: mcp-maf:latest"
docker-run: docker-build
@echo "🐳 Running Docker container..."
@docker run -p 8000:8000 --env-file .env mcp-maf:latest
docker-up:
@echo "🐳 Starting Docker Compose services..."
@docker-compose -f docker/docker-compose.yml up -d
@echo "✅ Services started!"
@echo ""
@echo "📍 MCP-MAF Server: http://localhost:8000"
@echo ""
docker-down:
@echo "🐳 Stopping Docker Compose services..."
@docker-compose -f docker/docker-compose.yml down
@echo "✅ Services stopped!"
docker-logs:
@docker-compose -f docker/docker-compose.yml logs -f
# ============================================================================
# 實用工具
# ============================================================================
health:
@echo "🏥 Checking server health..."
@curl -s http://localhost:8000/health | jq . || curl -s http://localhost:8000/health
test-sse:
@echo "🔌 Testing SSE connection..."
@echo "📡 Connecting to http://localhost:8000/sse"
@echo "🛑 Press Ctrl+C to stop"
@echo ""
@curl -N http://localhost:8000/sse
logs:
@echo "📝 Tailing server logs..."
@tail -f logs/server.log
clean:
@echo "🧹 Cleaning up..."
@find . -type d -name "__pycache__" -exec rm -rf {} + 2>/dev/null || true
@find . -type f -name "*.pyc" -delete 2>/dev/null || true
@find . -type f -name "*.pyo" -delete 2>/dev/null || true
@find . -type d -name "*.egg-info" -exec rm -rf {} + 2>/dev/null || true
@find . -type d -name ".pytest_cache" -exec rm -rf {} + 2>/dev/null || true
@rm -rf htmlcov .coverage build/ dist/ logs/*.log
@echo "✅ Cleanup complete!"
# ============================================================================
# 快速開始
# ============================================================================
quickstart: setup install
@echo ""
@echo "🎉 MCP-MAF is ready!"
@echo ""
@echo "💡 Starting server in 3 seconds..."
@sleep 3
@make run
# ============================================================================
# 開發環境完整設置
# ============================================================================
dev-setup: setup install-dev
@echo ""
@echo "🎉 Development environment ready!"
@echo ""
@echo "💡 Useful commands:"
@echo " make dev - Start dev server"
@echo " make test - Run tests"
@echo " make lint - Check code quality"
@echo " make format - Format code"
@echo ""
