@programinglive/dev-workflow-mcp-server 1.8.1 → 1.9.1

package/docs/GCP_DEPLOYMENT.md

@@ -1,298 +0,0 @@
-# Deploying to Google Cloud Platform with Docker
-
-This guide walks you through deploying the dev-workflow MCP server to Google Cloud Compute Engine using Docker and PostgreSQL.
-
-## Prerequisites
-
-- Google Cloud Platform account with a Compute Engine instance running
-- SSH access to your GCP instance
-- Git installed locally and on GCP instance
-- Basic familiarity with Docker and SSH
-
-## Architecture Overview
-
-The deployment consists of two Docker containers:
-- **MCP Server**: Node.js application running the dev-workflow MCP server
-- **PostgreSQL**: Database for persistent workflow state storage
-
-Communication between your local MCP client and the cloud server happens via SSH tunneling.
-
-## Step 1: Prepare Your GCP Instance
-
-### 1.1 SSH into Your Instance
-
-```bash
-ssh your-username@YOUR_GCP_IP
-```
-
-### 1.2 Run the Setup Script
-
-From your local machine, copy the setup script to your GCP instance:
-
-```bash
-scp scripts/setup-gcp-instance.sh your-username@YOUR_GCP_IP:~/
-ssh your-username@YOUR_GCP_IP 'bash ~/setup-gcp-instance.sh'
-```
-
-This script will:
-- Install Docker and Docker Compose
-- Install Git
-- Create the application directory
-
-**Note**: You may need to log out and back in for Docker group permissions to take effect.
-
-## Step 2: Deploy the Application
-
-### 2.1 Clone the Repository
-
-On your GCP instance:
-
-```bash
-cd ~/dev-workflow-mcp-server
-git clone https://github.com/programinglive/dev-workflow-mcp-server.git .
-```
-
-### 2.2 Configure Environment Variables
-
-Create a `.env` file from the production template:
-
-```bash
-cp .env.production .env
-nano .env
-```
-
-Update the following values:
-- `POSTGRES_PASSWORD`: Set a strong, unique password
-- `DEV_WORKFLOW_DB_URL`: Update with the same password
-- `DEV_WORKFLOW_USER_ID`: (Optional) Set your username
-
-Example `.env`:
-```bash
-DEV_WORKFLOW_DB_TYPE=postgres
-DEV_WORKFLOW_DB_URL=postgres://devworkflow:MySecureP@ssw0rd@postgres:5432/devworkflow
-POSTGRES_PASSWORD=MySecureP@ssw0rd
-DEV_WORKFLOW_USER_ID=dhika
-NODE_ENV=production
-```
-
-### 2.3 Start the Containers
-
-```bash
-docker-compose up -d
-```
-
-### 2.4 Verify Deployment
-
-Check that both containers are running:
-
-```bash
-docker-compose ps
-```
-
-You should see:
-```
-NAME                      STATUS
-dev-workflow-mcp          Up
-dev-workflow-postgres     Up (healthy)
-```
-
-View logs:
-```bash
-docker-compose logs -f mcp-server
-```
-
-## Step 3: Configure Local MCP Client
-
-Update your local MCP client configuration to connect via SSH.
-
-### Windows (Claude Desktop)
-
-Edit `C:\Users\DHIKA\.gemini\antigravity\mcp_config.json`:
-
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "ssh",
-      "args": [
-        "-i", "C:\\Users\\DHIKA\\.ssh\\id_rsa",
-        "your-username@34.50.121.142",
-        "docker", "exec", "-i", "dev-workflow-mcp", "node", "/app/index.js"
-      ]
-    }
-  }
-}
-```
-
-### Linux/Mac
-
-Edit your MCP config file:
-
-```json
-{
-  "mcpServers": {
-    "dev-workflow": {
-      "command": "ssh",
-      "args": [
-        "-i", "/home/user/.ssh/id_rsa",
-        "your-username@34.50.121.142",
-        "docker", "exec", "-i", "dev-workflow-mcp", "node", "/app/index.js"
-      ]
-    }
-  }
-}
-```
-
-**Important**: Replace:
-- `your-username` with your actual GCP username
-- `34.50.121.142` with your actual GCP external IP
-- SSH key path with your actual key location
-
-## Step 4: Test the Connection
-
-### 4.1 Test SSH Connection
-
-From your local machine:
-
-```bash
-ssh your-username@34.50.121.142 'docker exec -i dev-workflow-mcp node /app/index.js call get_workflow_status'
-```
-
-You should see the workflow status output.
-
-### 4.2 Test via MCP Client
-
-Restart your MCP client (e.g., Claude Desktop) and try using a dev-workflow command like `start_task`.
-
-## Updating the Deployment
-
-### Automated Deployment
-
-Use the deployment script from your local machine:
-
-```bash
-# Set environment variables
-export GCP_USER=your-username
-export GCP_HOST=34.50.121.142
-export GCP_SSH_KEY=~/.ssh/id_rsa
-
-# Run deployment
-bash scripts/deploy-gcp.sh
-```
-
-### Manual Update
-
-On your GCP instance:
-
-```bash
-cd ~/dev-workflow-mcp-server
-git pull origin main
-docker-compose down
-docker-compose build --no-cache
-docker-compose up -d
-```
-
-## Database Management
-
-### Backup Database
-
-```bash
-docker exec dev-workflow-postgres pg_dump -U devworkflow devworkflow > backup.sql
-```
-
-### Restore Database
-
-```bash
-cat backup.sql | docker exec -i dev-workflow-postgres psql -U devworkflow devworkflow
-```
-
-### Access PostgreSQL Console
-
-```bash
-docker exec -it dev-workflow-postgres psql -U devworkflow devworkflow
-```
-
-Common commands:
-- `\dt` - List tables
-- `\d table_name` - Describe table
-- `SELECT * FROM workflow_state;` - View workflow data
-
-## Troubleshooting
-
-### Container Won't Start
-
-Check logs:
-```bash
-docker-compose logs mcp-server
-docker-compose logs postgres
-```
-
-### Database Connection Issues
-
-Verify PostgreSQL is healthy:
-```bash
-docker-compose ps
-docker exec dev-workflow-postgres pg_isready -U devworkflow
-```
-
-### SSH Connection Fails
-
-Test basic SSH:
-```bash
-ssh -v your-username@YOUR_GCP_IP
-```
-
-Check SSH key permissions:
-```bash
-chmod 600 ~/.ssh/id_rsa
-```
-
-### MCP Client Can't Connect
-
-1. Verify SSH works: `ssh your-username@YOUR_GCP_IP 'echo test'`
-2. Test Docker exec: `ssh your-username@YOUR_GCP_IP 'docker ps'`
-3. Check MCP server: `ssh your-username@YOUR_GCP_IP 'docker logs dev-workflow-mcp'`
-
-## Security Best Practices
-
-1. **Change Default Passwords**: Always use strong, unique passwords in `.env`
-2. **Firewall Configuration**: Only expose necessary ports (SSH port 22)
-3. **SSH Key Authentication**: Disable password authentication, use SSH keys only
-4. **Regular Updates**: Keep Docker images and system packages updated
-5. **Backup Regularly**: Schedule automated database backups
-
-## Performance Optimization
-
-### Monitor Resource Usage
-
-```bash
-docker stats
-```
-
-### Increase PostgreSQL Performance
-
-Edit `docker-compose.yml` to add PostgreSQL tuning:
-
-```yaml
-postgres:
-  environment:
-    POSTGRES_SHARED_BUFFERS: 256MB
-    POSTGRES_EFFECTIVE_CACHE_SIZE: 1GB
-```
-
-## Uninstalling
-
-To completely remove the deployment:
-
-```bash
-cd ~/dev-workflow-mcp-server
-docker-compose down -v  # -v removes volumes (deletes data!)
-cd ~
-rm -rf dev-workflow-mcp-server
-```
-
-## Support
-
-For issues or questions:
-- GitHub Issues: https://github.com/programinglive/dev-workflow-mcp-server/issues
-- Documentation: https://devworkflow.programinglive.com/

package/docs/NETLIFY_DEPLOYMENT.md

@@ -1,125 +0,0 @@
-# Netlify Deployment Guide
-
-Deploy the Dev Workflow web dashboard to Netlify for a public-facing documentation and demo site.
-
-## Overview
-
-The web dashboard can be deployed to Netlify as a static Next.js application. This deployment mode provides:
-
-- **Static documentation pages** - Full access to the `/docs` section
-- **Demo interface** - Showcase the workflow features
-- **API endpoints** - Serverless functions for version and npm download stats
-
-> **Note:** Database features (history, summary) return placeholder data in this deployment mode. For full functionality with persistent data, use the [local development server](./web-dashboard.md) or [Plesk deployment](./PLESK_DEPLOYMENT.md).
-
-## Live Site
-
-The official deployment is available at:
-- **Primary:** https://devworkflow.programinglive.com
-- **Netlify:** https://devworkflow.netlify.app
-
-## Prerequisites
-
-- Netlify account (free tier works)
-- Node.js 18+ for local builds
-- Git repository connected to Netlify (optional, for auto-deploy)
-
-## Quick Deploy
-
-### Option 1: Netlify CLI
-
-```bash
-# Install Netlify CLI
-npm install -g netlify-cli
-
-# Login to Netlify
-netlify login
-
-# Navigate to web directory
-cd web
-
-# Create new site and deploy
-netlify sites:create --name your-site-name
-netlify deploy --prod --build
-```
-
-### Option 2: Netlify Dashboard
-
-1. Go to [app.netlify.com](https://app.netlify.com)
-2. Click "Add new site" > "Import an existing project"
-3. Connect your GitHub repository
-4. Configure build settings:
-   - **Base directory:** `web`
-   - **Build command:** `npm run build`
-   - **Publish directory:** `.next`
-5. Deploy
-
-## Configuration
-
-The `web/netlify.toml` file configures the build:
-
-```toml
-[build]
-  command = "npm run build"
-  publish = ".next"
-
-[[plugins]]
-  package = "@netlify/plugin-nextjs"
-```
-
-## Custom Domain Setup
-
-1. Go to your site's **Domain management** in Netlify
-2. Click **Add a domain**
-3. Enter your subdomain (e.g., `devworkflow.yourdomain.com`)
-4. Add a CNAME record in your DNS provider:
-   - **Host:** `devworkflow` (or your subdomain)
-   - **Value:** `your-site-name.netlify.app`
-5. Click **Provision certificate** for HTTPS
-
-## API Endpoints
-
-The following API routes are available as Netlify Functions:
-
-| Endpoint | Description |
-| --- | --- |
-| `/api/version` | Returns current package version |
-| `/api/npm-downloads` | Returns monthly npm download count |
-| `/api/summary` | Returns placeholder summary data |
-| `/api/history` | Returns placeholder history data |
-| `/api/docs` | Returns documentation content |
-
-## Limitations
-
-When deployed to Netlify (static mode):
-
-- **No persistent database** - History and summary return empty/placeholder data
-- **No real-time updates** - Data is static between deployments
-- **Version is build-time** - Update `web/app/api/version/route.ts` before each release
-
-## Updating the Deployment
-
-### Manual Redeploy
-
-```bash
-cd web
-netlify deploy --prod --build
-```
-
-### Auto-Deploy (Recommended)
-
-Connect your GitHub repository to Netlify for automatic deployments on push to main branch.
-
-## Troubleshooting
-
-| Issue | Solution |
-| --- | --- |
-| 404 on custom domain | Provision SSL certificate in Netlify dashboard |
-| Build fails | Ensure `web/package.json` has no native dependencies |
-| Functions timeout | Netlify has 10s limit; optimize API routes |
-
-## Related
-
-- [Web Dashboard Guide](./web-dashboard.md)
-- [Plesk Deployment](./PLESK_DEPLOYMENT.md)
-- [Main README](../README.md)

package/docs/PLESK_DEPLOYMENT.md

@@ -1,170 +0,0 @@
-# Deploying dev-workflow-mcp-server to Plesk
-
-This guide covers deploying the dev-workflow MCP server (Node.js backend + Next.js frontend) to Plesk hosting.
-
-## Prerequisites
-
-- Plesk control panel access
-- Node.js 18+ installed on the server
-- Git installed on the server
-- Domain/subdomain configured in Plesk
-
-## Deployment Steps
-
-### 1. Set Up Node.js Application in Plesk
-
-1. Log in to Plesk control panel
-2. Go to **Domains** → Select your domain
-3. Click **Node.js** (or **Applications** if using newer Plesk)
-4. Click **Add Application**
-5. Configure:
-   - **Application root**: `/var/www/vhosts/yourdomain.com/dev-workflow-mcp-server` (or your path)
-   - **Startup file**: `index.js`
-   - **Node.js version**: 18.x or higher
-   - **Port**: Leave as auto (Plesk assigns a port)
-
-### 2. Clone Repository
-
-SSH into your Plesk server:
-
-```bash
-cd /var/www/vhosts/yourdomain.com
-git clone https://github.com/programinglive/dev-workflow-mcp-server.git
-cd dev-workflow-mcp-server
-```
-
-### 3. Install Dependencies
-
-```bash
-npm install
-```
-
-### 4. Build the Application
-
-```bash
-npm run build
-```
-
-This builds:
-- **Backend**: Vite bundle → `dist/index.mjs`
-- **Frontend**: Next.js static + server → `web/.next/`
-- **Docs**: HTML files → `dist/docs/`
-
-### 5. Configure Environment (if needed)
-
-Create `.env` file in the project root if you need custom settings:
-
-```bash
-# Example (adjust as needed)
-NODE_ENV=production
-PORT=3000
-```
-
-### 6. Start the Application
-
-In Plesk:
-1. Go back to **Node.js Applications**
-2. Find your application
-3. Click **Start** (or it may auto-start)
-
-Alternatively, via SSH:
-
-```bash
-npm start
-```
-
-### 7. Configure Reverse Proxy (Plesk)
-
-Plesk automatically sets up a reverse proxy. Verify:
-1. Go to **Domains** → Your domain → **Web Server Settings**
-2. Ensure **Proxy** is enabled
-3. Verify the proxy points to the Node.js app port
-
-### 8. Verify Deployment
-
-- Visit `https://yourdomain.com` → Should see the Next.js frontend
-- Visit `https://yourdomain.com/docs` → Should see documentation
-- Check browser console for any `_next/static` 500 errors
-
-If you see 500 errors on `_next/static` requests:
-- SSH to server and check logs: `tail -f /var/log/plesk/nodejs/yourdomain.com.log`
-- Ensure `.next` directory exists: `ls -la web/.next/`
-- Verify Node.js is running: `ps aux | grep node`
-
-### 9. Set Up Auto-Restart (Optional)
-
-In Plesk, the Node.js app should auto-restart on failure. To verify:
-1. Go to **Node.js Applications**
-2. Check **Restart policy** is set to auto-restart
-
-### 10. Enable HTTPS (Recommended)
-
-1. Go to **Domains** → Your domain → **SSL/TLS Certificates**
-2. Click **Install** (use Let's Encrypt free certificate)
-3. Plesk auto-redirects HTTP → HTTPS
-
-## Troubleshooting
-
-### `_next/static` returns 500
-
-**Cause**: Next.js build output not deployed or server crashed.
-
-**Fix**:
-```bash
-# SSH to server
-npm run build --prefix web
-npm start
-# Check logs
-tail -f /var/log/plesk/nodejs/yourdomain.com.log
-```
-
-### Application won't start
-
-**Check**:
-1. Node.js version: `node --version` (must be 18+)
-2. Dependencies: `npm install`
-3. Build output: `ls -la dist/` and `ls -la web/.next/`
-4. Logs: Check Plesk control panel logs
-
-### Port conflicts
-
-Plesk assigns ports automatically. If you get a port conflict:
-1. Go to **Node.js Applications** → Edit
-2. Let Plesk auto-assign a new port
-3. Restart the app
-
-## Updating the Application
-
-To deploy a new version:
-
-```bash
-cd /var/www/vhosts/yourdomain.com/dev-workflow-mcp-server
-git pull origin main
-npm install
-npm run build
-# Plesk will auto-restart the app
-```
-
-Or manually restart in Plesk control panel:
-1. **Node.js Applications** → Select app → **Restart**
-
-## Production Checklist
-
-- [ ] Node.js 18+ installed
-- [ ] `npm install` completed
-- [ ] `npm run build` succeeded (no errors)
-- [ ] `.next` directory exists with static files
-- [ ] HTTPS/SSL certificate installed
-- [ ] Reverse proxy configured
-- [ ] Application started and running
-- [ ] `https://yourdomain.com` loads without 500 errors
-- [ ] `_next/static` assets load correctly
-- [ ] Logs show no errors
-
-## Support
-
-For issues:
-1. Check Plesk logs: `/var/log/plesk/nodejs/`
-2. SSH and run `npm start` manually to see real-time errors
-3. Verify Node.js and npm versions
-4. Ensure all dependencies installed: `npm install`

package/docs/PRD.md

@@ -1,86 +0,0 @@
-# Product Requirements Document (PRD)
-
-## 1. Overview
-- **Product**: Development Workflow MCP Server
-- **Prepared by**: Cascade (AI assistant)
-- **Date**: 2025-12-27
-- **Status**: Live v1.8.0
-
-## 2. Problem Statement
-Developers need structured guidance to maintain disciplined workflows across projects. Existing tooling lacks enforcement of sequential best practices (testing, documentation, release hygiene) and offers limited visibility into historical task execution.
-
-## 3. Goals & Objectives
-1. Enforce a consistent, auditable development workflow across teams.
-2. Provide actionable guidance for each workflow phase within IDE-integrated environments.
-3. Maintain per-project, per-user workflow state while supporting shared infrastructure (e.g., SQLite summaries, dashboard).
-4. **Support flexible data persistence**: Enable usage of various database backends (MySQL, PostgreSQL, SQLite) to adapt to different hosting and enterprise environments.
-
-## 4. Non-Goals
-- Replacing full-featured project management tools.
-- Implementing source control hosting or CI/CD pipelines.
-- Providing opinionated task estimation or prioritization features.
-
-## 5. Target Users & Personas
-- **Individual developers** seeking workflow discipline.
-- **Team leads** requiring enforced process compliance.
-- **Tool integrators** embedding MCP capabilities into IDEs or agents.
-
-## 6. User Stories
-1. As a developer, I want to be guided through the workflow steps so I can avoid skipping critical tasks.
-2. As a team lead, I want an auditable history of workflow completion so I can ensure compliance.
-3. As an integrator, I want a simple API (tools/prompts) so I can plug the MCP server into existing agent workflows.
-4. As a devops engineer, I want to configure the server to use my existing database infrastructure (MySQL/PostgreSQL) instead of local files.
-
-## 7. Functional Requirements
-- Provide MCP tools covering the full workflow lifecycle (start task, fix, test, document, commit, release, complete).
-- Persist workflow state per project and per user, with compatibility handling for legacy locations.
-- Offer aggregated project summaries (JSON artifacts, Database sync, optional web dashboard).
-- Guard release commands to ensure prerequisites are satisfied.
-- Support `run_full_workflow` for scripted execution of all steps with validation.
-- Web dashboard displays version dynamically from `package.json` via `/api/version` endpoint to stay in sync after releases.
-- [x] **Consolidated CI/CD**: Unified release and publish workflows.
-- [x] **Multi-Database Support**: SQLite, MySQL, and PostgreSQL adapters implemented and verified.
-- [x] **Environment Configuration**: `.env` file support added.
-- [x] **Comprehensive Testing**: Automated tests for DB adapters and environment loading.
-- [x] **Modular Architecture**: Refactored handlers.js into focused handler modules for better maintainability.
-- [x] **Test Organization**: Split monolithic test file into focused test modules with shared utilities.
-- [x] **PRD Location**: Moved PRD.md to docs/ root for easier access.
-- **Multi-Database Support**: Abstract the storage layer to support:
-    - SQLite (default/local)
-    - MySQL
-    - PostgreSQL
-
-## 8. Technical Considerations
-- Node.js (ESM) codebase leveraging `@modelcontextprotocol/sdk`.
-- File-based state stored under `.state/users/<user>/workflow-state.json` with compatibility symlinks.
-- **Database Abstraction**: Implement an Adapter/Repository pattern or use an ORM (e.g., Knex, Prisma, Drizzle) to support multiple SQL dialects.
-- Vite build pipeline for distribution bundle; source usage recommended for MCP.
-- Windows compatibility requirements (Python, Build Tools for native modules).
-- **Deployment options**: Local development, Netlify (static), Plesk (full-featured).
-
-## 9. Success Metrics
-- ≥90% of workflow operations executed via MCP tools (vs. manual overrides).
-- Reduction in release guard violations to <5% of attempts.
-- Positive qualitative feedback on guidance clarity from pilot teams.
-- Seamless switching between SQLite, MySQL, and PostgreSQL via configuration.
-
-## 10. Milestones
-1. **MVP**: Core workflow tools, state persistence, basic history (complete).
-2. **Enhancements**: Improved project root detection, compatibility mirrors, `run_full_workflow` automation (complete).
-3. **v1.5.0**: Netlify deployment support for static web dashboard (complete).
-4. **v1.6.0+**: Dark/Light mode, UI Improvements (complete).
-5. **Multi-Database Support**: Refactor storage layer to support MySQL and PostgreSQL (complete v1.7.1).
-7. **v1.7.14 Performance & Resilience**: Implemented connection timeouts and optimized startup sequence for stdio clients (complete).
-8. **v1.7.15 Schema Alignment**: Implemented Postgres/MySQL column normalization and automated integer User ID hashing for cross-dashboard compatibility (complete).
-9. **Future**: Expanded dashboard analytics, customizable workflows, richer integrations.
-
-## 11. Risks & Mitigations
-- **Risk**: Workflow feels overly prescriptive. **Mitigation**: Provide escape hatches (`force_complete_task`, `drop_task`) with audit trails.
-- **Risk**: State corruption due to concurrent access. **Mitigation**: File locking and defensive JSON parsing (existing code handles gracefully, but monitor).
-- **Risk**: Integration friction with IDE clients. **Mitigation**: Maintain detailed README instructions and example configurations.
-- **Risk**: Complicated setup for users not needing external DBs. **Mitigation**: Keep SQLite/File-system as the default zero-config option.
-
-## 12. Open Questions
-- Should additional workflow phases (e.g., design review) be supported?
-- How should multi-branch workflows be represented in history summaries?
-- What telemetry or analytics are acceptable within privacy constraints?