WIP refactor: cli, programmatic options instances

README.md

@@ -17,7 +17,7 @@ The Model Context Protocol (MCP) is an open standard that enables AI assistants
 
 ## Prerequisites
 
-- Node.js 18.0.0 or higher
+- Node.js 20.0.0 or higher
 - npm (or another Node package manager)
 
 ## Installation
@@ -74,7 +74,7 @@ These are the most relevant NPM scripts from package.json:
 
 ## Usage
 
-The MCP server communicates over stdio and provides access to PatternFly documentation through the following tools. Both tools accept an argument named urlList which must be an array of strings. Each string is either:
+The MCP server communicates over stdio and provides access to PatternFly documentation through the following tools. Both tools accept an argument named `urlList` which must be an array of strings. Each string is either:
 - An external URL (e.g., a raw GitHub URL to a .md file), or
 - A local file path (e.g., documentation/.../README.md). When running with the --docs-host flag, these paths are resolved under the llms-files directory instead.
 
@@ -118,7 +118,7 @@ Then, passing a local path such as react-core/6.0.0/llms.txt in urlList will loa
 
 ## MCP client configuration examples
 
-Most MCP clients use a JSON configuration that tells the client how to start this server. The server itself does not read that JSON; it only reads CLI flags and environment variables. Below are examples you can adapt to your MCP client.
+Most MCP clients use a JSON configuration to specify how to start this server. The server itself only reads CLI flags and environment variables, not the JSON configuration. Below are examples you can adapt to your MCP client.
 
 ### Minimal client config (npx)
 
@@ -197,30 +197,71 @@ npx @modelcontextprotocol/inspector-cli \
 ## Environment variables
 
 - DOC_MCP_FETCH_TIMEOUT_MS: Milliseconds to wait before aborting an HTTP fetch (default: 15000)
-- DOC_MCP_CLEAR_COOLDOWN_MS: Default cooldown value used in internal cache configuration. The current public API does not expose a clearCache tool.
+- DOC_MCP_CLEAR_COOLDOWN_MS: Default cooldown value used in internal cache configuration. The current public API does not expose a `clearCache` tool.
 
 ## Programmatic usage (advanced)
 
-The package provides programmatic access through the `start()` function (or `main()` as an alternative):
+The package provides programmatic access through the `start()` function:
 
 ```typescript
-import { start, main, type CliOptions } from '@patternfly/patternfly-mcp';
+import { start, main, type CliOptions, type ServerInstance } from '@patternfly/patternfly-mcp';
 
 // Use with default options (equivalent to CLI without flags)
-await start();
+const server = await start();
 
 // Override CLI options programmatically
-await start({ docsHost: true });
+const serverWithOptions = await start({ docsHost: true });
 
 // Multiple options can be overridden
-await start({ 
+const customServer = await start({ 
   docsHost: true,
   // Future CLI options can be added here
 });
 
 // TypeScript users can use the CliOptions type for type safety
 const options: Partial<CliOptions> = { docsHost: true };
-await start(options);
+const typedServer = await start(options);
+
+// Server instance provides shutdown control
+console.log('Server running:', server.isRunning()); // true
+
+// Graceful shutdown
+await server.stop();
+console.log('Server running:', server.isRunning()); // false
+```
+
+### ServerInstance Interface
+
+The `start()` function returns a `ServerInstance` object with the following methods:
+
+```typescript
+interface ServerInstance {
+  /**
+   * Stop the server gracefully
+   */
+  stop(): Promise<void>;
+
+  /**
+   * Check if server is running
+   */
+  isRunning(): boolean;
+}
+```
+
+**Usage Examples**:
+```typescript
+const server = await start();
+
+// Check if server is running
+if (server.isRunning()) {
+  console.log('Server is active');
+}
+
+// Graceful shutdown
+await server.stop();
+
+// Verify shutdown
+console.log('Server running:', server.isRunning()); // false
 ```
 
 ## Returned content details

jest.setupTests.ts

@@ -1 +1,4 @@
 // Shared helpers for all Jest tests
+
+// Set NODE_ENV to test for all tests
+// process.env.NODE_ENV = 'test';

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

@@ -1,55 +1,5 @@
 // Jest Snapshot v1, https://jestjs.io/docs/snapshot-testing
 
-exports[`freezeOptions should return frozen options with consistent properties: frozen 1`] = `
-{
-  "contextPath": "/",
-  "docsHost": true,
-  "docsPath": "/documentation",
-  "llmsFilesPath": "/llms-files",
-  "name": "@patternfly/patternfly-mcp",
-  "pfExternal": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content",
-  "pfExternalAccessibility": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/accessibility",
-  "pfExternalCharts": "https://raw.githubusercontent.com/patternfly/patternfly-react/refs/heads/main/packages/react-charts/src",
-  "pfExternalChartsComponents": "https://raw.githubusercontent.com/patternfly/patternfly-react/refs/heads/main/packages/react-charts/src/victory/components",
-  "pfExternalChartsDesign": "https://raw.githubusercontent.com/patternfly/patternfly-react/refs/heads/main/packages/react-charts/src/charts",
-  "pfExternalDesign": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/design-guidelines",
-  "pfExternalDesignComponents": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/design-guidelines/components",
-  "pfExternalDesignLayouts": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/design-guidelines/layouts",
-  "repoName": "patternfly-mcp",
-  "resourceMemoOptions": {
-    "fetchUrl": {
-      "cacheErrors": false,
-      "cacheLimit": 100,
-      "expire": 180000,
-    },
-    "readFile": {
-      "cacheErrors": false,
-      "cacheLimit": 50,
-      "expire": 120000,
-    },
-  },
-  "separator": "
-
----
-
-",
-  "toolMemoOptions": {
-    "fetchDocs": {
-      "cacheErrors": false,
-      "cacheLimit": 15,
-      "expire": 60000,
-    },
-    "usePatternFlyDocs": {
-      "cacheErrors": false,
-      "cacheLimit": 10,
-      "expire": 60000,
-    },
-  },
-  "urlRegex": /\\^\\(https\\?:\\)\\\\/\\\\//i,
-  "version": "0.0.0",
-}
-`;
-
 exports[`options should return specific properties 1`] = `
 {
   "DEFAULT_SEPARATOR": "
@@ -136,8 +86,9 @@ exports[`options should return specific properties 1`] = `
     },
   },
   "URL_REGEX": /\\^\\(https\\?:\\)\\\\/\\\\//i,
-  "freezeOptions": [Function],
+  "generateSessionId": [Function],
   "parseCliOptions": [Function],
+  "setOptions": [Function],
 }
 `;
 
@@ -158,3 +109,53 @@ exports[`parseCliOptions should attempt to parse args without --docs-host flag 1
   "docsHost": false,
 }
 `;
+
+exports[`setOptions should return options with consistent properties: options 1`] = `
+{
+  "contextPath": "/",
+  "docsHost": true,
+  "docsPath": "/documentation",
+  "llmsFilesPath": "/llms-files",
+  "name": "@patternfly/patternfly-mcp",
+  "pfExternal": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content",
+  "pfExternalAccessibility": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/accessibility",
+  "pfExternalCharts": "https://raw.githubusercontent.com/patternfly/patternfly-react/refs/heads/main/packages/react-charts/src",
+  "pfExternalChartsComponents": "https://raw.githubusercontent.com/patternfly/patternfly-react/refs/heads/main/packages/react-charts/src/victory/components",
+  "pfExternalChartsDesign": "https://raw.githubusercontent.com/patternfly/patternfly-react/refs/heads/main/packages/react-charts/src/charts",
+  "pfExternalDesign": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/design-guidelines",
+  "pfExternalDesignComponents": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/design-guidelines/components",
+  "pfExternalDesignLayouts": "https://raw.githubusercontent.com/patternfly/patternfly-org/refs/heads/main/packages/documentation-site/patternfly-docs/content/design-guidelines/layouts",
+  "repoName": "patternfly-mcp",
+  "resourceMemoOptions": {
+    "fetchUrl": {
+      "cacheErrors": false,
+      "cacheLimit": 100,
+      "expire": 180000,
+    },
+    "readFile": {
+      "cacheErrors": false,
+      "cacheLimit": 50,
+      "expire": 120000,
+    },
+  },
+  "separator": "
+
+---
+
+",
+  "toolMemoOptions": {
+    "fetchDocs": {
+      "cacheErrors": false,
+      "cacheLimit": 15,
+      "expire": 60000,
+    },
+    "usePatternFlyDocs": {
+      "cacheErrors": false,
+      "cacheLimit": 10,
+      "expire": 60000,
+    },
+  },
+  "urlRegex": /\\^\\(https\\?:\\)\\\\/\\\\//i,
+  "version": "0.0.0",
+}
+`;

src/__tests__/__snapshots__/server.test.ts.snap

@@ -21,6 +21,69 @@ exports[`runServer should attempt to run server, create transport, connect, and
       },
     ],
   ],
+  "process": [
+    [
+      "SIGINT",
+      [Function],
+    ],
+  ],
+  "registerTool": [],
+}
+`;
+
+exports[`runServer should attempt to run server, disable SIGINT handler: console 1`] = `
+{
+  "info": [],
+  "log": [
+    [
+      "PatternFly MCP server running on stdio",
+    ],
+  ],
+  "mcpServer": [
+    [
+      {
+        "name": "@patternfly/patternfly-mcp",
+        "version": "0.0.0",
+      },
+      {
+        "capabilities": {
+          "tools": {},
+        },
+      },
+    ],
+  ],
+  "process": [],
+  "registerTool": [],
+}
+`;
+
+exports[`runServer should attempt to run server, enable SIGINT handler explicitly: console 1`] = `
+{
+  "info": [],
+  "log": [
+    [
+      "PatternFly MCP server running on stdio",
+    ],
+  ],
+  "mcpServer": [
+    [
+      {
+        "name": "@patternfly/patternfly-mcp",
+        "version": "0.0.0",
+      },
+      {
+        "capabilities": {
+          "tools": {},
+        },
+      },
+    ],
+  ],
+  "process": [
+    [
+      "SIGINT",
+      [Function],
+    ],
+  ],
   "registerTool": [],
 }
 `;
@@ -50,6 +113,12 @@ exports[`runServer should attempt to run server, register a tool: console 1`] =
       },
     ],
   ],
+  "process": [
+    [
+      "SIGINT",
+      [Function],
+    ],
+  ],
   "registerTool": [
     [
       "loremIpsum",
@@ -91,6 +160,12 @@ exports[`runServer should attempt to run server, register multiple tools: consol
       },
     ],
   ],
+  "process": [
+    [
+      "SIGINT",
+      [Function],
+    ],
+  ],
   "registerTool": [
     [
       "loremIpsum",
@@ -133,6 +208,12 @@ exports[`runServer should attempt to run server, use custom options: console 1`]
       },
     ],
   ],
+  "process": [
+    [
+      "SIGINT",
+      [Function],
+    ],
+  ],
   "registerTool": [],
 }
 `;
@@ -165,6 +246,12 @@ exports[`runServer should attempt to run server, use default tools: console 1`]
       },
     ],
   ],
+  "process": [
+    [
+      "SIGINT",
+      [Function],
+    ],
+  ],
   "registerTool": [
     [
       "usePatternFlyDocs",