mlgym-deploy 3.3.42 → 3.3.44

package/README.md

@@ -32,12 +32,47 @@ Configure in your MCP client settings:
 
 ## Configuration
 
+### For Published Package (Production)
+
 Set the backend URL via environment variable:
 
 ```bash
 export MLGYM_BACKEND_URL=https://backend.eu.ezb.net
 ```
 
+### For Local Development
+
+When developing locally, you'll need to configure the MCP server with absolute paths. Configuration files are user-specific and not tracked in git.
+
+1. **Copy example files** to create your local config:
+
+```bash
+cp cursor-config.json.example cursor-config.json
+cp mcp.json.example mcp.json
+cp claude-desktop-config.json.example claude-desktop-config.json
+cp ADD_TO_CURSOR_SETTINGS.json.example ADD_TO_CURSOR_SETTINGS.json
+```
+
+2. **Update the path** in your config file with your absolute path:
+
+```json
+{
+  "mcpServers": {
+    "gitlab-backend": {
+      "command": "node",
+      "args": ["/your/absolute/path/to/mcp-server/index.js"],
+      "env": {
+        "GITLAB_BACKEND_URL": "https://backend.eu.ezb.net",
+        "GITLAB_URL": "https://git.mlgym.io",
+        "COOLIFY_URL": "https://coolify.eu.ezb.net"
+      }
+    }
+  }
+}
+```
+
+**Note:** Absolute paths are required because the IDE launches the MCP server from its own working directory, not the project directory. Relative paths won't work.
+
 ## License
 
 MIT

package/claude-desktop-config.json

@@ -2,7 +2,7 @@
   "mcpServers": {
     "gitlab-backend": {
       "command": "node",
-      "args": ["/home/chka/NetBeansProjects/gitlab_backend/mcp-server/index.js"]
+      "args": ["/home/sreedhar/Work/Projects/mlgym/gitlab_backend/mcp-server/index.js"]
     }
   }
 }

package/claude-desktop-config.json.example

@@ -0,0 +1,8 @@
+{
+  "mcpServers": {
+    "gitlab-backend": {
+      "command": "node",
+      "args": ["/path/to/your/gitlab_backend/mcp-server/index.js"]
+    }
+  }
+}

package/cursor-config.json

@@ -2,7 +2,7 @@
   "mcp.servers": {
     "gitlab-backend": {
       "command": "node",
-      "args": ["/home/chka/NetBeansProjects/gitlab_backend/mcp-server/index.js"],
+      "args": ["/home/sreedhar/Work/Projects/mlgym/gitlab_backend/mcp-server/index.js"],
       "env": {
         "GITLAB_BACKEND_URL": "https://backend.eu.ezb.net",
         "GITLAB_URL": "https://git.mlgym.io",

package/cursor-config.json.example

@@ -0,0 +1,13 @@
+{
+  "mcp.servers": {
+    "gitlab-backend": {
+      "command": "node",
+      "args": ["/path/to/your/gitlab_backend/mcp-server/index.js"],
+      "env": {
+        "GITLAB_BACKEND_URL": "https://backend.eu.ezb.net",
+        "GITLAB_URL": "https://git.mlgym.io",
+        "COOLIFY_URL": "https://coolify.eu.ezb.net"
+      }
+    }
+  }
+}

package/docs/CURSOR_SETUP.md

@@ -0,0 +1,204 @@
+# MCP Setup Guide for Cursor IDE
+
+## Prerequisites
+✅ Node.js installed
+✅ MCP dependencies installed (already done)
+✅ Cursor IDE with MCP support
+
+## Setup Instructions
+
+### 1. Configure MCP in Cursor
+
+Open Cursor Settings (Cmd/Ctrl+,) and add the MCP server configuration:
+
+```json
+{
+  "mcp.servers": {
+    "mlgym-deploy": {
+      "command": "node",
+      "args": ["${workspaceFolder}/mcp-server/index.js"],
+      "env": {
+        "GITLAB_BACKEND_URL": "https://backend.eu.ezb.net",
+        "GITLAB_URL": "https://git.mlgym.io",
+        "COOLIFY_URL": "https://coolify.eu.ezb.net"
+      }
+    }
+  }
+}
+```
+
+### 2. Using MCP Tools in Cursor
+
+Once MCP is configured, you can use these commands directly in Cursor chat:
+
+```
+@mcp mlgym_user_create    - Create a new user account
+@mcp mlgym_auth_login     - Login with existing credentials
+@mcp mlgym_deploy         - Deploy a project (recommended)
+@mcp mlgym_status         - Check deployment status
+@mcp mlgym_deploy_logs    - View deployment logs
+```
+
+### 3. MCP Tool Details
+
+#### mlgym_user_create
+Creates a complete user account with:
+- GitLab account
+- Coolify account
+- SSH key generation and registration
+- Authentication token storage
+
+**Parameters:**
+- `email` (required): User email address
+- `name` (required): User full name
+- `password` (required): User password (min 8 characters)
+- `accept_terms` (required): Must be `true`
+
+**Example:**
+```json
+{
+  "email": "user@example.com",
+  "name": "John Doe",
+  "password": "SecurePass123!",
+  "accept_terms": true
+}
+```
+
+#### mlgym_auth_login
+Login with existing user credentials to get authentication token.
+
+**Parameters:**
+- `email` (required): Email address
+- `password` (required): Password
+
+**Example:**
+```json
+{
+  "email": "user@example.com",
+  "password": "SecurePass123!"
+}
+```
+
+#### mlgym_deploy (RECOMMENDED)
+Complete deployment workflow in one call. Automatically authenticates (uses cached token if available), analyzes project, creates GitLab repo, and deploys to Coolify.
+
+**Parameters:**
+- `project_name` (required): Project name (lowercase alphanumeric with hyphens, e.g., "my-app")
+- `project_description` (required): Brief project description (min 10 characters)
+- `email` (optional): Email for authentication (if not already authenticated)
+- `password` (optional): Password (if not already authenticated)
+- `hostname` (optional): Custom hostname
+- `local_path` (optional): Local project directory path (defaults to current directory)
+- `project_type` (optional): Override auto-detected type (nodejs, python, static, go)
+- `framework` (optional): Override auto-detected framework (nextjs, express, react, vue, flask, fastapi, html)
+
+**Example:**
+```json
+{
+  "project_name": "my-awesome-app",
+  "project_description": "A simple Node.js application",
+  "email": "user@example.com",
+  "password": "SecurePass123!",
+  "local_path": "."
+}
+```
+
+#### Other Available Tools
+
+- **mlgym_status**: Check deployment status and project configuration
+- **mlgym_deploy_logs**: View deployment logs (requires project_name)
+- **mlgym_set_env_vars**: Set environment variables for deployment
+- **mlgym_set_health_check**: Configure health check endpoints
+- **mlgym_set_domain**: Set custom domain for deployment
+- **mlgym_set_deployment_commands**: Configure build/start commands
+- **mlgym_deploy_manual**: Manual deployment trigger
+- **mlgym_set_options**: Configure deployment options
+- **mlgym_rollback**: Rollback to previous deployment
+- **mlgym_help**: Get help on available tools
+
+### 4. Typical Workflow
+
+#### First-time User
+1. Create account: `@mcp mlgym_user_create`
+2. Deploy project: `@mcp mlgym_deploy` (includes authentication)
+
+#### Existing User
+1. Login: `@mcp mlgym_auth_login` (or use credentials in mlgym_deploy)
+2. Deploy project: `@mcp mlgym_deploy`
+3. Check status: `@mcp mlgym_status`
+4. View logs: `@mcp mlgym_deploy_logs`
+
+### 5. Testing MCP Connection
+
+Test that MCP is working:
+```bash
+# Test the MCP server directly
+node mcp-server/index.js
+
+# Should output the MCP protocol initialization message
+```
+
+### 6. Authentication
+
+MCP stores authentication tokens in `~/.mlgym/mcp_config.json` automatically after:
+- First user creation (`mlgym_user_create`)
+- Successful login (`mlgym_auth_login`)
+- Successful deployment with credentials (`mlgym_deploy`)
+
+### 7. Troubleshooting
+
+If MCP tools don't appear in Cursor:
+1. Restart Cursor after configuration
+2. Check the MCP server is accessible:
+   ```bash
+   node mcp-server/index.js
+   ```
+3. Verify settings in Cursor preferences (look for "mcp.servers")
+4. Check Cursor logs for MCP errors (View → Output → MCP)
+5. Ensure you're using Cursor with MCP support (latest version)
+
+### 8. Debug Mode
+
+Debug logging is enabled by default. To see detailed output:
+```bash
+# Start Cursor from terminal to see MCP logs
+cd ~/your-project
+cursor .
+```
+
+See [DEBUG.md](./DEBUG.md) for more details on debug logging.
+
+## Environment Variables
+
+The MCP server uses these production endpoints:
+- **Backend**: https://backend.eu.ezb.net
+- **GitLab**: https://git.mlgym.io
+- **Coolify**: https://coolify.eu.ezb.net
+
+These are pre-configured in the MCP server configuration.
+
+## Quick Test
+
+```bash
+# In Cursor terminal, test user creation
+echo '{
+  "jsonrpc": "2.0",
+  "method": "tools/call",
+  "params": {
+    "name": "mlgym_user_create",
+    "arguments": {
+      "email": "test@example.com",
+      "name": "Test User",
+      "password": "TestPass123!",
+      "accept_terms": true
+    }
+  },
+  "id": 1
+}' | node mcp-server/index.js
+```
+
+## Additional Resources
+
+- [Debug Guide](./DEBUG.md) - Enable and configure debug logging
+- [Test Results](../tests/TEST_RESULTS.md) - Current test coverage and results
+- Production Backend: https://backend.eu.ezb.net

package/docs/NPM_RELEASE.md

@@ -0,0 +1,230 @@
+# NPM Release Procedure
+
+This document describes how to publish the `mlgym-deploy` MCP server package to npm.
+
+## Prerequisites
+
+- npm account with publish access to `mlgym-deploy` package
+- npm access token (preferred method)
+- Package version must be incremented before publishing
+
+## Authentication Methods
+
+### Method 1: Access Token (Recommended) ✅
+
+Using an access token is **preferred** because:
+- ✅ No 2FA/OTP required during publish
+- ✅ Faster and more automated
+- ✅ Works in CI/CD pipelines
+- ✅ Can be revoked/rotated easily
+- ✅ Suitable for scripted deployments
+
+#### Setup Access Token
+
+1. **Configure token locally:**
+   ```bash
+   npm config set //registry.npmjs.org/:_authToken <YOUR_TOKEN>
+   ```
+
+2. **Verify authentication:**
+   ```bash
+   npm whoami
+   # Should output: chka_s5
+   ```
+
+3. **Publish:**
+   ```bash
+   cd mcp-server
+   npm publish
+   ```
+
+### Method 2: OTP/2FA (Alternative)
+
+If you don't have an access token, you can use 2FA:
+
+```bash
+npm publish --otp=<6-DIGIT-CODE>
+```
+
+**Downsides:**
+- Requires manual 2FA code entry each time
+- Codes expire quickly (30 seconds)
+- Not suitable for automation
+- Slower workflow
+
+## Release Workflow
+
+### Step 1: Increment Version
+
+Edit `mcp-server/package.json` and `mcp-server/index.js`:
+
+```json
+{
+  "version": "3.3.44"
+}
+```
+
+```javascript
+const CURRENT_VERSION = '3.3.44';  // Update with change description
+```
+
+### Step 2: Update CHANGELOG (if exists)
+
+Document what changed in this release.
+
+### Step 3: Commit Changes
+
+```bash
+git add mcp-server/package.json mcp-server/index.js
+git commit -m "Bump version to 3.3.44
+
+- Description of changes
+- What was fixed/added/improved"
+```
+
+### Step 4: Publish to npm
+
+**Using Access Token (Recommended):**
+
+```bash
+cd mcp-server
+npm publish
+```
+
+**Using OTP:**
+
+```bash
+cd mcp-server
+npm publish --otp=123456
+```
+
+### Step 5: Verify Publication
+
+```bash
+# Check latest version
+npm view mlgym-deploy version
+
+# Check publication time
+npm view mlgym-deploy time.modified
+
+# Test installation
+npm install -g mlgym-deploy@latest
+mlgym-mcp --help
+```
+
+### Step 6: Tag Release (Optional)
+
+```bash
+git tag -a v3.3.44 -m "Release v3.3.44"
+git push origin v3.3.44
+```
+
+## NPM Access Token Management
+
+### Current Token
+
+**Token:** `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`
+**User:** chka_s5
+**Scope:** Publish access to mlgym-deploy
+
+### Token Storage
+
+**Local config (recommended for development):**
+```bash
+npm config set //registry.npmjs.org/:_authToken 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
+```
+
+**Per-project .npmrc (not recommended - security risk):**
+```
+//registry.npmjs.org/:_authToken=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
+```
+⚠️ **Never commit .npmrc with tokens to git!**
+
+**Environment variable (good for CI/CD):**
+```bash
+export NPM_TOKEN=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
+echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+```
+
+### Revoking a Token
+
+If token is compromised:
+
+1. Login to npmjs.com
+2. Go to Account Settings → Access Tokens
+3. Find the token and click "Delete"
+4. Generate a new token
+5. Update local config with new token
+
+## Common Issues
+
+### Issue: "npm ERR! code E404"
+
+**Cause:** Package name doesn't exist or you don't have access
+**Solution:** Verify package name and permissions
+
+### Issue: "npm ERR! code EOTP"
+
+**Cause:** 2FA required but not provided
+**Solution:** Use access token method instead of OTP
+
+### Issue: "npm ERR! 403 Forbidden"
+
+**Cause:** Invalid or expired token
+**Solution:** Regenerate access token
+
+### Issue: "Version already exists"
+
+**Cause:** Version number in package.json hasn't been incremented
+**Solution:** Bump version before publishing
+
+### Issue: "npm auto-corrected some errors"
+
+**Cause:** package.json formatting issues
+**Solution:** Run `npm pkg fix` and commit the changes
+
+## Automated CI/CD Publishing
+
+For GitLab CI/CD pipeline:
+
+```yaml
+publish_npm:
+  stage: publish
+  only:
+    - tags
+  script:
+    - cd mcp-server
+    - echo "//registry.npmjs.org/:_authToken=${NPM_TOKEN}" > ~/.npmrc
+    - npm publish
+  variables:
+    NPM_TOKEN: $NPM_TOKEN  # Set in GitLab CI/CD variables
+```
+
+## Version History
+
+| Version | Date | SDK Version | Notable Changes |
+|---------|------|-------------|-----------------|
+| 3.3.43  | 2026-01-22 | 1.25.3 | SDK security upgrade, contact info |
+| 3.3.42  | 2025-XX-XX | 0.6.1  | deploy_dollie tool |
+| 3.0.0   | 2024-XX-XX | 0.6.0  | Monolithic workflows |
+
+## Quick Reference
+
+```bash
+# Configure token (one-time setup)
+npm config set //registry.npmjs.org/:_authToken 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
+
+# Verify auth
+npm whoami
+
+# Publish
+cd mcp-server && npm publish
+
+# Verify publication
+npm view mlgym-deploy version
+```
+
+---
+
+**Last Updated:** 2026-01-22
+**Maintainer:** chka_s5 (operations@stratus5.com)

package/index.js

@@ -18,7 +18,7 @@ import crypto from 'crypto';
 const execAsync = promisify(exec);
 
 // Current version of this MCP server - INCREMENT FOR WORKFLOW FIXES
-const CURRENT_VERSION = '3.3.42';  // Add deploy_dollie tool for Next.js dev containers with SSH
+const CURRENT_VERSION = '3.3.44';  // Update README with installation and configuration instructions
 const PACKAGE_NAME = 'mlgym-deploy';
 
 // Debug logging configuration - ENABLED BY DEFAULT
@@ -90,7 +90,13 @@ const CONFIG = {
   backend_url: process.env.MLGYM_API_ENDPOINT || 'https://backend.eu.ezb.net',
   gitlab_url: 'https://git.mlgym.io',
   coolify_url: 'https://coolify.eu.ezb.net',
-  config_file: path.join(os.homedir(), '.mlgym', 'mcp_config.json')
+  config_file: path.join(os.homedir(), '.mlgym', 'mcp_config.json'),
+
+  // Contact information (user-facing)
+  contact: {
+    support_email: 'operations@stratus5.com',
+    docs_url: 'https://mlgym.info'
+  }
 };
 
 // Helper to load/save authentication
@@ -4619,8 +4625,7 @@ Examples show both what users say AND the tool call that gets executed.
 💡 Most parameters are optional with sensible defaults
 
 📚 Documentation: https://mlgym.info
-🌐 Backend: https://backend.eu.ezb.net
-📊 Dashboard: https://platform.mlgym.info
+📧 Support: operations@stratus5.com
 `;
 
   return {

package/mcp.json.example

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "gitlab-backend": {
+      "command": "node",
+      "args": ["/path/to/your/gitlab_backend/mcp-server/index.js"],
+      "env": {
+        "GITLAB_BACKEND_URL": "https://backend.eu.ezb.net",
+        "GITLAB_URL": "https://git.mlgym.io",
+        "COOLIFY_URL": "https://coolify.eu.ezb.net"
+      }
+    }
+  }
+}

package/package.json

@@ -1,11 +1,11 @@
 {
   "name": "mlgym-deploy",
-  "version": "3.3.42",
+  "version": "3.3.44",
   "description": "MCP server for MLGym - Complete deployment management: deploy, configure, monitor, and rollback applications",
   "main": "index.js",
   "type": "module",
   "bin": {
-    "mlgym-mcp": "./index.js"
+    "mlgym-mcp": "index.js"
   },
   "scripts": {
     "start": "node index.js"
@@ -20,13 +20,17 @@
   ],
   "author": "MLGym Team",
   "license": "MIT",
+  "engines": {
+    "node": ">=18.0.0"
+  },
   "repository": {
     "type": "git",
     "url": "git@code.stratus5.com:chka/gitlab_backend.git"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^0.6.0",
-    "axios": "^1.6.0"
+    "@modelcontextprotocol/sdk": "^1.25.3",
+    "axios": "^1.6.0",
+    "package": "*"
   },
   "mcp": {
     "name": "MLGym Deploy",