🧭 Type of Feature

• Developer tooling or test improvement
• Enhancement to existing functionality
• New feature or capability
• New MCP-compliant server
• New component or integration
• Packaging, automation and deployment
• Other (please describe below)

🧭 Epic

Title: Add .devcontainer/ support for VS Code
Goal: Enable instant onboarding for new contributors using GitHub Codespaces, Dev Containers or VS Code Remote Containers
Why now: Many contributors use VS Code or Codespaces. A devcontainer allows one-click access to a fully configured environment with preinstalled tools and settings, reducing setup friction.

🙋‍♂️ User Story 1

As a: new contributor
I want: to open the project in VS Code and start developing immediately
So that: I don’t have to manually install Python, Docker, or setup .env

✅ Acceptance Criteria

Scenario: Launch repo in Codespaces or with Remote Containers
  Given a cloned repo or Codespaces launch
  When I open the workspace in VS Code
  Then it installs Python 3.11, uv, Docker CLI, and project deps

🙋‍♂️ User Story 2

As a: project maintainer
I want: the devcontainer to include Make targets, .env.example, and test tools
So that: all contributors use a consistent, reproducible dev setup

✅ Acceptance Criteria

Scenario: Make and test inside devcontainer
  Given I'm inside the container
  When I run `make install-dev && make test`
  Then the test suite should pass

📐 Design Sketch (optional)

Basic folder structure:

.devcontainer/
├── devcontainer.json
├── Dockerfile
├── postCreateCommand.sh

devcontainer.json example:

{
  "name": "mcpgateway",
  "build": { "dockerfile": "Dockerfile" },
  "features": {},
  "postCreateCommand": "./postCreateCommand.sh",
  "customizations": {
    "vscode": {
      "extensions": ["ms-python.python", "ms-azuretools.vscode-docker"]
    }
  },
  "remoteEnv": {
    "MCPGATEWAY_DEV_MODE": "true"
  }
}

🔗 MCP Standards Check

• Change adheres to current MCP specifications
• No breaking changes to existing MCP-compliant integrations
• If deviations exist, please describe them below:

🔄 Alternatives Considered

• Document manual setup instructions only (already exists in README)
• Use Gitpod (more external tooling, less VS Code-native)

Required: document this in a Architecture Decision Record.

📓 Additional Context

This issue aligns with the existing Makefile dev targets (make venv, make install-dev, make lint, make serve) and could re-use .env.example. It's a good starter issue to practice Dockerfile editing and DevContainer basics, updating the mkdocs documentation and more.

Check that all the makefile targets run correctly inside the devcontainer - and all dependencies are considered, including various linters and tools. Scan the Makefile to ensure all tools are provided.