troubleshooting

MCP Server Troubleshooting Guide

Development Issues

UV and Dependencies

Problem: uv command not found

# Solution: Install UV
curl -LsSf https://astral.sh/uv/install.sh | sh
source ~/.bashrc

Problem: Package installation fails

# Check UV version
uv --version

# Clear cache and reinstall
uv cache clean
uv pip install --force-reinstall -r requirements.txt

Problem: Import errors during development

# Check Python path
uv run python -c "import sys; print(sys.path)"

# Install in development mode
uv pip install -e .

Testing Issues

Problem: Tests fail with import errors

# Check test environment
uv run python -m pytest --collect-only

# Ensure test dependencies are installed
uv add --dev pytest pytest-asyncio

# Run tests with verbose output
uv run pytest -v --tb=short

Problem: Async tests hang or fail

# Common issue: Missing pytest-asyncio
# Solution: Ensure all async tests use @pytest.mark.asyncio

import pytest

@pytest.mark.asyncio
async def test_async_function():
    # Your async test code here
    pass

Problem: Database tests fail

# Check if test database is properly isolated
uv run pytest tests/test_database.py -v -s

# Use temp database for tests
import tempfile
import pytest

@pytest.fixture
def temp_db():
    with tempfile.NamedTemporaryFile(suffix='.db') as f:
        yield f.name

Code Quality Issues

Problem: Black formatting conflicts

# Fix formatting issues
uv run black . --diff  # Preview changes
uv run black .         # Apply changes

Problem: mypy type checking errors

# Check specific file
uv run mypy servers/file_server/main.py

# Common fixes:
# 1. Add type hints
# 2. Use typing imports
# 3. Add # type: ignore comments for external libs

Problem: Import sorting issues

# Fix import order
uv run isort . --diff  # Preview changes
uv run isort .         # Apply changes

Runtime Issues