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

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

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

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

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