Skip to content

Commit 2ae96ad

Browse files
crivetimihaicrivetimihai
authored
Merge pull request #90 from manavgup/feature/codespaces
Feature/codespaces
2 parents b0925a7 + b5addea commit 2ae96ad

File tree

7 files changed

+256
-2
lines changed

7 files changed

+256
-2
lines changed

‎.devcontainer/.bashrc

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Export VENV_DIR environment variable for virtual environment path
2+
3+
export VENV_DIR="$HOME/.venv/mcpgateway"
4+
5+
# Automatically activate the virtual environment if it exists
6+
if [ -f "$VENV_DIR/bin/activate" ]; then
7+
source "$VENV_DIR/bin/activate"
8+
fi

‎.devcontainer/Dockerfile

Lines changed: 31 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,31 @@
1+
# Use official Python 3.11 slim image as base
2+
FROM python:3.11-slim
3+
4+
# Install Docker CLI (for container management inside devcontainer)
5+
RUN apt-get update && apt-get install -y \
6+
docker.io \
7+
curl \
8+
git \
9+
build-essential \
10+
&& rm -rf /var/lib/apt/lists/*
11+
12+
# Set working directory
13+
WORKDIR /workspace
14+
15+
# Install pip upgrade and pdm (Python package manager used in Makefile)
16+
RUN python3 -m pip install --upgrade pip setuptools pdm uv
17+
18+
# Note: Project files will be mounted by devcontainer, so no need to copy them during build
19+
# Dependencies will be installed via postCreateCommand.sh using make install-dev
20+
21+
# Expose port 4444 for the gateway
22+
EXPOSE 4444
23+
24+
# Default shell
25+
SHELL ["/bin/bash", "-c"]
26+
27+
# Set environment variables for development
28+
ENV MCPGATEWAY_DEV_MODE=true
29+
30+
# Set entrypoint to bash for interactive use
31+
ENTRYPOINT ["/bin/bash"]

‎.devcontainer/devcontainer.json

Lines changed: 30 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,30 @@
1+
{
2+
"name": "mcpgateway-devcontainer",
3+
"build": {
4+
"dockerfile": "Dockerfile",
5+
"context": ".."
6+
},
7+
"features": {},
8+
"postCreateCommand": ".devcontainer/postCreateCommand.sh",
9+
"customizations": {
10+
"vscode": {
11+
"extensions": [
12+
"ms-python.python",
13+
"ms-azuretools.vscode-docker"
14+
],
15+
"settings": {
16+
"terminal.integrated.profiles.linux": {
17+
"bash-venv": {
18+
"path": "/bin/bash",
19+
"args": ["-c", "source ~/.venv/mcpgateway/bin/activate && exec bash"]
20+
}
21+
},
22+
"terminal.integrated.defaultProfile.linux": "bash-venv"
23+
}
24+
}
25+
},
26+
"remoteEnv": {
27+
"MCPGATEWAY_DEV_MODE": "true",
28+
"VENV_DIR": "/Users/mg/.venv/mcpgateway"
29+
}
30+
}

‎.devcontainer/postCreateCommand.sh

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,19 @@
1+
#!/bin/bash
2+
set -e
3+
4+
# Copy .env.example to .env if .env does not exist
5+
if [ ! -f .env ]; then
6+
cp .env.example .env
7+
echo "Copied .env.example to .env"
8+
fi
9+
10+
# Install development dependencies using Makefile target
11+
make install-dev
12+
13+
# Run tests to verify setup
14+
make test
15+
16+
echo "Devcontainer setup complete."
17+
18+
# Activate the virtual environment for the current session
19+
source ~/.venv/mcpgateway/bin/activate

‎Makefile

Lines changed: 1 addition & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -139,8 +139,7 @@ serve-ssl: certs
139139
SSL=true CERT_FILE=certs/cert.pem KEY_FILE=certs/key.pem ./run-gunicorn.sh
140140

141141
dev:
142-
@$(VENV_DIR)/bin/uvicorn mcpgateway.main:app --reload --reload-exclude='public/'
143-
142+
@$(VENV_DIR)/bin/uvicorn mcpgateway.main:app --host 0.0.0.0 --port 8000 --reload --reload-exclude='public/'
144143
run:
145144
./run.sh
146145

‎README.md

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -318,6 +318,63 @@ For more details, see the [Claude MCP quickstart](https://modelcontextprotocol.i
318318

319319
---
320320

321+
## Quick Start (VS Code Dev Container)
322+
323+
For the fastest development setup, use the provided VS Code Dev Container configuration. This provides a fully configured development environment with Python 3.11, Docker CLI, and all project dependencies pre-installed.
324+
325+
### Prerequisites
326+
327+
* **VS Code** with the [Dev Containers extension](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)
328+
* **Docker** or **Podman** installed and running
329+
330+
### Using the Dev Container
331+
332+
1. **Clone the repository:**
333+
```bash
334+
git clone https://github.com/ibm/mcp-context-forge.git
335+
cd mcp-context-forge
336+
```
337+
338+
2. **Open in VS Code:**
339+
```bash
340+
code .
341+
```
342+
343+
3. **Reopen in Container:**
344+
- VS Code will detect the `.devcontainer` configuration
345+
- Click "Reopen in Container" when prompted, or
346+
- Use Command Palette (`Ctrl/Cmd+Shift+P`) → "Dev Containers: Reopen in Container"
347+
348+
4. **Wait for setup:**
349+
- The container will build automatically (first time may take a few minutes)
350+
- Development dependencies will be installed via `make install-dev`
351+
- Tests will run automatically to verify the setup
352+
353+
5. **Start developing:**
354+
```bash
355+
make dev # Start development server
356+
make test # Run tests
357+
make lint # Run linting
358+
```
359+
360+
### GitHub Codespaces
361+
362+
You can also use this project with GitHub Codespaces for cloud-based development:
363+
364+
1. Click the "Code" button on the GitHub repository page
365+
2. Select "Codespaces" tab
366+
3. Click "Create codespace on main"
367+
4. Wait for the environment to be ready (same setup as local dev container)
368+
369+
The devcontainer includes:
370+
- Python 3.11 with all project dependencies
371+
- Docker CLI for container management
372+
- VS Code extensions for Python and Docker development
373+
- Pre-configured environment variables for development mode
374+
- Automatic setup of `.env` file from `.env.example`
375+
376+
---
377+
321378
## Quick Start (manual install)
322379

323380
### Prerequisites

‎docs/docs/architecture/adr/005-vscode-devcontainer-support.md

Lines changed: 110 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,110 @@
1+
# ADR-005: VS Code Dev Container Support
2+
3+
## Status
4+
5+
Accepted
6+
7+
## Context
8+
9+
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:
10+
11+
- Installing Python 3.11
12+
- Installing Docker/Podman
13+
- Setting up virtual environments
14+
- Installing development dependencies
15+
- Configuring environment variables
16+
- Running tests to verify setup
17+
18+
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.
19+
20+
## Decision
21+
22+
We will add VS Code Dev Container support to the project by implementing:
23+
24+
1. **`.devcontainer/devcontainer.json`** - Configuration specifying:
25+
- Container build instructions
26+
- VS Code extensions (Python, Docker)
27+
- Post-creation commands
28+
- Environment variables for development mode
29+
30+
2. **`.devcontainer/Dockerfile`** - Container definition with:
31+
- Python 3.11 slim base image
32+
- Docker CLI for container management
33+
- System dependencies (curl, git, build-essential)
34+
- Python tooling (pip, setuptools, pdm, uv)
35+
- Development environment setup
36+
37+
3. **`.devcontainer/postCreateCommand.sh`** - Setup script that:
38+
- Copies `.env.example` to `.env` if needed
39+
- Runs `make install-dev` to install development dependencies
40+
- Runs `make test` to verify the environment
41+
42+
4. **Documentation updates** - README.md section explaining:
43+
- How to use the devcontainer in VS Code
44+
- How to use with GitHub Codespaces
45+
- Benefits and included tools
46+
47+
## Consequences
48+
49+
### Positive
50+
51+
- **Instant onboarding**: New contributors can start developing immediately with one click
52+
- **Consistent environments**: All developers use the same Python version, tools, and dependencies
53+
- **Reduced setup friction**: No need to manually install Python, Docker, or configure environments
54+
- **GitHub Codespaces support**: Cloud-based development without local setup requirements
55+
- **Automated verification**: Tests run automatically to ensure the environment is working
56+
- **Standardized tooling**: Everyone gets the same VS Code extensions and configuration
57+
58+
### Negative
59+
60+
- **Additional maintenance**: Need to keep devcontainer configuration in sync with project requirements
61+
- **Container build time**: Initial setup takes a few minutes for first-time users
62+
- **Docker dependency**: Requires Docker/Podman to be installed and running
63+
- **Limited to VS Code**: Only benefits developers using VS Code or Codespaces
64+
65+
### Neutral
66+
67+
- **File size increase**: Adds minimal files to the repository
68+
- **Learning curve**: Developers unfamiliar with Dev Containers may need to learn the workflow
69+
70+
## Alternatives Considered
71+
72+
1. **Manual setup instructions only** (current state)
73+
- Pros: No additional complexity
74+
- Cons: High setup friction, inconsistent environments
75+
76+
2. **Gitpod integration**
77+
- Pros: Cloud-based development
78+
- Cons: Less VS Code-native, additional external dependency
79+
80+
3. **Docker Compose for development**
81+
- Pros: Tool-agnostic
82+
- Cons: More complex setup, less integrated with VS Code
83+
84+
4. **Vagrant-based development environment**
85+
- Pros: Full VM isolation
86+
- Cons: Resource-heavy, slower, less modern workflow
87+
88+
## Implementation Details
89+
90+
The devcontainer uses:
91+
- **Python 3.11**: As specified in the project requirements
92+
- **PDM and UV**: For package management (matching the project's tooling)
93+
- **Make targets**: Leverages existing `make install-dev` and `make test` workflows
94+
- **Environment variables**: Sets `MCPGATEWAY_DEV_MODE=true` for development
95+
- **VS Code extensions**: Includes Python and Docker extensions for optimal development experience
96+
97+
## Verification
98+
99+
The implementation was tested by:
100+
1. Building the devcontainer in VS Code
101+
2. Verifying that development dependencies install correctly
102+
3. Confirming that the test suite passes
103+
4. Checking that all Make targets work properly inside the container
104+
105+
## References
106+
107+
- [VS Code Dev Containers documentation](https://code.visualstudio.com/docs/devcontainers/containers)
108+
- [GitHub Codespaces documentation](https://docs.github.com/en/codespaces)
109+
- [Dev Container specification](https://containers.dev/)
110+
- Project issue/PR requesting devcontainer support

0 commit comments

Comments
 (0)