DevContainer MCP Server
A comprehensive Model Context Protocol (MCP) server that enables AI-powered DevContainer management. This server allows developers to create, configure, build, test, and modify DevContainer environments using natural language prompts through VS Code, Cursor, or any MCP-compatible editor.
🌟 Features
- Natural Language Processing: Convert plain English descriptions into valid
devcontainer.jsonconfigurations - Template System: 11+ pre-built templates for popular development stacks (Node.js, Python, Go, Rust, Java, etc.)
- Container Management: Build, test, start, stop, and monitor DevContainers using DevContainer CLI
- Live Modification: Update existing configurations based on natural language requests
- Status Monitoring: Real-time container health and configuration status
- Multi-Editor Support: Compatible with VS Code, Cursor, Claude Desktop, and other MCP clients
- CLI Tool: Standalone command-line interface for direct usage
📋 Table of Contents
- Installation
- Configuration
- Usage Examples
- Available Tools
- Templates
- CLI Tool
- Troubleshooting
- API Reference
- Contributing
🚀 Installation
Prerequisites
- Node.js 18+
- Docker or Podman
- DevContainer CLI:
npm install -g @devcontainers/cli
Install Package
npm install -g devcontainer-mcp-server
Development Installation
git clone https://github.com/Siddhant-K-code/mcp-devcontainer.git
cd mcp-devcontainer
npm install
npm run build
⚙️ Configuration
VS Code Setup
Add to your VS Code settings.json:
{
"mcp.servers": {
"devcontainer": {
"command": "devcontainer-mcp-server",
"args": [],
"env": {}
}
}
}
Cursor Setup
Add to your Cursor configuration:
{
"mcp": {
"servers": {
"devcontainer": {
"command": "devcontainer-mcp-server"
}
}
}
}
Claude Desktop Setup
Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:
{
"mcpServers": {
"devcontainer": {
"command": "devcontainer-mcp-server",
"args": []
}
}
}
📚 Usage Examples
Natural Language Prompts
Generate a React TypeScript project:
"Create a React TypeScript project with Tailwind CSS on port 3000"
Python Django with PostgreSQL:
"Python Django web application with PostgreSQL database and Redis cache"
Go microservice:
"Go API server with Gin framework, PostgreSQL database, and Docker support on port 8080"
Full-stack MEAN application:
"MEAN stack development environment with MongoDB, Express, Angular, and Node.js"
Expected Outputs
The system automatically detects technologies and generates appropriate configurations:
- Languages: JavaScript, TypeScript, Python, Go, Rust, Java, PHP, Ruby
- Frameworks: React, Angular, Vue, Express, Django, Flask, Spring, Rails
- Databases: PostgreSQL, MySQL, MongoDB, Redis, SQLite, Elasticsearch
- Tools: Docker, Git, development tools, VS Code extensions
- Ports: Automatic port detection and forwarding
🛠️ Available Tools
1. generate_devcontainer
Generate DevContainer configuration from natural language.
Parameters:
prompt(required): Natural language descriptionworkspaceRoot(optional): Workspace path (default: ".")baseTemplate(optional): Template to start from
2. build_devcontainer
Build container from configuration.
Parameters:
workspaceRoot(optional): Workspace path (default: ".")configPath(optional): Custom config pathrebuild(optional): Force rebuild (default: false)
3. test_devcontainer
Test container functionality.
Parameters:
workspaceRoot(optional): Workspace path (default: ".")testCommands(optional): Custom test commands array
4. list_templates
Show available templates.
Parameters:
category(optional): Filter by category
5. modify_devcontainer
Modify existing configuration.
Parameters:
workspaceRoot(optional): Workspace path (default: ".")modifications(required): Desired changes description
6. get_devcontainer_status
Check container status.
Parameters:
workspaceRoot(optional): Workspace path (default: ".")
📦 Templates
Backend Templates
- nodejs-typescript: Node.js with TypeScript support
- python: Python with common packages and debugging
- go: Go development with standard tooling
- rust: Rust environment with Cargo and debugging
- java: Java with Maven/Gradle support
- php: PHP with Composer and debugging
- ruby: Ruby with Rails support
Frontend Templates
- react: Modern React development stack with TypeScript and Vite
Full-Stack Templates
- mean-stack: MongoDB, Express, Angular, Node.js
- docker-compose: Multi-service development
Universal Templates
- universal: Multi-language development environment
Template Features
Each template includes:
- Appropriate base image and runtime
- Language-specific tools and debuggers
- Recommended VS Code extensions
- Common port forwarding
- Package manager setup commands
🖥️ CLI Tool
The package includes a standalone CLI tool for direct usage:
Generate Configuration
devcontainer-mcp-cli generate "React TypeScript app with Tailwind CSS"
Build Container
devcontainer-mcp-cli build --workspace . --rebuild
Test Container
devcontainer-mcp-cli test --command "npm test" --command "npm run lint"
List Templates
devcontainer-mcp-cli templates --category backend
Check Status
devcontainer-mcp-cli status --workspace .
Modify Configuration
devcontainer-mcp-cli modify "add Redis support and port 6379"
🐛 Troubleshooting
Common Issues
DevContainer CLI not found:
npm install -g @devcontainers/cli
Docker not running:
- Ensure Docker Desktop is running
- Check Docker daemon status:
docker info
Build failures:
- Check devcontainer.json syntax
- Verify base image availability
- Review build logs for specific errors
Permission issues:
- Ensure Docker has proper permissions
- Check file system permissions for workspace
Error Messages
"No suitable template found":
- Try with a more specific prompt
- Use
list_templatesto see available options - Specify a base template explicitly
"DevContainer configuration not found":
- Generate configuration first with
generate_devcontainer - Check
.devcontainer/devcontainer.jsonexists
"Build timeout":
- Check internet connection for image downloads
- Consider using lighter base images
- Increase timeout if needed for large images
📖 API Reference
MCP Protocol Compliance
The server implements the Model Context Protocol specification:
- Tool registration with complete schemas
- Proper request/response handling
- Error responses in MCP format
- Text content responses
Response Format
All tools return structured responses with:
- Success/failure status
- Detailed output and error messages
- Reasoning for configuration choices
- Generated configurations in JSON format
Error Handling
Comprehensive error handling for:
- Invalid configurations
- Build failures
- CLI availability issues
- File system errors
- Network timeouts
🧪 Testing
Run the test suite:
npm test
Run with coverage:
npm run test:coverage
Test specific components:
npm test -- config-generator.test.ts
npm test -- template-manager.test.ts
npm test -- devcontainer-manager.test.ts
🏗️ Development
Project Structure
src/
├── index.ts # Main MCP server
├── config-generator.ts # Natural language processing
├── devcontainer-manager.ts # Container operations
├── template-manager.ts # Template management
├── cli.ts # CLI tool
└── __tests__/ # Test suite
Build and Run
npm run build # Compile TypeScript
npm run dev # Development mode
npm run start # Production mode
npm run lint # Code linting
Adding New Templates
- Edit
src/template-manager.ts - Add template configuration to the templates array
- Include appropriate metadata (languages, frameworks, category)
- Add tests for the new template
- Update documentation
Adding Language Support
- Update language patterns in
config-generator.ts - Add framework detection patterns
- Map to appropriate VS Code extensions
- Create or update templates as needed
- Add test cases
🤝 Contributing
We welcome contributions! Please see our contributing guidelines:
- Fork the repository
- Create a feature branch
- Make your changes with tests
- Ensure all tests pass
- Submit a pull request
Development Workflow
- Install dependencies:
npm install - Run tests:
npm test - Build project:
npm run build - Test CLI:
npm run cli -- --help
📄 License
MIT License - see LICENSE file for details.
🙏 Acknowledgments
- DevContainer CLI for container management
- Model Context Protocol for the protocol specification
- VS Code DevContainers for the container standards