feat: support cwd field for stdio servers (fixes #189)

Author: ravitemer

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [5.11.1] - 2025-07-08
+
+### Added
+
+- **`cwd` field support for stdio servers**: 
+  - Added `cwd` field to `MCPServerConfig` type definition
+  - Added validation for `cwd` field in server configuration
+  - Updated documentation with examples and use cases
 
 ## [5.11.0] - 2025-06-26
 

doc/mcp/servers_json.md

@@ -63,7 +63,8 @@ The `config` file should have a `mcpServers` key. This contains `stdio` and `rem
                 "DB_URL": "postgresql://user:${DB_PASSWORD}@localhost/myapp",
                 "DB_PASSWORD": "password123",
                 "FALLBACK_VAR": null
-            }
+            },
+            "cwd": "/home/ubuntu/server-dir/"
         }
     }
 }
@@ -75,6 +76,7 @@ The `config` file should have a `mcpServers` key. This contains `stdio` and `rem
 ##### Optional fields: 
 - `args`: Array of command arguments (supports `${VARIABLE}` and `${cmd: command}` placeholders)
 - `env`: Environment variables with placeholder resolution and system fallback
+- `cwd`: The current working directory for the MCP server process (supports `${VARIABLE}` and `${cmd: command}` placeholders)
 - `dev`: Development mode configuration for auto-restart on file changes
 - `name`: Display name that will be shown in the UI
 - `description`: Short description about the server (useful when the server is disabled and `auto_toggle_mcp_servers` is `true`)
@@ -98,6 +100,33 @@ Given `API_KEY=secret` in the environment:
 
 > ⚠️ **Legacy Syntax**: `$VAR` (args) and `$: command` (env) are deprecated but still supported with warnings. Use `${VAR}` and `${cmd: command}` instead.
 
+
+#### `cwd` Example:
+
+The `cwd` field is particularly useful when your MCP server needs to run in a specific directory context. Here's a practical example:
+
+```json
+{
+    "mcpServers": {
+        "project-server": {
+            "command": "npm",
+            "args": ["start"],
+            "cwd": "/home/ubuntu/my-mcp-project/",
+            "env": {
+                "NODE_ENV": "development"
+            }
+        }
+    }
+}
+```
+
+**Use cases for `cwd`:**
+- When the MCP server needs to access relative files in its project directory
+- When using npm/yarn scripts that depend on being in the project root
+
+> **Note**: The top-level `cwd` field sets the working directory for the server process itself, while `dev.cwd` (used in development mode) sets the directory for file watching. These serve different purposes and can be used together.
+
+
 ##### `dev` Development Mode
 
 The `dev` field enables automatic server restarts when files change during development:

lua/mcphub/types.lua

@@ -34,6 +34,7 @@
 ---@field command? string
 ---@field args? table
 ---@field env? table<string,string>
+---@field cwd? string
 ---@field headers? table<string,string>
 ---@field url? string
 

lua/mcphub/utils/validation.lua

@@ -151,6 +151,17 @@ function M.validate_server_config(name, config)
                 ),
             }
         end
+
+        if config.cwd and (type(config.cwd) ~= "string" or config.cwd == "") then
+            return {
+                ok = false,
+                error = Error(
+                    "VALIDATION",
+                    Error.Types.SETUP.INVALID_CONFIG,
+                    string.format("Server '%s' has invalid cwd: must be a non-empty string", name)
+                ),
+            }
+        end
     elseif has_sse then
         -- Validate SSE config
         if type(config.url) ~= "string" or config.url == "" then

lua/mcphub/utils/version.lua

@@ -1,9 +1,9 @@
 return {
-    PLUGIN_VERSION = "5.11.0", -- Current plugin version
+    PLUGIN_VERSION = "5.11.1", -- Current plugin version
     REQUIRED_NODE_VERSION = { -- Required mcp-hub version
         major = 3,
         minor = 7,
-        patch = 0,
-        string = "3.7.0",
+        patch = 2,
+        string = "3.7.2",
     },
 }