docs: troubleshooting steps, examples

.github/ISSUE_TEMPLATE.md

@@ -11,5 +11,5 @@
 ### Assumptions and questions, context, version information
 <!-- Please do not post sensitive information, we are not liable. -->
 <!-- Append a sanitized log/demo/screenshot/animated GIF of the problem.  -->
-<!-- Package.json version, tag, or git commit information. -->
+<!-- PatternFly MCP version, Node.js version, tag or git commit information. -->
 ...

.github/ISSUE_TEMPLATE/bug_report.md

@@ -19,5 +19,5 @@ about: Create a report to help us improve
 ### Additional context, version info
 <!-- Please do not post sensitive information, we are not liable. -->
 <!-- Append a sanitized log/demo/screenshot/animated GIF of the problem.  -->
-<!-- Package.json version, tag, or git commit information. -->
+<!-- PatternFly MCP version, Node.js version, tag or git commit information. -->
 ...

.github/PULL_REQUEST_TEMPLATE.md

@@ -23,18 +23,25 @@ PR tips
 1. `> [test prompt]`
 -->
 <!--
+### Check the work
+1. Update the NPM packages with `$ npm install`
+1. `$ npm run build`
+1. `npx -y @modelcontextprotocol/inspector node dist/cli.js`
+1. next...
+-->
+<!--
 ### Unit test check
-1. update the NPM packages with `$ npm install`
+1. Update the NPM packages with `$ npm install`
 1. `$ npm test`
 -->
 <!--
 ### E2E test check
-1. update the NPM packages with `$ npm install`
+1. Update the NPM packages with `$ npm install`
 1. `$ npm run test:integration`
 -->
 <!--
 ### Check the build
-1. update the NPM packages with `$ npm install`
+1. Update the NPM packages with `$ npm install`
 1. `$ npm run build`
 1. next...
 -->

CONTRIBUTING.md

@@ -25,10 +25,20 @@ 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.
+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.
 
-- 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.
+**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 <repository-url>`, 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 **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.
 
 #### Development workflow
 - Make changes to the codebase

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,24 +48,37 @@ 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
+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
+```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@latest
+```
+
+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

cspell.config.json

@@ -5,6 +5,7 @@
     "codemods",
     "ized",
     "llms",
+    "localappdata",
     "midrun",
     "modelcontextprotocol",
     "nosniff",

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@latest
+```
+
+**stdio mode with terminal logging:**
+```bash
+npx -y @patternfly/patternfly-mcp@latest --log-stderr
 ```
 
 **HTTP mode:**
 ```bash
-npx @patternfly/patternfly-mcp --http --port 8080
+npx -y @patternfly/patternfly-mcp@latest --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@latest --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@latest --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@latest --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 \

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 <path-to-the-file>/toolPluginGitStatus.js --plugin-isolation "none"`
+ * 2. Run the server with: `npx -y @patternfly/patternfly-mcp@latest --tool <path-to-the-file>/toolPluginGitStatus.js --plugin-isolation "none"`
  *
  * Note:
  * - External tool file loading requires Node.js >= 22.

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 <path-to-the-file>/toolPluginHelloWorld.js`
+ * 2. Run the server with: `npx -y @patternfly/patternfly-mcp@latest --tool <path-to-the-file>/toolPluginHelloWorld.js`
  *
  * Note:
  * - External tool file loading requires Node.js >= 22.

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,68 @@ 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
+
+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.
+
+### 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
+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)**.
+
+### 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.

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"
     }
   }
 }