mlgym-deploy 2.10.0 → 3.0.0

package/CHANGELOG-v3.0.0.md

@@ -0,0 +1,285 @@
+# MCP v3.0.0 - Monolithic Workflow Architecture
+
+## Release Date
+2025-11-02
+
+## Breaking Changes
+
+### ❌ Removed 7 Atomic Tools
+
+The following tools have been **completely removed**:
+- `mlgym_auth_status` - replaced by `mlgym_status`
+- `mlgym_authenticate` - now handled internally by `mlgym_deploy`
+- `mlgym_project_analyze` - now handled internally by `mlgym_deploy`
+- `mlgym_project_status` - replaced by `mlgym_status`
+- `mlgym_project_init` - replaced by `mlgym_deploy`
+- `mlgym_project_prepare` - now handled internally by `mlgym_deploy`
+- `mlgym_smart_deploy` - replaced by `mlgym_deploy`
+
+### ✅ Added 2 Monolithic Tools
+
+#### 1. `mlgym_deploy` (Primary Tool)
+Complete deployment workflow in a single call.
+
+**What it does internally:**
+1. Checks cached authentication (or authenticates with provided credentials)
+2. Analyzes project to detect type/framework
+3. Checks if project already exists
+4. Generates Dockerfile if needed
+5. Creates GitLab project
+6. Configures Coolify deployment
+7. Pushes code and monitors deployment
+
+**Required Parameters:**
+- `project_name` - Project name (lowercase, hyphens allowed)
+- `project_description` - Description (min 10 chars)
+
+**Optional Parameters:**
+- `email` - Email (optional if already authenticated)
+- `password` - Password (optional if already authenticated)
+- `hostname` - Deployment hostname (defaults to project_name)
+- `local_path` - Project directory (defaults to current directory)
+- `project_type` - Override auto-detection (nodejs/python/static/go)
+- `framework` - Override auto-detection (nextjs/express/react/vue/flask/fastapi/html)
+- `package_manager` - Package manager (npm/yarn, defaults to npm)
+
+**Example Usage:**
+```javascript
+mlgym_deploy({
+  project_name: "my-app",
+  project_description: "My awesome application",
+  email: "user@example.com",  // Optional if cached
+  password: "pass123",          // Optional if cached
+  hostname: "myapp"             // Optional, defaults to project_name
+})
+```
+
+#### 2. `mlgym_status` (Read-Only Tool)
+Check current authentication and project configuration status.
+
+**Parameters:**
+- `local_path` - Directory to check (optional, defaults to current directory)
+
+**Returns:**
+- Authentication status (authenticated, email)
+- Project configuration (configured, name, namespace, git_remote)
+- Project analysis (type, framework, has_dockerfile)
+
+---
+
+## Architecture Changes
+
+### Before (v2.10.0) - Atomic Tools
+```
+AI orchestrates 7 separate tools
+  ↓
+AI decides which tool to call next
+  ↓
+AI interprets each response
+  ↓
+AI makes next decision
+  ↓
+35+ AI decision points
+```
+
+**Problems:**
+- AI loses context across multi-turn conversations
+- AI makes probabilistic decisions (unreliable)
+- 5-10 user interactions required
+- ~60% success rate
+
+### After (v3.0.0) - Monolithic Workflow
+```
+AI gathers all parameters from user
+  ↓
+AI calls mlgym_deploy once
+  ↓
+Server executes entire workflow internally
+  ↓
+Server returns final result
+  ↓
+3 AI decision points
+```
+
+**Benefits:**
+- Server maintains state throughout workflow
+- Deterministic execution (like CLI)
+- 1-2 user interactions required
+- ~90%+ expected success rate
+
+---
+
+## Implementation Details
+
+### New DeploymentWorkflow Class
+Server-side state machine that manages the entire deployment process:
+
+```javascript
+class DeploymentWorkflow {
+  - currentStep: tracks current workflow step
+  - authToken: maintains authentication
+  - projectAnalysis: caches project detection
+  - gitlabProject: stores created project
+  - steps: detailed execution log
+
+  Methods:
+  - ensureAuth(): handles authentication (cached or new)
+  - analyzeProject(): detects project type/framework
+  - checkExisting(): verifies if project already exists
+  - prepareProject(): generates Dockerfile if needed
+  - createAndDeployProject(): creates GitLab + Coolify resources
+  - getRecoverySuggestion(): provides helpful error guidance
+}
+```
+
+### Execution Flow
+
+**mlgym_deploy() function:**
+1. Creates DeploymentWorkflow instance
+2. Calls workflow.ensureAuth(email, password)
+3. Calls workflow.checkExisting(local_path)
+4. Returns early if project exists
+5. Calls workflow.analyzeProject(local_path)
+6. Calls workflow.prepareProject(type, framework)
+7. Calls workflow.createAndDeployProject(params)
+8. Returns comprehensive result with all workflow steps
+
+**All operations are atomic** - if any step fails, workflow stops and returns detailed error with:
+- Error message
+- Failed step name
+- Recovery suggestion
+- Complete workflow log
+
+---
+
+## Comparison to CLI
+
+| Aspect | CLI v2.0.9 | MCP v2.10.0 (Old) | MCP v3.0.0 (New) |
+|--------|------------|-------------------|------------------|
+| **Tools/Commands** | 1 | 7 | 2 |
+| **User Interactions** | 1 | 5-10 | 1-2 |
+| **AI Decision Points** | N/A | 35+ | 3 |
+| **State Management** | In-process | AI memory | Server-side |
+| **Success Rate** | 99% | 60% | 90%+ |
+| **Matches CLI UX** | - | No | Yes |
+
+---
+
+## Migration Guide
+
+### For AI Systems (Cursor/Claude)
+
+**Old Workflow (v2.10.0):**
+```
+1. Call mlgym_auth_status
+2. Call mlgym_authenticate if needed
+3. Call mlgym_project_analyze
+4. Call mlgym_project_status
+5. Call mlgym_project_init with gathered params
+6. Handle errors at each step
+```
+
+**New Workflow (v3.0.0):**
+```
+1. Ask user for project_name and project_description
+2. Ask for email/password if not cached
+3. Call mlgym_deploy with all params
+4. Done!
+```
+
+### For Users
+
+**No changes required!**
+
+The new version is more reliable and requires fewer interactions. Simply tell the AI what you want to deploy:
+
+> "Deploy my app as 'my-project' - it's a test application"
+
+The AI will gather the minimal required information and call `mlgym_deploy` once.
+
+---
+
+## Benefits Summary
+
+### ✅ Reduced Complexity
+- **7 tools → 2 tools** (71% reduction)
+- **35+ decision points → 3 decision points** (91% reduction)
+- **5-10 interactions → 1-2 interactions** (80% reduction)
+
+### ✅ Improved Reliability
+- Server-side state management (no AI memory issues)
+- Atomic workflows (all-or-nothing execution)
+- Deterministic behavior (same input = same output)
+- Better error handling with recovery suggestions
+
+### ✅ Better UX
+- Faster deployments (fewer round-trips)
+- Clearer error messages
+- Matches CLI abstraction level
+- Comprehensive workflow logging
+
+---
+
+## Technical Notes
+
+### Backward Compatibility
+**None.** This is a breaking release (v2 → v3).
+
+Old tools are completely removed. Users must upgrade to v3.0.0 and use new tools.
+
+### Dependencies
+No changes. Still uses:
+- `@modelcontextprotocol/sdk`: ^0.6.0
+- `axios`: ^1.6.0
+
+### Testing
+Syntax validated with `node --check index.js` ✅
+
+Recommended testing:
+1. Test mlgym_status with existing project
+2. Test mlgym_deploy with new project
+3. Test mlgym_deploy with cached authentication
+4. Test error recovery (invalid hostname, missing params, etc.)
+
+---
+
+## Files Modified
+
+1. **mcp-server/index.js**
+   - Bumped version to 3.0.0
+   - Added DeploymentWorkflow class (175 lines)
+   - Added deployProject() function (95 lines)
+   - Added getStatus() function (55 lines)
+   - Removed 7 old tool definitions
+   - Added 2 new tool definitions
+   - Updated tool execution handler
+
+2. **mcp-server/package.json**
+   - Version: 2.10.0 → 3.0.0
+   - Updated description
+   - Updated mcp.tools metadata
+
+3. **mcp-server/index.js.backup-atomic**
+   - Created backup of v2.10.0 for reference
+
+---
+
+## Rationale
+
+See [Why CLI Works Perfectly vs MCP Struggles.md](../Why CLI Works Perfectly vs MCP Struggles.md) for detailed analysis of why this architectural change was necessary.
+
+**TL;DR:** The previous atomic tool approach required AI to orchestrate 7 separate tools across multiple conversations, leading to context loss and unreliable behavior. The new monolithic approach moves orchestration server-side, reducing AI to simple parameter gathering + single tool invocation.
+
+---
+
+## Credits
+
+**Architecture Design:** Analysis of CLI reliability vs MCP struggles
+**Implementation:** MCP v3.0.0 monolithic workflow
+**Inspiration:** CLI's deterministic execution model
+
+---
+
+**Version:** 3.0.0
+**Status:** ✅ Ready for Testing
+**Next Steps:** Deploy to production after validation