mcp-perforce-server 1.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 iPraBhu
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/MCP_CONFIG_EXAMPLES.md

@@ -0,0 +1,205 @@
+# 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
+
+## 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",
+        "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",
+          "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"
+  }
+}
+```

package/README.md

@@ -0,0 +1,224 @@
+# MCP Perforce Server
+
+[![npm version](https://badge.fury.io/js/mcp-perforce-server.svg)](https://www.npmjs.com/package/mcp-perforce-server)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
+[![TypeScript](https://img.shields.io/badge/TypeScript-Ready-blue)](https://www.typescriptlang.org/)
+
+Enterprise-grade MCP (Model Context Protocol) server providing secure, non-interactive Perforce operations for AI-assisted development workflows with Claude, ChatGPT, VS Code, and Cursor IDE.
+
+> **Created by [Pratik Bhuite](https://github.com/iPraBhu)** using vibe coding to solve real-world Perforce automation challenges. Open source, community-driven, and ready for customization!
+
+## Overview
+
+Production-ready server that exposes Perforce VCS operations through the Model Context Protocol, enabling AI assistants and code editors to interact with Perforce repositories safely and efficiently. Perfect for DevOps automation, enterprise development workflows, and AI-powered version control management.
+
+**Key Features:**
+- 🔒 **Enterprise Security** - Read-only defaults with configurable access controls
+- 🌐 **Cross-platform Support** - Windows, macOS, Linux compatibility
+- 🤖 **AI Integration** - Works with Claude, ChatGPT, VS Code, Cursor, and other AI assistants
+- ⚡ **Non-interactive Operations** - Automated Perforce commands with comprehensive error handling
+- 📁 **Multi-project Support** - Automatic `.p4config` detection with upward directory search
+- 🛡️ **Production Ready** - Structured JSON responses with standardized error codes
+- 🔧 **Developer Friendly** - TypeScript support with comprehensive documentation
+- 🚀 **Zero Configuration** - Works out-of-the-box with sensible defaults
+
+## Why Choose MCP Perforce Server?
+
+**Alternative to:**
+- Manual Perforce CLI operations in AI workflows
+- Custom Git-to-Perforce bridges for AI assistants
+- Unsafe direct P4 command execution in development environments
+- Complex Perforce API integrations for code assistants
+
+**Perfect for:**
+- Enterprise teams using Perforce with AI development tools
+- DevOps automation with Anthropic Claude or OpenAI ChatGPT
+- VS Code and Cursor IDE users working with Perforce repositories  
+- Secure version control operations in AI-assisted coding workflows
+
+## Origin Story
+
+This project was born from a real need! I ([Pratik Bhuite](https://github.com/iPraBhu)) was facing challenges integrating Perforce with AI development tools and decided to solve it using **vibe coding** - building something that just works, feels right, and solves real problems.
+
+**🤝 Community Welcome**
+- ✅ **Use freely** - This is open source, use it however you need
+- 🐛 **Report issues** - Found a bug? Please let me know!
+- 🔧 **Customize** - Fork it, modify it, make it yours
+- 💡 **Contribute** - Ideas, PRs, and feedback are always welcome
+
+## Installation
+
+```bash
+npm install -g mcp-perforce-server
+```
+
+## Quick Start
+
+1. **Prerequisites:** Perforce CLI (`p4`) installed and in PATH
+
+2. **Configuration:** Choose one method:
+
+   **Method A: .p4config file** (Recommended)
+   ```
+   P4PORT=your-perforce-server:1666
+   P4USER=your-username
+   P4CLIENT=your-workspace-name
+   ```
+
+   **Method B: MCP Environment Variables**
+   ```json
+   {
+     "mcpServers": {
+       "perforce": {
+         "command": "mcp-perforce-server",
+         "env": {
+           "P4PORT": "your-perforce-server:1666",
+           "P4USER": "your-username", 
+           "P4CLIENT": "your-workspace-name"
+         }
+       }
+     }
+   }
+   ```
+
+3. **Verification:**
+   ```bash
+   mcp-perforce-server --help
+   ```
+
+## Security Configuration
+
+**Default Security Posture:**
+- `P4_READONLY_MODE=true` - Read-only operations only
+- `P4_DISABLE_DELETE=true` - Delete operations disabled
+
+**Production Environments:**
+```bash
+# Read-only mode (safest)
+P4_READONLY_MODE=true P4_DISABLE_DELETE=true
+
+# Write-enabled, delete-protected (recommended)  
+P4_READONLY_MODE=false P4_DISABLE_DELETE=true
+
+# Full access (use with caution)
+P4_READONLY_MODE=false P4_DISABLE_DELETE=false
+```
+
+## Supported Operations
+
+### Repository Operations
+- `p4.info` - Server and client information
+- `p4.status` - Workspace status
+- `p4.sync` - Sync from depot
+- `p4.opened` - List opened files
+
+### File Operations  
+- `p4.add` - Add files to Perforce
+- `p4.edit` - Open files for edit
+- `p4.delete` - Mark files for deletion
+- `p4.revert` - Revert changes
+- `p4.diff` - Show file differences
+
+### Changelist Operations
+- `p4.changelist.create` - Create new changelist
+- `p4.changelist.update` - Update changelist
+- `p4.changelist.submit` - Submit changelist
+- `p4.submit` - Submit default changelist
+
+### Utilities
+- `p4.filelog` - File history
+- `p4.clients` - List workspaces
+- `p4.config.detect` - Configuration diagnostics
+
+## Integration
+
+### VS Code / Cursor
+For silent operation without approval prompts, add these settings:
+```json
+{
+  "mcpServers": {
+    "perforce": {
+      "command": "mcp-perforce-server",
+      "env": {
+        "P4_READONLY_MODE": "false",
+        "LOG_LEVEL": "error"
+      },
+      "alwaysAllow": ["p4.*"],
+      "disabled": false
+    }
+  }
+}
+```
+
+See [MCP_CONFIG_EXAMPLES.md](MCP_CONFIG_EXAMPLES.md) for IDE-specific configuration.
+
+### Claude Desktop
+Add to `claude_desktop_config.json`:
+```json
+{
+  "mcpServers": {
+    "perforce": {
+      "command": "mcp-perforce-server",
+      "env": {
+        "P4_READONLY_MODE": "false"
+      }
+    }
+  }
+}
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `P4_READONLY_MODE` | Enable read-only mode | `true` |
+| `P4_DISABLE_DELETE` | Disable delete operations | `true` |
+| `P4_PATH` | Path to p4 executable | `p4` |
+| `P4CONFIG` | Config file name | `.p4config` |
+| `LOG_LEVEL` | Logging level | `warn` |
+
+## Error Handling
+
+Standardized error codes for reliable error handling:
+- `P4_NOT_FOUND` - Perforce executable not found
+- `P4_AUTH_FAILED` - Authentication failure
+- `P4_CLIENT_UNKNOWN` - Unknown workspace
+- `P4_CONNECTION_FAILED` - Server connection failed
+- `P4_READONLY_MODE` - Operation blocked by read-only mode
+- `P4_DELETE_DISABLED` - Delete operation blocked
+
+## Development
+
+```bash
+# Local development
+git clone https://github.com/iPraBhu/mcp-perforce-server.git
+cd mcp-perforce-server
+npm install
+npm run build
+
+# Run tests
+npm test
+
+# Development mode
+npm run watch
+```
+
+## Contributing
+
+This project was created with ❤️ by [Pratik Bhuite](https://github.com/iPraBhu) to solve real Perforce automation challenges. 
+
+**Ways to contribute:**
+- 🐛 **Report bugs** - Open an issue if something's not working
+- 💡 **Suggest features** - Have an idea? Let's discuss it!
+- 🔧 **Submit PRs** - Code contributions are welcome
+- 📖 **Improve docs** - Help make the documentation better
+- ⭐ **Star the repo** - Show your support!
+
+**Found this useful?** Consider giving it a star ⭐ and sharing with others who might benefit!
+
+## License
+
+MIT License - Feel free to use, modify, and distribute as needed. See [LICENSE](LICENSE) for details.
+
+**TL;DR:** Use it however you want, just keep the license notice. Built for the community! 🚀

package/dist/p4/config.d.ts

@@ -0,0 +1,67 @@
+export interface P4ConfigResult {
+    found: boolean;
+    configPath?: string;
+    projectRoot?: string;
+    config: Record<string, string>;
+    environment: Record<string, string>;
+}
+export interface P4ServerConfig {
+    readOnlyMode: boolean;
+    disableDelete: boolean;
+}
+export declare class P4Config {
+    private static readonly DEFAULT_CONFIG_NAME;
+    /**
+     * Find .p4config file by searching upward from the given directory
+     */
+    findConfig(startPath?: string): Promise<P4ConfigResult>;
+    /**
+     * Search upward through parent directories for config file
+     */
+    private searchUpward;
+    /**
+     * Parse .p4config file content
+     */
+    private parseConfigFile;
+    /**
+     * Build environment variables from config
+     */
+    private buildEnvironment;
+    /**
+     * Get project root directory from workspace path
+     */
+    getProjectRoot(workspacePath?: string): Promise<string>;
+    /**
+     * Setup environment and working directory for p4 command
+     */
+    setupForCommand(workspacePath?: string): Promise<{
+        cwd: string;
+        env: Record<string, string>;
+        configResult: P4ConfigResult;
+    }>;
+    /**
+     * Validate that Perforce environment is properly configured
+     */
+    validateEnvironment(configResult: P4ConfigResult): {
+        valid: boolean;
+        errors: string[];
+    };
+    /**
+     * Get server configuration from environment variables
+     */
+    getServerConfig(): P4ServerConfig;
+    /**
+     * Extract MCP-provided Perforce environment variables
+     */
+    private getMcpEnvironment;
+    /**
+     * Create a minimal .p4config file template
+     */
+    static createTemplate(options?: {
+        port?: string;
+        user?: string;
+        client?: string;
+        charset?: string;
+    }): string;
+}
+//# sourceMappingURL=config.d.ts.map

package/dist/p4/config.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"config.d.ts","sourceRoot":"","sources":["../../src/p4/config.ts"],"names":[],"mappings":"AAGA,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,OAAO,CAAC;IACf,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAC/B,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,MAAM,WAAW,cAAc;IAC7B,YAAY,EAAE,OAAO,CAAC;IACtB,aAAa,EAAE,OAAO,CAAC;CACxB;AAED,qBAAa,QAAQ;IACnB,OAAO,CAAC,MAAM,CAAC,QAAQ,CAAC,mBAAmB,CAAe;IAE1D;;OAEG;IACG,UAAU,CAAC,SAAS,GAAE,MAAsB,GAAG,OAAO,CAAC,cAAc,CAAC;IAiC5E;;OAEG;YACW,YAAY;IAgC1B;;OAEG;YACW,eAAe;IA4B7B;;OAEG;IACH,OAAO,CAAC,gBAAgB;IA+BxB;;OAEG;IACG,cAAc,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC;IAW7D;;OAEG;IACG,eAAe,CAAC,aAAa,CAAC,EAAE,MAAM,GAAG,OAAO,CAAC;QACrD,GAAG,EAAE,MAAM,CAAC;QACZ,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;QAC5B,YAAY,EAAE,cAAc,CAAC;KAC9B,CAAC;IAgBF;;OAEG;IACH,mBAAmB,CAAC,YAAY,EAAE,cAAc,GAAG;QAAE,KAAK,EAAE,OAAO,CAAC;QAAC,MAAM,EAAE,MAAM,EAAE,CAAA;KAAE;IA4BvF;;OAEG;IACH,eAAe,IAAI,cAAc;IAOjC;;OAEG;IACH,OAAO,CAAC,iBAAiB;IAkBzB;;OAEG;IACH,MAAM,CAAC,cAAc,CAAC,OAAO,GAAE;QAC7B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,OAAO,CAAC,EAAE,MAAM,CAAC;KACb,GAAG,MAAM;CAyBhB"}