Skip to content

ADR-005: VS Code Dev Container Support

Status

Accepted

Context

New contributors to the MCP Context Forge project face significant setup friction when trying to get a development environment running. The manual setup process requires:

  • Installing Python 3.11
  • Installing Docker/Podman
  • Setting up virtual environments
  • Installing development dependencies
  • Configuring environment variables
  • Running tests to verify setup

This setup complexity can discourage contributions and slow down the onboarding process for new developers. Many contributors use VS Code or GitHub Codespaces, which support Dev Containers for standardized development environments.

Decision

We will add VS Code Dev Container support to the project by implementing:

  1. .devcontainer/devcontainer.json - Configuration specifying:
  2. Container build instructions
  3. VS Code extensions (Python, Docker)
  4. Post-creation commands

  5. Environment variables for development mode

  6. .devcontainer/Dockerfile - Container definition with:

  7. Python 3.11 slim base image
  8. Docker CLI for container management
  9. System dependencies (curl, git, build-essential)
  10. Python tooling (pip, setuptools, pdm, uv)

  11. Development environment setup

  12. .devcontainer/postCreateCommand.sh - Setup script that:

  13. Copies .env.example to .env if needed
  14. Runs make install-dev to install development dependencies

  15. Runs make test to verify the environment

  16. Documentation updates - README.md section explaining:

  17. How to use the devcontainer in VS Code
  18. How to use with GitHub Codespaces
  19. Benefits and included tools

Consequences

Positive

  • Instant onboarding: New contributors can start developing immediately with one click
  • Consistent environments: All developers use the same Python version, tools, and dependencies
  • Reduced setup friction: No need to manually install Python, Docker, or configure environments
  • GitHub Codespaces support: Cloud-based development without local setup requirements
  • Automated verification: Tests run automatically to ensure the environment is working
  • Standardized tooling: Everyone gets the same VS Code extensions and configuration

Negative

  • Additional maintenance: Need to keep devcontainer configuration in sync with project requirements
  • Container build time: Initial setup takes a few minutes for first-time users
  • Docker dependency: Requires Docker/Podman to be installed and running
  • Limited to VS Code: Only benefits developers using VS Code or Codespaces

Neutral

  • File size increase: Adds minimal files to the repository
  • Learning curve: Developers unfamiliar with Dev Containers may need to learn the workflow

Alternatives Considered

  1. Manual setup instructions only (current state)
  2. Pros: No additional complexity

  3. Cons: High setup friction, inconsistent environments

  4. Gitpod integration

  5. Pros: Cloud-based development

  6. Cons: Less VS Code-native, additional external dependency

  7. Docker Compose for development

  8. Pros: Tool-agnostic

  9. Cons: More complex setup, less integrated with VS Code

  10. Vagrant-based development environment

  11. Pros: Full VM isolation
  12. Cons: Resource-heavy, slower, less modern workflow

Implementation Details

The devcontainer uses:

  • Python 3.11: As specified in the project requirements
  • PDM and UV: For package management (matching the project's tooling)
  • Make targets: Leverages existing make install-dev and make test workflows
  • Environment variables: Sets DEV_MODE=true for development
  • VS Code extensions: Includes Python and Docker extensions for optimal development experience

Verification

The implementation was tested by:

  1. Building the devcontainer in VS Code
  2. Verifying that development dependencies install correctly
  3. Confirming that the test suite passes
  4. Checking that all Make targets work properly inside the container

References