@programinglive/dev-workflow-mcp-server 1.7.14 → 1.7.17

package/CHANGELOG.md

@@ -2,6 +2,52 @@
 
 All notable changes to this project will be documented in this file. See [standard-version](https://github.com/conventional-changelog/standard-version) for commit guidelines.
 
+### [1.7.17](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.16...v1.7.17) (2025-12-26)
+
+
+### 📝 Documentation
+
+* update release notes for v1.7.16 ([0afd96b](https://github.com/programinglive/dev-workflow-mcp-server/commit/0afd96b754717953eb162f65426129457fc8626e))
+
+
+### ✨ Features
+
+* allow skipping release step ([004e4fa](https://github.com/programinglive/dev-workflow-mcp-server/commit/004e4fae071e064b2c2efb9d69ecd97e794d3cb8))
+
+
+### 🧹 Chores
+
+* add @programinglive/commiter setup ([1d2a19d](https://github.com/programinglive/dev-workflow-mcp-server/commit/1d2a19d0453b50c6f0db35b15924b51a27c4891a))
+
+### [1.7.16](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.15...v1.7.16) (2025-12-24)
+
+
+### 🐛 Bug Fixes
+
+* align database schema with dashboard and improve user ID handling ([69e7f38](https://github.com/programinglive/dev-workflow-mcp-server/commit/69e7f381955d15bb727a6e309082a344729d1c1e))
+
+
+### 🧹 Chores
+
+* cleanup temporary debugging scripts ([a5e2b15](https://github.com/programinglive/dev-workflow-mcp-server/commit/a5e2b15b894632efadce46d83caf4d008e50fdd3))
+* sync version to 1.7.15 across web and landing pages ([c520e4a](https://github.com/programinglive/dev-workflow-mcp-server/commit/c520e4a5d795c880fb74f31142b128a9c55beb6f))
+
+
+### 📝 Documentation
+
+* update macOS MCP config instructions ([1e368da](https://github.com/programinglive/dev-workflow-mcp-server/commit/1e368da37bede45e0282b1312002f2fedeb6ad60))
+
+### [1.7.15](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.14...v1.7.15) (2025-12-19)
+
+
+### 🐛 Bug Fixes
+
+* optimize startup performance and add database connection resilience ([bff2714](https://github.com/programinglive/dev-workflow-mcp-server/commit/bff27146fe9537788741e4a084191bce93588569))
+* refactor Navbar and History to use absolute API client URLs v1.7.18 ([dc33eae](https://github.com/programinglive/dev-workflow-mcp-server/commit/dc33eae612067c5246ca69d08960090c0a0ad6bd))
+* sync all version labels to 1.7.14 and improve netlify routing ([78712eb](https://github.com/programinglive/dev-workflow-mcp-server/commit/78712eb398458605f77b2ba78c9ff61a0be1d335))
+* sync all version strings to 1.7.14 ([e2a1795](https://github.com/programinglive/dev-workflow-mcp-server/commit/e2a1795a7b794c8874b1e610de3370cd6ed5fa7a))
+* sync version to 1.7.14 and fix static routing via trailingSlash ([1c152bd](https://github.com/programinglive/dev-workflow-mcp-server/commit/1c152bd23bbfd30a73e0a89107f4ea18564d20d0))
+
 ### [1.7.14](https://github.com/programinglive/dev-workflow-mcp-server/compare/v1.7.13...v1.7.14) (2025-12-19)
 
 

package/README.md

@@ -8,6 +8,11 @@
 
 An MCP (Model Context Protocol) server that helps enforce development discipline and workflow best practices. This server acts as your coding conscience, reminding you to follow proper development workflows.
 
+### 🛡️ Resilience Features
+- **Startup Resilience**: 5-second connection timeouts for external databases.
+- **Background Loading**: Non-critical assets (compatibility mirrors) initialize in the background to ensure sub-second startup.
+- **Diagnostic Mode**: Automatic startup timing logs displayed in stderr.
+
 ## 🎯 Purpose
 
 This MCP server guides you through a disciplined development workflow:
@@ -100,7 +105,12 @@ Point your MCP client to the server entry point. Replace `<PROJECT_ROOT>` with t
   "mcpServers": {
     "dev-workflow": {
       "command": "node",
-      "args": ["<PROJECT_ROOT>/index.js"]
+      "cwd": "<PROJECT_ROOT>",
+      "args": ["index.js"],
+      "env": {
+        "DEV_WORKFLOW_DB_TYPE": "postgres",
+        "DEV_WORKFLOW_DB_URL": "postgres://USER:PASS@HOST:5432/devworkflow"
+      }
     }
   }
 }
@@ -177,6 +187,28 @@ Point your MCP client to the server entry point. Replace `<PROJECT_ROOT>` with t
 
 > **Note:** On Windows paths in JSON require escaped backslashes (e.g., `"C:\\path\\to\\project"`).
 
+#### Full Windsurf MCP Config Example (macOS)
+
+If you keep this repository checked out at `/Users/alex/code/dev-workflow-mcp-server` and want to point Windsurf at a hosted PostgreSQL instance, drop the following into `~/Library/Application Support/Windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "dev-workflow": {
+      "command": "node",
+      "cwd": "/Users/alex/code/dev-workflow-mcp-server",
+      "args": ["index.js"],
+      "env": {
+        "DEV_WORKFLOW_DB_TYPE": "postgres",
+        "DEV_WORKFLOW_DB_URL": "postgres://devworkflow:devworkflow_secure_password@34.50.121.142:5432/devworkflow"
+      }
+    }
+  }
+}
+```
+
+This mirrors the Windows configuration shared in previous releases, but avoids `npx` lookup issues on macOS by launching the local `index.js` directly.
+
 ### 4. Restart Windsurf/Claude Desktop
 
 After adding the configuration, restart the application to load the MCP server.
@@ -201,6 +233,29 @@ Antigravity users should configure the MCP server in their `mcp_config.json`.
 
 See [Antigravity Getting Started](./docs/antigravity/GETTING-STARTED.md) for detailed instructions and troubleshooting.
 
+### ⚡ Performance Optimization (Recommended)
+
+To ensure the fastest possible startup (critical for IDE-integrated clients like Claude Desktop), we recommend pointing directly to `index.js` using `node` rather than `npx`. This avoids the overhead of checking for package updates.
+
+**Optimized Configuration:**
+
+```json
+{
+  "mcpServers": {
+    "dev-workflow": {
+      "command": "node",
+      "args": ["<PROJECT_ROOT>\\index.js"],
+      "env": {
+        "DEV_WORKFLOW_USER_ID": "your_user_id"
+      }
+    }
+  }
+}
+```
+
+The server automatically times its own startup and logs it to stderr:
+`Dev Workflow MCP Server running on stdio (startup took 15ms)`
+
 ## ⚙️ Configuration
 
 ### Database Setup
@@ -241,6 +296,19 @@ export DEV_WORKFLOW_DB_TYPE=postgres
 export DEV_WORKFLOW_DB_URL="postgresql://user:password@localhost:5432/dev_workflow"
 ```
 
+#### 🛠️ Database Schema Normalization (Postgres/MySQL)
+To ensure compatibility with existing reporting dashboards, the `PostgresAdapter` and `MysqlAdapter` automatically normalize column names:
+- `task_description` → DB column: `description`
+- `timestamp` → DB column: `completed_at`
+
+The adapters use aliases in queries so the MCP tools still receive the expected `task_description` and `timestamp` fields.
+
+#### 👤 User ID Handling (Postgres/MySQL)
+These databases use an `INTEGER` column for `user_id`.
+- **Numeric strings** (e.g., `"1"`) are parsed directly into integers.
+- **Non-numeric strings** (e.g., `"programinglive"`) are automatically hashed into a consistent, positive integer to ensure compatibility with the schema while maintaining unique user isolation.
+
+
 ### User & State Management
 
 | Variable | Description |
@@ -444,7 +512,7 @@ This keeps workflow state local to each developer's machine.
 - `create_documentation` - Mark documentation as created
 - `check_ready_to_commit` - Verify all steps are complete
 - `commit_and_push` - Commit and push changes
-- `perform_release` - Record release details
+- `perform_release` - Record release details (or use `skip_release` when the project has no release automation)
 - `complete_task` - Mark task as complete and reset
 - `force_complete_task` - Force completion with reason
 - `drop_task` - Abandon current task
@@ -485,6 +553,7 @@ The tool will:
 5. `check_ready_to_commit`
 6. `commit_and_push` with `commitMessage` and optional `branch`
 7. `perform_release` with `releaseCommand`, plus optional `releaseNotes`, `releaseType`, and `preset`
+   - Alternatively call `skip_release` with a justification when the repository has no Node-based release step (e.g., Python-only or docs-only tasks)
 8. `complete_task` reusing `commitMessage`
 
 All arguments except the optional flags are required and must be non-empty strings.
@@ -503,7 +572,7 @@ The package ships with a release guard (`release-wrapper.js`) that backs the `np
 
 If any requirements are missing, the guard exits with guidance to return to the MCP tools. This prevents accidentally bumping versions or tagging releases outside the managed workflow. To release correctly:
 
-1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client.
+1. Use `perform_release {"command":"patch"}` (or `minor`/`major`) via the MCP client, or `skip_release {"reason":"<explanation>"}` if no release applies.
 2. The guard runs automatically, verifies the workflow state, and records the release before letting you finish with `complete_task`.
 
 ### Automated npm Publishing

package/db/adapters/postgres.js

@@ -15,11 +15,25 @@ export class PostgresAdapter extends DbAdapter {
         this.pool = null;
     }
 
+    getNumericUserId(userId) {
+        let numericUserId = parseInt(userId, 10);
+        if (isNaN(numericUserId)) {
+            let hash = 0;
+            for (let i = 0; i < userId.length; i++) {
+                hash = (hash << 5) - hash + userId.charCodeAt(i);
+                hash |= 0;
+            }
+            numericUserId = Math.abs(hash);
+        }
+        return numericUserId;
+    }
+
     async connect() {
         if (!this.pool) {
             this.pool = new Pool({
                 connectionString: this.config.connectionUrl,
-                // pg pool handles connections automatically
+                connectionTimeoutMillis: 5000, // 5 second timeout for new connections
+                idleTimeoutMillis: 10000,      // close idle connections after 10 seconds
             });
             await this.migrate();
         }
@@ -31,23 +45,55 @@ export class PostgresAdapter extends DbAdapter {
             await client.query(`
         CREATE TABLE IF NOT EXISTS workflow_history (
           id SERIAL PRIMARY KEY,
-          user_id TEXT NOT NULL,
+          user_id INTEGER NOT NULL,
           project_path TEXT DEFAULT '',
-          task_description TEXT NOT NULL,
+          description TEXT NOT NULL,
           task_type TEXT NOT NULL,
           commit_message TEXT,
-          timestamp TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
+          completed_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
           forced BOOLEAN DEFAULT FALSE,
           force_reason TEXT,
           dropped BOOLEAN DEFAULT FALSE,
           drop_reason TEXT,
-          UNIQUE (user_id, project_path, timestamp, task_description)
+          UNIQUE (user_id, project_path, completed_at, description)
         )
       `);
 
+            // Migration: Add columns to existing table if they don't exist
+            const columns = await client.query(`
+                SELECT column_name FROM information_schema.columns WHERE table_name = 'workflow_history'
+            `);
+            const existingColumns = columns.rows.map(r => r.column_name);
+
+            if (!existingColumns.includes('project_path')) {
+                await client.query('ALTER TABLE workflow_history ADD COLUMN project_path TEXT DEFAULT \'\'');
+            }
+            if (!existingColumns.includes('forced')) {
+                await client.query('ALTER TABLE workflow_history ADD COLUMN forced BOOLEAN DEFAULT FALSE');
+            }
+            if (!existingColumns.includes('force_reason')) {
+                await client.query('ALTER TABLE workflow_history ADD COLUMN force_reason TEXT');
+            }
+            if (!existingColumns.includes('dropped')) {
+                await client.query('ALTER TABLE workflow_history ADD COLUMN dropped BOOLEAN DEFAULT FALSE');
+            }
+            if (!existingColumns.includes('drop_reason')) {
+                await client.query('ALTER TABLE workflow_history ADD COLUMN drop_reason TEXT');
+            }
+            // Ensure completed_at vs timestamp handled if table exists
+            if (!existingColumns.includes('completed_at') && existingColumns.includes('timestamp')) {
+                await client.query('ALTER TABLE workflow_history RENAME COLUMN timestamp TO completed_at');
+            } else if (existingColumns.includes('completed_at') && !existingColumns.includes('timestamp')) {
+                // Keep completed_at
+            }
+            // Logic for description vs task_description
+            if (!existingColumns.includes('description') && existingColumns.includes('task_description')) {
+                await client.query('ALTER TABLE workflow_history RENAME COLUMN task_description TO description');
+            }
+
             await client.query(`
         CREATE TABLE IF NOT EXISTS project_summary (
-          user_id TEXT,
+          user_id INTEGER,
           project_path TEXT DEFAULT '',
           total_tasks INTEGER DEFAULT 0,
           task_types JSONB,
@@ -60,7 +106,7 @@ export class PostgresAdapter extends DbAdapter {
 
             await client.query(`
         CREATE TABLE IF NOT EXISTS workflow_state (
-          user_id TEXT,
+          user_id INTEGER,
           project_path TEXT DEFAULT '',
           state_json JSONB,
           updated_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP,
@@ -75,12 +121,13 @@ export class PostgresAdapter extends DbAdapter {
     async insertHistoryEntry(userId, projectPath, entry) {
         await this.connect();
         const normalizedProjectPath = projectPath || '';
+        const numericUserId = this.getNumericUserId(userId);
 
         const query = `
       INSERT INTO workflow_history
-      (user_id, project_path, task_description, task_type, commit_message, timestamp, forced, force_reason, dropped, drop_reason)
+      (user_id, project_path, description, task_type, commit_message, completed_at, forced, force_reason, dropped, drop_reason)
       VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10)
-      ON CONFLICT (user_id, project_path, timestamp, task_description) DO UPDATE SET
+      ON CONFLICT (user_id, project_path, completed_at, description) DO UPDATE SET
         commit_message=EXCLUDED.commit_message,
         forced=EXCLUDED.forced,
         force_reason=EXCLUDED.force_reason,
@@ -89,12 +136,12 @@ export class PostgresAdapter extends DbAdapter {
     `;
 
         await this.pool.query(query, [
-            userId,
+            numericUserId,
             normalizedProjectPath,
-            entry.taskDescription,
+            entry.taskDescription || entry.description,
             entry.taskType,
             entry.commitMessage,
-            entry.timestamp || new Date().toISOString(),
+            entry.timestamp || entry.completed_at || new Date().toISOString(),
             entry.forced || false,
             entry.forceReason || null,
             entry.dropped || false,
@@ -107,14 +154,16 @@ export class PostgresAdapter extends DbAdapter {
     async updateSummaryForUser(userId, projectPath) {
         await this.connect();
         const normalizedProjectPath = projectPath || '';
+        const numericUserId = this.getNumericUserId(userId);
 
         const res = await this.pool.query(`
-      SELECT task_type, timestamp, task_description
+      SELECT task_type, completed_at as timestamp, description as task_description
       FROM workflow_history
       WHERE user_id = $1 AND project_path = $2
-      ORDER BY timestamp DESC
+      ORDER BY completed_at DESC
       LIMIT 20
-    `, [userId, normalizedProjectPath]);
+    `, [numericUserId, normalizedProjectPath]);
+        // ... (lines continue similarly)
 
         const rows = res.rows;
 
@@ -144,7 +193,7 @@ export class PostgresAdapter extends DbAdapter {
     `;
 
         await this.pool.query(upsert, [
-            userId,
+            numericUserId,
             normalizedProjectPath,
             rows.length,
             JSON.stringify(taskTypes),
@@ -157,10 +206,11 @@ export class PostgresAdapter extends DbAdapter {
     async getSummaryForUser(userId, projectPath) {
         await this.connect();
         const normalizedProjectPath = projectPath || '';
+        const numericUserId = this.getNumericUserId(userId);
 
         const res = await this.pool.query(`
       SELECT * FROM project_summary WHERE user_id = $1 AND project_path = $2
-    `, [userId, normalizedProjectPath]);
+    `, [numericUserId, normalizedProjectPath]);
 
         const row = res.rows[0];
         if (!row) return null;
@@ -183,16 +233,18 @@ export class PostgresAdapter extends DbAdapter {
         const sanitizedPageSize = Math.min(100, Math.max(1, Number.isFinite(Number(pageSize)) ? Math.floor(Number(pageSize)) : 20));
         const offset = (sanitizedPage - 1) * sanitizedPageSize;
 
+        const numericUserId = this.getNumericUserId(userId);
+
         const clauses = [];
-        const params = [userId, normalizedProjectPath];
+        const params = [numericUserId, normalizedProjectPath];
         let paramIdx = 3;
 
         if (startDate) {
-            clauses.push(`DATE(timestamp) >= DATE($${paramIdx++})`);
+            clauses.push(`DATE(completed_at) >= DATE($${paramIdx++})`);
             params.push(startDate);
         }
         if (endDate) {
-            clauses.push(`DATE(timestamp) <= DATE($${paramIdx++})`);
+            clauses.push(`DATE(completed_at) <= DATE($${paramIdx++})`);
             params.push(endDate);
         }
 
@@ -205,10 +257,10 @@ export class PostgresAdapter extends DbAdapter {
         const total = parseInt(countRes.rows[0].total, 10);
 
         const entriesRes = await this.pool.query(`
-      SELECT *
+      SELECT *, description as task_description, completed_at as timestamp
       FROM workflow_history
       WHERE ${where}
-      ORDER BY timestamp DESC
+      ORDER BY completed_at DESC
       LIMIT $${paramIdx++}
       OFFSET $${paramIdx++}
     `, [...params, sanitizedPageSize, offset]);
@@ -228,23 +280,25 @@ export class PostgresAdapter extends DbAdapter {
         const { startDate, endDate, frequency = "daily" } = options;
         const format = FREQUENCY_FORMATS[frequency] || FREQUENCY_FORMATS.daily;
 
+        const numericUserId = this.getNumericUserId(userId);
+
         const clauses = [];
-        const params = [userId, normalizedProjectPath];
+        const params = [numericUserId, normalizedProjectPath];
         let paramIdx = 3;
 
         if (startDate) {
-            clauses.push(`DATE(timestamp) >= DATE($${paramIdx++})`);
+            clauses.push(`DATE(completed_at) >= DATE($${paramIdx++})`);
             params.push(startDate);
         }
         if (endDate) {
-            clauses.push(`DATE(timestamp) <= DATE($${paramIdx++})`);
+            clauses.push(`DATE(completed_at) <= DATE($${paramIdx++})`);
             params.push(endDate);
         }
 
         const where = [`user_id = $1`, `project_path = $2`, ...clauses].join(" AND ");
 
         const res = await this.pool.query(`
-      SELECT to_char(timestamp, '${format}') AS period, COUNT(*) AS count
+      SELECT to_char(completed_at, '${format}') AS period, COUNT(*) AS count
       FROM workflow_history
       WHERE ${where}
       GROUP BY period
@@ -267,8 +321,10 @@ export class PostgresAdapter extends DbAdapter {
         updated_at=EXCLUDED.updated_at
     `;
 
+        const numericUserId = this.getNumericUserId(userId);
+
         await this.pool.query(query, [
-            userId,
+            numericUserId,
             normalizedProjectPath,
             JSON.stringify(state),
             new Date().toISOString()
@@ -278,10 +334,11 @@ export class PostgresAdapter extends DbAdapter {
     async getState(userId, projectPath) {
         await this.connect();
         const normalizedProjectPath = projectPath || '';
+        const numericUserId = this.getNumericUserId(userId);
 
         const res = await this.pool.query(`
       SELECT state_json FROM workflow_state WHERE user_id = $1 AND project_path = $2
-    `, [userId, normalizedProjectPath]);
+    `, [numericUserId, normalizedProjectPath]);
 
         const row = res.rows[0];
         if (!row) return null;

package/db/adapters/sqlite.js

@@ -25,9 +25,15 @@ export class SqliteAdapter extends DbAdapter {
         // Otherwise, attempt to find project root relative to CWD
         const initCwd = process.env.INIT_CWD || process.cwd();
         let projectRoot = initCwd;
-        while (projectRoot !== path.dirname(projectRoot)) {
+        let limit = 20; // Prevent infinite loop in weird environments
+        while (projectRoot !== path.dirname(projectRoot) && limit > 0) {
             if (existsSync(path.join(projectRoot, "package.json"))) break;
             projectRoot = path.dirname(projectRoot);
+            limit--;
+        }
+        if (limit === 0) {
+            console.error("Warning: Could not find project root effectively, defaulting to INIT_CWD");
+            projectRoot = initCwd;
         }
         return path.join(projectRoot, ".state", DB_FILENAME);
     }

package/docs/product/PRD.md

@@ -4,7 +4,7 @@
 - **Product**: Development Workflow MCP Server
 - **Prepared by**: Cascade (AI assistant)
 - **Date**: 2025-12-16
-- **Status**: Live v1.7.11
+- **Status**: Live v1.7.15
 
 ## 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.
@@ -67,7 +67,9 @@ Developers need structured guidance to maintain disciplined workflows across pro
 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).
-6. **Future**: Expanded dashboard analytics, customizable workflows, richer integrations.
+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.

package/docs/release-notes/RELEASE_NOTES.md

@@ -4,6 +4,8 @@ Authoritative history of user-visible changes for the Development Workflow MCP S
 
 | Version | Date | Notes |
 |---------|------|-------|
+| 1.7.16 | 2025-12-24 | align database schema with dashboard and improve user ID handling (69e7f38) |
+| 1.7.15 | 2025-12-19 | optimize startup performance and add database connection resilience (bff2714) |
 | 1.7.14 | 2025-12-19 | add API dependencies and update login to use API client (94bb42f) |
 | 1.7.13 | 2025-12-18 | remote db connection, history api 500 errors, and windows startup (ce559a6) |
 | 1.7.12 | 2025-12-17 | post-release cleanup v1.7.11 (c2ee733) |
@@ -41,6 +43,27 @@ Authoritative history of user-visible changes for the Development Workflow MCP S
 
 
 
+
+
+## 1.7.16 – 🐛 Bug Fixes
+
+Released on **2025-12-24**.
+
+- align database schema with dashboard and improve user ID handling (69e7f38)
+- cleanup temporary debugging scripts (a5e2b15)
+- sync version to 1.7.15 across web and landing pages (c520e4a)
+- update macOS MCP config instructions (1e368da)
+
+## 1.7.15 – 🐛 Bug Fixes
+
+Released on **2025-12-19**.
+
+- optimize startup performance and add database connection resilience (bff2714)
+- refactor Navbar and History to use absolute API client URLs v1.7.18 (dc33eae)
+- sync all version labels to 1.7.14 and improve netlify routing (78712eb)
+- sync all version strings to 1.7.14 (e2a1795)
+- sync version to 1.7.14 and fix static routing via trailingSlash (1c152bd)
+
 ## 1.7.14 – ✨ Features
 
 Released on **2025-12-19**.

package/index.js

@@ -191,20 +191,30 @@ Use 'check_ready_to_commit' to verify workflow completion.
 
 // Start server
 export async function main() {
+  const startTime = Date.now();
+  console.error(`[${new Date().toISOString()}] MCP Server starting...`);
+
   try {
     // Initialize workflow state
     workflowState = new WorkflowState();
+    console.error(`[${new Date().toISOString()}] Loading workflow state...`);
     await workflowState.load();
+    console.error(`[${new Date().toISOString()}] Workflow state loaded.`);
+
+    console.error(`[${new Date().toISOString()}] Ensuring primary file...`);
     await workflowState.ensurePrimaryFile();
+    console.error(`[${new Date().toISOString()}] Workflow state initialization complete.`);
   } catch (error) {
-    console.error("Warning: Failed to initialize workflow state:", error.message);
+    console.error(`[${new Date().toISOString()}] Warning: Failed to initialize workflow state:`, error.message);
     // Continue anyway - workflow state is optional for MCP to function
     workflowState = new WorkflowState();
   }
 
   const transport = new StdioServerTransport();
+  console.error(`[${new Date().toISOString()}] Connecting transport...`);
   await server.connect(transport);
-  console.error("Dev Workflow MCP Server running on stdio");
+  const duration = Date.now() - startTime;
+  console.error(`[${new Date().toISOString()}] Dev Workflow MCP Server running on stdio (startup took ${duration}ms)`);
 }
 
 // --- Lightweight CLI: dev-workflow-mcp call <toolName> [--args '<json>'] ---

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@programinglive/dev-workflow-mcp-server",
-  "version": "1.7.14",
+  "version": "1.7.17",
   "description": "MCP server to enforce development workflow discipline",
   "homepage": "https://devworkflow.programinglive.com/",
   "mcpName": "io.github.programinglive/dev-workflow-mcp-server",
@@ -62,11 +62,13 @@
   "devDependencies": {
     "@commitlint/cli": "^20.2.0",
     "@commitlint/config-conventional": "^20.2.0",
-    "@programinglive/commiter": "^1.2.16",
+    "@programinglive/commiter": "^1.2.17",
     "autoprefixer": "^10.4.22",
+    "cross-env": "^10.1.0",
     "husky": "^9.1.7",
     "postcss": "^8.5.6",
     "standard-version": "^9.5.0",
+    "supertest": "^7.1.4",
     "tailwindcss": "^3.4.18"
   },
   "standard-version": {

package/scripts/release.cjs

@@ -11,6 +11,9 @@ const FS_FOK_PRELOAD_FLAG = buildPreloadFlag(fsFokPreloadPath);
 
 require('./preload/fs-f-ok.cjs');
 
+const DEFAULT_PRD_RELATIVE_PATH = path.join('docs', 'PRD.md');
+const DEFAULT_PRD_DISPLAY_PATH = 'docs/PRD.md';
+
 const VALID_RELEASE_TYPES = new Set([
   'major',
   'minor',
@@ -161,6 +164,8 @@ function runRelease({
     throw new Error('Working tree has uncommitted changes. Commit or stash before running release.');
   }
 
+  ensurePrdPresence({ cwd, dependencies });
+
   const testResult = runProjectTests({ spawn, env });
   if (testResult && typeof testResult.status === 'number' && testResult.status !== 0) {
     return testResult;
@@ -219,9 +224,31 @@ module.exports = {
   detectPackageManager,
   runProjectTests,
   runRelease,
-  isWorkingTreeClean
+  isWorkingTreeClean,
+  ensurePrdPresence
 };
 
+function ensurePrdPresence({ cwd = process.cwd(), dependencies = {} } = {}) {
+  const {
+    fsExistsSync = fs.existsSync,
+    logger = console,
+    prdRelativePath = DEFAULT_PRD_RELATIVE_PATH,
+    prdDisplayPath = DEFAULT_PRD_DISPLAY_PATH
+  } = dependencies;
+
+  const resolvedPath = path.isAbsolute(prdRelativePath)
+    ? prdRelativePath
+    : path.join(cwd, prdRelativePath);
+
+  if (fsExistsSync(resolvedPath)) {
+    return true;
+  }
+
+  const warn = typeof logger?.warn === 'function' ? logger.warn.bind(logger) : console.warn.bind(console);
+  warn(`⚠️  Product Requirements Document missing (${prdDisplayPath}). Add ${DEFAULT_PRD_DISPLAY_PATH} so teams understand release expectations.`);
+  return false;
+}
+
 function buildPreloadFlag(filePath) {
   const resolved = path.resolve(filePath);
   const escaped = resolved.includes(' ')

package/tests/build.test.js

@@ -8,7 +8,7 @@ import path from 'path';
 const exec = promisify(execCallback);
 
 test('build generates dist/index.mjs file', async () => {
-  const { stderr } = await exec('npm run build:server');
+  const { stderr } = await exec('npx cross-env NODE_ENV=development npm run build:server');
   // Allow the known vite warning about node:process
   const knownWarning = '[plugin vite:resolve] Module "node:process" has been externalized for browser compatibility';
   const tailwindOutput = '≈ tailwindcss';