This guide provides step-by-step instructions for setting up a complete development environment for the MCP Server with LangGraph project. Whether you’re on macOS, Linux, or Windows, this guide will get you up and running.
This setup is optimized for productivity with hot reload, debugging support, code formatting, and comprehensive testing tools.
Create Virtual Environment and Install Dependencies
With uv, virtual environment creation and dependency installation happen in one command!uv sync automatically:
Creates .venv if it doesn’t exist
Installs all dependencies from pyproject.toml
Uses uv.lock for reproducible builds
Copy
Ask AI
## Install ALL dependencies (recommended for development)uv sync## Or use the Makefilemake install-dev # Same as: uv sync## Install production dependencies onlymake install # Same as: uv sync --frozen --no-dev## Verify installationuv run python -c "import fastapi, langchain, anthropic; print('All imports successful')"
No need to manually create or activate virtual environments!
Use uv run <command> to run commands in the virtual environment without activation.
Most developers don’t need this section.uv sync handles everything automatically.Only use manual uv venv if you need:
A specific Python version different from your default
A custom virtual environment location
Fine-grained control over the environment
If you need manual control:
Copy
Ask AI
## Create venv manually with specific Python versionuv venv --python 3.12## Activate it (only if needed)## macOS/Linuxsource .venv/bin/activate## Windows (Git Bash)source .venv/Scripts/activate## Then installuv sync
## Build imagedocker build -t mcp-server-langgraph:dev .## Run containerdocker run -p 8000:8000 \ --env-file .env \ mcp-server-langgraph:dev## Or use docker compose docker compose up
## Run unit testsuv run pytest -m unit## Run with coverageuv run pytest -m unit --cov=src --cov-report=html## Run integration tests (requires services)docker compose -f docker-compose.dev.yml up -duv run pytest -m integration## Run specific test fileuv run pytest tests/unit/test_auth.py## Run specific testuv run pytest tests/unit/test_auth.py::test_create_token## Run with verbose outputuv run pytest -v --tb=short## Watch mode (requires pytest-watch)uv run pytest-watch
## Run with pdb debuggeruv run pytest --pdb## Drop into debugger on failureuv run pytest --pdb --maxfail=1## Use ipdb for better debugginguv add --dev ipdbuv run pytest --pdb --pdbcls=IPython.terminal.debugger:TerminalPdb
## Makefile.PHONY: help install dev test lint format cleanhelp: ## Show this help @grep -E '^[a-zA-Z_-]+:.*?## .*$$' $(MAKEFILE_LIST) | sort | awk 'BEGIN {FS = ":.*?## "}; {printf "\033[36m%-20s\033[0m %s\n", $$1, $$2}'install: ## Install dependencies uv sync pre-commit installdev: ## Run development server uvicorn src.main:app --reload --host 0.0.0.0 --port 8000test: ## Run tests pytest -m unit --cov=src --cov-report=term --cov-report=htmltest-integration: ## Run integration tests docker compose -f docker-compose.dev.yml up -d pytest -m integration docker compose -f docker-compose.dev.yml downlint: ## Run linters black --check src/ tests/ isort --check src/ tests/ flake8 src/ tests/ mypy src/ bandit -r src/format: ## Format code black src/ tests/ isort src/ tests/clean: ## Clean up find . -type d -name __pycache__ -exec rm -rf {} + find . -type d -name .pytest_cache -exec rm -rf {} + find . -type d -name .mypy_cache -exec rm -rf {} + find . -type f -name "*.pyc" -delete rm -rf htmlcov/ rm -rf .coveragedocker-build: ## Build Docker image docker build -t mcp-server-langgraph:dev .docker-run: ## Run Docker container docker run -p 8000:8000 --env-file .env mcp-server-langgraph:devservices-up: ## Start development services docker compose -f docker-compose.dev.yml up -dservices-down: ## Stop development services docker compose -f docker-compose.dev.yml downservices-logs: ## View service logs docker compose -f docker-compose.dev.yml logs -f
Usage:
Copy
Ask AI
## Show all commandsmake help## Install dependenciesmake install## Run dev servermake dev## Run testsmake test## Format and lintmake formatmake lint## Start servicesmake services-up
# Find process using port 8000lsof -i :8000# Kill processkill -9 PID# Or use different portuvicorn src.main:app --reload --port 8001
Import Errors
Copy
Ask AI
# Reinstall dependencies (creates .venv if needed)uv sync# Use uv run to avoid activation issuesuv run python -c "import sys; print('\n'.join(sys.path))"# Or activate virtualenv if preferredsource .venv/bin/activatepython -c "import sys; print('\n'.join(sys.path))"# Add src to PYTHONPATHexport PYTHONPATH="${PYTHONPATH}:${PWD}/src"
# Run tests with verbose outputpytest -vv --tb=long# Run single test to debugpytest tests/unit/test_auth.py::test_create_token -vv# Clear pytest cacherm -rf .pytest_cache# Reinstall test dependenciesuv sync
## Use uv instead of pip (10-100x faster)uv add package-name## Use pytest-xdist for parallel testsuv add --dev pytest-xdistpytest -n auto # Use all CPU cores## Use pytest-sugar for better outputuv add --dev pytest-sugar## Cache Docker layersdocker build --cache-from mcp-server-langgraph:latest .
