diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 7577346..38dc214 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -59,7 +59,7 @@ Development pull requests (PRs) should be opened against the default branch. > If your pull request work contains any of the following warning signs > - has no related issue > - ignores existing code style -> - out of sync commits (not rebased against the default branch) +> - out-of-sync commits (not rebased against the default branch) > - poorly structured commits and messages > - any one commit relies on other commits to work (beyond "review requested updates") > - dramatic file restructures that attempt complex behavior @@ -116,7 +116,7 @@ Basic code style guidelines are generally enforced by ESLint, but there are addi - Tests should focus on functionality. - Tests should not be written for external packages. That is the responsibility of the external package, or it shouldn't be used. -#### Typescript +#### TypeScript - Typings within the project may be generally loose for initial development but should be refined over time. - Typings exposed to consumers should always attempt to maintain consistency. - Typings for tests are less of a focus than functionality checks. @@ -142,9 +142,28 @@ npm run test:integration This mode leverages the `--mode test` and `--mode-test-url` flags to redirect resource lookups to a fixture server instead of live or local resources. +## Maintenance: Node.js engine bumps + +The `Node.js` engine requirements are updated on a predictable biannual schedule to ensure the server remains secure, leverages modern runtime features, and provides stability for consumers. + +> Our engine requirements are intended to be the minimum to run the MCP server. They are not intended to be a maximum, as newer versions may introduce breaking changes or require additional configuration. + +### Schedule and process +- **Timing**: Bumps are generally targeted for **Spring (April/May)** and **Fall (October/November)**, aligned with the [Node.js release schedule](https://nodejs.org/en/about/previous-releases) as versions enter or exit LTS. +- **Security**: Out-of-band updates may be performed if critical security considerations arise. +- **Version Targets**: + - Focus on the latest **even-numbered (LTS/Stable)** versions (e.g., bumping to 22, 24, or 26). + - GitHub Workflows should be updated to include the latest available even version. + +### Acceptance criteria for bumps +- Update `package.json` engine requirements. +- Update related GitHub Action workflows (CI/CD). +- Update "Environmental Requirements" in documentation. +- Ensure all tests pass on the new target version. + ## AI agent -### User Section +### User section Current agent interaction can be triggered with the chat command @@ -157,12 +176,12 @@ For detailed information on agent interaction, see [guidelines/README.md](./guid As developers, we often have our own preferred workflows, and that includes working with AI agents. To that point, we've added agent guidance to allow customization for your work environment through a tool-agnostic git-ignored directory `./.agent` in the root of the project. -#### Noting AI Agent contributions +#### Noting AI agent contributions Please reference [PatternFly's AI-assisted development guidelines](https://github.com/patternfly/.github/blob/main/CONTRIBUTING.md) for guidance on how to acknowledge AI agent contributions. -### Agent Only +### Agent only Agents: This repository contains a hierarchical guideline system. Agents should review agent-only comment blocks. F1A - F1B(["Built-In resources"]) + F1B <--> F1A + F1B(["Built-In resources & discovery layer"]) end end D1(["Server proxy"]) + D1 <--> F1 + subgraph G1["Child process host"] + G1A(["Tools host & isolation sandbox"]) + end + D1 <--> G1 end - B1(["Local external tools, prompts, resources"]) + B1(["Local and remote external tools, prompts, resources"]) B1 <--> D1 ``` @@ -67,19 +84,19 @@ flowchart TD ### Planned features and integrations -To get towards our future state, there are a series of planned features and integrations. +Our roadmap focuses on expanding the server's reach and providing a more integrated development experience. -Current focus: -- **YAML configuration for remote tools, resources and prompts** - YAML configuration for remote MCP tools, resources, and prompt plugins -- **MCP resource, prompts, and helper function sharing** - A way to share MCP resources, prompts, and helper functions towards external tool plugins. -- **Find PatternFly documentation tool** - A tool that reaches out to known PatternFly documentation sources, caches locally, and integrates the results with existing MCP tools and resources. -- **PatternFly API integration** - A JSON API for PatternFly documentation, components, and patterns. -- **Hosted resource for sharing MCP tools, resources, prompts** - Shared tooling customization through PatternFly AI tooling repository (or equivalent) +#### In-progress +- **Hybrid documentation**: A JSON API for documentation, components, and patterns that ensures the server is always in sync with the latest releases. + - **PatternFly API Integration**: Embedded integration into the server for standalone purposes, quick starts, and immediate access. + - **Child Process Lifecycle Management**: Background process while you work for API synchronization. -Under consideration: -- **MCP client** - A tailored MCP client specific for the PatternFly MCP server. -- **Auditing for shared tools, resources, and prompts** - An auditing tool that helps you refine your shared tools, resources, and prompts. -- **Containerized PatternFly MCP server, client, and LLM** - A containerized PatternFly MCP server, client, and embedded LLM. Use your own PatternFly chat client resource. +#### In-planning and under review +- **Resource-Tool Integration**: Directly integrate MCP resources into tool responses to reduce token counts and allow tools to accept URI links as inputs. +- **Environment & Analysis Tooling**: A third built-in tool focused on environment snapshots, code analysis, and whitelisted resource access for local project analysis. +- **Agentless MCP Client**: An MCP client for use without an LLM, allowing PatternFly tooling to integrate into CLI tools and CI/CD pipelines. +- **YAML Configuration**: Remote tool, resource, and prompt plugins configured via YAML. +- **Resource/Helper Sharing**: Mechanisms to share resources and helper functions across external tool plugins. #### Future state @@ -87,21 +104,30 @@ Under consideration: flowchart TD subgraph A1["MCP server"] subgraph E1["Session context"] - subgraph F1["Logging, stats context"] + subgraph F1["Logging, Resource discovery context"] F1C(["Built-In prompts"]) F1C <--> F1A subgraph F1A["Built-In tools"] - F1AA(["Search PF docs"]) - F1AB(["Use PF docs"]) - F1AC(["Find PF docs"]) + F1AA(["Search PatternFly docs"]) + F1AB(["Use PatternFly docs"]) + F1AC(["Analyze environment"]) end F1B <--> F1A - F1B(["Built-In resources"]) + F1B(["Built-In resources & discovery layer"]) end end - F1B --> D1 D1(["Server proxy"]) + D1 <--> F1 + subgraph G1["Child process host"] + G1A(["Tools host & isolation sandbox"]) + G1B(["API synchronization process"]) + end + D1 <--> G1 + end + subgraph H1["Agentless client layer"] + H1A(["CLI & Automation integration"]) end + A1 <--> H1 B1(["Local and remote external tools, prompts, resources"]) B1 <--> D1 ``` diff --git a/docs/development.md b/docs/development.md index ddaadb0..960153b 100644 --- a/docs/development.md +++ b/docs/development.md @@ -3,12 +3,14 @@ Complete guide to using the PatternFly MCP Server for development including CLI and programmatic API usage. **Development:** -- [CLI Usage](#cli-usage) -- [Programmatic Usage](#programmatic-usage) -- [Tool Plugins](#tool-plugins) -- [Initial Troubleshooting](#initial-troubleshooting) +- [CLI usage](#cli-usage) +- [Programmatic usage](#programmatic-usage) +- [MCP tool plugins](#mcp-tool-plugins) +- [Initial troubleshooting](#initial-troubleshooting) +- [Project maintenance](#project-maintenance) +- [In-progress and future work](#in-progress-and-future-work) -## CLI Usage +## CLI usage ### Available options @@ -31,8 +33,8 @@ Complete guide to using the PatternFly MCP Server for development including CLI #### Notes - **HTTP transport mode** - By default, the server uses `stdio`. Use the `--http` flag to enable HTTP transport. - **Logging** - The server uses a `diagnostics_channel`-based logger that keeps STDIO stdout pure by default. -- **Programmatic API** - The server can also be used programmatically with options. See [Programmatic Usage](#programmatic-usage) for more details. -- **Tool Plugins** - The server can load external tool plugins at startup. See [Tool Plugins](#tool-plugins) for more details. +- **Programmatic API** - The server can also be used programmatically with options. See [Programmatic usage](#programmatic-usage) for more details. +- **Tool plugins** - The server can load external tool plugins at startup. See [MCP tool plugins](#mcp-tool-plugins) for more details. - **Test Mode** - When `--mode test` is used, the server redirects resource requests to the URL provided by `--mode-test-url`, enabling E2E testing without local filesystem access. ### Basic use scenarios @@ -128,6 +130,11 @@ const server: PfMcpInstance = await start(options); The documentation catalog `src/docs.json` pins remote resources to specific commit SHAs (or explicit refs) for stability and reproducibility. This avoids unexpected upstream changes from breaking results. The `searchPatternFlyDocs` tool handles these lookups transparently for the user. +#### Programmatic runtime requirements + +- **Node.js 20+**: Required to run the core MCP server. +- **Node.js 22+**: Required for loading external tool plugins (`--tool`) and for developers working on advanced process isolation features. + **Example: Programmatic test mode** ```typescript import { start, type PfMcpInstance } from '@patternfly/patternfly-mcp'; @@ -220,7 +227,7 @@ const logSubscription = subscribe(logChannel, logHandler); Reference typings are exported from the package. The full listing can be found in [src/index.ts](../src/index.ts). -### Embedding the Server +### Embedding the server You can embed the MCP server inside your application using the `start()` function and provide **Tool Modules** directly. @@ -267,17 +274,17 @@ main(); See [examples/](examples/) for more programmatic usage examples. -## MCP Tool Plugins +## MCP tool plugins You can extend the server's capabilities by loading **Tool Plugins** at startup. These plugins run out‑of‑process in an isolated **Tools Host** to ensure security and stability. -### Environmental Requirements +### Tool plugin runtime requirements - **Node.js >= 22**: Loading external tool plugins (`--tool`) requires Node.js version 22 or higher due to the use of advanced process isolation and ESM module loading features. - **ESM**: Plugins MUST be authored as ECMAScript Modules. - **Dependency Resolution**: Plugins importing from `@patternfly/patternfly-mcp` require the package to be resolvable in the execution environment. This may require a local `npm install` in the plugin's directory or project root if the package is not available globally. -### Security & Isolation +### Security & isolation The server provides two isolation modes for external plugins via the `--plugin-isolation` flag: @@ -293,11 +300,11 @@ The server provides two isolation modes for external plugins via the `--plugin-i - **`Tool Factory`**: A function wrapper `(options) => Tool` (internal). - **`Tool Module`**: The programmatic result of `createMcpTool`, representing a collection of tools. -### Authoring Tools +### Authoring tools We recommend using the `createMcpTool` helper to define tools. It ensures your tools are properly normalized for the server. -#### Authoring a single Tool Module +#### Authoring a single tool module ```ts import { createMcpTool } from '@patternfly/patternfly-mcp'; @@ -329,7 +336,7 @@ export default createMcpTool([ ]); ``` -#### Input Schema Format +#### Input schema format The `inputSchema` property accepts either **plain JSON Schema objects** or **Zod schemas**. Both formats are automatically converted to the format required by the MCP SDK. @@ -357,24 +364,31 @@ const inputSchema = z.object({ See [examples/toolPluginHelloWorld.js](examples/toolPluginHelloWorld.js) for a basic example. -## Initial Troubleshooting +## Initial troubleshooting -### Tool Plugins +### Tool plugins - **Plugins don't appear**: Verify the Node version (requires Node.js >= 20; >= 22 for tool plugins) and check logs (enable `--log-stderr`). - **Startup warnings/errors**: Startup `load:ack` warnings/errors from tool plugins are logged when stderr/protocol logging is enabled. -- **Schema errors**: If `tools/call` rejects with schema errors, ensure `inputSchema` is valid. See [Authoring Tools](#authoring-tools) for details. +- **Schema errors**: If `tools/call` rejects with schema errors, ensure `inputSchema` is valid. See [Authoring tools](#authoring-tools) for details. - **Network access issues**: If the tool is having network access issues, you may need to configure `--plugin-isolation none`. This is generally discouraged for security reasons but may be necessary in some cases. -### HTTP Transport +### HTTP transport - **Connection issues**: Ensure the port is not already in use and the host is correct. - **CORS errors**: Configure `--allowed-origins` if accessing from a web client. - **DNS rebinding protection**: If behind a proxy, ensure correct `Host` header and configure `--allowed-hosts`. -### General Issues +### General issues - **Server won't start**: Check Node.js version (requires Node.js >= 20; >= 22 for tool plugins). - **Missing tools/resources**: Verify the server started successfully and check logs with `--log-stderr`. - **Type errors**: Ensure TypeScript types are installed: `npm install --save-dev @types/node` +## Project maintenance + +For information on how we manage project dependencies, including our biannual Node.js engine bump schedule, please refer to the [Maintenance section in CONTRIBUTING.md](../CONTRIBUTING.md#maintenance-nodejs-engine-bumps). + +## In-progress and future work + +For more information on our development roadmap, including "in-progress" and "future" work, please refer to the [Architecture & Roadmap](./architecture.md#roadmap) documentation. diff --git a/docs/usage.md b/docs/usage.md index 27bd13e..4f672e7 100644 --- a/docs/usage.md +++ b/docs/usage.md @@ -62,15 +62,35 @@ Fetch full documentation and component JSON schemas for specific PatternFly URLs ## Built-in resources -> MCP resources represent indexed collections of documentation. +> MCP resources represent indexed collections of documentation and machine-readable metadata. -The server exposes this resource-centric architecture via the `patternfly://` URI scheme: +The server exposes a resource-centric architecture via the `patternfly://` URI scheme. MCP clients can use these resources directly. [Review the roadmap for future resource updates](./architecture.md#roadmap). -- **`patternfly://context`**: General PatternFly MCP server context and high-level rules. -- **`patternfly://docs/index`**: Index of all available documentation pages. -- **`patternfly://docs/{name}`**: Documentation for a specific component (e.g., `patternfly://docs/Button`). -- **`patternfly://schemas/index`**: Index of all available component schemas. -- **`patternfly://schemas/{name}`**: JSON Schema for a specific component (e.g., `patternfly://schemas/Button`). +> **Note on AI content**: Specialized AI guidance resources are sourced from the [patternfly/ai-helpers](https://github.com/patternfly/ai-helpers) integration. These are specifically optimized to help LLMs generate more accurate PatternFly code. [See Data sources and integrations in architecture](./architecture.md#data-sources-and-integrations). + +### Discovery resources + +Use these indexes to discover what is available in the library: + +- **`patternfly://docs/index{?version,category,section}`**: A comprehensive index of all available PatternFly documentation pages. +- **`patternfly://docs/meta{?version}`**: Metadata discovery for available PatternFly documentation pages, helpful for understanding available filter parameters. +- **`patternfly://components/index{?version,category}`**: A list of all available PatternFly component names. +- **`patternfly://components/meta{?version}`**: Metadata discovery for components, helpful for understanding available filter parameters. +- **`patternfly://schemas/index{?version,category}`**: An index of all available component JSON schemas. +- **`patternfly://schemas/meta{?version}`**: Metadata discovery for JSON schemas, helpful for understanding available filter parameters. + +### Component and documentation resources + +Access specific component documentation or technical specifications using the following URI templates (RFC 6570): + +- **`patternfly://docs/{name}{?version,category,section}`**: Full human-readable documentation for a specific component (e.g., `patternfly://docs/button`) or guideline. +- **`patternfly://schemas/{name}{?version,category}`**: Machine-readable JSON Schema for a specific component, detailing props, types, and validation rules (e.g., `patternfly://schemas/button`). + +### Context and guidelines + +- **`patternfly://context`**: General PatternFly MCP server context, including high-level development rules and accessibility guidelines. + +> **Tip for LLMs**: When a user asks about a component you aren't familiar with, first check `patternfly://docs/index` to find the correct name, then read the documentation via `patternfly://docs/{name}`. Use `patternfly://components/index` for a cleaner list of component-only names. ## MCP client configuration