Skip to content
Back to search

p4mcp-server

[Community Supported] Perforce P4 MCP Server is a Model Context Protocol (MCP) server that integrates with the Perforce P4 version control system.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/perforce--p4mcp-server/badge.svg)](/listings/perforce--p4mcp-server)

HTML

<a href="/listings/perforce--p4mcp-server"><img src="/api/listings/perforce--p4mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 1,689 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

This file has changed since it was scanned, so this is not exactly the text that was scanned, and no line is marked. The findings are listed with the safety scan above.

  1. <p align="center">
  2. <img src="./icons/logo-p4mcp-reg.svg" alt="Perforce P4 MCP Server" width="480" />
  3. </p><br>
  4. <div align="center">
  5. ![Support](https://img.shields.io/badge/Support-Community-yellow.svg)
  6. ![GitHub release](https://img.shields.io/github/v/release/perforce/p4mcp-server?color=blue)
  7. <h1>Perforce P4 MCP Server</h1>
  8. <p>
  9. <strong>Perforce 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. It also integrates with P4 DAM through its REST API to manage <a href="#features">resources</a>.</strong>
  10. </p>
  11. <nav aria-label="Quick navigation">
  12. <p align="center">
  13. <a href="#features">Features</a> ·
  14. <a href="#prerequisites">Prerequisites</a> ·
  15. <a href="#system-requirements">System Requirements</a> ·
  16. <a href="#local-p4-mcp-server-installation">Install</a> ·
  17. <a href="#deployment">Deployment</a> ·
  18. <a href="#mcp-client-configuration">Client Configurations</a> ·
  19. <a href="#p4-configuration">P4 Configurations</a> ·
  20. <a href="#available-tools">Tools</a>
  21. </p>
  22. <p align="center">
  23. <a href="#logging-and-usage-data">Logging</a> ·
  24. <a href="#troubleshooting">Troubleshoot</a> ·
  25. <a href="#support">Support</a> ·
  26. <a href="#contributions">Contributions</a> ·
  27. <a href="#license">License</a>
  28. </p>
  29. </nav>
  30. </div>
  31. ## Features
  32. - **Comprehensive P4 integration**: Read/write tools across files, changelists, shelves, workspaces, jobs, reviews, streams, and server information.
  33. - **Code review workflows**: P4 Code Review support for review discovery, voting, state transitions, commenting, and participant management.
  34. - **P4 DAM integration**: Access P4 DAM assets and metadata through MCP-compatible AI assistants. Search for assets, retrieve metadata, manage reviews, create asset bundles, update asset tags, and browse projects. To learn more, see [Configure P4 DAM access for P4 MCP Server](https://help.perforce.com/helix-core/helix-dam/current/Content/HTH-Admin/DAM/configure-p4dam-to-p4-mcp.html) in the P4 DAM documentation.
  35. - **Safety first**: Read-only mode by default, ownership checks, interactive MCP elicitation (PROCEED/CANCEL) for destructive delete and obliterate operations.
  36. - **Flexible toolsets**: Configure which tool categories to enable: server, files, changelists, shelves, workspaces, jobs, reviews, streams, and p4dam.
  37. - **Robust logging**: Application and session logging to the `logs/` directory.
  38. - **Optional telemetry**: Consent-gated usage statistics. Disabled by default.
  39. - **Cross platform**: Supported on macOS, Linux and Windows with pre-built binaries.
  40. ## Prerequisites
  41. - **P4 Server access**: Connection to a P4 Server with proper credentials
  42. - **Authentication**: Valid P4 login (ticket-based or password)
  43. ## System Requirements
  44. | Component | Supported Versions |
  45. |-----------|-------------------|
  46. | **Operating Systems** | Windows 10+<br>macOS 12+<br>Linux (glibc 2.34+, e.g. Ubuntu 22.04+, Rocky Linux 9+) |
  47. | **Perforce P4 Server** | 2026.1 *(earlier versions untested)* |
  48. | **Python** | 3.11+ *(required only for building from source)* |
  49. ## Local P4 MCP Server Installation
  50. <details><summary><b>uvx (easiest, no install required)</b></summary>
  51. If you have [uv](https://docs.astral.sh/uv/) installed, you can run P4 MCP Server directly without any manual installation:
  52. ```bash
  53. # Run the server
  54. uvx p4mcp-server
  55. # Check version
  56. uvx p4mcp-server --version
  57. # Run with arguments
  58. uvx p4mcp-server --readonly --allow-usage
  59. ```
  60. This automatically fetches and runs the latest version from PyPI. No Python virtual environment setup or dependency management needed.
  61. **Requirements:**
  62. - [uv](https://docs.astral.sh/uv/) installed on your system
  63. - Python 3.11+ (uv will handle this automatically)
  64. </details>
  65. <details><summary><b>Pre-built binaries (recommended for offline/air-gapped)</b></summary>
  66. Download the appropriate binary for your operating system:
  67. - **macOS**: [p4-mcp-server-mac.zip](https://github.com/perforce/p4mcp-server/releases/latest/download/p4-mcp-server-mac.zip)
  68. - **Windows**: [p4-mcp-server-win.zip](https://github.com/perforce/p4mcp-server/releases/latest/download/p4-mcp-server-win.zip)
  69. - **Linux**: [p4-mcp-server-linux.zip](https://github.com/perforce/p4mcp-server/releases/latest/download/p4-mcp-server-linux.zip)
  70. Extract and use the executable directly. No Python installation is required.
  71. ```bash
  72. # macOS / Linux
  73. unzip p4-mcp-server-mac.zip # or p4-mcp-server-linux.zip
  74. ./p4-mcp-server --help
  75. ```
  76. ```powershell
  77. # Windows
  78. Expand-Archive p4-mcp-server-win.zip -DestinationPath .
  79. .\p4-mcp-server.exe --help
  80. ```
  81. </details>
  82. <details><summary><b>Build from source</b></summary>
  83. Requirements:
  84. - Python 3.11+ (with Tkinter)
  85. Build:
  86. - macOS: <code>chmod +x build.sh &amp;&amp; ./build.sh package</code>
  87. - Linux: <code>chmod +x build.sh &amp;&amp; ./build.sh package</code>
  88. - Windows: <code>build.bat package</code>
  89. Output:
  90. - macOS & Linux: <code>p4-mcp-server-&lt;version&gt;.tgz</code>
  91. - Windows: <code>p4-mcp-server-&lt;version&gt;.zip</code>
  92. </details>
  93. ## Deployment
  94. ### STDIO-based deployment
  95. <details><summary><b>Local</b></summary>
  96. Run the P4 MCP Server directly on your machine using the default STDIO transport.
  97. Add the following to your `mcp.json`:
  98. ```json
  99. {
  100. "mcpServers": {
  101. "perforce-p4-mcp": {
  102. "command": "/absolute/path/to/p4-mcp-server",
  103. "env": {
  104. "P4PORT": "ssl:perforce.example.com:1666",
  105. "P4USER": "your_username",
  106. "P4CLIENT": "your_workspace",
  107. "P4DAM_API_KEY": "your_api_key"
  108. },
  109. "args": [
  110. "--readonly", "--allow-usage"
  111. ]
  112. }
  113. }
  114. }
  115. ```
  116. > **Note:** This example shows explicit `env` values. If `P4CONFIG` is set, you can omit them and use the generic configuration example in the `MCP client configuration` section instead.
  117. </details>
  118. <details><summary><b>Docker</b></summary>
  119. Run the P4 MCP Server from a Docker container with STDIO transport, allowing MCP clients to manage the container lifecycle.
  120. > **Note:** Docker-based execution is currently supported on macOS and Linux only.
  121. **Prerequisites**
  122. - Docker installed and running
  123. - Valid P4 credentials and access to a P4 server
  124. **Pull the Docker image**
  125. ```bash
  126. docker pull ghcr.io/perforce/p4mcp-server:latest
  127. ```
  128. <details><summary><b>Build from source instead</b></summary>
  129. ```bash
  130. cd /path/to/p4mcp-server
  131. docker build -t ghcr.io/perforce/p4mcp-server .
  132. ```
  133. </details>
  134. **Configure MCP Client**
  135. Add the following to your `mcp.json`:
  136. ```json
  137. {
  138. "servers": {
  139. "perforce-p4mcp-docker": {
  140. "command": "docker",
  141. "args": [
  142. "run", "-i", "--rm",
  143. "--hostname", "your-hostname",
  144. "-e", "P4PORT=ssl:perforce.example.com:1666",
  145. "-e", "P4USER=your_username",
  146. "-e", "P4CLIENT=your_workspace",
  147. "-e", "P4DAM_API_KEY=your_api_key",
  148. "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro",
  149. "ghcr.io/perforce/p4mcp-server:latest"
  150. ]
  151. }
  152. }
  153. }
  154. ```
  155. **Configuration Options**
  156. | Flag | Description |
  157. |------|-------------|
  158. | `-i` | Interactive mode (required for STDIO) |
  159. | `--rm` | Remove container when stopped |
  160. | `--hostname` | Match workspace host restriction |
  161. | `-e P4PORT` | P4 server address |
  162. | `-e P4USER` | P4 username |
  163. | `-e P4CLIENT` | Workspace name |
  164. | `-v` | Mount P4 tickets file |
  165. **Authentication**
  166. Using P4 tickets:
  167. ```bash
  168. # macOS/Linux
  169. -v /Users/your_username/.p4tickets:/home/mcpuser/.p4tickets:ro
  170. ```
  171. > **Note:** Use the full path to your tickets file (not `~`). After running `p4 login`, restart the MCP server to pick up the new ticket.
  172. > **Note:** By default the container starts as root, copies the bind-mounted tickets file to a location readable by the non-root `mcpuser`, then drops privileges (via `gosu`) so the server runs as `mcpuser`. This auto-copy lets an owner-only (`0600`) tickets file owned by a foreign uid work on runtimes that preserve host ownership (native Linux Docker/podman). A `:ro` bind mount of the ticket is supported — the file is copied, not modified in place (this is distinct from a read-only container root filesystem; see below). Note the auto-copy runs **only when the container starts as root** (the default); forcing a non-root uid or a read-only root filesystem changes this behavior, as described below.
  173. > **Kubernetes / restricted (non-root-enforced) profiles:** the image intentionally starts as root and drops to `mcpuser` (uid 1000) via `gosu`, so the server always runs non-root — both paths are supported. For `runAsNonRoot` / restricted PodSecurity / OpenShift restricted SCC, set `securityContext.runAsUser: 1000` (and `fsGroup: 1000` when mounting the ticket). In that mode the entrypoint's root-only ticket copy is skipped, so the mounted ticket must already be readable by uid 1000 (owner-matched mount, `-e P4PASSWD="your_ticket_content"`, or `podman -v <host>:/home/mcpuser/.p4tickets:U`).
  174. > **Read-only root filesystem (`--read-only` / `readOnlyRootFilesystem`):** provide a writable/tmpfs `/home/mcpuser` (e.g. `--tmpfs /home/mcpuser`) so the ticket copy can be written; otherwise the ticket copy fails and P4 will report a normal auth error.
  175. Using a password:
  176. ```bash
  177. -e P4PASSWD="your_password"
  178. ```
  179. **Workspace Host Restrictions**
  180. > ⚠️ **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.
  181. To resolve this, set the container hostname to match your workspace's host restriction:
  182. ```bash
  183. --hostname your-hostname
  184. ```
  185. To find your workspace host name:
  186. ```bash
  187. # macOS/Linux
  188. p4 client -o your_workspace | grep "^Host:"
  189. ```
  190. **Mounting Client Root for Write Operations**
  191. > ⚠️ **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**.
  192. Add a volume mount for your client root:
  193. ```bash
  194. -v /path/to/your/client/root:/path/to/your/client/root
  195. ```
  196. Example configuration with client root mounted:
  197. ```json
  198. {
  199. "servers": {
  200. "perforce-p4mcp-docker": {
  201. "command": "docker",
  202. "args": [
  203. "run", "-i", "--rm",
  204. "--hostname", "your-hostname",
  205. "-e", "P4PORT=ssl:perforce.example.com:1666",
  206. "-e", "P4USER=your_username",
  207. "-e", "P4CLIENT=your_workspace",
  208. "-e", "P4DAM_API_KEY=your_api_key",
  209. "-v", "/Users/your_username/.p4tickets:/home/mcpuser/.p4tickets",
  210. "-v", "/path/to/client/root:/path/to/client/root",
  211. "ghcr.io/perforce/p4mcp-server:latest"
  212. ]
  213. }
  214. }
  215. }
  216. ```
  217. To find your client root:
  218. ```bash
  219. p4 client -o your_workspace | grep "^Root:"
  220. ```
  221. > **Note:** The mount path inside the container must match the client root path exactly, as P4 tracks files by their absolute paths.
  222. </details>
  223. ### HTTP-based deployment
  224. > **Security:** HTTP binds to `127.0.0.1` (local only) by default. Use `--host 0.0.0.0` for remote clients. HTTP has no authentication, so expose it only on trusted networks.
  225. <details><summary><b>VM</b></summary>
  226. Run the MCP server on a VM using the HTTP transport, allowing clients to connect over the network.
  227. **Start the server on the VM:**
  228. ```bash
  229. P4PORT=ssl:perforce.example.com:1666 P4USER=your_username P4PASSWD=YOUR_TICKET ./p4-mcp-server --readonly --transport http --host 0.0.0.0 --port 8000
  230. ```
  231. **Configure the MCP client:**
  232. Add the following to your `mcp.json`:
  233. ```json
  234. {
  235. "servers": {
  236. "perforce-p4-mcp": {
  237. "type": "http",
  238. "url": "http://<ip-or-hostname>:8000/mcp"
  239. }
  240. }
  241. }
  242. ```
  243. > **Note:** Ensure the VM's firewall allows inbound connections on the chosen port. For production use, consider placing the server behind a reverse proxy with TLS.
  244. </details>
  245. <details><summary><b>Docker</b></summary>
  246. Run the MCP server in a Docker container using HTTP transport and expose the MCP endpoint over a host port.
  247. **Start the container:**
  248. ```bash
  249. docker run --rm -p 8000:8000 \
  250. -e P4PORT=ssl:perforce.example.com:1666 \
  251. -e P4USER=your_username \
  252. -e P4PASSWD=YOUR_TICKET \
  253. -e P4DAM_API_KEY=your_api_key \
  254. ghcr.io/perforce/p4mcp-server:latest \
  255. python3 -m p4mcp.main --readonly --transport http --host 0.0.0.0 --port 8000
  256. ```
  257. > **Note:** In a container, `--host 0.0.0.0` is required. To allow only the Docker host, use `-p 127.0.0.1:8000:8000`.
  258. **Configure the MCP client:**
  259. Add the following to your `mcp.json`:
  260. ```json
  261. {
  262. "servers": {
  263. "perforce-p4-mcp": {
  264. "type": "http",
  265. "url": "http://<ip-or-hostname>:8000/mcp"
  266. }
  267. }
  268. }
  269. ```
  270. > **Note:** Docker supports HTTP-based deployment as well. The container image defaults to STDIO transport, so the HTTP startup command must explicitly override the default command. If you need write operations, also mount the client root and ticket file paths into the container.
  271. </details>
  272. ## MCP client configuration
  273. > **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.
  274. > **Tip:** If you have [uv](https://docs.astral.sh/uv/) installed, you can use `uvx p4mcp-server` instead of `/absolute/path/to/p4-mcp-server` in the `command` field. This eliminates the need to download or build binaries manually.
  275. > <details> <summary><strong>Server configuration example using uvx</strong></summary>
  276. >
  277. > ```json
  278. >{
  279. > "mcpServers": {
  280. > "perforce-p4-mcp": {
  281. > "command": "uvx",
  282. > "args": [
  283. > "p4mcp-server",
  284. > "--readonly", "--allow-usage"
  285. > ],
  286. > "env": {
  287. > "P4PORT": "ssl:perforce.example.com:1666",
  288. > "P4USER": "your_username",
  289. > "P4CLIENT": "your_workspace",
  290. > "P4DAM_API_KEY": "your_api_key"
  291. > }
  292. > }
  293. > }
  294. >}
  295. >```
  296. ></details>
  297. >
  298. > <details> <summary><strong>Server configuration example using binary path</strong></summary>
  299. >
  300. > ```json
  301. >{
  302. > "mcpServers": {
  303. > "perforce-p4-mcp": {
  304. > "command": "/absolute/path/to/p4-mcp-server",
  305. > "env": {
  306. > },
  307. > "args": [
  308. > "--readonly", "--allow-usage"
  309. > ]
  310. > }
  311. > }
  312. >}
  313. >```
  314. </details>
  315. <br>
  316. <details>
  317. <summary><strong>JetBrains IDEs (IntelliJ IDEA, Rider, PyCharm, etc.)</strong></summary>
  318. See 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.
  319. </details>
  320. <details>
  321. <summary><strong>Claude Code</strong></summary>
  322. See the [Claude Code MCP docs](https://docs.anthropic.com/en/docs/claude-code/mcp) for more information.
  323. **Using uvx (no installation required):**
  324. ```json
  325. {
  326. "mcpServers": {
  327. "perforce-p4-mcp": {
  328. "command": "uvx",
  329. "args": [
  330. "p4mcp-server",
  331. "--readonly", "--allow-usage"
  332. ],
  333. "env": {
  334. "P4PORT": "ssl:perforce.example.com:1666",
  335. "P4USER": "your_username",
  336. "P4CLIENT": "your_workspace",
  337. "P4DAM_API_KEY": "your_api_key"
  338. }
  339. }
  340. }
  341. }
  342. ```
  343. **Using pre-built binary:**
  344. ```json
  345. {
  346. "mcpServers": {
  347. "perforce-p4-mcp": {
  348. "command": "/absolute/path/to/p4-mcp-server",
  349. "env": {
  350. "P4PORT": "ssl:perforce.example.com:1666",
  351. "P4USER": "your_username",
  352. "P4CLIENT": "your_workspace",
  353. "P4DAM_API_KEY": "your_api_key"
  354. },
  355. "args": [
  356. "--readonly", "--allow-usage"
  357. ]
  358. }
  359. }
  360. }
  361. ```
  362. </details>
  363. <details>
  364. <summary><strong>Cursor</strong></summary>
  365. See the [Cursor MCP documentation](https://docs.cursor.com/en/context/mcp) for more information.
  366. ```json
  367. {
  368. "mcpServers": {
  369. "perforce-p4-mcp": {
  370. "command": "/absolute/path/to/p4-mcp-server",
  371. "env": {
  372. "P4PORT": "ssl:perforce.example.com:1666",
  373. "P4USER": "your_username",
  374. "P4CLIENT": "your_workspace",
  375. "P4DAM_API_KEY": "your_api_key"
  376. },
  377. "args": [
  378. "--readonly", "--allow-usage"
  379. ]
  380. }
  381. }
  382. }
  383. ```
  384. </details>
  385. <details>
  386. <summary><strong>Eclipse</strong></summary>
  387. See the [Eclipse MCP documentation](https://eclipse.dev/lmos/docs/arc/mcp) for more information.
  388. ```json
  389. {
  390. "servers": {
  391. "perforce-p4-mcp": {
  392. "command": "/absolute/path/to/p4-mcp-server",
  393. "env": {
  394. "P4PORT": "ssl:perforce.example.com:1666",
  395. "P4USER": "your_username",
  396. "P4CLIENT": "your_workspace",
  397. "P4DAM_API_KEY": "your_api_key"
  398. },
  399. "args": [
  400. "--readonly", "--allow-usage"
  401. ]
  402. }
  403. }
  404. }
  405. ```
  406. </details>
  407. <details><summary><strong>Kiro</strong></summary>
  408. See the [Kiro MCP documentation](https://kiro.dev/docs/mcp/configuration/) for more information.
  409. ```json
  410. {
  411. "mcpServers": {
  412. "perforce-p4-mcp": {
  413. "command": "/absolute/path/to/p4-mcp-server",
  414. "env": {
  415. "P4PORT": "ssl:perforce.example.com:1666",
  416. "P4USER": "your_username",
  417. "P4CLIENT": "your_workspace",
  418. "P4DAM_API_KEY": "your_api_key"
  419. },
  420. "args": [
  421. "--readonly", "--allow-usage"
  422. ]
  423. }
  424. }
  425. }
  426. ```
  427. </details>
  428. <details>
  429. <summary><strong>VS Code</strong></summary>
  430. See the [VS Code documentation](https://code.visualstudio.com/docs/copilot/customization/mcp-servers) for more information.
  431. ```json
  432. {
  433. "servers": {
  434. "perforce-p4-mcp": {
  435. "command": "/absolute/path/to/p4-mcp-server",
  436. "env": {
  437. "P4PORT": "ssl:perforce.example.com:1666",
  438. "P4USER": "your_username",
  439. "P4CLIENT": "your_workspace",
  440. "P4DAM_API_KEY": "your_api_key"
  441. },
  442. "args": [
  443. "--readonly", "--allow-usage"
  444. ]
  445. }
  446. }
  447. }
  448. ```
  449. </details>
  450. <details>
  451. <summary><strong>Windsurf</strong></summary>
  452. See the [Windsurf MCP documentation](https://docs.windsurf.com/windsurf/cascade/mcp) for more information.
  453. ```json
  454. {
  455. "mcpServers": {
  456. "perforce-p4-mcp": {
  457. "command": "/absolute/path/to/p4-mcp-server",
  458. "env": {
  459. "P4PORT": "ssl:perforce.example.com:1666",
  460. "P4USER": "your_username",
  461. "P4CLIENT": "your_workspace",
  462. "P4DAM_API_KEY": "your_api_key"
  463. },
  464. "args": [
  465. "--readonly", "--allow-usage"
  466. ]
  467. }
  468. }
  469. }
  470. ```
  471. </details>
  472. ### P4 Environment Variables
  473. - `P4PORT` - P4 Server address. Examples: `ssl:perforce.example.com:1666`, `localhost:1666`
  474. - `P4USER` - Your P4 username
  475. - `P4CLIENT` - Your current P4 workspace. Optional, but recommended
  476. ### Result limit environment variables
  477. - `P4MCP_MAX_RESULTS` - Cap on the number of rows the P4 server returns per command (`p4.maxresults`). Default: `10000`. Set to `0` to disable the limit (server default in effect). When a command would exceed this limit the server aborts it with an error rather than truncating results, so keep the value generous. Can be overridden by the `--max-results` CLI argument. Must be a non-negative integer; an invalid value fails fast at startup before any P4 connection is attempted.
  478. - `P4MCP_MAX_SCAN_ROWS` - Cap on the number of rows the P4 server scans per command (`p4.maxscanrows`). Unset by default, so admin/group policy governs scan limits. Can be overridden by the `--max-scan-rows` CLI argument. Must be a non-negative integer when supplied.
  479. ### Logging environment variables
  480. - `P4MCP_LOG_DIR` - Directory for log files. Default: `logs/` in the server executable's directory. Can be overridden by the `--log-dir` CLI argument.
  481. ### SSL/TLS environment variables
  482. - `P4MCP_TLS_CA_MODE` - TLS certificate source mode.
  483. - `system` (default): use OS trust store via `truststore`. **Note:** In this mode, `truststore` overrides the `verify=` parameter — custom CA bundles set via `P4MCP_CA_BUNDLE` or `--ca-bundle` are ignored. To use a custom CA bundle, set `P4MCP_TLS_CA_MODE=certifi`.
  484. - `certifi`: disable `truststore` injection and use default Python TLS certificate behavior. Custom CA bundles (`P4MCP_CA_BUNDLE` / `--ca-bundle`) take effect only in this mode.
  485. - `P4MCP_SSL_VERIFY` - Set to `false` to disable SSL verification for P4 Code Review API requests. Default: `true`. Works in both TLS modes.
  486. - `P4MCP_CA_BUNDLE` - Path to a custom CA certificate bundle (PEM) for P4 Code Review API requests. Takes priority over `P4MCP_SSL_VERIFY`. **Requires `P4MCP_TLS_CA_MODE=certifi`** to take effect.
  487. ### Telemetry environment variables
  488. - `OTEL_EXPORTER_OTLP_ENDPOINT` - OTLP collector endpoint for telemetry export. Default: `https://grpc.public.prd.shared.perforce.com`.
  489. - `OTEL_EXPORTER_OTLP_PROTOCOL` - OTLP export protocol. Only `grpc` is supported; other values fall back to `grpc` with a warning.
  490. ### P4 DAM environment variables
  491. - `P4DAM_API_KEY` - P4 DAM API key. Sent as `Authorization: account_key='<key>'` with all P4 DAM API requests. Requires an active P4 DAM session. **When unset, P4 DAM tools are not registered.** The toolset is silently skipped at startup.
  492. > **P4 DAM URL discovery:** The P4 DAM base URL is read from the `P4.HTH.URL` P4 property on the server. If the property is unset, P4 DAM tool calls fail at runtime.
  493. >
  494. > **SSL for P4 DAM:** P4 DAM API requests use the same SSL configurations as Swarm — `P4MCP_TLS_CA_MODE`, `--ca-bundle` / `P4MCP_CA_BUNDLE`, and `--ssl-no-verify` / `P4MCP_SSL_VERIFY`.
  495. ### Supported arguments
  496. - `--readonly` - Control write operations.
  497. - If present, uses read-only mode. Safe for exploration and testing.
  498. - If missing, enables write operations. Requires proper permissions on your P4 Server.
  499. - `--allow-usage` - Allow usage statistics.
  500. - If present, allows anonymous usage statistics collection.
  501. - If missing, disables all usage statistics.
  502. - `--toolsets` - Specify which tool categories to enable.
  503. - Available: `files`, `changelists`, `shelves`, `workspaces`, `jobs`, `reviews`, `streams`, `p4dam`
  504. - Default: All toolsets enabled.
  505. - `query_server` is always available regardless of the `--toolsets` setting.
  506. - `--search-transform` - Enable search-based tool discovery to reduce token overhead.
  507. - `regex` — Expose a regex pattern-matching search tool. Best for targeted lookups.
  508. - `bm25` — Expose a natural-language relevance-ranked search tool. Best for exploratory queries.
  509. - `both` — Expose both search tools with distinct names (`regex_search_tools`/`regex_call_tool` and `semantic_search_tools`/`semantic_call_tool`).
  510. - If omitted, the full tool catalog is sent to the client (default, backward-compatible).
  511. - When enabled, `query_server` is always directly visible to the client.
  512. - **Security:** Admin permission checks (`CheckPermissionMiddleware`) and `--readonly` filtering remain fully enforced. Search transforms query the real tool catalog internally, so tools blocked by middleware or excluded by read-only mode are never discoverable or callable through the search interface.
  513. - `--max-results <N>` - Cap on the number of rows the P4 server returns per command (`p4.maxresults`).
  514. - Default: `10000`. Set to `0` to disable the limit (server default in effect).
  515. - Protects against runaway AI-driven queries exhausting local memory or overwhelming the server.
  516. - When a command would exceed this limit the server aborts it with an error — it does not truncate — so keep the value generous.
  517. - Must be a non-negative integer; an invalid value fails fast at startup before any P4 connection is attempted.
  518. > **Priority order:** `--max-results` > `P4MCP_MAX_RESULTS` > default (`10000`).
  519. - `--max-scan-rows <N>` - Cap on the number of rows the P4 server scans per command (`p4.maxscanrows`).
  520. - Unset by default, so admin/group policy governs scan limits.
  521. - Must be a non-negative integer when supplied; an invalid value fails fast at startup.
  522. > **Priority order:** `--max-scan-rows` > `P4MCP_MAX_SCAN_ROWS` > default (unset).
  523. - `--ssl-no-verify` - Disable SSL certificate verification for P4 Code Review API requests.
  524. - Useful for environments with self-signed or internal CA certificates.
  525. - Works in both `system` and `certifi` TLS modes.
  526. - These SSL options only affect HTTPS Swarm connections. If the Swarm URL is `http://`, they have no effect.
  527. - `--ca-bundle <path>` - Path to a custom CA certificate bundle (PEM) for P4 Code Review API requests.
  528. - Use this to trust an internal CA without disabling verification entirely.
  529. - **Requires `P4MCP_TLS_CA_MODE=certifi`** to take effect. In the default `system` mode, `truststore` uses the OS trust store and ignores this setting.
  530. - If both `--ca-bundle` and `--ssl-no-verify` are provided, `--ca-bundle` takes priority (verification is performed using the specified bundle).
  531. > **Priority order:** `--ca-bundle` > `--ssl-no-verify` > `P4MCP_CA_BUNDLE` > `P4MCP_SSL_VERIFY` > default (`true`). CLI args take priority over environment variables.
  532. - `--host <address>` - HTTP bind address. Default: `127.0.0.1` (local only). Use `0.0.0.0` to allow remote clients (no authentication; trusted networks only).
  533. - `--log-dir <path>` - Directory for log files.
  534. - Specify a custom directory for log files (both application and session logs).
  535. - Default: `logs/` in the server executable's directory.
  536. - Can also be set via `P4MCP_LOG_DIR` environment variable.
  537. - CLI argument takes priority over environment variable.
  538. > **Priority order:** `--log-dir` > `P4MCP_LOG_DIR` > default (`logs/` in the server executable's directory).
  539. ### Required configurations
  540. - Use absolute paths for the `command` field in all configurations.
  541. - Ensure environment variables are properly set for each host.
  542. - Different hosts may have different argument parsing. Refer to the host's documentation.
  543. ## P4 configuration
  544. ### User configuration
  545. **Example setup**
  546. ```bash
  547. # Windows (PowerShell)
  548. $env:P4PORT = "ssl:perforce.example.com:1666"
  549. $env:P4USER = "your_username"
  550. $env:P4CLIENT = "your_workspace"
  551. ```
  552. ```bash
  553. # macOS/Linux (Bash)
  554. export P4PORT="ssl:perforce.example.com:1666"
  555. export P4USER="your_username"
  556. export P4CLIENT="your_workspace"
  557. ```
  558. > **`P4USER` must be a standard user.** P4 MCP Server runs commands such as `p4 describe` and `p4 changes` that a `service`-type user is not permitted to run, so a service user will cause tools to fail at runtime. Configure `P4USER` with a Perforce user of type `standard`. See [`p4 user`](https://help.perforce.com/helix-core/server-apps/cmdref/current/Content/CmdRef/p4_user.html) in the P4 CLI documentation.
  559. #### Connection-limit options
  560. These options bound how much work a single P4 command can do, protecting the server against runaway queries:
  561. - `max_results` — Caps how many rows the P4 server returns per command. On by default with a generous value to protect against runaway queries. Lower the value to tighten the bound. Configured via `P4MCP_MAX_RESULTS` or `--max-results`.
  562. - `max_scan_rows` — Caps how many rows the server scans per command. Unset by default (governed by admin/group policy). Configured via `P4MCP_MAX_SCAN_ROWS` or `--max-scan-rows`.
  563. ### Admin configuration
  564. Manage access through group-level and user-level server properties.
  565. P4 resolves each property to a single value using two rules, applied in order:
  566. 1. **Highest sequence number wins.** The `-s` flag is the primary sort key. It applies across all scopes — a group property at `-s5` beats a user property at `-s1` or default.
  567. 2. **At the same sequence number, scope is the tiebreaker:** user > group > global. Between groups at the same sequence, the alphabetically-first group name wins.
  568. P4 does not compare values semantically. It does not know that `false` is more restrictive than `true`. The winning property's value is returned as-is and checked by the MCP server.
  569. If no property applies, MCP remains enabled unless explicitly disabled.
  570. #### Master switch (global disable)
  571. To disable MCP for all users:
  572. ```
  573. p4 property -a -n mcp.enabled -v false
  574. ```
  575. To re-enable group/user-based control, delete the global property first:
  576. ```
  577. p4 property -d -n mcp.enabled
  578. ```
  579. <details><summary><b>Group-based restrictions</b></summary>
  580. To prevent access for all members of a specific group:
  581. ```
  582. p4 property -a -n mcp.enabled -v false -g noaccessgroup
  583. ```
  584. You can set multiple group restrictions the same way.
  585. When a user belongs to multiple groups with conflicting settings, P4's property resolution determines which value wins.
  586. The highest sequence number (`-s`) wins. At equal sequence numbers, the alphabetically-first group name wins.
  587. Example:
  588. ```
  589. p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
  590. p4 property -a -n mcp.enabled -v true -s2 -g accessgroup
  591. ```
  592. In this example, `accessgroup` wins because `-s2` is higher than `-s1`.
  593. </details>
  594. <details><summary><b>User-based restrictions</b></summary>
  595. To block a specific user regardless of group membership:
  596. ```
  597. p4 property -a -n mcp.enabled -v false -u noaccessuser
  598. ```
  599. At the same sequence number, user-level properties override group-level and global settings (P4's scope tiebreaker).
  600. Example: Even if `noaccessuser` is in `accessgroup` (where MCP is enabled), the user property at the same sequence takes precedence and MCP is disabled.
  601. > **Note:** A group property at a higher `-s` value can override a user property at a lower sequence number. To ensure a user-level property always wins, give it a high `-s` value or ensure no group properties use a higher sequence.
  602. </details>
  603. <details><summary><b>Toolset allowlist (global)</b></summary>
  604. Restrict which toolsets are available server-wide using `mcp.toolsets.allowed`. Only listed toolsets will be enabled; all others are blocked.
  605. Available toolsets: `server`, `changelists`, `files`, `jobs`, `reviews`, `shelves`, `workspaces`, `streams`
  606. Allow only changelists and files:
  607. ```
  608. p4 property -a -n mcp.toolsets.allowed -v changelists,files
  609. ```
  610. Remove the allowlist to restore all toolsets:
  611. ```
  612. p4 property -d -n mcp.toolsets.allowed
  613. ```
  614. </details>
  615. <details><summary><b>Global read-only mode</b></summary>
  616. Disable all write operations (modify tools) while keeping read operations (query tools) available:
  617. ```
  618. p4 property -a -n mcp.toolsets.write -v false
  619. ```
  620. Re-enable writes:
  621. ```
  622. p4 property -a -n mcp.toolsets.write -v true
  623. ```
  624. When `write=false`, all `modify_*` tools are blocked but all `query_*` tools continue to work.
  625. </details>
  626. <details><summary><b>Toolset enable/disable per group</b></summary>
  627. Enable or disable individual toolsets for a specific group.
  628. Disable a toolset for a specific group:
  629. ```
  630. p4 property -a -n mcp.toolset.changelists.enabled -v false -g reviewers
  631. ```
  632. Users in `reviewers` are blocked from changelists. Users in other groups (with no explicit setting) retain default access.
  633. To restrict a toolset to only one group, disable it for every other group that should not have access:
  634. ```
  635. p4 property -a -n mcp.toolset.files.enabled -v false -g reviewers
  636. p4 property -a -n mcp.toolset.files.enabled -v false -g interns
  637. # Only groups without an explicit "false" retain default access to files
  638. ```
  639. > **Note:** All toolsets are enabled by default. Setting `enabled=true` for a group is redundant unless you are explicitly overriding a previous `false` setting. At the same sequence number, a group property overrides a global property (P4's scope tiebreaker), so a group `enabled=true` can override a global `enabled=false`. To ensure a global setting cannot be overridden, give it a high `-s` value. To isolate a toolset to specific groups, disable it for the groups you want to block.
  640. </details>
  641. <details><summary><b>Write control per toolset per group</b></summary>
  642. Control write access for each toolset at the group level.
  643. Disable writes for a specific toolset per group:
  644. ```
  645. p4 property -a -n mcp.toolset.workspaces.write -v false -g reviewers
  646. ```
  647. This blocks `modify_workspaces` for the group while `query_workspaces` remains accessible.
  648. </details>
  649. <details><summary><b>Tool-specific overrides</b></summary>
  650. Restrict a group to specific tools within a toolset using `mcp.toolset.<name>.tools`.
  651. Allow only `query_files` (block `modify_files`) for developers:
  652. ```
  653. p4 property -a -n mcp.toolset.files.tools -v query_files -g developers
  654. ```
  655. Allow both query and modify for leads:
  656. ```
  657. p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads
  658. ```
  659. Tool-specific overrides can restrict access even when writes are enabled:
  660. ```
  661. p4 property -a -n mcp.toolsets.write -v true
  662. p4 property -a -n mcp.toolset.files.tools -v query_files -g developers
  663. # Result: modify_files is BLOCKED — tool list restricts
  664. ```
  665. > **Note:** Tool-specific overrides cannot bypass write restrictions. The server checks write permissions before evaluating tool lists. If `write=false` is set at any level, write tools are blocked regardless of the tool list.
  666. </details>
  667. <details><summary><b>Multi-group conflict resolution</b></summary>
  668. When a user belongs to multiple groups with conflicting settings, P4 resolves each property to a single value. The MCP server does not perform its own multi-group logic — it uses whichever value P4 returns.
  669. P4's resolution rules for a given property name:
  670. 1. **Highest `-s` (sequence number) wins.** This is the primary sort key.
  671. 2. **At the same sequence number:** user scope > group scope > global scope.
  672. 3. **Between groups at the same sequence:** the alphabetically-first group name wins.
  673. P4 does not compare values. It picks the winning entry by position, not by content.
  674. **Example — groups at the same sequence (default):**
  675. ```
  676. p4 property -a -n mcp.toolset.files.enabled -v true -g developers
  677. p4 property -a -n mcp.toolset.files.enabled -v false -g leads
  678. # User in both groups → resolved value is "true"
  679. # Reason: "developers" < "leads" alphabetically, so developers wins
  680. ```
  681. Swapping the values would give `false` — `developers` still wins regardless of the value.
  682. **Example — only one group has a setting:**
  683. ```
  684. p4 property -a -n mcp.toolset.files.enabled -v false -g leads
  685. # developers has no setting
  686. # User in developers + leads → resolved value is "false"
  687. # Reason: leads is the only group with a value, so it wins
  688. ```
  689. **Example — write access:**
  690. ```
  691. p4 property -a -n mcp.toolset.files.write -v false -g developers
  692. p4 property -a -n mcp.toolset.files.write -v true -g leads
  693. # User in both groups → resolved value is "false"
  694. # Reason: "developers" < "leads" alphabetically, not because false is "more restrictive"
  695. ```
  696. **Example — tool lists (no union):**
  697. ```
  698. p4 property -a -n mcp.toolset.reviews.tools -v query_reviews -g developers
  699. p4 property -a -n mcp.toolset.reviews.tools -v query_reviews,modify_reviews -g leads
  700. # User in both groups → resolved value is "query_reviews"
  701. # Reason: "developers" wins alphabetically. P4 returns one value, not a union.
  702. ```
  703. **Example — using `-s` to control which group wins:**
  704. ```
  705. p4 property -a -n mcp.enabled -v false -s1 -g noaccessgroup
  706. p4 property -a -n mcp.enabled -v true -s2 -g accessgroup
  707. # accessgroup wins because -s2 > -s1 (highest sequence wins)
  708. ```
  709. > **Tip:** To get predictable results with multiple groups, always use explicit `-s` values rather than relying on alphabetical group name ordering.
  710. </details>
  711. <details><summary><b>Disabling a specific toolset globally</b></summary>
  712. Disable a single toolset for all users without affecting others:
  713. ```
  714. p4 property -a -n mcp.toolset.reviews.enabled -v false
  715. ```
  716. This blocks both `query_reviews` and `modify_reviews` for all users. Other toolsets remain unaffected.
  717. </details>
  718. <details><summary><b>Emergency read-only for a specific group</b></summary>
  719. Restrict a specific group to read-only without affecting other groups:
  720. ```
  721. p4 property -a -n mcp.toolsets.write -v false -g problematic_group
  722. ```
  723. Users in other groups retain full write access. If a user belongs to both the restricted group and an unrestricted group, P4's property resolution determines the outcome — typically the alphabetically-first group name wins at equal sequence numbers. Use explicit `-s` values for predictable results.
  724. </details>
  725. <br>
  726. #### How properties are resolved
  727. The MCP server checks properties in this order. Each property is resolved independently by P4 using the standard resolution rules (highest `-s` wins, then user > group > global at equal sequence, then alphabetically-first group name).
  728. | Check order | Property | MCP server behavior |
  729. |-------------|----------|---------------------|
  730. | 1 | `mcp.enabled` | If resolved value is `false`, block all access |
  731. | 2 | `mcp.toolsets.write` | If resolved value is `false` and tool is a write operation, block |
  732. | 3 | `mcp.toolsets.allowed` | If set, only listed toolsets are available |
  733. | 4 | `mcp.toolset.<name>.enabled` | If resolved value is `false`, block the toolset |
  734. | 5 | `mcp.toolset.<name>.write` | If resolved value is `false` and tool is a write operation, block |
  735. | 6 | `mcp.toolset.<name>.tools` | If set, only listed tools within the toolset are available |
  736. <br><strong>Important notes </strong>
  737. - Each property is resolved to a single value by P4 before the MCP server sees it. P4 uses: highest sequence number (`-s`) first, then scope (user > group > global) as a tiebreaker, then alphabetical group name. The MCP server does not perform its own multi-group or multi-scope resolution.
  738. - `mcp.enabled` acts as the main switch. When its resolved value is `false`, all access is blocked.
  739. - At the same sequence number, a group or user property overrides a global property. To ensure a global `false` cannot be overridden, assign it a high `-s` value.
  740. - Scope hierarchy (user > group > global) only applies as a tiebreaker at equal sequence numbers. A group property at `-s5` will beat a user property at default sequence or `-s1`.
  741. - When a user belongs to multiple groups, the alphabetically-first group name wins (at equal `-s`). The winning value is used as-is — P4 does not compare `true` vs `false` or pick the "most restrictive" value. Use explicit `-s` values to control which group takes priority.
  742. - Tool-specific overrides (`mcp.toolset.<name>.tools`) can further restrict access but cannot bypass write restrictions. Write checks are evaluated before tool lists.
  743. - Property changes take effect within 60 seconds due to server-side caching, or immediately on a new MCP server connection.
  744. - Only the value `false` (case-insensitive) disables or blocks access. Any other value (including `true`, `1`, `yes`, or invalid strings) is treated as not blocking.
  745. ## Available tools
  746. ### Query tools (read operations)
  747. <details>
  748. <summary><strong><code>query_server</code></strong> - Get server information and current user details</summary>
  749. - **Actions**:
  750. - `server_info` - Get P4 version, uptime, and configuration
  751. - `current_user` - Get current user information and permissions
  752. - **Use cases** - Server diagnostics, user verification, connection testing
  753. </details>
  754. <details>
  755. <summary><strong><code>query_workspaces</code></strong> - Workspace information and management</summary>
  756. - **Actions**:
  757. - `list` - List all workspaces (optionally filtered by user)
  758. - `get` - Get a detailed workspace specification
  759. - `type` - Check workspace type and configuration
  760. - `status` - Check workspace sync status
  761. - **Parameters**: `workspace_name`, `user`, `max_results`
  762. - **Use cases**: Workspace discovery, configuration review, status checking
  763. </details>
  764. <details>
  765. <summary><strong><code>query_changelists</code></strong> - Access changelist information and history</summary>
  766. - **Actions**:
  767. - `get` - Get detailed changelist information (files, description, jobs)
  768. - `list` - List changelists with filters (status, user, workspace)
  769. - **Parameters**: `changelist_id`, `status` (pending/submitted), `workspace_name`, `max_results`
  770. - **Use cases**: Code review, history tracking, changelist analysis
  771. </details>
  772. <details>
  773. <summary><strong><code>query_files</code></strong> - File operations and information</summary>
  774. - **Actions**:
  775. - `content` - Get file content at a specific revision
  776. - `history` - Get file revision history and integration records
  777. - `info` - Get file basic details (type, size, permissions)
  778. - `metadata` - Get file metadata (attributes, filesize, etc.)
  779. - `diff` - Compare file versions (depot-to-depot or mixed)
  780. - `annotations` - Get file annotations with blame information
  781. - `search` - Search for files by name pattern (wildcard matching)
  782. - `grep` - Search for files by content pattern (text search)
  783. - **Parameters**: `file_path`, `file2` (for diff), `pattern` (for search/grep), `case_insensitive` (for grep), `max_results`, `diff2` (boolean), `ranges` (for content)
  784. - `ranges` - Optional list of `[start, end]` line pairs, 1-based and inclusive (e.g. `[[10, 20], [50, 60]]`). Applies to the `content` action only. When set, the response returns a `chunks` array with one entry per range instead of the whole file.
  785. - **Use cases**: Code analysis, file comparison, history tracking, blame analysis, file discovery, content search, retrieving specific line ranges from large files
  786. </details>
  787. <details>
  788. <summary><strong><code>query_shelves</code></strong> - Shelved changelist operations and inspection</summary>
  789. - **Actions**:
  790. - `list` - List shelved changes by user or globally
  791. - `diff` - Show differences in shelved files
  792. - `files` - List files in a specific shelf
  793. - **Parameters**: `changelist_id`, `user`, `max_results`
  794. - **Use cases**: Code review, work-in-progress tracking, collaboration
  795. </details>
  796. <details>
  797. <summary><strong><code>query_jobs</code></strong> - Job tracking and defect management</summary>
  798. - **Actions**:
  799. - `list_jobs` - List jobs associated with a changelist
  800. - `get_job` - Get detailed job information and status
  801. - **Parameters**: `changelist_id`, `job_id`, `max_results`
  802. - **Use cases**: Defect tracking, requirement traceability, project management
  803. </details>
  804. <details>
  805. <summary><strong><code>query_reviews</code></strong> - Review discovery, details, and activity</summary>
  806. - **Actions**:
  807. - `list` - List all reviews with optional filtering
  808. - `dashboard` - Get current user's review dashboard (my reviews, needs attention)
  809. - `get` - Get detailed review information
  810. - `transitions` - Get available state transitions for a review
  811. - `files_readby` - Get files read status by users
  812. - `files` - Get files in a review (with optional version range)
  813. - `activity` - Get review activity history
  814. - `comments` - Get comments on a review
  815. - **Parameters**:
  816. - `review_id` - Review ID (required for get, transitions, files_readby, files, comments, activity)
  817. - `review_fields` - Comma-separated fields to return (e.g., "id,description,author,state")
  818. - `comments_fields` - Fields for comments (default: "id,body,user,time")
  819. - `up_voters` - List of up voters for transitions
  820. - `from_version`, `to_version` - Version range for files action
  821. - `max_results` - Maximum results (default: 10)
  822. - **Use cases**: Code review discovery, review status tracking, comment retrieval, review activity monitoring
  823. </details>
  824. <details>
  825. <summary><strong><code>query_streams</code></strong> - Stream hierarchy, integration status, and workspace validation</summary>
  826. - **Actions**:
  827. - `list` - List streams with optional filters (path pattern, owner, type)
  828. - `get` - Get a detailed stream specification
  829. - `children` - Get child streams of a given stream
  830. - `parent` - Get the parent stream
  831. - `graph` - Get the full stream graph (parent + children)
  832. - `integration_status` - Get integration status between stream and parent (p4 istat)
  833. - `get_workspace` - Get a workspace spec bound to a stream
  834. - `list_workspaces` - List workspaces bound to a stream
  835. - `validate_file` - Validate file paths against a stream's view
  836. - `validate_submit` - Validate opened files for submit in a stream workspace
  837. - `check_resolve` - Check for pending stream spec conflicts
  838. - `interchanges` - List changelists awaiting integration between streams
  839. - **Parameters**:
  840. - `stream_name` - Stream depot path (required for get, children, parent, graph, check_resolve, interchanges)
  841. - `stream_path` - Path pattern(s) for list (e.g., `["//depot/..."]`)
  842. - `filter` - Filter expression for list (e.g., `"Owner=alice&Type=development"`)
  843. - `fields` - Fields to return for list (e.g., `["Stream", "Owner", "Type"]`)
  844. - `workspace` - Workspace name for get_workspace, validate_file, validate_submit
  845. - `file_paths` - File paths for validate_file
  846. - `view_without_edit` - View locked stream spec without opening for edit
  847. - `at_change` - Retrieve historical stream spec at a changelist number
  848. - `both_directions` - Show integration status in both directions
  849. - `force_refresh` - Force istat cache refresh
  850. - `reverse`, `long_output`, `limit` - Options for interchanges
  851. - `unloaded`, `all_streams`, `viewmatch` - Filters for list
  852. - `max_results` - Maximum results
  853. - **Use cases**: Stream hierarchy exploration, integration status tracking, workspace validation, view compatibility checks
  854. </details>
  855. <details>
  856. <summary><strong><code>query_p4dam_assets</code></strong> - Search P4 DAM assets by keyword or filters</summary>
  857. - **Parameters**: `search_term`, `project_ids`, `repository_ids`, `path`, `tag`, `file_extension`, `user`, `all_revisions`, `max_results`, `offset`
  858. - **Use cases**: Asset discovery, filtering by project/repository/tag/extension, browsing P4 DAM content. Use when you don't have a depot path yet.
  859. </details>
  860. <details>
  861. <summary><strong><code>query_p4dam_asset</code></strong> - Fetch full metadata for a single P4 DAM asset</summary>
  862. - **Parameters**: `depot_path` (required), `identifier`, `project_id`, `repository_id`, `include`
  863. - **Use cases**: Fetching commit info, asset bundles, weblinks, custom attributes, and project/repository matches for a known asset. Use after `query_p4dam_assets` to get full detail on a specific file.
  864. </details>
  865. <details>
  866. <summary><strong><code>query_p4dam_projects</code></strong> - List P4 DAM projects</summary>
  867. - **Parameters**: `search_term`, `limit`, `offset`
  868. - **Use cases**: Discovering available projects before creating an asset bundle or file review, resolving project IDs for other calls.
  869. </details>
  870. <details>
  871. <summary><strong><code>query_p4dam_repositories</code></strong> - List repositories in a P4 DAM project</summary>
  872. - **Parameters**: `project_id` (required), `search_term`, `limit`, `offset`
  873. - **Use cases**: Finding repository type (`helix_stream` or `helix_classic`) and `linked_streams` — needed to supply `stream_path` or discover branches when creating asset bundles or file reviews.
  874. </details>
  875. <details>
  876. <summary><strong><code>query_p4dam_helix_classic_branches</code></strong> - List Helix Classic branches in a repository</summary>
  877. - **Parameters**: `project_id` (required), `repository_id` (required), `limit`, `offset`
  878. - **Use cases**: Finding the branch ID required when creating an asset bundle or file review in a Helix Classic repository.
  879. </details>
  880. <details>
  881. <summary><strong><code>fetch_p4dam_media</code></strong> - Fetch and render a P4 DAM media URL as an image</summary>
  882. - **Parameters**: `url` (required — `thumbnail_url`, `preview_url`, `sprite_url`, or `file_url` from asset results)
  883. - **Use cases**: Rendering thumbnails, previews, and sprite sheets for image assets directly in the client. For non-image files returns MIME type and size instead of image content. Pass URLs from `query_p4dam_assets` or `query_p4dam_asset` results — only `thumbnail_url`, `preview_url`, and `sprite_url` are present for image files.
  884. </details>
  885. <details>
  886. <summary><strong><code>query_p4dam_file_reviews</code></strong> - List file (asset) reviews for a project</summary>
  887. - **Parameters**: `project_id` (required), `depot_path`, `include`, `limit`, `offset`
  888. - **Use cases**: Browsing active reviews in a project, filtering by depot path, discovering review UUIDs for detail lookups.
  889. </details>
  890. <details>
  891. <summary><strong><code>query_p4dam_file_review</code></strong> - Fetch a single file review by UUID</summary>
  892. - **Parameters**: `project_id` (required), `review_id` (required)
  893. - **Use cases**: Retrieving full review detail — state, view_paths, asset_bundle, creator, and `download_url` for bundle reviews.
  894. </details>
  895. <details>
  896. <summary><strong><code>query_p4dam_workflows</code></strong> - List P4 DAM workflows</summary>
  897. - **Parameters**: `include`, `limit`, `offset`
  898. - **Use cases**: Discovering available workflows and their states. Pass `include=['states']` to get all states in a single call — use the state `short_name` as the `state` parameter in file review operations.
  899. </details>
  900. <details>
  901. <summary><strong><code>query_p4dam_workflow</code></strong> - Fetch a single workflow by short name or UUID</summary>
  902. - **Parameters**: `workflow_id` (required), `include`
  903. - **Use cases**: Inspecting a workflow's states (`kind`: open/review/done, `color`, `position`) and transition rules.
  904. </details>
  905. <details>
  906. <summary><strong><code>query_p4dam_workflow_states</code></strong> - List states for a workflow</summary>
  907. - **Parameters**: `workflow_id` (required), `limit`, `offset`
  908. - **Use cases**: Listing all states with `short_name`, `kind`, `color`, and `position`. The `short_name` is the value to pass as `state` when creating or updating a file review.
  909. </details>
  910. <details>
  911. <summary><strong><code>query_p4dam_custom_attribute_templates</code></strong> - List custom attribute templates for a project</summary>
  912. - **Parameters**: `project_id` (required)
  913. - **Use cases**: Discovering available custom attributes before setting values — returns each template's UUID, name, type (`text`, `single-select`, `multi-select`, `checkbox`), and `available_values` for select types. Pass the UUID to `update_p4dam_asset_custom_attributes`.
  914. </details>
  915. ### Modify tools (write operations)
  916. <details>
  917. <summary><strong><code>modify_workspaces</code></strong> - Workspace creation and management</summary>
  918. - **Actions** - `create`, `update`, `delete`, `switch`
  919. - **Parameters** - `name`, `specs` (WorkspaceSpec object with View, Root, Options, etc.)
  920. - **Requires** - Read-only mode disabled, appropriate permissions
  921. - **Use cases** - Environment setup, workspace maintenance, branch switching
  922. </details>
  923. <details>
  924. <summary><strong><code>modify_changelists</code></strong> - Changelist lifecycle management</summary>
  925. - **Actions** - `create`, `update`, `submit`, `delete`, `move_files`
  926. - **Parameters** - `changelist_id`, `description`, `file_paths`
  927. - **Safety** - Ownership checks, interactive PROCEED/CANCEL elicitation prompt for delete operations with item details
  928. - **Use cases** - Code submission, work organization, file grouping
  929. </details>
  930. <details>
  931. <summary><strong><code>modify_files</code></strong> - File system operations and version control</summary>
  932. - **Actions** - `add`, `edit`, `delete`, `move`, `revert`, `reconcile`, `resolve`, `sync`
  933. - **Parameters** - `file_paths`, `changelist`, `force`, `mode` (for resolve operations)
  934. - **Resolve modes** - `auto`, `safe`, `force`, `preview`, `theirs`, `yours`
  935. - **Use cases** - File editing, conflict resolution, workspace synchronization
  936. </details>
  937. <details>
  938. <summary><strong><code>modify_shelves</code></strong> - Shelving operations for work in progress</summary>
  939. - **Actions** - `shelve`, `unshelve`, `update`, `delete`, `unshelve_to_changelist`
  940. - **Parameters** - `changelist_id`, `file_paths`, `target_changelist`, `force`
  941. - **Use cases** - Temporary storage, code sharing, backup before experiments
  942. </details>
  943. <details>
  944. <summary><strong><code>modify_jobs</code></strong> - Job and changelist integration</summary>
  945. - **Actions** - `link_job`, `unlink_job`
  946. - **Parameters** - `changelist_id`, `job_id`
  947. - **Use cases** - Defect tracking integration, requirement linking
  948. </details>
  949. <details>
  950. <summary><strong><code>modify_reviews</code></strong> - Review creation, transitions, participants, and comments</summary>
  951. - **Actions**:
  952. - `create` - Create a new review from a changelist
  953. - `refresh_projects` - Refresh project associations
  954. - `vote` - Vote on a review (up, down, clear)
  955. - `transition` - Change review state (needsRevision, needsReview, approved, committed, rejected, archived)
  956. - `append_participants` - Add reviewers/groups to a review
  957. - `replace_participants` - Replace all participants
  958. - `delete_participants` - Remove participants from a review
  959. - `add_comment` - Add a comment to a review
  960. - `reply_comment` - Reply to an existing comment
  961. - `edit_comment` - Edit an existing comment's body and/or task state
  962. - `append_change` - Add a changelist to an existing review
  963. - `replace_with_change` - Replace review content with a changelist
  964. - `join` - Join a review as a participant
  965. - `leave` - Leave a review
  966. - `archive_inactive` - Archive inactive reviews
  967. - `mark_comment_read` / `mark_comment_unread` - Mark individual comment read status
  968. - `mark_all_comments_read` / `mark_all_comments_unread` - Mark all comments read status
  969. - `update_author` - Change the review author
  970. - `update_description` - Update review description
  971. - `obliterate` - Permanently delete a review
  972. - **Parameters**:
  973. - `review_id` - Review ID (required for most actions)
  974. - `change_id` - Changelist ID (required for create, append_change, replace_with_change)
  975. - `description` - Review description
  976. - `reviewers`, `required_reviewers` - Lists of reviewer usernames
  977. - `reviewer_groups` - Reviewer groups with requirements
  978. - `vote_value` - Vote value: `up`, `down`, `clear`
  979. - `version` - Review version for voting
  980. - `transition` - Target state: `needsRevision`, `needsReview`, `approved`, `committed`, `approved:commit`, `rejected`, `archived`
  981. - `jobs`, `fix_status`, `cleanup` - Job linking and cleanup options for transitions
  982. - `users`, `groups` - Structured participant data for append/replace/delete
  983. - `body` - Comment body text
  984. - `task_state` - Comment task state: `open`, `comment`, `addressed`, `verified`. `add_comment` accepts only `open` and `comment`; `addressed` and `verified` are reachable through `edit_comment`.
  985. - `notify` - Notification mode: `immediate`, `delayed`
  986. - `comment_id` - Comment ID for replies, edits, or marking read/unread
  987. - `context` - Comment context (file, line numbers, content, version)
  988. - `not_updated_since`, `max_reviews` - Filters for archive_inactive
  989. - `new_author`, `new_description` - Values for update actions
  990. - **Use cases**: Code review workflow, review state management, collaborative commenting, participant management, review cleanup
  991. </details>
  992. <details>
  993. <summary><strong><code>modify_streams</code></strong> - Stream lifecycle, spec editing, propagation, and workspace management</summary>
  994. - **Actions**:
  995. - `create` - Create a new stream (mainline, development, release, task, virtual, etc.)
  996. - `update` - Update stream properties (name, description, options, paths, parent_view)
  997. - `delete` - Delete a stream
  998. - `edit_spec` - Open stream spec for editing (p4 stream edit)
  999. - `resolve_spec` - Resolve stream spec conflicts
  1000. - `revert_spec` - Revert stream spec edits
  1001. - `shelve_spec` - Shelve stream spec edits to a numbered changelist
  1002. - `unshelve_spec` - Unshelve stream spec edits
  1003. - `copy` - Copy changes between parent and child streams
  1004. - `merge` - Merge changes between parent and child streams
  1005. - `integrate` - Integrate changes with advanced options
  1006. - `populate` - Populate a new stream with files (branch)
  1007. - `switch` - Switch a workspace to a different stream
  1008. - `create_workspace` - Create a new workspace bound to a stream
  1009. - **Parameters**:
  1010. - `stream_name` - Stream depot path (required for create, update, delete, edit_spec, resolve_spec, revert_spec, switch)
  1011. - `stream_type` - Stream type for create: `mainline`, `development`, `sparsedev`, `release`, `sparserel`, `task`, `virtual`
  1012. - `parent` - Parent stream for non-mainline create
  1013. - `name`, `description` - Stream display name and description
  1014. - `options` - Stream options: `allsubmit/ownersubmit`, `unlocked/locked`, `toparent/notoparent`, `fromparent/nofromparent`, `mergedown/mergeany`
  1015. - `parent_view` - Parent view treatment: `inherit` or `noinherit`
  1016. - `paths`, `remapped`, `ignored` - Stream view mappings
  1017. - `changelist` - Changelist for spec editing or propagation operations
  1018. - `resolve_mode` - Resolve mode for resolve_spec: `auto`, `accept_theirs`, `accept_yours`
  1019. - `parent_stream` - Override parent for propagation (-P flag)
  1020. - `branch` - Branch spec for integrate/populate (-b flag)
  1021. - `file_paths` - File paths for propagation
  1022. - `preview` - Preview only, no changes (-n flag)
  1023. - `force` - Force operation (-f flag)
  1024. - `reverse` - Reverse direction (-r flag)
  1025. - `max_files` - Limit files processed (-m flag)
  1026. - `quiet` - Suppress informational messages (-q flag)
  1027. - `output_base` - Show base revision with scheduled resolve (-Ob flag for merge/integrate) or list files created (-o flag for populate)
  1028. - `virtual` - Copy using virtual stream (-v flag, copy only)
  1029. - `schedule_branch_resolve` - Schedule branch resolves instead of automatic branching (-Rb flag, integrate only)
  1030. - `integrate_around_deleted` - Integrate around deleted revisions (-Di flag, integrate only)
  1031. - `skip_cherry_picked` - Skip cherry-picked revisions already integrated (-Rs flag, integrate only)
  1032. - `source_path`, `target_path` - Source and target paths for populate
  1033. - `workspace` - Workspace name for switch
  1034. - `workspace_name`, `root`, `host`, `alt_roots` - Workspace creation parameters
  1035. - **Safety**: Stream existence validation, locked stream detection, bound workspace warnings, open file checks for view-affecting changes
  1036. - **Use cases**: Stream creation and management, branch propagation (merge/copy/integrate), spec conflict resolution, workspace provisioning
  1037. </details>
  1038. <details>
  1039. <summary><strong><code>create_p4dam_asset_bundle</code></strong> - Create a P4 DAM asset bundle</summary>
  1040. - **Parameters**: `depot_path` (required, must end `.p4bundle`), `project` (required), `repository` (required), `view_paths` (required), `stream_path`, `helix_classic_branch`, `description`, `hero_file_path`
  1041. - **Use cases**: Creating a named, scoped collection of depot files for review. Supply `stream_path` for Helix Stream repos, `helix_classic_branch` for Helix Classic repos.
  1042. </details>
  1043. <details>
  1044. <summary><strong><code>update_p4dam_asset_bundle</code></strong> - Update an existing asset bundle</summary>
  1045. - **Parameters**: `bundle_id` (required), `description`, `view_paths`, `hero_file_path`
  1046. - **Use cases**: Changing a bundle's description, adjusting its file scope (`view_paths`), or updating the cover image. `depot_path` is immutable after creation.
  1047. </details>
  1048. <details>
  1049. <summary><strong><code>delete_p4dam_asset_bundle</code></strong> - Delete a P4 DAM asset bundle</summary>
  1050. - **Parameters**: `bundle_id` (required)
  1051. - **Use cases**: Removing an asset bundle that is no longer needed. Irreversible.
  1052. </details>
  1053. <details>
  1054. <summary><strong><code>sync_p4dam_asset_bundle</code></strong> - Sync asset bundle files to a local workspace</summary>
  1055. - **Parameters**: `view_paths` (required), `workspace_root` (required), `client_name`, `bundle_id`, `stream_path`
  1056. - **Use cases**: Downloading an asset bundle's scoped files via `p4 sync`. Creates or reuses a named P4 client — subsequent syncs are incremental. Use `stream_path` for Helix Stream repos (applies `LimitView`, requires Perforce 2025.2+).
  1057. </details>
  1058. <details>
  1059. <summary><strong><code>create_p4dam_file_review</code></strong> - Create a P4 DAM asset review</summary>
  1060. - **Parameters**: `project_id` (required), `name` (required), `depot_path` (required), `view_paths` (required), `state` (required), `repository`, `helix_classic_branch`, `asset_bundle`, `hero_file_path`, `description`, `position`, `base_commit_id`, `head_commit_id`
  1061. - **Use cases**: Opening a review for a single asset or an asset bundle (`.p4bundle`). For bundle reviews, `asset_bundle` is auto-detected from `depot_path` when omitted.
  1062. </details>
  1063. <details>
  1064. <summary><strong><code>update_p4dam_file_review</code></strong> - Update a P4 DAM file review</summary>
  1065. - **Parameters**: `project_id` (required), `review_id` (required), `state`, `name`, `view_paths`, `hero_file_path`, `description`, `position`
  1066. - **Use cases**: Transitioning a review to a new workflow state, updating its name or description, adjusting view scope. State transitions must be permitted by the project workflow for the current user.
  1067. </details>
  1068. <details>
  1069. <summary><strong><code>delete_p4dam_file_review</code></strong> - Delete a P4 DAM file review</summary>
  1070. - **Parameters**: `project_id` (required), `review_id` (required)
  1071. - **Use cases**: Removing a review that is no longer needed. Irreversible. The API returns the deleted review object on success.
  1072. </details>
  1073. <details>
  1074. <summary><strong><code>update_p4dam_asset_tags</code></strong> - Add or remove asset tags and auto-tags</summary>
  1075. - **Parameters**: `paths` (required — list of `{path, identifier?}`), `create`, `delete`, `delete_auto`, `propagatable`, `identifier`
  1076. - **Use cases**: Tagging one or many assets in a single call. Supports individual files, specific revisions, and recursive folder paths (`//depot/folder/...`). `create` adds user tags, `delete` removes user tags, `delete_auto` removes auto-generated tags. Set `propagatable=true` to apply tags to the latest revision and all future revisions.
  1077. </details>
  1078. <details>
  1079. <summary><strong><code>create_p4dam_comment</code></strong> - Post a comment on a file review or file, or reply to a comment</summary>
  1080. - **Parameters**: `type` (required), `content` (required), `project`, `repository`, `file_review`, `commit`, `path`, `stream_path`, `helix_classic_branch`, `comment`
  1081. - **Use cases**: Comment on an asset bundle file review (`file_review`), a specific file within a review (`file_review_file`), a committed file or asset bundle without a review (`commit_file`), or reply to an existing comment (`comment`). Required parameters depend on type — see `type` description.
  1082. </details>
  1083. <details>
  1084. <summary><strong><code>update_p4dam_asset_custom_attributes</code></strong> - Set or remove custom attribute values for assets</summary>
  1085. - **Parameters**: `paths` (required — list of `{path, identifier?}`), `create` (list of `{uuid, value}`), `delete` (list of attribute UUIDs to remove), `propagatable`
  1086. - **Use cases**: Setting or clearing custom metadata on one or more assets. Discover available attributes and their UUIDs first with `query_p4dam_custom_attribute_templates`. `value` is a string for `text`/`single-select`/`checkbox` types and a list of strings for `multi-select`.
  1087. </details>
  1088. <details>
  1089. <summary><strong><code>regenerate_p4dam_preview</code></strong> - Regenerate an asset preview image</summary>
  1090. - **Parameters**: `depot_path` (required), `commit_id` (required)
  1091. - **Use cases**: Re-triggering preview generation when a preview is missing or outdated. `commit_id` is the changeset number from `query_p4dam_asset` results.
  1092. </details>
  1093. <br>
  1094. > **Warnings in tool responses**
  1095. >
  1096. > When a P4 command produces a benign informational or warning message (for example, `file(s) up-to-date` or `file not on client`), the tool returns a success `status` and includes the message text in an optional top-level `warnings` list. The field appears only when there is at least one warning. Genuine failures are unaffected and still return an error `status` with the existing `code` and `error` fields.
  1097. ## Logging and Usage Data
  1098. ### Logging system
  1099. **Log locations:**
  1100. - **Application log**: `logs/p4mcp.log` - Main server operations and errors
  1101. - **Session logs**: `logs/sessions/*.log` - Individual session activities are recorded only when the `--allow-usage` flag is specified in the server's startup arguments.
  1102. ### Usage Data
  1103. **Privacy-first approach:**
  1104. - **Disabled by default**: No data collection without explicit consent
  1105. - **Consent-gated**: First-run prompt for telemetry permission
  1106. - **Transparent**: Clear explanation of data collected
  1107. - **Revocable**: Easy opt-out at any time
  1108. **Data collected (if consented):**
  1109. - Tool usage frequency (anonymized)
  1110. - Error rates and types (no personal data)
  1111. - Performance metrics
  1112. - Feature adoption statistics
  1113. - P4 server version
  1114. **Data not collected:**
  1115. - File contents or names
  1116. - P4 Server details except version
  1117. - User credentials or personal information
  1118. - Specific project information
  1119. **Control:**
  1120. - Usage data is only collected if the `--allow-usage` argument is provided at startup.
  1121. ## Troubleshooting
  1122. ### Server Startup Issues
  1123. <details>
  1124. <summary><strong>Unable to start server</strong></summary>
  1125. **Symptoms**: OS cannot find or execute the binary; error includes `ENOENT` or "No such file or directory".
  1126. <br>**Solutions**:
  1127. 1. **Check the path:** Make sure the `command` field uses the correct absolute path for your OS:
  1128. - macOS/Linux: `/absolute/path/to/p4-mcp-server`
  1129. - Windows: `C:\absolute\path\to\p4-mcp-server.exe`
  1130. 2. **Ensure the binary exists and is executable:**
  1131. - macOS/Linux:
  1132. ```bash
  1133. ls -l /absolute/path/to/p4-mcp-server && chmod +x /absolute/path/to/p4-mcp-server
  1134. ```
  1135. - Windows:
  1136. ```powershell
  1137. dir C:\absolute\path\to\p4-mcp-server.exe
  1138. ```
  1139. 3. **On Windows, ensure the binary is not blocked:**
  1140. - Right-click the `.exe` file, select **Properties**, and if present, click **Unblock**.
  1141. </details>
  1142. ### Connection Issues
  1143. <details>
  1144. <summary><strong>Connect to server failed; check $P4PORT</strong></summary>
  1145. **Symptoms**: Cannot connect to P4 Server
  1146. **Solutions**:
  1147. 1. Verify the `P4PORT` environment variable: `echo $P4PORT` (macOS) or `echo $env:P4PORT` (Windows)
  1148. 2. Test the direct connection: `p4 info`
  1149. 3. Check server availability: `ping perforce.example.com`
  1150. 4. Verify the port and protocol (`ssl:` prefix for SSL connections).
  1151. </details>
  1152. <details>
  1153. <summary><strong>SSL certificate not trusted (P4 connection)</strong></summary>
  1154. **Symptoms**: SSL trust errors when connecting to the P4 server
  1155. **Solutions**:
  1156. 1. Trust the server: `p4 trust -f -y`
  1157. 2. Check trust status: `p4 trust -l`
  1158. 3. For persistent issues, verify the SSL configuration.
  1159. </details>
  1160. <details>
  1161. <summary><strong>SSL certificate errors for P4 Code Review API (reviews)</strong></summary>
  1162. **Symptoms**: `CERTIFICATE_VERIFY_FAILED` errors when using review tools
  1163. **Solutions**:
  1164. 1. **System trust store**: By default, the server uses the OS trust store via `truststore`. Ensure your corporate CA is installed in the OS certificate store.
  1165. 2. **Custom CA bundle**: To use a custom CA certificate, you must **first** set `P4MCP_TLS_CA_MODE=certifi` (to disable `truststore`), then provide the CA path via `--ca-bundle /path/to/ca.pem` or `P4MCP_CA_BUNDLE`. In the default `system` mode, `truststore` overrides custom CA bundles and they are silently ignored.
  1166. 3. **Disable verification**: Use `--ssl-no-verify` or set `P4MCP_SSL_VERIFY=false` (not recommended for production). This works in both TLS modes.
  1167. > **Note:** These SSL settings only apply when the Swarm URL uses HTTPS. If Swarm is configured with an `http://` URL, SSL verification is not performed and these settings have no effect.
  1168. </details>
  1169. ### Authentication Problems
  1170. <details>
  1171. <summary><strong>User not logged in</strong></summary>
  1172. **Symptoms**: Authentication failures
  1173. **Solutions**:
  1174. 1. Log in to P4: `p4 login -a`
  1175. 2. Check login status: `p4 login -s`
  1176. 3. Verify the user exists: `p4 users -m 1 your_username`
  1177. 4. For persistent issues, check password or use ticket-based authentication.
  1178. </details>
  1179. <details>
  1180. <summary><strong>Password invalid</strong></summary>
  1181. **Symptoms**: Login failures
  1182. **Solutions**:
  1183. 1. Reset the password through a P4 administrator.
  1184. 2. Use ticket-based authentication: `p4 login -a`
  1185. 3. Verify the username is correct: `p4 info`
  1186. </details>
  1187. ### Workspace Issues
  1188. <details>
  1189. <summary><strong>Client unknown</strong></summary>
  1190. **Symptoms**: Workspace not found errors
  1191. **Solutions**:
  1192. 1. List the available workspaces: `p4 clients`
  1193. 2. Verify the `P4CLIENT` environment variable.
  1194. 3. Create a workspace if needed: `p4 client workspace_name`
  1195. 4. Check the workspace ownership: `p4 client -o workspace_name`
  1196. </details>
  1197. <details>
  1198. <summary><strong>File(s) not in client view</strong></summary>
  1199. **Symptoms**: Files are outside the workspace mapping
  1200. **Solutions**:
  1201. 1. Check the client view: `p4 client -o workspace_name`
  1202. 2. Update the workspace mapping to include the required paths.
  1203. 3. Use `p4 where file_path` to check the mapping.
  1204. </details>
  1205. ### Permission Errors
  1206. <details>
  1207. <summary><strong>Operation not permitted</strong></summary>
  1208. **Symptoms**: Insufficient permissions for operations
  1209. **Solutions**:
  1210. 1. Check the file ownership: `p4 opened file_path`
  1211. 2. Verify the user permissions: `p4 protects file_path`
  1212. 3. Ensure proper group membership.
  1213. 4. For admin operations, verify admin permissions.
  1214. </details>
  1215. <details>
  1216. <summary><strong>File is opened by another user</strong></summary>
  1217. **Symptoms**: Exclusive lock conflicts
  1218. **Solutions**:
  1219. 1. Check who has the file open: `p4 opened file_path`
  1220. 2. Contact the user to resolve conflicts.
  1221. 3. Admin can force operations if necessary.
  1222. </details>
  1223. ### Performance Issues
  1224. <details>
  1225. <summary><strong>Slow operations</strong></summary>
  1226. **Symptoms**: Long response times
  1227. **Solutions**:
  1228. 1. Use the `max_results` parameter to limit the query size.
  1229. 2. Use specific file paths instead of wildcards.
  1230. 3. Check network connectivity to P4.
  1231. 4. Monitor server performance.
  1232. </details>
  1233. <details>
  1234. <summary><strong>Memory issues</strong></summary>
  1235. **Symptoms**: High memory usage
  1236. **Solutions**:
  1237. 1. Reduce `max_results` for large queries.
  1238. 2. Process files in batches.
  1239. 3. Restart the MCP server periodically for long-running sessions.
  1240. </details>
  1241. ### Tool Execution
  1242. <details>
  1243. <summary><strong>Unable to execute tools</strong></summary>
  1244. **Symptoms**: Conflict with built-in or other MCP tools
  1245. <br>**Solutions**:
  1246. 1. Disable any built-in or conflicting MCP server tools in your environment or configuration.
  1247. 2. Ensure the P4 MCP server tools are properly registered and enabled.
  1248. 3. Restart the MCP server after applying configuration changes to load the correct tools.
  1249. </details>
  1250. <details>
  1251. <summary><strong>Correct tools not picked up</strong></summary>
  1252. **Symptoms**: Invalid context or outdated session history
  1253. <br>**Solutions**:
  1254. 1. Provide a P4-related context when writing prompts.
  1255. 2. Start a new session if the existing session is old or contains conflicting prompt history.
  1256. </details>
  1257. ### Common Error Patterns
  1258. 1. **Authentication**: Ensure valid login before MCP operations.
  1259. 2. **Workspace mapping**: Verify client views include target files.
  1260. 3. **Permissions**: Check user and file permissions for write operations.
  1261. 4. **Network**: Verify connectivity for remote P4 Servers.
  1262. ### Getting Help
  1263. 1. **Check the logs**: Always check `logs/p4mcp.log` first.
  1264. 2. **Test P4**: Ensure `p4 info` works before troubleshooting MCP.
  1265. 3. **Report issues to the community**: Report issues with log excerpts and environment details.
  1266. ## Support
  1267. Perforce P4 MCP Server is a community supported project and is not officially supported by Perforce.
  1268. Pull 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.
  1269. All issues should be reported and managed via GitHub (not via Perforce's standard support process).
  1270. ## Contributions
  1271. We welcome contributions to the P4 MCP Server project.
  1272. ## License
  1273. This project is licensed under the MIT License. See [LICENSE](LICENSE.txt) for details.
  1274. ### Third-Party Notices
  1275. This project includes third-party components. Their licenses and attributions are listed in [THIRD-PARTY-NOTICES](THIRD-PARTY-NOTICES.txt).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.