Nexlayer/nexlayer-mcp

Nexlayer MCP Server

A Model Context Protocol (MCP) server that provides tools for deploying and managing applications on the Nexlayer cloud platform through AI agents.

Features

This MCP server provides 12 essential tools for complete application deployment workflows with AI agent optimization:

Core Deployment Tools

• nexlayer_deploy - Final deployment step (requires prepared YAML with container images)
• nexlayer_extend_deployment - Extend deployment duration using session token
• nexlayer_claim_deployment - Claim ownership of a deployment
• nexlayer_get_schema - Get current YAML schema with LLM-friendly examples and validation
• nexlayer_add_deployment_reservation - Reserve application names to prevent conflicts
• nexlayer_remove_deployment_reservation - Release reserved application names
• nexlayer_get_reservations - List all active deployment reservations
• nexlayer_feedback - Send feedback to Nexlayer team

Repository Analysis Tools

• nexlayer_clone_repo - Clone GitHub repositories for analysis

Container Building Tools

• nexlayer_build_images - Build container images using Kaniko and push to Google Artifact Registry

File Generation Tools

• nexlayer_generate_intelligent_dockerfiles - AI-powered Dockerfile generation with framework detection
• nexlayer_generate_intelligent_yaml - Schema-driven YAML configuration generation

Advanced Features

• Schema-Driven YAML Generation: Automatically fetches and uses current Nexlayer schema
• Dockerfile Overwrite Protection: Automatically skips existing Dockerfiles
• Google Artifact Registry Integration: Built-in authentication and image pushing
• Multi-Framework Support: Detects and optimizes for Node.js, Python, Java, Go, React, Next.js
• AI Agent Optimization: Automatic agent detection and capability-based tool selection
• Comprehensive Logging: Structured logging with session tracking and performance monitoring
• HTTP Transport Support: Direct API access via HTTP endpoints
• Prompt System: 5 comprehensive prompts for deployment guidance

Quick Start

Installation

npm install nexlayer-mcp

Basic Usage

# Start the MCP server
npx nexlayer-mcp

# Or with HTTP transport
HTTP_TRANSPORT=true npx nexlayer-mcp

# With bearer token authentication
HTTP_TRANSPORT=true BEARER_TOKEN=your-secret-token npx nexlayer-mcp

Bearer Token Authentication

When HTTP transport is enabled, you can secure the API endpoints with bearer token authentication:

# Set environment variables
export HTTP_TRANSPORT=true
export BEARER_TOKEN=your-secret-token

# Start server with authentication
npx nexlayer-mcp

API Usage with Authentication:

# All /api endpoints require the Bearer token
curl -H "Authorization: Bearer your-secret-token" \
     http://localhost:3000/api/tools

# Health check (no authentication required)
curl http://localhost:3000/health

Error Responses:

• 401 Unauthorized: Missing or invalid Authorization header
• 403 Forbidden: Invalid Bearer token

Configuration

Add to your MCP client configuration:

{
  "mcpServers": {
    "nexlayer": {
      "command": "npx",
      "args": ["nexlayer-mcp@latest"]
    }
  }
}

Tool Reference

Core Deployment Tools

nexlayer_deploy

Deploy prepared YAML configuration to Nexlayer platform.

Parameters:

• yamlContent (string, required): Complete Nexlayer YAML configuration
• sessionToken (string, optional): Nexlayer session token

Example:

await nexlayer_deploy({
  yamlContent: "apiVersion: v1\nkind: Pod\n...",
  sessionToken: "abc123"
});

nexlayer_extend_deployment

Extend an existing deployment's duration.

Parameters:

• sessionToken (string, required): Session token from original deployment
• applicationName (string, required): Name of the application

nexlayer_claim_deployment

Take ownership of a deployment.

Parameters:

• sessionToken (string, required): Session token from deployment
• applicationName (string, required): Name of the application

nexlayer_get_schema

Get current Nexlayer YAML schema for configuration validation.

Parameters: None

Repository Analysis Tools

nexlayer_clone_repo

Clone a GitHub repository for analysis and deployment.

Parameters:

• repoUrl (string, required): GitHub repository URL
• verbose (boolean, optional): Enable verbose logging

Example:

await nexlayer_clone_repo({
  repoUrl: "https://github.com/username/repo",
  verbose: true
});

Container Building Tools

nexlayer_build_images

Build and push container images using Kaniko.

Parameters:

• repoPath (string, required): Path to repository with Dockerfiles
• verbose (boolean, optional): Enable verbose build logging
• timeout (number, optional): Build timeout in milliseconds (default: 300000)

File Generation Tools

nexlayer_generate_intelligent_dockerfiles

Generate optimized Dockerfiles for repository services.

Parameters:

• repoPath (string, required): Local repository path to analyze
• outputPath (string, optional): Custom output directory for Dockerfiles
• optimizations (object, optional): Build optimization settings

nexlayer_generate_intelligent_yaml

Generate optimized Nexlayer YAML configuration.

Parameters:

• applicationName (string, required): Application name
• repositoryAnalysis (object, optional): Repository analysis data
• builtImages (array, optional): Images built with nexlayer_build_images
• environmentVariables (object, optional): Environment variables to include
• optimizations (object, optional): Deployment optimizations

Deployment Workflow

Manual 5-Step Process

1. Clone Repository

   const cloneResult = await nexlayer_clone_repo({
     repoUrl: "https://github.com/username/repo"
   });
   

2. Generate Dockerfiles

   const dockerfileResult = await nexlayer_generate_intelligent_dockerfiles({
     repoPath: "/tmp/repo-abc123"
   });
   

3. Build Images

   const buildResult = await nexlayer_build_images({
     repoPath: "/tmp/repo-abc123"
   });
   

4. Generate YAML

   const yamlResult = await nexlayer_generate_intelligent_yaml({
     applicationName: "my-app",
     builtImages: buildResult.images
   });
   

5. Deploy

   const deployResult = await nexlayer_deploy({
     yamlContent: yamlResult.content
   });
   

Management Operations

Extend Deployment

await nexlayer_extend_deployment({
  sessionToken: "abc123",
  applicationName: "my-app"
});

Claim Deployment

await nexlayer_claim_deployment({
  sessionToken: "abc123",
  applicationName: "my-app"
});

Get Schema

const schema = await nexlayer_get_schema();

Advanced Configuration

Environment Variables

• HTTP_TRANSPORT: Enable HTTP transport (default: false)
• WEBSOCKET_ENABLED: Enable WebSocket transport (default: true)
• NODE_ENV: Environment mode (development/production)

Google Artifact Registry Authentication

The server includes built-in GAR authentication support:

# Set service account credentials
export GOOGLE_APPLICATION_CREDENTIALS=/path/to/service-account.json
export GCP_PROJECT_ID=your-project-id

# Run with authentication
docker run -e GOOGLE_APPLICATION_CREDENTIALS -e GCP_PROJECT_ID nexlayer-mcp

Development

Project Structure

src/
├── server.ts           # MCP server initialization and agent detection
├── tools/              # Modular tool implementations
│   ├── registry.ts     # Centralized tool registration system
│   ├── core.ts         # Deployment lifecycle tools (8 tools)
│   ├── analysis.ts     # Repository analysis tools (1 tool)
│   ├── kaniko.ts       # Container building tools (1 tool)
│   └── generator.ts    # File generation tools (2 tools)
├── services/           # External service integrations
├── utils/              # Logging, tracing, and utilities
├── prompts/            # AI agent guidance prompts
└── agent/              # AI agent detection and optimization

Adding New Tools

1. Define Tool Interface in types/nexlayer.ts
2. Implement Tool Logic in appropriate module
3. Add Zod Schema for parameter validation
4. Register Tool in module's registerTools() method

Testing

# Run test suite
npm test

# Test specific tool
npm run test:tools

# Test HTTP transport
npm run test:http

Troubleshooting

Common Issues

1. "Kaniko executor not found"

   • Ensure Kaniko is properly installed
   • Check /kaniko/executor path exists

2. "Repository clone failed"

   • Verify repository URL is correct
   • Check repository is public or accessible
   • Ensure network connectivity

3. "Build failed"

   • Check Dockerfiles exist in repository
   • Verify Kaniko executor is available
   • Check registry access and authentication

4. "Deployment failed"

   • Validate YAML configuration
   • Check image URLs are accessible
   • Verify session token is valid

Debug Mode

Enable verbose logging:

await nexlayer_clone_repo({
  repoUrl: "https://github.com/username/repo",
  verbose: true
});

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests
5. Submit a pull request

License

ISC License - see LICENSE file for details.

Support

• Documentation:
• Issues: GitHub Issues
• Feedback: Use nexlayer_feedback tool