Improves DX for containers

containers/Dockerfile

@@ -8,7 +8,7 @@ WORKDIR /app
 RUN git clone --depth 1 https://github.com/Pimzino/spec-workflow-mcp.git .
 
 # Install dependencies and build
-RUN npm ci && npm run build
+RUN npm install && npm run build
 
 # Runtime stage
 FROM node:24-alpine
@@ -20,18 +20,15 @@ RUN npm ci --only=production
 
 # Copy built application and necessary resources
 COPY --from=builder /app/dist ./dist
-COPY --from=builder /app/src/locales ./src/locales
 
 RUN mkdir -p /workspace
 
-# Change ownership of the app directory to the node user (uid=1000)
-RUN chown -R node:node /app /workspace
-
-# Switch to the node user to match host user permissions
-USER node
+# Ensure application files are readable by any UID
+# This is necessary because we run the container with --user flag at runtime
+RUN chmod -R a+rX /app
 
 WORKDIR /workspace
 
 EXPOSE 3000
 
-CMD node /app/dist/index.js ${SPEC_WORKFLOW_PATH:-/workspace} --dashboard --port ${DASHBOARD_PORT:-3000}
+CMD ["sh", "-c", "node /app/dist/index.js ${SPEC_WORKFLOW_PATH:-/workspace} --dashboard --port ${DASHBOARD_PORT:-3000}"]

containers/README.md

@@ -18,11 +18,28 @@ From the containers directory, build the Docker image:
 docker build -t spec-workflow-mcp .
 ```
 
+The container will run with your host user's UID/GID at runtime using the `--user` flag, ensuring proper file permissions.
+
 ## MCP Server Configuration
 
-### For Claude Desktop or other MCP clients
+### Automated Setup (Recommended)
+
+The easiest way to configure the MCP server is to use the provided setup script:
+
+```bash
+# From your project directory (where you want to use spec-workflow)
+/path/to/spec-workflow-mcp/containers/setup-mcp.sh
+```
+
+This script will:
+- Detect your user ID and group ID automatically
+- Create or update `.mcp.json` with the correct configuration
+- Handle existing MCP configurations safely
+- Provide clear next steps
 
-Create or update the `.mcp.json` file in your project root with the following configuration:
+### Manual Configuration
+
+If you prefer to configure manually, create or update the `.mcp.json` file in your project root:
 
 ```json
 {
@@ -31,46 +48,36 @@ Create or update the `.mcp.json` file in your project root with the following co
         "command": "docker",
         "args": [
           "run", "--rm", "-i",
-          "-v", "./.spec-workflow:/home/username/project/.spec-workflow:rw",
+          "--user", "1000:1000",
+          "-v", "/full/path/to/project:/full/path/to/project:rw",
           "--entrypoint=node",
           "spec-workflow-mcp:latest",
-          "/app/dist/index.js", "./"
+          "/app/dist/index.js", "/full/path/to/project"
         ]
       }
     }
   }
 
 ```
 
+**Important**: Replace `1000:1000` with your actual user ID and group ID (get them with `id -u` and `id -g`).
+
 ## Important Configuration Notes
 
 ### Path Mapping Requirements
 
-The container requires the `.spec-workflow` directory to be mounted at the **exact same path** inside the container as it exists on your host system. This is critical for the MCP server to function correctly.
+The container requires the entire project directory to be mounted at the **exact same path** inside the container as it exists on the host system. This is so the MCP server can reliably create and manage the `.spec-workflow` directory
 
-**Example:** If your project is at `/home/steev/tabletopsentinel.com`, your configuration would be:
 
-```json
-{
-    "mcpServers": {
-      "spec-workflow": {
-        "command": "docker",
-        "args": [
-          "run", "--rm", "-i",
-          "-v", "./.spec-workflow:/home/steev/tabletopsentinel.com/.spec-workflow:rw",
-          "--entrypoint=node",
-          "spec-workflow-mcp:latest",
-          "/app/dist/index.js", "./"
-        ]
-      }
-    }
-}
+**Example:** If your project is at `/home/steev/myproject`, your configuration would mount:
+```
+-v /home/steev/myproject:/home/steev/myproject:rw
 ```
 
 ### Key Configuration Points
 
 - **Path Consistency**: The container path must match your host path exactly
-- **Volume Mount**: Only the `.spec-workflow` directory needs to be mounted
+- **Volume Mount**: The entire project directory must be mounted for the MCP server to access source code
 - **Auto-creation**: The `.spec-workflow` directory will be created if it doesn't exist
 - **SELinux Note**: If you're using SELinux, you may need to add `:z` to the volume mount (e.g., `:rw,z`)
 
@@ -112,10 +119,11 @@ docker-compose down
 
 ### Common Issues
 
-1. **Permission Denied**: Ensure the `.spec-workflow` directory has proper permissions
+1. **Permission Denied**: The container runs with your host user ID/GID via the `--user` flag. Ensure `.mcp.json` includes the correct user ID from `id -u` and group ID from `id -g`
 2. **Port Already in Use**: Choose a different port using the `DASHBOARD_PORT` variable
 3. **Path Not Found**: Verify that your `SPEC_WORKFLOW_PATH` matches your actual project location
 4. **SELinux Issues**: On SELinux-enabled systems, add `:z` to volume mounts
+5. **File Ownership Issues**: Rebuild the container with the correct user/group IDs if `.spec-workflow` files are created with wrong ownership
 
 ### Logs and Debugging