From 2a19db163c5e4b74c108b114788b6b81c023a65f Mon Sep 17 00:00:00 2001 From: CD Cabrera Date: Tue, 28 Apr 2026 20:59:59 -0400 Subject: [PATCH 1/6] docs: troubleshooting steps, rename examples * docs, troubleshooting steps, rename mcp server examples * github, refine issue templates --- .github/ISSUE_TEMPLATE.md | 2 +- .github/ISSUE_TEMPLATE/bug_report.md | 2 +- .github/PULL_REQUEST_TEMPLATE.md | 13 ++++- README.md | 29 +++++++--- cspell.config.json | 1 + docs/development.md | 38 +++++++++---- docs/examples/toolPluginGitStatus.js | 2 +- docs/examples/toolPluginHelloWorld.js | 2 +- docs/usage.md | 81 ++++++++++++++++++++++++--- mcp-config-example.json | 6 +- 10 files changed, 139 insertions(+), 37 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 81e8d163..76095571 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -11,5 +11,5 @@ ### Assumptions and questions, context, version information - + ... diff --git a/.github/ISSUE_TEMPLATE/bug_report.md b/.github/ISSUE_TEMPLATE/bug_report.md index 53e66cbf..62e253c7 100644 --- a/.github/ISSUE_TEMPLATE/bug_report.md +++ b/.github/ISSUE_TEMPLATE/bug_report.md @@ -19,5 +19,5 @@ about: Create a report to help us improve ### Additional context, version info - + ... diff --git a/.github/PULL_REQUEST_TEMPLATE.md b/.github/PULL_REQUEST_TEMPLATE.md index 4407d8ca..c5757246 100644 --- a/.github/PULL_REQUEST_TEMPLATE.md +++ b/.github/PULL_REQUEST_TEMPLATE.md @@ -23,18 +23,25 @@ PR tips 1. `> [test prompt]` --> + diff --git a/README.md b/README.md index c990a1e0..0d362a4e 100644 --- a/README.md +++ b/README.md @@ -22,7 +22,7 @@ Minimal configuration ```json { "mcpServers": { - "patternfly-docs": { + "patternfly-mcp": { "command": "npx", "args": ["-y", "@patternfly/patternfly-mcp@latest"], "description": "PatternFly rules and documentation" @@ -35,10 +35,10 @@ HTTP transport mode ```json { "mcpServers": { - "patternfly-docs": { + "patternfly-mcp": { "command": "npx", "args": ["-y", "@patternfly/patternfly-mcp@latest", "--http", "--port", "8080"], - "description": "PatternFly docs (HTTP transport)" + "description": "PatternFly rules and documentation (HTTP transport)" } } } @@ -48,8 +48,8 @@ HTTP transport mode ### For development, advanced usage -#### Run the server directly -Run the server immediately via `npx`: +#### Run the latest released server +Run the latest published package immediately via `npx`: ```bash npx -y @patternfly/patternfly-mcp @@ -61,11 +61,24 @@ Or with options npx -y @patternfly/patternfly-mcp --log-stderr --verbose ``` +#### Run a locally built server +```bash +# clone the repo, change the directory, npm install, npm run build, then in the repo context run... +npm start +``` + #### Inspect the server -Visualize and test the MCP interface: +Visualize and test the packaged MCP interface: + +```bash +npx -y @modelcontextprotocol/inspector npx -y @patternfly/patternfly-mcp +``` + +Build from source and test a local built MCP interface: ```bash -npx -y @modelcontextprotocol/inspector npx @patternfly/patternfly-mcp +# clone the repo, change the directory, npm install, npm run build, then in the repo context run... +npx -y @modelcontextprotocol/inspector node dist/cli.js ``` #### Embed the server in your application @@ -94,7 +107,7 @@ main(); For comprehensive usage, development, and project state [read the docs](./docs/README.md). - **Architecture**: Learn about our [hybrid documentation concept and data sources](./docs/architecture.md#data-sources-and-integrations). -- **Usage**: Detailed guide on [built-in tools and resources](./docs/usage.md). +- **Usage**: Detailed guide on [built-in tools, resources, and troubleshooting for general use](./docs/usage.md). - **Development**: Reference for [CLI options and tool plugins](./docs/development.md). ## Contributing diff --git a/cspell.config.json b/cspell.config.json index a98db4fc..bc46682e 100644 --- a/cspell.config.json +++ b/cspell.config.json @@ -5,6 +5,7 @@ "codemods", "ized", "llms", + "localappdata", "midrun", "modelcontextprotocol", "nosniff", diff --git a/docs/development.md b/docs/development.md index 045cd0f8..fe7c82de 100644 --- a/docs/development.md +++ b/docs/development.md @@ -41,43 +41,57 @@ Complete guide to using the PatternFly MCP Server for development including CLI **stdio mode (default):** ```bash -npx @patternfly/patternfly-mcp +npx -y @patternfly/patternfly-mcp +``` + +**stdio mode with terminal logging:** +```bash +npx -y @patternfly/patternfly-mcp --log-stderr ``` **HTTP mode:** ```bash -npx @patternfly/patternfly-mcp --http --port 8080 +npx -y @patternfly/patternfly-mcp --http --port 8080 ``` **HTTP mode with custom security**: ```bash -npx @patternfly/patternfly-mcp --http --port 3000 --allowed-origins "https://app.com" +npx -y @patternfly/patternfly-mcp --http --port 3000 --allowed-origins "https://app.com" ``` **Loading external tool plugins**: ```bash -npx @patternfly/patternfly-mcp --tool ./first-tool.js --tool ./second-tool.ts +npx -y @patternfly/patternfly-mcp --tool ./first-tool.js --tool ./second-tool.ts ``` + **Testing with a fixture server**: ```bash -npx @patternfly/patternfly-mcp --mode test --mode-test-url "http://localhost:3000" +npx -y @patternfly/patternfly-mcp --mode test --mode-test-url "http://localhost:3000" ``` ### Testing with MCP Inspector The `@modelcontextprotocol/inspector` is the recommended way to visualize the server's interface. -1. **Start the Inspector**: +1. **Build the PatternFly MCP**: ```bash - npx -y @modelcontextprotocol/inspector npx @patternfly/patternfly-mcp + npm install + npm run build ``` -2. **Interact**: The inspector opens a web interface (typically at `http://localhost:5173`) where you can list tools, execute them, and view resource contents. +2. **Start the Inspector**: + ```bash + npx -y @modelcontextprotocol/inspector node dist/cli.js + ``` +3. **Interact**: The inspector opens a web interface (typically at `http://localhost:5173`) where you can list tools, resources, and prompts, then execute and view their responses. + +#### Use the MCP Inspector with configuration + +If you use `@modelcontextprotocol/inspector-cli` with an MCP client config file, set `--server` to the server key in that file. For example, use `patternfly-mcp` when it matches `mcp-config-example.json`. -**Example with repository context:** ```bash -npx @modelcontextprotocol/inspector-cli \ - --config ./mcp-config.json \ - --server patternfly-docs \ +npx -y @modelcontextprotocol/inspector-cli \ + --config ./mcp-config-example.json \ + --server patternfly-mcp \ --cli \ --method tools/call \ --tool-name usePatternFlyDocs \ diff --git a/docs/examples/toolPluginGitStatus.js b/docs/examples/toolPluginGitStatus.js index 32c2b909..081bce83 100644 --- a/docs/examples/toolPluginGitStatus.js +++ b/docs/examples/toolPluginGitStatus.js @@ -3,7 +3,7 @@ * * To load this tool into the PatternFly MCP server: * 1. Save this file (e.g., `toolPluginGitStatus.js`) - * 2. Run the server with: `npx @patternfly/patternfly-mcp --tool /toolPluginGitStatus.js --plugin-isolation "none"` + * 2. Run the server with: `npx -y @patternfly/patternfly-mcp --tool /toolPluginGitStatus.js --plugin-isolation "none"` * * Note: * - External tool file loading requires Node.js >= 22. diff --git a/docs/examples/toolPluginHelloWorld.js b/docs/examples/toolPluginHelloWorld.js index 11a0b17f..9d9c7cf2 100644 --- a/docs/examples/toolPluginHelloWorld.js +++ b/docs/examples/toolPluginHelloWorld.js @@ -3,7 +3,7 @@ * * To load this tool into the PatternFly MCP server: * 1. Save this file (e.g., `toolPluginHelloWorld.js`) - * 2. Run the server with: `npx @patternfly/patternfly-mcp --tool /toolPluginHelloWorld.js` + * 2. Run the server with: `npx -y @patternfly/patternfly-mcp --tool /toolPluginHelloWorld.js` * * Note: * - External tool file loading requires Node.js >= 22. diff --git a/docs/usage.md b/docs/usage.md index e866e00d..bc2bd8e2 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -7,6 +7,7 @@ A comprehensive guide to PatternFly MCP Server tools, resources, and configurati - [Built-in resources](#built-in-resources) - [MCP client configuration](#mcp-client-configuration) - [Custom MCP tool plugins](#custom-mcp-tool-plugins) +- [Troubleshooting](#troubleshooting) ## Built-in tools @@ -101,10 +102,10 @@ Most MCP clients use JSON configuration to specify how the server is started. Be ```json { "mcpServers": { - "patternfly-docs": { + "patternfly-mcp": { "command": "npx", "args": ["-y", "@patternfly/patternfly-mcp@latest"], - "description": "PatternFly React development rules and documentation" + "description": "PatternFly rules and documentation" } } } @@ -115,10 +116,10 @@ Most MCP clients use JSON configuration to specify how the server is started. Be ```json { "mcpServers": { - "patternfly-docs": { + "patternfly-mcp": { "command": "npx", "args": ["-y", "@patternfly/patternfly-mcp@latest", "--http", "--port", "8080"], - "description": "PatternFly docs (HTTP transport)" + "description": "PatternFly rules and documentation (HTTP transport)" } } } @@ -129,7 +130,7 @@ Most MCP clients use JSON configuration to specify how the server is started. Be ```json { "mcpServers": { - "patternfly-docs": { + "patternfly-mcp": { "command": "npx", "args": [ "-y", @@ -148,7 +149,7 @@ Most MCP clients use JSON configuration to specify how the server is started. Be ```json { "mcpServers": { - "patternfly-docs": { + "patternfly-mcp": { "command": "npx", "args": [ "-y", @@ -161,7 +162,7 @@ Most MCP clients use JSON configuration to specify how the server is started. Be "--allowed-hosts", "localhost,127.0.0.1" ], - "description": "PatternFly docs (HTTP transport with security)" + "description": "PatternFly rules and documentation (HTTP transport with security)" } } } @@ -172,3 +173,69 @@ Most MCP clients use JSON configuration to specify how the server is started. Be You can extend the server's capabilities by loading custom **Tool Plugins** at startup. [See development documentation for tool plugins.](./development.md#mcp-tool-plugins) + +## Troubleshooting + +This guide is designed to help resolve common environment-related issues across macOS, Linux, and Windows. + +> **Note on Operating Systems**: Our primary development and testing environments are **macOS and Linux**. While we provide instructions for **Windows**, these commands are run at your own discretion. If you are unsure, please verify them with your IT or system administrator before proceeding. + +### 1. Verify Node.js Version +The PatternFly MCP server requires **Node.js 20 or higher**. + +- **How to check**: + - **macOS/Linux**: Open **Terminal** and type `node -v`. + - **Windows**: Open **PowerShell** or **Command Prompt** and type `node -v`. +- **Requirement**: You should see a version starting with `v20`, `v22`, or higher. +- **Solution**: If your version is lower than 20, please download and install the latest "LTS" (Long Term Support) version from [nodejs.org](https://nodejs.org/). + +### 2. Reset the npx Cache +If you encounter an `ERR_MODULE_NOT_FOUND` error or don't see the latest features, your system may be using a "stale" or corrupted version in its cache. + +#### **macOS and Linux** +Run this command in your **Terminal**: +```bash +rm -rf ~/.npm/_npx +``` + +#### **Windows** +Run the appropriate command for your terminal: +- **PowerShell**: + ```powershell + Remove-Item -Recurse -Force "$env:LOCALAPPDATA\npm-cache\_npx" + ``` +- **Command Prompt (CMD)**: + ```cmd + rd /s /q "%LocalAppData%\npm-cache\_npx" + ``` + +**Next Step**: Restart your MCP client (e.g., Claude Desktop, IDE, or Cursor) to force a fresh download. + +### 3. Windows-Specific: Symbolic Links +If you are developing locally or have cloned the repository on Windows, you may encounter issues with "missing" files in `.agents/skills` and `.claude/skills`. This is often due to Git not creating symbolic links correctly on Windows. + +- **The Fix**: Enable **Developer Mode** in Windows Settings (Privacy & security → For developers). +- **Git Config**: Run `git config --global core.symlinks true` and then re-clone the repository or run `git checkout .` to restore the links. + +### 4. Configuration Best Practices +To ensure you stay up to date with the latest PatternFly documentation, use the `@latest` tag in your configuration: + +```json +"patternfly-mcp": { + "command": "npx", + "args": ["-y", "@patternfly/patternfly-mcp@latest"], + "description": "PatternFly rules and documentation" +} +``` + +> Using `@latest` in the configuration means installs resolve to the "latest" published version when npm/npx fetches the package, typically on a new `npx` run. + +### 5. Common Error: `ERR_MODULE_NOT_FOUND` +If your logs show `Error [ERR_MODULE_NOT_FOUND]`, it likely indicates a corrupted cache following a PatternFly MCP version update. Please follow the [Reset the npx Cache](#2-reset-the-npx-cache) steps above for your specific operating system. + +### 6. Community Support +If you have tried the steps above and are still encountering issues, or if you have specific questions about using PatternFly with your AI assistant, the following community resources are available: + +- **[PatternFly Slack](https://patternfly.slack.com/)**: Join our Slack community for real-time support and conversation. +- **[GitHub Discussions](https://github.com/orgs/patternfly/discussions)**: A great place to ask questions, share ideas, and see how others are leveraging PatternFly. +- **[PatternFly on Medium](https://medium.com/patternfly)**: Read articles and deep-dives into PatternFly design and development practices. diff --git a/mcp-config-example.json b/mcp-config-example.json index 09465c06..14c90855 100644 --- a/mcp-config-example.json +++ b/mcp-config-example.json @@ -1,9 +1,9 @@ { "mcpServers": { - "patternfly-docs": { + "patternfly-mcp": { "command": "npx", - "args": ["@patternfly/patternfly-mcp"], - "description": "PatternFly development rules and documentation" + "args": ["-y","@patternfly/patternfly-mcp@latest"], + "description": "PatternFly rules and documentation" } } } From eee30e93b24018394726a68796705f5b01b58b83 Mon Sep 17 00:00:00 2001 From: CD Cabrera Date: Thu, 30 Apr 2026 15:03:09 -0400 Subject: [PATCH 2/6] fix: review update --- README.md | 6 +++--- docs/development.md | 12 ++++++------ docs/examples/toolPluginGitStatus.js | 2 +- docs/examples/toolPluginHelloWorld.js | 2 +- 4 files changed, 11 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index 0d362a4e..0a7aeeba 100644 --- a/README.md +++ b/README.md @@ -52,13 +52,13 @@ HTTP transport mode Run the latest published package immediately via `npx`: ```bash -npx -y @patternfly/patternfly-mcp +npx -y @patternfly/patternfly-mcp@latest ``` Or with options ```bash -npx -y @patternfly/patternfly-mcp --log-stderr --verbose +npx -y @patternfly/patternfly-mcp@latest --log-stderr --verbose ``` #### Run a locally built server @@ -71,7 +71,7 @@ npm start Visualize and test the packaged MCP interface: ```bash -npx -y @modelcontextprotocol/inspector npx -y @patternfly/patternfly-mcp +npx -y @modelcontextprotocol/inspector npx -y @patternfly/patternfly-mcp@latest ``` Build from source and test a local built MCP interface: diff --git a/docs/development.md b/docs/development.md index fe7c82de..2ec5ed69 100644 --- a/docs/development.md +++ b/docs/development.md @@ -41,32 +41,32 @@ Complete guide to using the PatternFly MCP Server for development including CLI **stdio mode (default):** ```bash -npx -y @patternfly/patternfly-mcp +npx -y @patternfly/patternfly-mcp@latest ``` **stdio mode with terminal logging:** ```bash -npx -y @patternfly/patternfly-mcp --log-stderr +npx -y @patternfly/patternfly-mcp@latest --log-stderr ``` **HTTP mode:** ```bash -npx -y @patternfly/patternfly-mcp --http --port 8080 +npx -y @patternfly/patternfly-mcp@latest --http --port 8080 ``` **HTTP mode with custom security**: ```bash -npx -y @patternfly/patternfly-mcp --http --port 3000 --allowed-origins "https://app.com" +npx -y @patternfly/patternfly-mcp@latest --http --port 3000 --allowed-origins "https://app.com" ``` **Loading external tool plugins**: ```bash -npx -y @patternfly/patternfly-mcp --tool ./first-tool.js --tool ./second-tool.ts +npx -y @patternfly/patternfly-mcp@latest --tool ./first-tool.js --tool ./second-tool.ts ``` **Testing with a fixture server**: ```bash -npx -y @patternfly/patternfly-mcp --mode test --mode-test-url "http://localhost:3000" +npx -y @patternfly/patternfly-mcp@latest --mode test --mode-test-url "http://localhost:3000" ``` ### Testing with MCP Inspector diff --git a/docs/examples/toolPluginGitStatus.js b/docs/examples/toolPluginGitStatus.js index 081bce83..879326c3 100644 --- a/docs/examples/toolPluginGitStatus.js +++ b/docs/examples/toolPluginGitStatus.js @@ -3,7 +3,7 @@ * * To load this tool into the PatternFly MCP server: * 1. Save this file (e.g., `toolPluginGitStatus.js`) - * 2. Run the server with: `npx -y @patternfly/patternfly-mcp --tool /toolPluginGitStatus.js --plugin-isolation "none"` + * 2. Run the server with: `npx -y @patternfly/patternfly-mcp@latest --tool /toolPluginGitStatus.js --plugin-isolation "none"` * * Note: * - External tool file loading requires Node.js >= 22. diff --git a/docs/examples/toolPluginHelloWorld.js b/docs/examples/toolPluginHelloWorld.js index 9d9c7cf2..9738a454 100644 --- a/docs/examples/toolPluginHelloWorld.js +++ b/docs/examples/toolPluginHelloWorld.js @@ -3,7 +3,7 @@ * * To load this tool into the PatternFly MCP server: * 1. Save this file (e.g., `toolPluginHelloWorld.js`) - * 2. Run the server with: `npx -y @patternfly/patternfly-mcp --tool /toolPluginHelloWorld.js` + * 2. Run the server with: `npx -y @patternfly/patternfly-mcp@latest --tool /toolPluginHelloWorld.js` * * Note: * - External tool file loading requires Node.js >= 22. From ce6de72c86cbbe85743193e9f776f8de47c30494 Mon Sep 17 00:00:00 2001 From: CD Cabrera Date: Thu, 30 Apr 2026 15:19:39 -0400 Subject: [PATCH 3/6] fix: review update --- CONTRIBUTING.md | 5 +++-- docs/usage.md | 5 ++--- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 6c93899b..43cdce2c 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,8 +27,9 @@ your contribution is aligned with the project's goals. The repo uses **symlinks** so agent tools can find shared skills (for example `.agents/skills` and `.claude/skills` point at `guidelines/skills`). On **Windows**, a plain clone can leave those as plain files instead of links, which breaks that layout. -- Prefer **Developer Mode** (Settings → Privacy & security → For developers) so Git can create symlinks without running as Administrator, **or** clone with symlink support enabled (for example `git clone -c core.symlinks=true …`). -- If symlinks were not created, enable `core.symlinks` and re-check out the affected paths, or work from **WSL** / **Git for Windows** with symlink support configured. +- **The Fix**: Enable **Developer Mode** in Windows Settings (Privacy & security → For developers) so Git can create symlinks without running as Administrator. +- **Git Config**: Run `git config --global core.symlinks true` and then re-clone the repository or run `git checkout .` to restore the links. +- **Alternative**: Work from **WSL** or **Git for Windows** with symlink support configured (e.g., `git clone -c core.symlinks=true ...`). #### Development workflow - Make changes to the codebase diff --git a/docs/usage.md b/docs/usage.md index bc2bd8e2..cdb64ef3 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -212,10 +212,9 @@ Run the appropriate command for your terminal: **Next Step**: Restart your MCP client (e.g., Claude Desktop, IDE, or Cursor) to force a fresh download. ### 3. Windows-Specific: Symbolic Links -If you are developing locally or have cloned the repository on Windows, you may encounter issues with "missing" files in `.agents/skills` and `.claude/skills`. This is often due to Git not creating symbolic links correctly on Windows. +If you are developing locally or have cloned the repository on Windows, you may encounter issues with "missing" files in `.agents/skills` and `.claude/skills`. This is typically due to how Windows handles symbolic links. -- **The Fix**: Enable **Developer Mode** in Windows Settings (Privacy & security → For developers). -- **Git Config**: Run `git config --global core.symlinks true` and then re-clone the repository or run `git checkout .` to restore the links. +For detailed instructions on enabling and restoring symlinks, please refer to the **[Windows and repository symlinks section in CONTRIBUTING.md](../CONTRIBUTING.md#windows-and-repository-symlinks)**. ### 4. Configuration Best Practices To ensure you stay up to date with the latest PatternFly documentation, use the `@latest` tag in your configuration: From aaaa217286bdf4a6a526cae2d2602276a755609b Mon Sep 17 00:00:00 2001 From: CD Cabrera Date: Thu, 30 Apr 2026 15:25:28 -0400 Subject: [PATCH 4/6] fix: review update --- CONTRIBUTING.md | 7 +++---- docs/usage.md | 2 +- 2 files changed, 4 insertions(+), 5 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 43cdce2c..b5573395 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,11 +25,10 @@ your contribution is aligned with the project's goals. ##### Windows and repository symlinks -The repo uses **symlinks** so agent tools can find shared skills (for example `.agents/skills` and `.claude/skills` point at `guidelines/skills`). On **Windows**, a plain clone can leave those as plain files instead of links, which breaks that layout. +The repo uses **symlinks** so agent tools can find shared skills (for example `.agents/skills` and `.claude/skills` point at `guidelines/skills`). On **Windows**, Git can check out those paths as plain files instead of links, which breaks that layout. -- **The Fix**: Enable **Developer Mode** in Windows Settings (Privacy & security → For developers) so Git can create symlinks without running as Administrator. -- **Git Config**: Run `git config --global core.symlinks true` and then re-clone the repository or run `git checkout .` to restore the links. -- **Alternative**: Work from **WSL** or **Git for Windows** with symlink support configured (e.g., `git clone -c core.symlinks=true ...`). +- Prefer **Developer Mode** (Settings → Privacy & security → For developers) so Git can create symlinks without running as Administrator, **or** clone with symlink support enabled (for example `git clone -c core.symlinks=true …`). +- If symlinks were not created, enable `core.symlinks` and re-check out the affected paths, or work from **WSL** / **Git for Windows** with symlink support configured. #### Development workflow - Make changes to the codebase diff --git a/docs/usage.md b/docs/usage.md index cdb64ef3..0242566c 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -212,7 +212,7 @@ Run the appropriate command for your terminal: **Next Step**: Restart your MCP client (e.g., Claude Desktop, IDE, or Cursor) to force a fresh download. ### 3. Windows-Specific: Symbolic Links -If you are developing locally or have cloned the repository on Windows, you may encounter issues with "missing" files in `.agents/skills` and `.claude/skills`. This is typically due to how Windows handles symbolic links. +If you are developing locally or have cloned the repository on Windows, you may encounter issues with "missing" files in `.agents/skills` and `.claude/skills`. That usually means **Git** checked out symlinked paths as plain files instead of links—for example when symlink creation is restricted until Developer Mode is on or `core.symlinks` is set. For detailed instructions on enabling and restoring symlinks, please refer to the **[Windows and repository symlinks section in CONTRIBUTING.md](../CONTRIBUTING.md#windows-and-repository-symlinks)**. From 53ae8a903a39451444f72b85ec35cba9b43e4961 Mon Sep 17 00:00:00 2001 From: CD Cabrera Date: Thu, 30 Apr 2026 15:54:46 -0400 Subject: [PATCH 5/6] fix: review update --- CONTRIBUTING.md | 16 ++++++++++++++-- docs/usage.md | 4 ++-- 2 files changed, 16 insertions(+), 4 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index b5573395..5383ba14 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -27,8 +27,20 @@ your contribution is aligned with the project's goals. The repo uses **symlinks** so agent tools can find shared skills (for example `.agents/skills` and `.claude/skills` point at `guidelines/skills`). On **Windows**, Git can check out those paths as plain files instead of links, which breaks that layout. -- Prefer **Developer Mode** (Settings → Privacy & security → For developers) so Git can create symlinks without running as Administrator, **or** clone with symlink support enabled (for example `git clone -c core.symlinks=true …`). -- If symlinks were not created, enable `core.symlinks` and re-check out the affected paths, or work from **WSL** / **Git for Windows** with symlink support configured. +Some paths in this repo are **symbolic links** so tools can reach shared skills without needing to host multiple versions of the same files. For example, `.agents/skills` and `.claude/skills` point at `guidelines/skills`. On **Windows**, Git may create **regular folders or files** instead of links, so these locations can look empty or broken. + +**Before you clone the repository** + +- Turn on **Developer Mode** (Settings → Privacy & security → For developers). That usually lets Git create symlinks without running as Administrator. +- Prefer cloning with links enabled, for example: `git clone -c core.symlinks=true `, or use **WSL** / **Git for Windows** with symlink support configured. + +**If the repo is already on disk and the links are broken** + +Turning on Developer Mode or Git symlink settings **does not always fix** paths Git has already created as ordinary files. +- Delete the broken `.agents/skills` and `.claude/skills` entries, or remove the entire folder/directory and **clone again** +- Then follow the above steps for `"Before you clone the repository"` + +> If you are unsure of any steps, please verify them with your IT or system administrator before proceeding. #### Development workflow - Make changes to the codebase diff --git a/docs/usage.md b/docs/usage.md index 0242566c..25ab802c 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -176,7 +176,7 @@ You can extend the server's capabilities by loading custom **Tool Plugins** at s ## Troubleshooting -This guide is designed to help resolve common environment-related issues across macOS, Linux, and Windows. +These are **first-step checks** for common setup problems, not full diagnostics. If something still fails, use the community links at the end of this section or ask your IT team, especially on **Windows**, where permissions, security software, and Git setup vary and may be beyond simple troubleshooting. > **Note on Operating Systems**: Our primary development and testing environments are **macOS and Linux**. While we provide instructions for **Windows**, these commands are run at your own discretion. If you are unsure, please verify them with your IT or system administrator before proceeding. @@ -212,7 +212,7 @@ Run the appropriate command for your terminal: **Next Step**: Restart your MCP client (e.g., Claude Desktop, IDE, or Cursor) to force a fresh download. ### 3. Windows-Specific: Symbolic Links -If you are developing locally or have cloned the repository on Windows, you may encounter issues with "missing" files in `.agents/skills` and `.claude/skills`. That usually means **Git** checked out symlinked paths as plain files instead of links—for example when symlink creation is restricted until Developer Mode is on or `core.symlinks` is set. +On Windows, folders such as `.agents/skills` and `.claude/skills` can look empty if **Git** created them as normal folders instead of **links** to `guidelines/skills`. This often happens because Developer Mode, or Git symlink support, hasn't been enabled. For detailed instructions on enabling and restoring symlinks, please refer to the **[Windows and repository symlinks section in CONTRIBUTING.md](../CONTRIBUTING.md#windows-and-repository-symlinks)**. From 604d05a507c4aa239f9dbfa76c2d39cd1735a875 Mon Sep 17 00:00:00 2001 From: CD Cabrera Date: Thu, 30 Apr 2026 16:10:53 -0400 Subject: [PATCH 6/6] fix: review update --- CONTRIBUTING.md | 8 +++----- mcp-config-example.json | 2 +- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 5383ba14..29f479a1 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -25,20 +25,18 @@ your contribution is aligned with the project's goals. ##### Windows and repository symlinks -The repo uses **symlinks** so agent tools can find shared skills (for example `.agents/skills` and `.claude/skills` point at `guidelines/skills`). On **Windows**, Git can check out those paths as plain files instead of links, which breaks that layout. - Some paths in this repo are **symbolic links** so tools can reach shared skills without needing to host multiple versions of the same files. For example, `.agents/skills` and `.claude/skills` point at `guidelines/skills`. On **Windows**, Git may create **regular folders or files** instead of links, so these locations can look empty or broken. -**Before you clone the repository** +**Before you clone the repository** -- Turn on **Developer Mode** (Settings → Privacy & security → For developers). That usually lets Git create symlinks without running as Administrator. +- Turn on **Developer Mode** (Settings -> Privacy & security -> For developers). That usually lets Git create symlinks without running as Administrator. - Prefer cloning with links enabled, for example: `git clone -c core.symlinks=true `, or use **WSL** / **Git for Windows** with symlink support configured. **If the repo is already on disk and the links are broken** Turning on Developer Mode or Git symlink settings **does not always fix** paths Git has already created as ordinary files. - Delete the broken `.agents/skills` and `.claude/skills` entries, or remove the entire folder/directory and **clone again** -- Then follow the above steps for `"Before you clone the repository"` +- Then follow the **Before you clone the repository** steps above > If you are unsure of any steps, please verify them with your IT or system administrator before proceeding. diff --git a/mcp-config-example.json b/mcp-config-example.json index 14c90855..ea466d99 100644 --- a/mcp-config-example.json +++ b/mcp-config-example.json @@ -2,7 +2,7 @@ "mcpServers": { "patternfly-mcp": { "command": "npx", - "args": ["-y","@patternfly/patternfly-mcp@latest"], + "args": ["-y", "@patternfly/patternfly-mcp@latest"], "description": "PatternFly rules and documentation" } }