diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 81e8d16..7609557 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 53e66cb..62e253c 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 4407d8c..c575724 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/CONTRIBUTING.md b/CONTRIBUTING.md index 6c93899..29f479a 100644 --- a/CONTRIBUTING.md +++ b/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 `, 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 diff --git a/README.md b/README.md index c990a1e..0a7aeeb 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,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 diff --git a/cspell.config.json b/cspell.config.json index a98db4f..bc46682 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 045cd0f..2ec5ed6 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@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 \ diff --git a/docs/examples/toolPluginGitStatus.js b/docs/examples/toolPluginGitStatus.js index 32c2b90..879326c 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@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 11a0b17..9738a45 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@latest --tool /toolPluginHelloWorld.js` * * Note: * - External tool file loading requires Node.js >= 22. diff --git a/docs/usage.md b/docs/usage.md index e866e00..25ab802 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,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. diff --git a/mcp-config-example.json b/mcp-config-example.json index 09465c0..ea466d9 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" } } }