feat(client): felt-3609 activate terminal mcp client

cspell.config.json

@@ -9,6 +9,8 @@
     "gatekeep",
     "ized",
     "jaccard",
+    "kubepods",
+    "libpod",
     "llms",
     "localappdata",
     "midrun",
@@ -34,6 +36,7 @@
     "unrepresentable",
     "unsub",
     "untampered",
-    "userns"
+    "userns",
+    "xclip"
   ]
 }

docs/experimental.md

@@ -24,10 +24,52 @@ Using an experimental flag without the `experimental` prefix (CLI or programmati
 
 | Internal name       | CLI flag                            | Programmatic option             | Value type  |
 |---------------------|-------------------------------------|---------------------------------|-------------|
+| `client`            | `--experimental-client`             | `experimentalClient`            | `boolean`   |
 | `contextManagement` | `--experimental-context-management` | `experimentalContextManagement` | `boolean`   |
 
 ---
 
+## client
+
+The interactive client launches an embedded terminal UI directly connected to the PatternFly MCP server over an in-process memory transport channel (`createMcpChannel`). It allows developers and contributors to interactively search, browse collections, inspect component schemas, view documentation, copy contents via system clipboard or OSC-52, and export local markdown files.
+
+> **Requirement**: The interactive client requires an interactive terminal (TTY) with standard input and output attached (`stdin.isTTY` and `stdout.isTTY`). Running non-interactively or in automated headless pipelines will exit with an error.
+
+### Controls
+
+| Keystroke | Context | Action |
+|-----------|---------|--------|
+| `/` | Search Screen | Prompt for new search query |
+| `<Tab>` | Search Screen | Cycle through registered collections filter |
+| `<↑/↓>` | Search & Reader | Navigate tree items or scroll reader document |
+| `<Enter>` | Search Screen | Select record to read or toggle collection expand/collapse |
+| `<Enter>` / `b` / `<Esc>` | Reader Screen | Return to search results view |
+| `c` | Reader Screen | Copy full document text to clipboard (`pbcopy`, `wl-copy`, `xclip`, or OSC-52) |
+| `r` | Reader Screen | Save document to local disk as a `.md` file |
+| `q` / `Ctrl+C` | Any Screen | Exit interactive client |
+
+### CLI
+
+Launch the interactive terminal client:
+
+```bash
+npx -y @patternfly/patternfly-mcp@latest --experimental-client
+```
+
+> **Note**: The interactive client communicates over an in-process/memory transport channel and cannot be combined with network transports like `--http`.
+
+### Programmatic
+
+```typescript
+import { start } from '@patternfly/patternfly-mcp';
+
+const server = await start({
+  experimentalClient: true
+});
+```
+
+---
+
 ## 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.

jest.setupTests.ts

@@ -68,3 +68,24 @@ jest.mock('@patternfly/patternfly-component-schemas/json', () => ({
     throw new Error(`Component "${componentName}" not found`);
   })
 }), { virtual: true });
+
+/**
+ * Suppress raw terminal output writes (screen clears, ANSI sequences) during unit test runs.
+ */
+const originalStdoutWrite = process.stdout.write.bind(process.stdout);
+
+beforeEach(() => {
+  process.stdout.write = jest.fn().mockImplementation((chunk: string | Uint8Array, encoding?: unknown, callback?: unknown) => {
+    if (typeof encoding === 'function') {
+      encoding();
+    } else if (typeof callback === 'function') {
+      callback();
+    }
+
+    return true;
+  }) as unknown as typeof process.stdout.write;
+});
+
+afterEach(() => {
+  process.stdout.write = originalStdoutWrite;
+});

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

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

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

@@ -16,6 +16,9 @@ Found 2 collections with 5 related resources. Use the attached resources to acce
     "type": "text",
   },
   {
+    "_meta": {
+      "groupId": "654321",
+    },
     "description": "A resource collection series for Lorem Button",
     "groupId": "654321",
     "mimeType": "text/markdown",
@@ -24,6 +27,11 @@ Found 2 collections with 5 related resources. Use the attached resources to acce
     "uri": "patternfly://docs/654321",
   },
   {
+    "_meta": {
+      "groupId": "654321",
+      "primaryCollection": "patternfly-docs",
+      "recordId": undefined,
+    },
     "description": "Design Guidelines",
     "groupId": "654321",
     "mimeType": "text/markdown",
@@ -33,6 +41,11 @@ Found 2 collections with 5 related resources. Use the attached resources to acce
     "uri": "patternfly://docs/e34567",
   },
   {
+    "_meta": {
+      "groupId": "654321",
+      "primaryCollection": "patternfly-docs",
+      "recordId": undefined,
+    },
     "description": "Design Guidelines",
     "groupId": "654321",
     "mimeType": "text/markdown",
@@ -42,6 +55,11 @@ Found 2 collections with 5 related resources. Use the attached resources to acce
     "uri": "patternfly://docs/34567",
   },
   {
+    "_meta": {
+      "groupId": "654321",
+      "primaryCollection": "patternfly-docs",
+      "recordId": "654321",
+    },
     "description": "Component JSON schema with property definitions for Lorem Button.",
     "groupId": "654321",
     "mimeType": "text/markdown",
@@ -50,6 +68,9 @@ Found 2 collections with 5 related resources. Use the attached resources to acce
     "uri": "patternfly://schemas/678e90",
   },
   {
+    "_meta": {
+      "groupId": "123456",
+    },
     "description": "A resource collection series for Button",
     "groupId": "123456",
     "mimeType": "text/markdown",
@@ -58,6 +79,11 @@ Found 2 collections with 5 related resources. Use the attached resources to acce
     "uri": "patternfly://docs/123456",
   },
   {
+    "_meta": {
+      "groupId": "123456",
+      "primaryCollection": "patternfly-docs",
+      "recordId": undefined,
+    },
     "description": "Design Guidelines",
     "groupId": "123456",
     "mimeType": "text/markdown",
@@ -67,6 +93,11 @@ Found 2 collections with 5 related resources. Use the attached resources to acce
     "uri": "patternfly://docs/34567b",
   },
   {
+    "_meta": {
+      "groupId": "123456",
+      "primaryCollection": "patternfly-docs",
+      "recordId": "123456",
+    },
     "description": "Component JSON schema with property definitions for Button.",
     "groupId": "123456",
     "mimeType": "text/markdown",