feat(tools): pf-4120 resource optimized searchPatternFly (#211)

* docs, experimental section for contextManagement
* options, activate experimental context management
* resource.pfContext, show experimental stats
* tools, activate shouldRegister for contextManagement
* tool.searchPf, resource responses, 2 tools into 1

Author: cdcabrera

docs/README.md

@@ -5,11 +5,13 @@ Welcome to the PatternFly MCP Server documentation. This guide is organized by u
 ### 🚀 Usage
 - **[MCP Tools and Resources](./usage.md)**: Use built-in tools and resources like `searchPatternFlyDocs` and `usePatternFlyDocs`.
 - **[Client Configuration](./usage.md)**: Configure the server for your environment.
+- **[Experimental settings](./experimental.md)**: Opt-in flags that may change; not documented in the stable usage guides.
 - **[Troubleshooting](./usage.md#troubleshooting)**: Steps for common setup problems.
 
 ### 🛠️ Developer reference
 - **[CLI Reference](./development.md#cli-usage)**: Reference of server options.
 - **[API Reference](./development.md#programmatic-usage)**: Using the server as a base library in your own Node.js MCP.
+- **[Experimental settings](./experimental.md)**: CLI and programmatic configuration for experimental flags.
 - **[Examples](./examples/README.md)**: Standalone snippets for HTTP transport, embedding, and custom tools.
 
 ### 🏗️ Architecture & design

docs/development.md

@@ -5,6 +5,7 @@ Complete guide to using the PatternFly MCP Server for development including CLI
 **Development:**
 - [CLI usage](#cli-usage)
 - [Programmatic usage](#programmatic-usage)
+- [Experimental settings](./experimental.md)
 - [MCP tool plugins](#mcp-tool-plugins)
 - [Initial troubleshooting](#initial-troubleshooting)
 - [Project maintenance](#project-maintenance)
@@ -36,7 +37,7 @@ Complete guide to using the PatternFly MCP Server for development including CLI
 - **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.
-- **Experimental options** - When an option is registered as experimental, use `--experimental-<lorem-ipsum>` on the CLI; for programmatic options use `experimental<LoremIpsum>`.
+- **Experimental options** - Opt-in flags use `--experimental-<name>` on the CLI and `experimental<Name>` programmatically. See [Experimental settings](./experimental.md) for the current list, examples, and lifecycle notes.
 
 ### Basic use scenarios
 
@@ -122,7 +123,7 @@ The `start()` function accepts an optional `PfMcpOptions` object for programmati
 | `docsPaths`                | `string[]`                               | Whitelist of local documentation directories resolved by `documentation:` slug. When empty (default), the slug is dormant. | `[]`             |
 
 #### Notes
-- **Experimental options** - When an option is registered as experimental use `experimental<LoremIpsum>` for programmatic options; for CLI options use `--experimental-<lorem-ipsum>`.
+- **Experimental options** - Opt-in flags use `experimental<Name>` programmatically and `--experimental-<name>` on the CLI. See [Experimental settings](./experimental.md) for the current list and configuration examples.
 
 #### Example usage
 

docs/experimental.md

@@ -0,0 +1,122 @@
+# Experimental settings
+
+Opt-in server options documented here are **not** covered by the same stability guarantees as the rest of the docs. They may change behavior, graduate to stable configuration, or be removed without a major release.
+
+**Stable docs:**
+- [Usage guide](./usage.md) — default tools, resources, and client configuration
+- [Development reference](./development.md) — CLI and programmatic API for supported options
+
+## How experimental options work
+
+- **CLI**: `--experimental-<kebab-name>` (for example, `--experimental-context-management`)
+- **Programmatic**: `experimental<CamelName>` on the object passed to `start()` (for example, `experimentalContextManagement: true`)
+- **Startup**: The server logs a warning when any registered experimental option is enabled
+
+Using an experimental flag without the `experimental` prefix (CLI or programmatic) is ignored.
+
+## Lifecycle
+
+1. **Experimental** — documented only on this page; behavior may change between releases.
+2. **Graduating** — when a flag loses its experimental prefix in code, its documentation moves to [usage](./usage.md) or [development](./development.md) in the same change; remove it from the index below.
+3. **Removed** — when a flag fails to graduate, delete the row and section here; stable docs should not need updates.
+
+## Index
+
+| Internal name       | CLI flag                            | Programmatic option             | Value type  |
+|---------------------|-------------------------------------|---------------------------------|-------------|
+| `contextManagement` | `--experimental-context-management` | `experimentalContextManagement` | `boolean`   |
+
+---
+
+## contextManagement
+
+Context management (also called **token-saver mode**) switches the server from the default two-step search-and-fetch workflow to a resource-link workflow for MCP clients that read `patternfly://` URIs directly.
+
+> `contextManagement` is part of a broader set of updates intended to optimize the PatternFly MCP server's use of MCP resources and streamline code. Additional refactors may be included under this umbrella under later releases.
+
+| Mode                    | Registered tools                                      | Typical workflow                                                                 |
+|-------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------|
+| **Default** _(off)_     | `searchPatternFlyDocs`, `usePatternFlyDocs`           | Search returns text with URLs and names; fetch content with `usePatternFlyDocs`. |
+| **Context management**  | `searchPatternFly` only                               | Search returns `resource_link` items; read content with `resources/read`.        |
+
+Built-in MCP resources (`patternfly://docs/...`, `patternfly://schemas/...`, indexes, and `patternfly://context`) remain available in both modes.
+
+### Tool: searchPatternFly
+
+Registered only when context management is enabled.
+
+Search PatternFly components, documentation, guidelines, and JSON schemas by keyword. Returns MCP `resource_link` content items (collections, docs, and schemas).
+
+**Parameters:**
+- `query`: `string` (required) — Case-insensitive, full or partial keyword query (e.g., `"button"`, `"react"`, `"*"` for all resources)
+- `version`: `string` (optional) — Filter by PatternFly version (`"current"`, `"latest"`, or `"v6"`)
+
+**Example:**
+```json
+{
+  "query": "button"
+}
+```
+
+### CLI
+
+```bash
+npx -y @patternfly/patternfly-mcp@latest --experimental-context-management
+```
+
+HTTP transport:
+
+```bash
+npx -y @patternfly/patternfly-mcp@latest --http --port 8080 --experimental-context-management
+```
+
+### Programmatic
+
+```typescript
+import { start } from '@patternfly/patternfly-mcp';
+
+const server = await start({
+  experimentalContextManagement: true
+});
+```
+
+### MCP client configuration
+
+Stdio:
+
+```json
+{
+  "mcpServers": {
+    "patternfly-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@patternfly/patternfly-mcp@latest",
+        "--experimental-context-management"
+      ],
+      "description": "PatternFly rules and documentation (experimental context management)"
+    }
+  }
+}
+```
+
+HTTP:
+
+```json
+{
+  "mcpServers": {
+    "patternfly-mcp": {
+      "command": "npx",
+      "args": [
+        "-y",
+        "@patternfly/patternfly-mcp@latest",
+        "--http",
+        "--port",
+        "8080",
+        "--experimental-context-management"
+      ],
+      "description": "PatternFly rules and documentation (HTTP, experimental context management)"
+    }
+  }
+}
+```

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)
+- [Experimental settings](./experimental.md)
 - [Troubleshooting](#troubleshooting)
 
 ## Built-in tools

src/__tests__/__snapshots__/options.defaults.test.ts.snap

@@ -2,6 +2,7 @@
 
 exports[`options defaults should return specific properties: defaults 1`] = `
 {
+  "contextManagement": false,
   "contextPath": "/",
   "contextUrl": "file:///",
   "docsPathSlug": "documentation:",

src/__tests__/__snapshots__/tool.searchPatternFly.test.ts.snap

@@ -0,0 +1,79 @@
+// Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
+
+exports[`searchPatternFlyTool should have a consistent return structure: structure 1`] = `
+{
+  "callback": [Function],
+  "name": "searchPatternFly",
+  "schema": true,
+}
+`;
+
+exports[`searchPatternFlyTool, callback should have a specific markdown format: Button 1`] = `
+[
+  {
+    "text": "# Search results for PatternFly version "v6" and "button".
+Found 2 collections with 5 related resources. Use the attached resources to access and read full content.",
+    "type": "text",
+  },
+  {
+    "description": "A resource collection series for Button",
+    "groupId": "123456",
+    "mimeType": "text/markdown",
+    "name": "Button (Collection)",
+    "type": "resource_link",
+    "uri": "patternfly://docs/123456",
+  },
+  {
+    "description": "Design Guidelines",
+    "groupId": "123456",
+    "mimeType": "text/markdown",
+    "name": "Button - Design (v6)",
+    "type": "resource_link",
+    "uri": "patternfly://docs/34567b",
+  },
+  {
+    "description": "Component JSON schema with property definitions for Button.",
+    "groupId": "123456",
+    "mimeType": "text/markdown",
+    "name": "Button - JSON Schema (v6)",
+    "type": "resource_link",
+    "uri": "patternfly://schemas/67b890",
+  },
+  {
+    "description": "A resource collection series for Lorem Button",
+    "groupId": "654321",
+    "mimeType": "text/markdown",
+    "name": "Lorem Button (Collection)",
+    "type": "resource_link",
+    "uri": "patternfly://docs/654321",
+  },
+  {
+    "description": "Design Guidelines",
+    "groupId": "654321",
+    "mimeType": "text/markdown",
+    "name": "Lorem Button - Design (v6)",
+    "type": "resource_link",
+    "uri": "patternfly://docs/e34567",
+  },
+  {
+    "description": "Design Guidelines",
+    "groupId": "654321",
+    "mimeType": "text/markdown",
+    "name": "Lorem Button - Guidelines (v6)",
+    "type": "resource_link",
+    "uri": "patternfly://docs/34567",
+  },
+  {
+    "description": "Component JSON schema with property definitions for Lorem Button.",
+    "groupId": "654321",
+    "mimeType": "text/markdown",
+    "name": "Lorem Button - JSON Schema (v6)",
+    "type": "resource_link",
+    "uri": "patternfly://schemas/678e90",
+  },
+]
+`;
+
+exports[`searchPatternFlyTool, callback should parse parameters, exact match 1`] = `"# Search results for PatternFly version "v6" and "button"."`;
+
+exports[`searchPatternFlyTool, callback should parse parameters, wildcard search 1`] = `"# Search results for PatternFly version "v6" and "all" resources."`;

src/__tests__/resource.patternFlyContext.test.ts

@@ -30,12 +30,33 @@ describe('resourceCallback', () => {
     {
       description: 'default',
       expected: 'Troubleshooting'
+    },
+    {
+      description: 'contextManagement enabled',
+      options: {
+        contextManagement: true,
+        experimental: ['contextManagement'],
+        mode: 'test',
+        version: '1.0.0',
+        nodeVersion: 22
+      },
+      expected: [
+        'search, list and access',
+        'list and access available documentation resources',
+        'Active Experimental Features',
+        'contextManagement'
+      ]
     }
-  ])('should return context content, $description', async ({ expected }) => {
-    const result = await resourceCallback(undefined as any);
+  ])('should return context content, $description', async ({ options, expected }) => {
+    const result = await resourceCallback(new URL('patternfly://context'), options as any);
 
     expect(result.contents).toBeDefined();
-    expect(Object.keys(result.contents[0] as any)).toEqual(['uri', 'mimeType', 'text']);
-    expect(result.contents[0]?.text).toContain(expected);
+    const text = result.contents[0]?.text;
+
+    if (Array.isArray(expected)) {
+      expected.forEach(snippet => expect(text).toContain(snippet));
+    } else {
+      expect(text).toContain(expected);
+    }
   });
 });

src/__tests__/server.test.ts

@@ -90,13 +90,13 @@ describe('runServer', () => {
   it.each([
     {
       description: 'use default tools, stdio',
-      options: { name: 'test-server-1', version: '1.0.0' },
+      options: { name: 'test-server-1', version: '1.0.0', contextManagement: undefined },
       tools: undefined,
       transportMethod: MockStdioServerTransport
     },
     {
       description: 'use default tools, http',
-      options: { name: 'test-server-2', version: '1.0.0', isHttp: true },
+      options: { name: 'test-server-2', version: '1.0.0', isHttp: true, contextManagement: false },
       tools: undefined,
       transportMethod: MockStartHttpTransport
     },