mcp-perforce-server 2.1.0 → 2.1.2

package/MCP_CONFIG_EXAMPLES.md

@@ -1,223 +1,214 @@
-# MCP Perforce Server Configuration Examples
-
-## Silent Operation Configuration
-
-To prevent VS Code from asking for approval on every command and to hide terminal execution:
-
-**Key Settings:**
-- `"alwaysAllow": ["p4.*"]` or `"alwaysAllow": true` - Auto-approve all p4 commands
-- `"LOG_LEVEL": "error"` - Minimize console output (only show errors)
-- `"disabled": false` - Ensure server is enabled
-
-## Authentication Configuration
-
-**Important:** Configure your Perforce credentials using one of these methods:
-
-1. **`.p4config` file** (Recommended) - Create in project root:
-   ```
-   P4PORT=perforce-server:1666
-   P4USER=your-username
-   P4CLIENT=your-workspace-name
-   P4PASSWD=your-password
-   ```
-
-2. **Environment variables** in MCP config (see examples below)
-
-The server automatically detects and uses these credentials. Passwords are masked in logs for security.
-
-## VS Code with Claude Dev/Cline
-
-### Option 1: Using .p4config file (Recommended)
-Create a `.p4config` file in your project root, then:
-```json
-{
-  "mcpServers": {
-    "perforce": {
-      "command": "mcp-perforce-server",
-      "args": [],
-      "env": {
-        "P4_READONLY_MODE": "false",
-        "P4_DISABLE_DELETE": "true",
-        "LOG_LEVEL": "error"
-      },
-      "alwaysAllow": ["p4.*"],
-      "disabled": false
-    }
-  }
-}
-```
-
-### Option 2: Direct configuration in MCP config
-```json
-{
-  "mcpServers": {
-    "perforce": {
-      "command": "mcp-perforce-server",
-      "args": [],
-      "env": {
-        "P4PORT": "perforce-server:1666",
-        "P4USER": "your-username",
-        "P4CLIENT": "your-workspace-name",
-        "P4PASSWD": "your-password",
-        "P4CHARSET": "utf8",
-        "P4_READONLY_MODE": "false",
-        "P4_DISABLE_DELETE": "true",
-        "LOG_LEVEL": "error"
-      },
-      "alwaysAllow": ["p4.*"],
-      "disabled": false
-    }
-  }
-}
-```
-
-## Cursor IDE
-
-### Option 1: Using .p4config file (Recommended)
-```json
-{
-  "mcp": {
-    "servers": {
-      "perforce": {
-        "command": "mcp-perforce-server",
-        "args": [],
-        "env": {
-          "P4_READONLY_MODE": "false", 
-          "P4_DISABLE_DELETE": "true",
-          "LOG_LEVEL": "error"
-        },
-        "alwaysAllow": true
-      }
-    }
-  }
-}
-```
-
-### Option 2: Direct configuration in MCP config
-```json
-{
-  "mcp": {
-    "servers": {
-      "perforce": {
-        "command": "mcp-perforce-server",
-        "args": [],
-        "env": {
-          "P4PORT": "perforce-server:1666",
-          "P4USER": "your-username", 
-          "P4CLIENT": "your-workspace-name",
-          "P4PASSWD": "your-password",
-          "P4_READONLY_MODE": "false",
-          "P4_DISABLE_DELETE": "true",
-          "LOG_LEVEL": "error"
-        },
-        "alwaysAllow": true
-      }
-    }
-  }
-}
-```
-
-## Claude Desktop
-
-### macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
-### Windows: %APPDATA%\Claude\claude_desktop_config.json
-
-### Option 1: Using .p4config file (Recommended)
-```json
-{
-  "mcpServers": {
-    "perforce": {
-      "command": "mcp-perforce-server",
-      "args": [],
-      "env": {
-        "P4_READONLY_MODE": "false",
-        "P4_DISABLE_DELETE": "true",
-        "LOG_LEVEL": "error"
-      },
-      "alwaysAllow": ["p4.*"]
-    }
-  }
-}
-```
-
-### Option 2: Direct configuration in MCP config
-```json
-{
-  "mcpServers": {
-    "perforce": {
-      "command": "mcp-perforce-server",
-      "args": [],
-      "env": {
-        "P4PORT": "perforce-server:1666",
-        "P4USER": "your-username",
-        "P4CLIENT": "your-workspace-name", 
-        "P4_READONLY_MODE": "false",
-        "P4_DISABLE_DELETE": "true",
-        "LOG_LEVEL": "error"
-      },
-      "alwaysAllow": ["p4.*"]
-    }
-  }
-}
-```
-
-## Local Development Setup (if not globally installed)
-
-Replace the "command" field with the full path to your built server:
-
-```json
-{
-  "command": "node",
-  "args": ["/full/path/to/your/mcp-perforce-server/dist/server.js"]
-}
-```
-
-## Safety Configuration Levels
-
-### Maximum Safety (Default)
-```json
-{
-  "env": {
-    "P4_READONLY_MODE": "true",
-    "P4_DISABLE_DELETE": "true"
-  }
-}
-```
-
-### Write-enabled, Delete Protected  
-```json
-{
-  "env": {
-    "P4_READONLY_MODE": "false",
-    "P4_DISABLE_DELETE": "true"
-  }
-}
-```
-
-## Configuration Notes
-
-### Silent Operation
-- `"alwaysAllow": ["p4.*"]` - Auto-approves all p4 commands, preventing VS Code approval prompts
-- `"alwaysAllow": true` - Auto-approves all commands (Cursor)
-- `"LOG_LEVEL": "error"` - Reduces console output to errors only
-- `"disabled": false` - Ensures the server is active
-
-### Security Levels
-- **Safe**: `P4_READONLY_MODE=true, P4_DISABLE_DELETE=true` (read-only)
-- **Recommended**: `P4_READONLY_MODE=false, P4_DISABLE_DELETE=true` (write, no delete)  
-- **Full Access**: `P4_READONLY_MODE=false, P4_DISABLE_DELETE=false` (use with caution)
-
-### Troubleshooting
-- If commands still show approval prompts, ensure `alwaysAllow` is configured
-- If you see terminal output, set `LOG_LEVEL` to `"error"`
-- Commands execute silently in the background without terminal windows
-
-### Full Access (Use with Caution)
-```json
-{
-  "env": {
-    "P4_READONLY_MODE": "false", 
-    "P4_DISABLE_DELETE": "false"
-  }
-}
-```
+# MCP Perforce Server Configuration Examples
+
+All examples in this document use the default safe profile: read-only enabled and delete disabled.
+
+## Client Config Fields
+
+| Field | Required | Example | Description |
+|---|---|---|---|
+| `command` | Yes | `"mcp-perforce-server"` | Executable to start the MCP server. |
+| `args` | No | `[]` or `["/path/to/dist/server.js"]` | Command arguments (use for local build path). |
+| `env` | No | `{ "P4_READONLY_MODE": "true" }` | Server environment variables. |
+| `alwaysAllow` | Client-specific | `["p4.*"]` or `true` | Auto-approve tool calls to reduce prompts. |
+| `disabled` | Client-specific | `false` | Enables/disables the server entry. |
+
+## Authentication Options
+
+| Method | Recommended | How it works |
+|---|---|---|
+| `.p4config` file | Yes | Place Perforce variables in a `.p4config` file in your project/workspace root. |
+| MCP `env` variables | Optional | Put Perforce variables directly in the MCP server config JSON. |
+
+`.p4config` example:
+
+```ini
+P4PORT=perforce-server:1666
+P4USER=your-username
+P4CLIENT=your-workspace-name
+P4PASSWD=your-password
+```
+
+## Environment Variables Used In Examples
+
+| Variable | Example Value | Default | Purpose |
+|---|---|---|---|
+| `P4_READONLY_MODE` | `"true"` | `true` | Keeps server in read-only mode. |
+| `P4_DISABLE_DELETE` | `"true"` | `true` | Keeps delete operations disabled. |
+| `LOG_LEVEL` | `"error"` | `warn` | Keeps console output minimal. |
+| `P4PORT` | `"perforce-server:1666"` | unset | Perforce server address (required if not in `.p4config`). |
+| `P4USER` | `"your-username"` | unset | Perforce user (required if not in `.p4config`). |
+| `P4CLIENT` | `"your-workspace-name"` | unset | Perforce client/workspace (required if not in `.p4config`). |
+| `P4PASSWD` | `"your-password"` | unset | Password/ticket (optional depending on server auth). |
+| `P4CHARSET` | `"utf8"` | unset | Optional Perforce charset. |
+
+For the complete server configuration table (all supported env vars), see [README.md](README.md#server-configuration-reference).
+
+## VS Code with Claude Dev/Cline
+
+### Option 1: Using `.p4config` (Recommended)
+
+```json
+{
+  "mcpServers": {
+    "perforce": {
+      "command": "mcp-perforce-server",
+      "args": [],
+      "env": {
+        "P4_READONLY_MODE": "true",
+        "P4_DISABLE_DELETE": "true",
+        "LOG_LEVEL": "error"
+      },
+      "alwaysAllow": ["p4.*"],
+      "disabled": false
+    }
+  }
+}
+```
+
+### Option 2: Direct MCP Env Configuration
+
+```json
+{
+  "mcpServers": {
+    "perforce": {
+      "command": "mcp-perforce-server",
+      "args": [],
+      "env": {
+        "P4PORT": "perforce-server:1666",
+        "P4USER": "your-username",
+        "P4CLIENT": "your-workspace-name",
+        "P4PASSWD": "your-password",
+        "P4CHARSET": "utf8",
+        "P4_READONLY_MODE": "true",
+        "P4_DISABLE_DELETE": "true",
+        "LOG_LEVEL": "error"
+      },
+      "alwaysAllow": ["p4.*"],
+      "disabled": false
+    }
+  }
+}
+```
+
+## Cursor IDE
+
+### Option 1: Using `.p4config` (Recommended)
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "perforce": {
+        "command": "mcp-perforce-server",
+        "args": [],
+        "env": {
+          "P4_READONLY_MODE": "true",
+          "P4_DISABLE_DELETE": "true",
+          "LOG_LEVEL": "error"
+        },
+        "alwaysAllow": true
+      }
+    }
+  }
+}
+```
+
+### Option 2: Direct MCP Env Configuration
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "perforce": {
+        "command": "mcp-perforce-server",
+        "args": [],
+        "env": {
+          "P4PORT": "perforce-server:1666",
+          "P4USER": "your-username",
+          "P4CLIENT": "your-workspace-name",
+          "P4PASSWD": "your-password",
+          "P4_READONLY_MODE": "true",
+          "P4_DISABLE_DELETE": "true",
+          "LOG_LEVEL": "error"
+        },
+        "alwaysAllow": true
+      }
+    }
+  }
+}
+```
+
+## Claude Desktop
+
+Config file paths:
+
+| Platform | Path |
+|---|---|
+| macOS | `~/Library/Application Support/Claude/claude_desktop_config.json` |
+| Windows | `%APPDATA%\Claude\claude_desktop_config.json` |
+
+### Option 1: Using `.p4config` (Recommended)
+
+```json
+{
+  "mcpServers": {
+    "perforce": {
+      "command": "mcp-perforce-server",
+      "args": [],
+      "env": {
+        "P4_READONLY_MODE": "true",
+        "P4_DISABLE_DELETE": "true",
+        "LOG_LEVEL": "error"
+      },
+      "alwaysAllow": ["p4.*"]
+    }
+  }
+}
+```
+
+### Option 2: Direct MCP Env Configuration
+
+```json
+{
+  "mcpServers": {
+    "perforce": {
+      "command": "mcp-perforce-server",
+      "args": [],
+      "env": {
+        "P4PORT": "perforce-server:1666",
+        "P4USER": "your-username",
+        "P4CLIENT": "your-workspace-name",
+        "P4_READONLY_MODE": "true",
+        "P4_DISABLE_DELETE": "true",
+        "LOG_LEVEL": "error"
+      },
+      "alwaysAllow": ["p4.*"]
+    }
+  }
+}
+```
+
+## Local Development Setup (If Not Globally Installed)
+
+Replace `command` with `node` and point `args` at your built server:
+
+```json
+{
+  "command": "node",
+  "args": ["/full/path/to/your/mcp-perforce-server/dist/server.js"]
+}
+```
+
+## Safety Profile Used In This Document
+
+| Profile | `P4_READONLY_MODE` | `P4_DISABLE_DELETE` | Behavior |
+|---|---|---|---|
+| Default safe profile | `true` | `true` | Read-only; write tools and delete operations blocked by default. |
+
+## Troubleshooting
+
+| Symptom | Check |
+|---|---|
+| Approval prompts still appear | Ensure `alwaysAllow` is configured for your client. |
+| Too much terminal output | Set `LOG_LEVEL` to `"error"`. |
+| Perforce auth/config errors | Verify `P4PORT`, `P4USER`, `P4CLIENT` are set via `.p4config` or MCP `env`. |