{"id":35797551,"url":"https://github.com/perforce/p4mcp-server","last_synced_at":"2026-02-26T18:28:15.101Z","repository":{"id":317785312,"uuid":"1060151124","full_name":"perforce/p4mcp-server","owner":"perforce","description":"[Community Supported] Perforce P4MCP Server is a Model Context Protocol (MCP) server that integrates with the Perforce P4 version control system.","archived":false,"fork":false,"pushed_at":"2025-10-03T01:25:28.000Z","size":432,"stargazers_count":8,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-10-03T03:37:41.405Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/perforce.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-09-19T13:10:22.000Z","updated_at":"2025-10-03T01:25:31.000Z","dependencies_parsed_at":"2025-10-03T03:37:43.477Z","dependency_job_id":"a24d3051-74b6-447b-834f-8dc3791b2ddd","html_url":"https://github.com/perforce/p4mcp-server","commit_stats":null,"previous_names":["perforce/p4mcp-server"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/perforce/p4mcp-server","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perforce%2Fp4mcp-server","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perforce%2Fp4mcp-server/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perforce%2Fp4mcp-server/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perforce%2Fp4mcp-server/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/perforce","download_url":"https://codeload.github.com/perforce/p4mcp-server/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/perforce%2Fp4mcp-server/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":29502934,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-02-16T05:57:17.024Z","status":"ssl_error","status_checked_at":"2026-02-16T05:56:49.929Z","response_time":115,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.5:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-01-07T10:00:54.771Z","updated_at":"2026-02-26T18:28:15.083Z","avatar_url":"https://github.com/perforce.png","language":"Python","funding_links":[],"categories":["📚 Projects (2474 total)"],"sub_categories":["MCP Servers"],"readme":"\n\u003cp align=\"center\"\u003e\n  \u003cimg src=\"./icons/logo-p4mcp-reg.svg\" alt=\"Perforce P4 MCP Server\" width=\"480\" /\u003e\n\u003c/p\u003e\u003cbr\u003e\n\n\n\u003cdiv align=\"center\"\u003e\n\n![Support](https://img.shields.io/badge/Support-Community-yellow.svg)\n\n![GitHub release](https://img.shields.io/github/v/release/perforce/p4mcp-server?color=blue)\n\n\u003ch1\u003ePerforce P4 MCP Server\u003c/h1\u003e\n\n\u003cp\u003e\n  \u003cstrong\u003ePerforce P4 MCP Server is a Model Context Protocol (MCP) server that integrates with the Perforce P4 version control system. It is built on FastMCP with direct P4 Python bindings to expose safe, structured read/write tools for changelists, files, shelves, workspaces, jobs, reviews, and server metadata.\u003c/strong\u003e\n\u003c/p\u003e\n\n\u003cnav aria-label=\"Quick navigation\"\u003e\n  \u003cp align=\"center\"\u003e\n    \u003ca href=\"#features\"\u003eFeatures\u003c/a\u003e ·\n    \u003ca href=\"#prerequisites\"\u003ePrerequisites\u003c/a\u003e ·\n    \u003ca href=\"#system-requirements\"\u003eSystem Requirements\u003c/a\u003e ·\n    \u003ca href=\"#local-p4-mcp-server-installation\"\u003eInstall\u003c/a\u003e ·\n    \u003ca href=\"#mcp-client-configuration\"\u003eClient Configurations\u003c/a\u003e ·\n    \u003ca href=\"#p4-configuration\"\u003eP4 Configurations\u003c/a\u003e ·\n    \u003ca href=\"#available-tools\"\u003eTools\u003c/a\u003e \n  \u003c/p\u003e\n   \u003cp align=\"center\"\u003e\n    \u003ca href=\"#logging-and-usage-data\"\u003eLogging\u003c/a\u003e ·\n    \u003ca href=\"#troubleshooting\"\u003eTroubleshoot\u003c/a\u003e ·\n    \u003ca href=\"#support\"\u003eSupport\u003c/a\u003e ·\n    \u003ca href=\"#contributions\"\u003eContributions\u003c/a\u003e ·\n    \u003ca href=\"#license\"\u003eLicense\u003c/a\u003e\n  \u003c/p\u003e\n\u003c/nav\u003e\n\u003c/div\u003e\n\n## Features\n\n- **Comprehensive P4 integration**: Read/write tools across files, changelists, shelves, workspaces, jobs, reviews, and server information\n- **Code review workflows**: P4 Code Review support for review discovery, voting, state transitions, commenting, and participant management\n- **Safety first**: Read-only mode by default, ownership checks, explicit confirmation for destructive deletes.\n- **Flexible toolsets**: Configure which tool categories to enable: files, changelists, shelves, workspaces, jobs and reviews.\n- **Robust logging**: Application and session logging to the `logs/` directory.\n- **Optional telemetry**: Consent-gated usage statistics. Disabled by default.\n- **Cross platform**: Supported on macOS and Windows with pre-built binaries.\n\n## Prerequisites\n\n- **P4 Server access**: Connection to a P4 Server with proper credentials\n- **Authentication**: Valid P4 login (ticket-based or password)\n\n## System Requirements\n\n| Component | Supported Versions |\n|-----------|-------------------|\n| **Operating Systems** | Windows 10+\u003cbr\u003emacOS 12+\u003cbr\u003eUbuntu 20.04+ |\n| **Perforce P4 Server** | 2025.2 *(earlier versions untested)* |\n| **Python** | 3.11+ *(required only for building from source)* |\n\n## Local P4 MCP Server installation\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003ePre-built binaries (recommended)\u003c/b\u003e\u003c/summary\u003e\n\nDownload the appropriate binary for your operating system:\n- **macOS**: [p4-mcp-server-mac.zip](https://github.com/perforce/p4mcp-server/releases/latest/download/p4-mcp-server-mac.zip)\n- **Windows**: [p4-mcp-server-win.zip](https://github.com/perforce/p4mcp-server/releases/latest/download/p4-mcp-server-win.zip)\n\nExtract and use the executable directly. No Python installation is required.\n\n```bash\n# Windows\nunzip p4-mcp-server-2025.2.0.zip\ncd p4-mcp-server-2025.2.0\n./p4-mcp-server.exe --help\n\n# macOS\ntar -xzf p4-mcp-server-2025.2.0.tgz\ncd p4-mcp-server-2025.2.0\n./p4-mcp-server --help\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eBuild from source\u003c/b\u003e\u003c/summary\u003e\n\nRequirements:\n  - Python 3.11+ (with Tkinter)\n\nBuild:\n  - macOS:  \u003ccode\u003echmod +x build.sh \u0026amp;\u0026amp; ./build.sh package\u003c/code\u003e\n  - Linux:  \u003ccode\u003echmod +x build.sh \u0026amp;\u0026amp; ./build.sh package\u003c/code\u003e\n  - Windows: \u003ccode\u003ebuild.bat package\u003c/code\u003e\n\nOutput:\n  - macOS: \u003ccode\u003ep4-mcp-server-\u0026lt;version\u0026gt;.tgz\u003c/code\u003e\n  - Windows: \u003ccode\u003ep4-mcp-server-\u0026lt;version\u0026gt;.zip\u003c/code\u003e\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eRun from Docker\u003c/b\u003e\u003c/summary\u003e\n\nRun the P4 MCP Server from a Docker container with STDIO transport, allowing MCP clients to manage the container lifecycle.\n\n\u003e **Note:** Docker-based execution is currently supported on macOS and Linux only.\n\n**Prerequisites**\n\n- Docker installed and running\n- Valid P4 credentials and access to a P4 server\n\n**Build the Docker Image**\n\n```bash\ncd /path/to/p4mcp-server\ndocker build -t p4-mcp-server .\n```\n\n**Configure MCP Client**\n\nAdd the following to your `mcp.json`:\n\n```json\n{\n    \"servers\": {\n        \"perforce-p4mcp-docker\": {\n            \"command\": \"docker\",\n            \"args\": [\n                \"run\", \"-i\", \"--rm\",\n                \"--hostname\", \"your-hostname\",\n                \"-e\", \"P4PORT=ssl:perforce.example.com:1666\",\n                \"-e\", \"P4USER=your_username\",\n                \"-e\", \"P4CLIENT=your_workspace\",\n                \"-v\", \"/Users/your_username/.p4tickets:/root/.p4tickets:ro\",\n                \"p4-mcp-server\"\n            ]\n        }\n    }\n}\n```\n\n**Configuration Options**\n\n| Flag | Description |\n|------|-------------|\n| `-i` | Interactive mode (required for STDIO) |\n| `--rm` | Remove container when stopped |\n| `--hostname` | Match workspace host restriction |\n| `-e P4PORT` | P4 server address |\n| `-e P4USER` | P4 username |\n| `-e P4CLIENT` | Workspace name |\n| `-v` | Mount P4 tickets file |\n\n**Authentication**\n\nUsing P4 tickets:\n```bash\n# macOS/Linux\n-v /Users/your_username/.p4tickets:/root/.p4tickets:ro\n```\n\n\u003e **Note:** Use the full path to your tickets file (not `~`). After running `p4 login`, restart the MCP server to pick up the new ticket.\n\nUsing a password:\n```bash\n-e P4PASSWD=\"your_password\"\n```\n\n**Workspace Host Restrictions**\n\n\u003e ⚠️ **Important:** Docker containers have their own hostname, which differs from your local machine. If your P4 workspace is restricted to a specific host, operations like `sync` will fail.\n\nTo resolve this, set the container hostname to match your workspace's host restriction:\n\n```bash\n--hostname your-hostname\n```\n\nTo find your workspace host name:\n```bash\n# macOS/Linux\np4 client -o your_workspace | grep \"^Host:\"\n```\n\n**Mounting Client Root for Write Operations**\n\n\u003e ⚠️ **Important:** By default, the Docker container cannot access your local workspace files. For write operations like `sync`, `submit`, or `reconcile`, you must mount your client root directory into the container at the **same path**.\n\nAdd a volume mount for your client root:\n```bash\n-v /path/to/your/client/root:/path/to/your/client/root\n```\n\nExample configuration with client root mounted:\n```json\n{\n    \"servers\": {\n        \"perforce-p4mcp-docker\": {\n            \"command\": \"docker\",\n            \"args\": [\n                \"run\", \"-i\", \"--rm\",\n                \"--hostname\", \"your-hostname\",\n                \"-e\", \"P4PORT=ssl:perforce.example.com:1666\",\n                \"-e\", \"P4USER=your_username\",\n                \"-e\", \"P4CLIENT=your_workspace\",\n                \"-v\", \"/Users/your_username/.p4tickets:/root/.p4tickets\",\n                \"-v\", \"/path/to/client/root:/path/to/client/root\",\n                \"p4-mcp-server\"\n            ]\n        }\n    }\n}\n```\n\nTo find your client root:\n```bash\np4 client -o your_workspace | grep \"^Root:\"\n```\n\n\u003e **Note:** The mount path inside the container must match the client root path exactly, as P4 tracks files by their absolute paths.\n\n\u003c/details\u003e\n\n## MCP client configuration\n\n\u003e **Note:** In all configuration examples below, if `P4CONFIG` is set, you do not need to set any environment variables in the `env` block. The server will use the configuration from the specified P4CONFIG file instead.\n\u003e \u003cdetails\u003e \u003csummary\u003e\u003cstrong\u003eServer configuration example\u003c/strong\u003e\u003c/summary\u003e\n\u003e\n\u003e  ```json\n\u003e{\n\u003e   \"mcpServers\": {\n\u003e      \"perforce-p4-mcp\": {\n\u003e         \"command\": \"/absolute/path/to/p4-mcp-server\",\n\u003e         \"env\": {\n\u003e         },\n\u003e         \"args\": [\n\u003e            \"--readonly\", \"--allow-usage\"\n\u003e         ]\n\u003e      }\n\u003e    }\n\u003e}\n\u003e```\n\u003c/details\u003e\n\n\u003cbr\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eJetBrains IDEs (IntelliJ IDEA, Rider, PyCharm, etc.)\u003c/strong\u003e\u003c/summary\u003e\n \nSee the [JetBrains AI Assistant VCS Integration documentation](https://www.jetbrains.com/help/ai-assistant/ai-in-vcs-integration.html#configure-a-perforce-mcp-server) for detailed configuration steps.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eClaude Code\u003c/strong\u003e\u003c/summary\u003e\n\nSee the [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more information.\n\n```json\n{\n  \"mcpServers\": {\n    \"perforce-p4-mcp\": {\n      \"command\": \"/absolute/path/to/p4-mcp-server\",\n      \"env\": {\n        \"P4PORT\": \"ssl:perforce.example.com:1666\",\n        \"P4USER\": \"your_username\",\n        \"P4CLIENT\": \"your_workspace\"\n      },\n      \"args\": [\n        \"--readonly\", \"--allow-usage\"\n      ]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eCursor\u003c/strong\u003e\u003c/summary\u003e\n\nSee the [Cursor MCP documentation](https://docs.cursor.com/en/context/mcp) for more information.\n\n```json\n{\n  \"mcpServers\": {\n    \"perforce-p4-mcp\": {\n      \"command\": \"/absolute/path/to/p4-mcp-server\",\n      \"env\": {\n        \"P4PORT\": \"ssl:perforce.example.com:1666\",\n        \"P4USER\": \"your_username\",\n        \"P4CLIENT\": \"your_workspace\"\n      },\n      \"args\": [\n        \"--readonly\", \"--allow-usage\"\n      ]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eEclipse\u003c/strong\u003e\u003c/summary\u003e\n\nSee the [Eclipse MCP documentation](https://eclipse.dev/lmos/docs/arc/mcp) for more information.\n\n```json\n{\n  \"servers\": {\n    \"perforce-p4-mcp\": {\n      \"command\": \"/absolute/path/to/p4-mcp-server\",\n      \"env\": {\n        \"P4PORT\": \"ssl:perforce.example.com:1666\",\n        \"P4USER\": \"your_username\",\n        \"P4CLIENT\": \"your_workspace\"\n      },\n      \"args\": [\n        \"--readonly\", \"--allow-usage\"\n      ]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cstrong\u003eKiro\u003c/strong\u003e\u003c/summary\u003e\n\nSee the [Kiro MCP documentation](https://kiro.dev/docs/mcp/configuration/) for more information.\n\n```json\n{\n  \"mcpServers\": {\n    \"perforce-p4-mcp\": {\n      \"command\": \"/absolute/path/to/p4-mcp-server\",\n      \"env\": {\n        \"P4PORT\": \"ssl:perforce.example.com:1666\",\n        \"P4USER\": \"your_username\",\n        \"P4CLIENT\": \"your_workspace\"\n      },\n      \"args\": [\n        \"--readonly\", \"--allow-usage\"\n      ]\n    }\n  }\n}\n```\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eVS Code\u003c/strong\u003e\u003c/summary\u003e\n\nSee the [VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more information.\nAdd the following to your VS Code MCP settings:\n\n```json\n{\n  \"servers\": {\n    \"perforce-p4-mcp\": {\n      \"command\": \"/absolute/path/to/p4-mcp-server\",\n      \"env\": {\n        \"P4PORT\": \"ssl:perforce.example.com:1666\",\n        \"P4USER\": \"your_username\",\n        \"P4CLIENT\": \"your_workspace\"\n      },\n      \"args\": [\n        \"--readonly\", \"--allow-usage\"\n      ]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eWindsurf\u003c/strong\u003e\u003c/summary\u003e\n\nSee the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for more information.\n\n```json\n{\n  \"mcpServers\": {\n    \"perforce-p4-mcp\": {\n      \"command\": \"/absolute/path/to/p4-mcp-server\",\n      \"env\": {\n        \"P4PORT\": \"ssl:perforce.example.com:1666\",\n        \"P4USER\": \"your_username\",\n        \"P4CLIENT\": \"your_workspace\"\n      },\n      \"args\": [\n        \"--readonly\", \"--allow-usage\"\n      ]\n    }\n  }\n}\n```\n\u003c/details\u003e\n\n###  P4 environment variables\n- `P4PORT` - P4 Server address. Examples: `ssl:perforce.example.com:1666`, `localhost:1666`\n- `P4USER` - Your P4 username\n- `P4CLIENT` - Your current P4 workspace. Optional, but recommended\n\n### Supported arguments\n\n- `--readonly` - Control write operations.\n  - If present, uses read-only mode. Safe for exploration and testing.\n  - If missing, enables write operations. Requires proper permissions on your P4 Server.\n\n- `--allow-usage` - Allow usage statistics.\n  - If present, allows anonymous usage statistics collection.\n  - If missing, disables all usage statistics.\n\n- `--toolsets` - Specify which tool categories to enable.\n  - Available: `files`, `changelists`, `shelves`, `workspaces`, `jobs`, `reviews`\n  - Default: All toolsets enabled.\n\n### Required configurations\n- Use absolute paths for the `command` field in all configurations.\n- Ensure environment variables are properly set for each host.\n- Different hosts may have different argument parsing. Refer to the host's documentation.\n\n\n\n## P4 configuration\n\n### User configuration\n\n**Example setup**\n```bash\n# Windows (PowerShell)\n$env:P4PORT = \"ssl:perforce.example.com:1666\"\n$env:P4USER = \"your_username\"\n$env:P4CLIENT = \"your_workspace\"\n```\n\n```bash\n# macOS (Bash)\nexport P4PORT=\"ssl:perforce.example.com:1666\"\nexport P4USER=\"your_username\"\nexport P4CLIENT=\"your_workspace\"\n```\n\n\n### Admin configuration\nManage access through group-level and user-level server properties.\nThese follow a strict order of precedence:\n- User-level properties override group properties.\n- Group-level properties are evaluated in the order of their sequence number (set with `-s`).\n- If no property applies, MCP remains enabled unless explicitly disabled.\n\n#### Master switch (global disable)\nTo disable MCP for all users:\n\n```\np4 property -a -n mcp.enabled -v false\n```\n\n\nTo re-enable group/user-based control, delete the global property first:\n\n```\np4 property -d -n mcp.enabled\n```\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eGroup-based restrictions\u003c/b\u003e\u003c/summary\u003e\n\nTo prevent access for all members of a specific group:\n\n```\np4 property -a -n mcp.enabled -v false -g noaccessgroup\n```\n\nYou can set multiple group restrictions the same way.\n\nWhen a user belongs to multiple groups with conflicting settings, sequence order (-s) determines which settings apply.\n\nLower sequence numbers are evaluated first.\n\nExample:\n```\np4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup\np4 property -a -n mcp.enabled -v true  -s2 -g accessgroup\n```\nIn this example, `accessgroup` overrides `noaccessgroup` because it is evaluated later.\n\u003c/details\u003e\n\n\u003cdetails\u003e\u003csummary\u003e\u003cb\u003eUser-based restrictions\u003c/b\u003e\u003c/summary\u003e\n\nTo block a specific user regardless of group membership:\n\n```\np4 property -a -n mcp.enabled -v false -u noaccessuser\n```\n\n\nUser-level properties always override group-level settings.\n\nExample: Even if `noaccessuser` is in `accessgroup` (where MCP is enabled), the user property takes precedence and MCP is disabled.\n\u003c/details\u003e\n\n\u003cbr\u003e\u003cstrong\u003eImportant notes \u003c/strong\u003e\n\n- `mcp.enabled` acts as the main switch.\n\n- Avoid global properties (`-a` without `-u` or `-g`) unless you absolutely need to disable MCP for everyone.\n\n## Available tools\n\n### Query tools (read operations)\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003equery_server\u003c/code\u003e\u003c/strong\u003e - Get server information and current user details\u003c/summary\u003e\n\n- **Actions**: \n  - `server_info` - Get P4 version, uptime, and configuration\n  - `current_user` - Get current user information and permissions\n- **Use cases** - Server diagnostics, user verification, connection testing\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003equery_workspaces\u003c/code\u003e\u003c/strong\u003e - Workspace information and management\u003c/summary\u003e\n\n- **Actions**: \n  - `list` - List all workspaces (optionally filtered by user)\n  - `get` - Get a detailed workspace specification\n  - `type` - Check workspace type and configuration\n  - `status` - Check workspace sync status\n- **Parameters**: `workspace_name`, `user`, `max_results`\n- **Use cases**: Workspace discovery, configuration review, status checking\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003equery_changelists\u003c/code\u003e\u003c/strong\u003e - Access changelist information and history\u003c/summary\u003e\n\n- **Actions**:\n  - `get` - Get detailed changelist information (files, description, jobs)\n  - `list` - List changelists with filters (status, user, workspace)\n- **Parameters**: `changelist_id`, `status` (pending/submitted), `workspace_name`, `max_results`\n- **Use cases**: Code review, history tracking, changelist analysis\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003equery_files\u003c/code\u003e\u003c/strong\u003e - File operations and information\u003c/summary\u003e\n\n- **Actions**:\n  - `content` - Get file content at a specific revision\n  - `history` - Get file revision history and integration records\n  - `info` - Get file basic details (type, size, permissions)\n  - `metadata` - Get file metadata (attributes, filesize,  etc.)\n  - `diff` - Compare file versions (depot-to-depot or mixed)\n  - `annotations` - Get file annotations with blame information\n- **Parameters**: `file_path`, `file2` (for diff), `max_results`, `diff2` (boolean)\n- **Use cases**: Code analysis, file comparison, history tracking, blame analysis\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003equery_shelves\u003c/code\u003e\u003c/strong\u003e - Shelved changelist operations and inspection\u003c/summary\u003e\n\n- **Actions**:\n  - `list` - List shelved changes by user or globally\n  - `diff` - Show differences in shelved files\n  - `files` - List files in a specific shelf\n- **Parameters**: `changelist_id`, `user`, `max_results`\n- **Use cases**: Code review, work-in-progress tracking, collaboration\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003equery_jobs\u003c/code\u003e\u003c/strong\u003e - Job tracking and defect management\u003c/summary\u003e\n\n- **Actions**:\n  - `list_jobs` - List jobs associated with a changelist\n  - `get_job` - Get detailed job information and status\n- **Parameters**: `changelist_id`, `job_id`, `max_results`\n- **Use cases**: Defect tracking, requirement traceability, project management\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003equery_reviews\u003c/code\u003e\u003c/strong\u003e - Review discovery, details, and activity\u003c/summary\u003e\n\n- **Actions**: \n  - `list` - List all reviews with optional filtering\n  - `dashboard` - Get current user's review dashboard (my reviews, needs attention)\n  - `get` - Get detailed review information\n  - `transitions` - Get available state transitions for a review\n  - `files_readby` - Get files read status by users\n  - `files` - Get files in a review (with optional version range)\n  - `activity` - Get review activity history\n  - `comments` - Get comments on a review\n- **Parameters**: \n  - `review_id` - Review ID (required for get, transitions, files_readby, files, comments, activity)\n  - `review_fields` - Comma-separated fields to return (e.g., \"id,description,author,state\")\n  - `comments_fields` - Fields for comments (default: \"id,body,user,time\")\n  - `up_voters` - List of up voters for transitions\n  - `from_version`, `to_version` - Version range for files action\n  - `max_results` - Maximum results (default: 10)\n- **Use cases**: Code review discovery, review status tracking, comment retrieval, review activity monitoring\n\n\u003c/details\u003e\n\n### Modify tools (write operations)\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003emodify_workspaces\u003c/code\u003e\u003c/strong\u003e - Workspace creation and management\u003c/summary\u003e\n\n- **Actions** - `create`, `update`, `delete`, `switch`\n- **Parameters** - `name`, `specs` (WorkspaceSpec object with View, Root, Options, etc.)\n- **Requires** - Non-read only mode, appropriate permissions\n- **Use cases** - Environment setup, workspace maintenance, branch switching\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003emodify_changelists\u003c/code\u003e\u003c/strong\u003e - Changelist lifecycle management\u003c/summary\u003e\n\n- **Actions** - `create`, `update`, `submit`, `delete`, `move_files`\n- **Parameters** - `changelist_id`, `description`, `file_paths`\n- **Safety** - Ownership checks, confirmation for destructive operations\n- **Use cases** - Code submission, work organization, file grouping\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003emodify_files\u003c/code\u003e\u003c/strong\u003e - File system operations and version control\u003c/summary\u003e\n\n- **Actions** - `add`, `edit`, `delete`, `move`, `revert`, `reconcile`, `resolve`, `sync`\n- **Parameters** - `file_paths`, `changelist`, `force`, `mode` (for resolve operations)\n- **Resolve modes** - `auto`, `safe`, `force`, `preview`, `theirs`, `yours`\n- **Use cases** - File editing, conflict resolution, workspace synchronization\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003emodify_shelves\u003c/code\u003e\u003c/strong\u003e - Shelving operations for work in progress\u003c/summary\u003e\n\n- **Actions** - `shelve`, `unshelve`, `update`, `delete`, `unshelve_to_changelist`\n- **Parameters** - `changelist_id`, `file_paths`, `target_changelist`, `force`\n- **Use cases** - Temporary storage, code sharing, backup before experiments\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003emodify_jobs\u003c/code\u003e\u003c/strong\u003e - Job and changelist integration\u003c/summary\u003e\n\n- **Actions** - `link_job`, `unlink_job`\n- **Parameters** - `changelist_id`, `job_id`\n- **Use cases** - Defect tracking integration, requirement linking\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003emodify_reviews\u003c/code\u003e\u003c/strong\u003e - Review creation, transitions, participants, and comments\u003c/summary\u003e\n\n- **Actions**: \n  - `create` - Create a new review from a changelist\n  - `refresh_projects` - Refresh project associations\n  - `vote` - Vote on a review (up, down, clear)\n  - `transition` - Change review state (needsRevision, needsReview, approved, committed, rejected, archived)\n  - `append_participants` - Add reviewers/groups to a review\n  - `replace_participants` - Replace all participants\n  - `delete_participants` - Remove participants from a review\n  - `add_comment` - Add a comment to a review\n  - `reply_comment` - Reply to an existing comment\n  - `append_change` - Add a changelist to an existing review\n  - `replace_with_change` - Replace review content with a changelist\n  - `join` - Join a review as a participant\n  - `leave` - Leave a review\n  - `archive_inactive` - Archive inactive reviews\n  - `mark_comment_read` / `mark_comment_unread` - Mark individual comment read status\n  - `mark_all_comments_read` / `mark_all_comments_unread` - Mark all comments read status\n  - `update_author` - Change the review author\n  - `update_description` - Update review description\n  - `obliterate` - Permanently delete a review\n- **Parameters**: \n  - `review_id` - Review ID (required for most actions)\n  - `change_id` - Changelist ID (required for create, append_change, replace_with_change)\n  - `description` - Review description\n  - `reviewers`, `required_reviewers` - Lists of reviewer usernames\n  - `reviewer_groups` - Reviewer groups with requirements\n  - `vote_value` - Vote value: `up`, `down`, `clear`\n  - `version` - Review version for voting\n  - `transition` - Target state: `needsRevision`, `needsReview`, `approved`, `committed`, `approved:commit`, `rejected`, `archived`\n  - `jobs`, `fix_status`, `cleanup` - Job linking and cleanup options for transitions\n  - `users`, `groups` - Structured participant data for append/replace/delete\n  - `body` - Comment body text\n  - `task_state` - Comment task state: `open`, `comment`\n  - `notify` - Notification mode: `immediate`, `delayed`\n  - `comment_id` - Comment ID for replies or marking read/unread\n  - `context` - Comment context (file, line numbers, content, version)\n  - `not_updated_since`, `max_reviews` - Filters for archive_inactive\n  - `new_author`, `new_description` - Values for update actions\n- **Use cases**: Code review workflow, review state management, collaborative commenting, participant management, review cleanup\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003e\u003ccode\u003eexecute_delete\u003c/code\u003e\u003c/strong\u003e - Execute approved delete operations\u003c/summary\u003e\n\n- **Parameters** - `operation_id`, `source_tool`, `user_confirmed`\n- **Safety** - Requires explicit user confirmation, logs all operations\n- **Supported Resources** - Changelists, workspaces, shelves\n- **Use cases** - Cleanup operations, resource management\n\n\u003c/details\u003e\n\u003cbr\u003e\n\n## Logging and usage data\n\n### Logging system\n\n**Log locations:**\n- **Application log**: `logs/p4mcp.log` - Main server operations and errors\n- **Session logs**: `logs/sessions/*.log` - Individual session activities are recorded only when the `--allow-usage` is specified in the server's startup arguments.\n\n\n### Usage data\n\n**Privacy-first approach:**\n- **Disabled by default**: No data collection without explicit consent\n- **Consent-gated**: First-run prompt for telemetry permission\n- **Transparent**: Clear explanation of data collected\n- **Revocable**: Easy opt-out at any time\n\n**Data collected (if consented):**\n- Tool usage frequency (anonymized)\n- Error rates and types (no personal data)\n- Performance metrics\n- Feature adoption statistics\n- P4 server version\n\n**Data not collected:**\n- File contents or names\n- P4 Server details except version\n- User credentials or personal information\n- Specific project information\n\n**Control:**\n- Usage data is only collected if the `--allow-usage` argument is provided at startup.\n\n## Troubleshooting\n\n### Server startup issues\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eUnable to start server\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: OS cannot find or execute the binary; error includes `ENOENT` or \"No such file or directory\".\n\u003cbr\u003e**Solutions**:\n1. **Check the path:** Make sure the `command` field uses the correct absolute path for your OS:  \n   - macOS/Linux: `/absolute/path/to/p4-mcp-server`  \n   - Windows: `C:\\absolute\\path\\to\\p4-mcp-server.exe`\n2. **Ensure the binary exists and is executable:**  \n   - macOS/Linux:  \n     ```bash\n     ls -l /absolute/path/to/p4-mcp-server \u0026\u0026 chmod +x /absolute/path/to/p4-mcp-server\n     ```\n   - Windows:  \n     ```powershell\n     dir C:\\absolute\\path\\to\\p4-mcp-server.exe\n     ```\n3. **On Windows, ensure the binary is not blocked:**  \n   - Right-click the `.exe` file, select **Properties**, and if present, click **Unblock**.\n\n\u003c/details\u003e\n\n### Connection issues\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eConnect to server failed; check $P4PORT\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Cannot connect to P4 Server  \n**Solutions**:\n1. Verify the `P4PORT` environment variable: `echo $P4PORT` (macOS) or `echo $env:P4PORT` (Windows)\n2. Test the direct connection: `p4 info`\n3. Check server availability: `ping perforce.example.com`\n4. Verify the port and protocol (`ssl:` prefix for SSL connections).\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eSSL certificate not trusted\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: SSL trust errors when connecting  \n**Solutions**:\n1. Trust the server: `p4 trust -f -y`\n2. Check trust status: `p4 trust -l`\n3. For persistent issues, verify the SSL configuration.\n\n\u003c/details\u003e\n\n### Authentication problems\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eUser not logged in\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Authentication failures  \n**Solutions**:\n1. Log in to P4: `p4 login -a`\n2. Check login status: `p4 login -s`\n3. Verify the user exists: `p4 users -m 1 your_username`\n4. For persistent issues, check password or use ticket-based authentication.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003ePassword invalid\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Login failures  \n**Solutions**:\n1. Reset the password through P4 administrator.\n2. Use ticket-based authentication: `p4 login -a`\n3. Verify the username is correct: `p4 info`\n\n\u003c/details\u003e\n\n### Workspace issues\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eClient unknown\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Workspace not found errors  \n**Solutions**:\n1. List the available workspaces: `p4 clients`\n2. Verify the `P4CLIENT` environment variable.\n3. Create a workspace if needed: `p4 client workspace_name`\n4. Check the workspace ownership: `p4 client -o workspace_name`\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eFile(s) not in client view\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Files are outside the workspace mapping  \n**Solutions**:\n1. Check the client view: `p4 client -o workspace_name`\n2. Update the workspace mapping to include the required paths.\n3. Use `p4 where file_path` to check the mapping.\n\n\u003c/details\u003e\n\n### Permission errors\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eOperation not permitted\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Insufficient permissions for operations  \n**Solutions**:\n1. Check the file ownership: `p4 opened file_path`\n2. Verify the user permissions: `p4 protects file_path`\n3. Ensure proper group membership.\n4. For admin operations, verify admin permissions.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eFile is opened by another user\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Exclusive lock conflicts  \n**Solutions**:\n1. Check who has the file open: `p4 opened file_path`\n2. Contact the user to resolve conflicts.\n3. Admin can force operations if necessary.\n\n\u003c/details\u003e\n\n### Performance issues\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eSlow operations\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Long response times  \n**Solutions**:\n1. Use the `max_results` parameter to limit the query size.\n2. Use specific file paths instead of wildcards.\n3. Check network connectivity to P4.\n4. Monitor server performance.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eMemory issues\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: High memory usage  \n**Solutions**:\n1. Reduce `max_results` for large queries.\n2. Process files in batches.\n3. Restart the MCP server periodically for long-running sessions.\n\n\u003c/details\u003e\n\n### Tool execution\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eUnable to execute tools\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Conflict with built-in or other MCP tools\n\u003cbr\u003e**Solutions**:\n1. Disable any built-in or conflicting MCP server tools in your environment or configuration.\n2. Ensure the P4 MCP server tools are properly registered and enabled.\n3. Restart the MCP server after applying configuration changes to load the correct tools.\n\n\u003c/details\u003e\n\n\u003cdetails\u003e\n  \u003csummary\u003e\u003cstrong\u003eCorrect tools not picked up\u003c/strong\u003e\u003c/summary\u003e\n\n**Symptoms**: Invalid context or outdated session history\n\u003cbr\u003e**Solutions**:\n1. Provide a P4-related context when writing prompts.\n2. Start a new session if the existing session is old or contains conflicting prompt history.\n\n\u003c/details\u003e\n\n\n### Common error patterns\n\n1. **Authentication**: Ensure valid login before MCP operations.\n2. **Workspace mapping**: Verify client views include target files.\n3. **Permissions**: Check user and file permissions for write operations.\n4. **Network**: Verify connectivity for remote P4 Servers.\n\n### Getting help\n\n1. **Check the logs**: Always check `logs/p4mcp.log` first.\n2. **Test P4**: Ensure `p4 info` works before troubleshooting MCP.\n3. **Report issues to the community**: Report issues with log excerpts and environment details.\n\n## Support\n\nPerforce P4 MCP Server is a community supported project and is not officially supported by Perforce.\nPull requests and issues are the responsibility of the project's moderator(s); this may be a vetted individual or team with members outside of the Perforce organization.\nPerforce does not officially support these projects, therefore all issues should be reported and managed via GitHub (not via Perforce's standard support process).\n\n## Contributions\n\nWe welcome contributions to the P4 MCP Server project.\n\n\n## License\nThis project is licensed under the MIT License. See [LICENSE](LICENSE.txt) for details.\n\n### Third-Party Notices\nThis project includes third-party components. Their licenses and attributions are listed in [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES.txt).","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperforce%2Fp4mcp-server","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fperforce%2Fp4mcp-server","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fperforce%2Fp4mcp-server/lists"}