Development Setup

This document provides comprehensive guidance for setting up a development environment for MockLoop MCP, including prerequisites, installation steps, configuration, and development workflows.

Overview

MockLoop MCP development requires a Python environment with specific dependencies, database setup, and development tools. This guide covers:

• Environment Setup: Python, dependencies, and virtual environments
• Database Configuration: Local database setup for development
• Development Tools: Code formatting, linting, testing, and debugging
• IDE Configuration: VS Code, PyCharm, and other editor setups
• Docker Development: Containerized development environment

Prerequisites

System Requirements

• Python: 3.9 or higher (3.11+ recommended)
• Node.js: 16+ (for documentation and frontend tools)
• Git: Latest version
• Database: SQLite (included), PostgreSQL, or MySQL (optional)
• Redis: For caching and rate limiting (optional)

Operating System Support

MockLoop MCP development is supported on:

• Linux: Ubuntu 20.04+, CentOS 8+, Arch Linux
• macOS: 10.15+ (Catalina or later)
• Windows: 10/11 with WSL2 recommended

Environment Setup

1. Clone the Repository

# Clone the main repository
git clone https://github.com/mockloop/mockloop-mcp.git
cd mockloop-mcp

# Clone with all submodules
git clone --recursive https://github.com/mockloop/mockloop-mcp.git
cd mockloop-mcp

2. Python Environment Setup

Using uv (Recommended)

# Install uv if not already installed
curl -LsSf https://astral.sh/uv/install.sh | sh

# Create virtual environment and install dependencies
uv venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install development dependencies
uv pip install -e ".[dev,test,docs]"

Using pip and venv

# Create virtual environment
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Upgrade pip
pip install --upgrade pip

# Install development dependencies
pip install -e ".[dev,test,docs]"

Using conda

# Create conda environment
conda create -n mockloop-mcp python=3.11
conda activate mockloop-mcp

# Install dependencies
pip install -e ".[dev,test,docs]"

3. Verify Installation

# Check MockLoop MCP installation
python -c "import mockloop_mcp; print(mockloop_mcp.__version__)"

# Run basic tests
python -m pytest tests/unit/ -v

# Check CLI availability
mockloop --help

Database Setup

SQLite (Default)

SQLite requires no additional setup and is used by default:

# Initialize database
mockloop db init

# Run migrations
mockloop db migrate

# Verify setup
mockloop db status

PostgreSQL Setup

Installation

# Ubuntu/Debian
sudo apt-get install postgresql postgresql-contrib

# macOS with Homebrew
brew install postgresql
brew services start postgresql

# Create database and user
sudo -u postgres psql
CREATE DATABASE mockloop_dev;
CREATE USER mockloop_dev WITH PASSWORD 'dev_password';
GRANT ALL PRIVILEGES ON DATABASE mockloop_dev TO mockloop_dev;
\q

Configuration

# Set environment variables
export MOCKLOOP_DATABASE_TYPE=postgresql
export MOCKLOOP_DATABASE_HOST=localhost
export MOCKLOOP_DATABASE_PORT=5432
export MOCKLOOP_DATABASE_NAME=mockloop_dev
export MOCKLOOP_DATABASE_USER=mockloop_dev
export MOCKLOOP_DATABASE_PASSWORD=dev_password

# Or create .env file
cat > .env << EOF
MOCKLOOP_DATABASE_TYPE=postgresql
MOCKLOOP_DATABASE_HOST=localhost
MOCKLOOP_DATABASE_PORT=5432
MOCKLOOP_DATABASE_NAME=mockloop_dev
MOCKLOOP_DATABASE_USER=mockloop_dev
MOCKLOOP_DATABASE_PASSWORD=dev_password
EOF

MySQL Setup

Installation

# Ubuntu/Debian
sudo apt-get install mysql-server

# macOS with Homebrew
brew install mysql
brew services start mysql

# Create database and user
mysql -u root -p
CREATE DATABASE mockloop_dev;
CREATE USER 'mockloop_dev'@'localhost' IDENTIFIED BY 'dev_password';
GRANT ALL PRIVILEGES ON mockloop_dev.* TO 'mockloop_dev'@'localhost';
FLUSH PRIVILEGES;
EXIT;

Configuration

# Set environment variables
export MOCKLOOP_DATABASE_TYPE=mysql
export MOCKLOOP_DATABASE_HOST=localhost
export MOCKLOOP_DATABASE_PORT=3306
export MOCKLOOP_DATABASE_NAME=mockloop_dev
export MOCKLOOP_DATABASE_USER=mockloop_dev
export MOCKLOOP_DATABASE_PASSWORD=dev_password

Development Tools

Code Formatting and Linting

Pre-commit Hooks

# Install pre-commit
pip install pre-commit

# Install hooks
pre-commit install

# Run hooks manually
pre-commit run --all-files

Manual Tools

# Format code with black
black src/ tests/

# Sort imports with isort
isort src/ tests/

# Lint with flake8
flake8 src/ tests/

# Type checking with mypy
mypy src/

# Security scanning with bandit
bandit -r src/

Testing Setup

Running Tests

# Run all tests
pytest

# Run with coverage
pytest --cov=mockloop_mcp --cov-report=html

# Run specific test categories
pytest tests/unit/          # Unit tests
pytest tests/integration/   # Integration tests
pytest tests/e2e/          # End-to-end tests

# Run tests with specific markers
pytest -m "not slow"       # Skip slow tests
pytest -m "database"       # Only database tests

Test Configuration

Create pytest.ini:

[tool:pytest]
testpaths = tests
python_files = test_*.py
python_classes = Test*
python_functions = test_*
addopts = 
    --strict-markers
    --strict-config
    --verbose
    --tb=short
    --cov=mockloop_mcp
    --cov-branch
    --cov-report=term-missing
    --cov-report=html:htmlcov
    --cov-report=xml
markers =
    slow: marks tests as slow (deselect with '-m "not slow"')
    integration: marks tests as integration tests
    e2e: marks tests as end-to-end tests
    database: marks tests that require database
    redis: marks tests that require Redis
    network: marks tests that require network access

Documentation Development

MkDocs Setup

# Install documentation dependencies
pip install -r docs-requirements.txt

# Serve documentation locally
mkdocs serve

# Build documentation
mkdocs build

# Check for issues and broken links
mkdocs build --strict

Documentation Writing

# Watch for changes and auto-reload
mkdocs serve --dev-addr=0.0.0.0:8000

# Check for issues
mkdocs build --strict

# Generate API documentation
python scripts/generate_api_docs.py

GitHub Pages Deployment

The documentation is automatically deployed to GitHub Pages using GitHub Actions. The workflow is triggered on:

• Push to main/master: Automatically builds and deploys documentation
• Pull requests: Builds documentation to check for errors (no deployment)
• Manual trigger: Can be triggered manually from GitHub Actions tab

Setting Up GitHub Pages

1. Enable GitHub Pages in repository settings:
2. Go to Settings → Pages
3. Source: "GitHub Actions"

4. No need to select a branch when using GitHub Actions

5. Workflow Configuration: The workflow is defined in .github/workflows/docs.yml

6. Automatic Deployment:

   # Documentation is automatically deployed when you:
   git push origin main  # Push to main branch
   
   # Or when a PR is merged that changes documentation files
   

7. Manual Deployment (if needed):

8. Go to GitHub → Actions → "Build and Deploy Documentation"
9. Click "Run workflow" → "Run workflow"

Local Testing Before Deployment

# Test the exact build process used in CI
pip install -r docs-requirements.txt
mkdocs build --clean --strict

# Serve the built site locally
cd site && python -m http.server 8080

Troubleshooting Deployment

• Check GitHub Actions: Go to Actions tab to see build logs
• Verify dependencies: Ensure docs-requirements.txt includes all needed packages
• Test locally: Always test mkdocs build --strict before pushing
• Check permissions: Ensure repository has Pages and Actions enabled

IDE Configuration

VS Code Setup

Recommended Extensions

Create .vscode/extensions.json:

{
    "recommendations": [
        "ms-python.python",
        "ms-python.black-formatter",
        "ms-python.isort",
        "ms-python.flake8",
        "ms-python.mypy-type-checker",
        "ms-python.pylint",
        "charliermarsh.ruff",
        "ms-vscode.test-adapter-converter",
        "littlefoxteam.vscode-python-test-adapter",
        "ms-vscode.vscode-json",
        "redhat.vscode-yaml",
        "yzhang.markdown-all-in-one",
        "davidanson.vscode-markdownlint"
    ]
}

Workspace Settings

Create .vscode/settings.json:

{
    "python.defaultInterpreterPath": "./.venv/bin/python",
    "python.terminal.activateEnvironment": true,
    "python.testing.pytestEnabled": true,
    "python.testing.pytestArgs": [
        "tests"
    ],
    "python.testing.unittestEnabled": false,
    "python.linting.enabled": true,
    "python.linting.flake8Enabled": true,
    "python.linting.mypyEnabled": true,
    "python.formatting.provider": "black",
    "python.sortImports.args": [
        "--profile",
        "black"
    ],
    "editor.formatOnSave": true,
    "editor.codeActionsOnSave": {
        "source.organizeImports": true
    },
    "files.exclude": {
        "**/__pycache__": true,
        "**/*.pyc": true,
        ".pytest_cache": true,
        ".coverage": true,
        "htmlcov": true,
        ".mypy_cache": true
    }
}

Launch Configuration

Create .vscode/launch.json:

{
    "version": "0.2.0",
    "configurations": [
        {
            "name": "Python: MockLoop MCP",
            "type": "python",
            "request": "launch",
            "program": "${workspaceFolder}/src/mockloop_mcp/main.py",
            "args": ["serve"],
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}",
            "env": {
                "MOCKLOOP_LOG_LEVEL": "debug"
            }
        },
        {
            "name": "Python: Current File",
            "type": "python",
            "request": "launch",
            "program": "${file}",
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}"
        },
        {
            "name": "Python: Pytest",
            "type": "python",
            "request": "launch",
            "module": "pytest",
            "args": ["${workspaceFolder}/tests"],
            "console": "integratedTerminal",
            "cwd": "${workspaceFolder}"
        }
    ]
}

PyCharm Setup

Project Configuration

1. Open Project: File → Open → Select mockloop-mcp directory
2. Python Interpreter: File → Settings → Project → Python Interpreter → Add → Existing environment → Select .venv/bin/python
3. Code Style: File → Settings → Editor → Code Style → Python → Set to Black
4. Inspections: File → Settings → Editor → Inspections → Enable Python inspections

Run Configurations

Create run configurations for:

• MockLoop Server: Script path: src/mockloop_mcp/main.py, Parameters: serve
• Tests: Test runner: pytest, Target: tests/
• Specific Test: Test runner: pytest, Target: specific test file

Vim/Neovim Setup

Plugin Configuration

For Neovim with LSP support:

-- init.lua
require('lspconfig').pylsp.setup{
    settings = {
        pylsp = {
            plugins = {
                pycodestyle = {enabled = false},
                mccabe = {enabled = false},
                pyflakes = {enabled = false},
                flake8 = {enabled = true},
                black = {enabled = true},
                isort = {enabled = true},
                mypy = {enabled = true}
            }
        }
    }
}

Docker Development

Development Container

Create docker-compose.dev.yml:

version: '3.8'

services:
  mockloop-dev:
    build:
      context: .
      dockerfile: Dockerfile.dev
    volumes:
      - .:/workspace
      - /workspace/.venv  # Exclude venv from mount
    ports:
      - "8000:8000"
      - "5678:5678"  # Debug port
    environment:
      - MOCKLOOP_LOG_LEVEL=debug
      - MOCKLOOP_DATABASE_TYPE=postgresql
      - MOCKLOOP_DATABASE_HOST=postgres
    depends_on:
      - postgres
      - redis
    command: python -m debugpy --listen 0.0.0.0:5678 --wait-for-client -m mockloop_mcp.main serve

  postgres:
    image: postgres:15
    environment:
      POSTGRES_DB: mockloop_dev
      POSTGRES_USER: mockloop_dev
      POSTGRES_PASSWORD: dev_password
    ports:
      - "5432:5432"
    volumes:
      - postgres_data:/var/lib/postgresql/data

  redis:
    image: redis:7-alpine
    ports:
      - "6379:6379"
    volumes:
      - redis_data:/data

volumes:
  postgres_data:
  redis_data:

Create Dockerfile.dev:

FROM python:3.11-slim

# Install system dependencies
RUN apt-get update && apt-get install -y \
    git \
    build-essential \
    libpq-dev \
    && rm -rf /var/lib/apt/lists/*

# Set working directory
WORKDIR /workspace

# Install Python dependencies
COPY requirements-dev.txt .
RUN pip install --no-cache-dir -r requirements-dev.txt

# Install debugpy for remote debugging
RUN pip install debugpy

# Copy source code
COPY . .

# Install in development mode
RUN pip install -e ".[dev,test]"

# Expose ports
EXPOSE 8000 5678

# Default command
CMD ["python", "-m", "mockloop_mcp.main", "serve"]

Development Commands

# Start development environment
docker-compose -f docker-compose.dev.yml up -d

# View logs
docker-compose -f docker-compose.dev.yml logs -f mockloop-dev

# Run tests in container
docker-compose -f docker-compose.dev.yml exec mockloop-dev pytest

# Access container shell
docker-compose -f docker-compose.dev.yml exec mockloop-dev bash

# Stop environment
docker-compose -f docker-compose.dev.yml down

Development Workflow

1. Feature Development

# Create feature branch
git checkout -b feature/new-feature

# Make changes
# ... edit files ...

# Run tests
pytest

# Format code
black src/ tests/
isort src/ tests/

# Commit changes
git add .
git commit -m "feat: add new feature"

# Push branch
git push origin feature/new-feature

2. Testing Workflow

# Run quick tests during development
pytest tests/unit/ -x  # Stop on first failure

# Run full test suite before commit
pytest

# Run tests with coverage
pytest --cov=mockloop_mcp --cov-report=html

# Run specific test
pytest tests/unit/test_generator.py::test_generate_mock_server -v

# Run tests matching pattern
pytest -k "test_auth" -v

3. Documentation Workflow

# Start documentation server
mkdocs serve

# Edit documentation files
# ... edit docs/*.md ...

# Check for issues
mkdocs build --strict

# Generate API docs
python scripts/generate_api_docs.py

# Commit documentation changes
git add docs/
git commit -m "docs: update API documentation"

4. Database Development

# Create new migration
python scripts/create_migration.py "Add new table"

# Apply migrations
mockloop db migrate

# Rollback migration
mockloop db rollback --version 2

# Reset database (development only)
mockloop db reset --confirm

Debugging

Local Debugging

Python Debugger

# Add breakpoint in code
import pdb; pdb.set_trace()

# Or use built-in breakpoint() (Python 3.7+)
breakpoint()

VS Code Debugging

1. Set breakpoints in code
2. Press F5 or use Run → Start Debugging
3. Select "Python: MockLoop MCP" configuration

PyCharm Debugging

1. Set breakpoints in code
2. Right-click → Debug 'MockLoop Server'
3. Use debugger controls to step through code

Remote Debugging

Docker Remote Debugging

# In your code
import debugpy
debugpy.listen(("0.0.0.0", 5678))
debugpy.wait_for_client()  # Optional: wait for debugger to attach

Connect from VS Code:

{
    "name": "Python: Remote Attach",
    "type": "python",
    "request": "attach",
    "connect": {
        "host": "localhost",
        "port": 5678
    },
    "pathMappings": [
        {
            "localRoot": "${workspaceFolder}",
            "remoteRoot": "/workspace"
        }
    ]
}

Performance Profiling

# Profile with cProfile
python -m cProfile -o profile.stats -m mockloop_mcp.main serve

# Analyze profile
python -c "
import pstats
p = pstats.Stats('profile.stats')
p.sort_stats('cumulative').print_stats(20)
"

# Profile with py-spy
pip install py-spy
py-spy record -o profile.svg -- python -m mockloop_mcp.main serve

Environment Variables

Development Environment Variables

Create .env file:

# Database
MOCKLOOP_DATABASE_TYPE=sqlite
MOCKLOOP_DATABASE_PATH=./dev.db

# Logging
MOCKLOOP_LOG_LEVEL=debug
MOCKLOOP_LOG_FORMAT=text

# Development
MOCKLOOP_DEBUG=true
MOCKLOOP_RELOAD=true

# Testing
MOCKLOOP_TEST_DATABASE_URL=sqlite:///test.db
MOCKLOOP_TEST_REDIS_URL=redis://localhost:6379/1

# API Keys (for testing)
MOCKLOOP_TEST_API_KEY=test-key-12345

Loading Environment Variables

# In development scripts
from dotenv import load_dotenv
load_dotenv()

# Or use python-dotenv in code
import os
from pathlib import Path

env_path = Path('.') / '.env'
if env_path.exists():
    from dotenv import load_dotenv
    load_dotenv(env_path)

Troubleshooting

Common Issues

Import Errors

# Ensure package is installed in development mode
pip install -e .

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

# Verify installation
python -c "import mockloop_mcp; print(mockloop_mcp.__file__)"

Database Issues

# Reset database
rm -f dev.db
mockloop db init
mockloop db migrate

# Check database connection
python -c "
from mockloop_mcp.database import get_database_connection
conn = get_database_connection()
print('Database connection successful')
"

Port Conflicts

# Find process using port
lsof -i :8000

# Kill process
kill -9 <PID>

# Use different port
export MOCKLOOP_PORT=8001

Permission Issues

# Fix file permissions
chmod +x scripts/*.py

# Fix directory permissions
chmod -R 755 src/

Getting Help

• GitHub Issues: Report bugs and request features
• Discussions: Ask questions and share ideas
• Discord: Real-time chat with developers
• Documentation: Check the full documentation

Next Steps

After setting up your development environment:

1. Read the Contributing Guidelines for code standards
2. Review the Testing Guide for testing practices
3. Check the Release Process for deployment procedures
4. Explore the codebase and start contributing!

---

Welcome to MockLoop MCP development! We're excited to have you contribute to the project.