Development Environment
Set up a local development environment for working on the MCP stack.
Prerequisites
- Python 3.12
- Node.js 22
- Docker + Docker Compose
- Git
Python Setup
Create a virtual environment for each MCP server you're working on:
# Permission engine (shared)
cd mcp-servers/shared/mcp-permission-engine
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
# Ubuntu MCP
cd mcp-servers/ubuntu-server
python -m venv .venv
source .venv/bin/activate
pip install -e ".[dev]"
Web UI Setup
cd mcp-webui
npm install
npm run dev # Starts on port 8280
Running Without Docker
MCP servers can run directly on the host for development:
cd mcp-servers/ubuntu-server
PYTHONPATH=src:../shared/mcp-permission-engine/src \
MCP_USER_ID=default \
python -m ubuntu_mcp --config /path/to/config.yaml
Running Tests
# Python tests
cd mcp-servers/shared/mcp-permission-engine
python -m pytest tests/ -v
# Web UI tests
cd mcp-webui
npm test
# TypeScript type checking
cd mcp-webui
npm run typecheck
Running Docs Site
cd docs-site
npm install
npm run start # Starts on port 3000
Docker Development
# Build and run a single service
docker compose up -d --build ubuntu-mcp
# View logs
docker compose logs -f ubuntu-mcp
# Rebuild after changes
docker compose up -d --build ubuntu-mcp
# Access container shell
docker compose exec ubuntu-mcp bash