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.json configurations

• 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

Development Installation

⚙️ Configuration

VS Code Setup

Add to your VS Code settings.json:

Cursor Setup

Add to your Cursor configuration:

Claude Desktop Setup

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or equivalent:

📚 Usage Examples

Natural Language Prompts

Generate a React TypeScript project:

Python Django with PostgreSQL:

Go microservice:

Full-stack MEAN application:

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 description

• workspaceRoot (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 path

• rebuild (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

Build Container

Test Container

List Templates

Check Status

Modify Configuration

🐛 Troubleshooting

Common Issues

DevContainer CLI not found:

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_templates to see available options

• Specify a base template explicitly

"DevContainer configuration not found":

• Generate configuration first with generate_devcontainer

• Check .devcontainer/devcontainer.json exists

"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:

Run with coverage:

Test specific components:

🏗️ Development

Project Structure

Build and Run

Adding New Templates

1. Edit src/template-manager.ts

2. Add template configuration to the templates array

3. Include appropriate metadata (languages, frameworks, category)

4. Add tests for the new template

5. Update documentation

Adding Language Support

1. Update language patterns in config-generator.ts

2. Add framework detection patterns

3. Map to appropriate VS Code extensions

4. Create or update templates as needed

5. Add test cases

🤝 Contributing

We welcome contributions! Please see our contributing guidelines:

1. Fork the repository

2. Create a feature branch

3. Make your changes with tests

4. Ensure all tests pass

5. Submit a pull request

Development Workflow

1. Install dependencies: npm install

2. Run tests: npm test

3. Build project: npm run build

4. 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