MCP Full-Stack Server

An MCP (Model Context Protocol) Full-Stack Server implemented in Kotlin that enables AI agents to autonomously build and manage applications.

Overview

This server implements the MCP protocol to provide AI agents with powerful capabilities:

• Filesystem Operations: Secure file reading, writing, and directory management
• Bash Execution: Safe command execution with whitelisting and validation
• GitHub Integration: Version control operations (git commands)
• Knowledge Graph Memory: Persistent memory system for AI context
• Database Connectors: PostgreSQL, MongoDB, and MySQL integration
• Resource Management: Custom documentation and resource handling

Features

✅ Security First

• Path traversal protection
• Command whitelisting
• File size and extension validation
• Dangerous pattern detection

✅ Kubernetes Ready

• Docker support
• Kubernetes manifests included
• Health checks and readiness probes
• Resource limits and requests

✅ Observable

• Structured logging
• Health and readiness endpoints
• Metrics support (planned)

✅ CI/CD Ready

• Automated Docker builds with GitHub Actions
• Docker Hub integration
• Multi-branch deployment support (main/develop)
• Kubernetes deployment automation

Quick Start

Prerequisites

• JDK 21+
• Gradle 8.10+
• Kotlin 2.2.0+

Building

./gradlew build

Running

./gradlew run

Or with custom configuration:

export MCP_HOST=0.0.0.0
export MCP_PORT=3000
export MCP_WORKING_DIR=/workspace
./gradlew run

Running with Docker

docker build -t mcp-fullstack-server -f docker/Dockerfile .
docker run -p 3000:3000 mcp-fullstack-server

Testing

Running Tests

# Run all tests
./gradlew test

# Run specific test class
./gradlew test --tests "BashExecutorTest"

# Run with coverage report
./gradlew test jacocoTestReport

Test Coverage

• Total Tests: 57 tests (53 active, 4 temporarily disabled)
• Pass Rate: 100% of active tests (53/53 passing); 4 tests temporarily disabled
• Coverage by Module:
  • Filesystem: 100%
  • Bash: 100%
  • GitHub: 100%
  • Resources: 100%
  • PostgreSQL: 100%
  • MongoDB: 100%
  • Memory: 71% (2 tests disabled due to JSONL serialization issue)

For detailed testing instructions, see TESTING_GUIDE.md.

Configuration

The server is configured via src/main/resources/application.conf. You can override settings using environment variables:

Server Configuration

• MCP_HOST: Server host (default: 0.0.0.0)
• MCP_PORT: Server port (default: 3000)

Filesystem Configuration

• MCP_ALLOWED_DIRS: Comma-separated list of allowed directories
• MCP_MAX_FILE_SIZE: Maximum file size in bytes (default: 10MB)

Bash Configuration

• MCP_ALLOWED_COMMANDS: Comma-separated list of allowed commands
• MCP_WORKING_DIR: Working directory for bash commands
• MCP_COMMAND_TIMEOUT: Command timeout in seconds (default: 300)

GitHub Configuration

• MCP_REPO_PATH: Path to git repository
• GITHUB_TOKEN: GitHub personal access token

Database Configuration

• POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, POSTGRES_PASSWORD
• MONGODB_CONNECTION_STRING, MONGODB_DB

Memory Configuration

• MCP_MEMORY_PATH: Path for knowledge graph storage

Project Structure

mcp-fullstack-server/
├── src/main/kotlin/com/apptolast/mcp/
│   ├── Application.kt              # Main application entry point
│   ├── server/
│   │   └── ServerConfig.kt         # Configuration management
│   ├── modules/
│   │   ├── filesystem/             # Filesystem operations
│   │   ├── bash/                   # Bash command execution
│   │   ├── github/                 # Git/GitHub integration
│   │   ├── memory/                 # Knowledge graph memory
│   │   ├── database/               # Database connectors
│   │   └── resources/              # Resource management
│   ├── transport/        

... [View full README on GitHub](https://github.com/apptolast/McpServerKotlin#readme)