docs: troubleshooting steps, rename examples

* docs, troubleshooting steps, rename mcp server examples
* github, refine issue templates

Author: cdcabrera

.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,6 +23,13 @@ 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. `$ npm test`

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,9 +48,11 @@ HTTP transport mode
 
 ### For development, advanced usage
 
-#### Run the server directly
+#### Run the latest released server
 Run the server immediately via `npx`:
 
+With the latest released package
+
 ```bash
 npx -y @patternfly/patternfly-mcp
 ```
@@ -61,13 +63,26 @@ Or with options
 npx -y @patternfly/patternfly-mcp --log-stderr --verbose
 ```
 
+#### Run a locally built server
+```bash
+# clone the repo, change directories, 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 @patternfly/patternfly-mcp
 ```
 
+Build from source and test a local built MCP interface:
+
+```bash
+# clone the repo, change directories, 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
 
 ```typescript
@@ -94,7 +109,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

@@ -67,22 +67,16 @@ npx @patternfly/patternfly-mcp --mode test --mode-test-url "http://localhost:300
 
 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.
-
-**Example with repository context:**
-```bash
-npx @modelcontextprotocol/inspector-cli \
-  --config ./mcp-config.json \
-  --server patternfly-docs \
-  --cli \
-  --method tools/call \
-  --tool-name usePatternFlyDocs \
-  --tool-arg name="Button"
-```
+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.
 
 ## Programmatic usage
 

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,7 +102,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", "@patternfly/patternfly-mcp@latest"],
       "description": "PatternFly React development rules and documentation"
@@ -115,7 +116,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", "@patternfly/patternfly-mcp@latest", "--http", "--port", "8080"],
       "description": "PatternFly docs (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",
@@ -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` tells the system to check for updates periodically, helping to ensure you are working with the most current PatternFly specifications.
+
+### 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"
+      "description": "PatternFly rules and documentation"
     }
   }
 }