refactor(mcpSdk,server): pf-3836 sdk related typings

src/__tests__/options.context.test.ts

@@ -1,7 +1,8 @@
 import { z } from 'zod';
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { runServer, type McpTool } from '../server';
+import { type McpTool } from '../mcpSdk';
+import { runServer } from '../server';
 import { getOptions, setOptions } from '../options.context';
 import { DEFAULT_OPTIONS } from '../options.defaults';
 

src/mcpSdk.ts

@@ -1,7 +1,110 @@
-import { ResourceTemplate, type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpResource } from './server';
+import {
+  ResourceTemplate,
+  type McpServer,
+  type ResourceMetadata,
+  type CompleteResourceTemplateCallback
+} from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type GlobalOptions } from './options';
 import { listAllCombinations, listIncrementalCombinations, splitUri } from './server.helpers';
 
+/**
+ * A tool registered with the MCP server.
+ *
+ * @note Use of `any` here is intentional as part of a pass-through policy around
+ * `inputSchema`. Input schemas are actually reconstructed as part of the
+ * tools-as-plugins architecture to help guarantee that a minimal tool schema is
+ * always available and minimally valid.
+ *
+ * 0. `name` `{string}`: Name of the tool.
+ * 1. `schema` `{Object}`: Descriptions and schemas provided to allow parameter input and outputs in a standardized format.
+ *    - `schema.description` `{string}`: Concise description of functionality for the tool.
+ *    - `schema.inputSchema` `{*}`: Internally, a raw Zod schema. Externally, a JSON or raw Zod schema. External tools are
+ *       converted to Zod for user convenience.
+ * 2. `handler` `{Function}`: Tool handler function for returning content.
+ */
+type McpTool = [
+  name: string,
+  schema: {
+    description: string;
+    inputSchema: any;
+  },
+  handler: (arg?: unknown) => any | Promise<any>
+];
+
+/**
+ * A function that creates a tool registered with the MCP server.
+ */
+type McpToolCreator = ((options?: GlobalOptions) => McpTool) & { toolName?: string };
+
+/**
+ * Configuration for a generated metadata MCP resource.
+ *
+ * @interface McpResourceMetadataMetaConfig
+ *
+ * @property [uri] - Override URI for the meta-resource. (e.g., `test://lorem/meta`, `test://ipsum/meta{?var}`).
+ * @property [name] - Registered name for the meta-resource (defaults to `{primaryName}-meta`).
+ * @property [title] - Title shown for the meta-resource in listings and generated Markdown.
+ * @property [description] - Description for the meta-resource in listings and generated Markdown.
+ * @property [searchFields] - Query parameter names included on the meta-URI template for completion.
+ *   - If an empty array is provided the meta-resource uses a static URI, no template
+ *   - If omitted the search fields are inferred from the `uri` or the primary resource template.
+ * @property [mimeType] - MIME type of the meta-resource body. Acceptable values are:
+ *   - 'text/markdown'
+ *   - 'application/json'
+ * @property [metaHandler] - A custom handler for the meta-resource. It accepts an optional object as its
+ *     argument for passing parameters and returns a serialized value to the MCP client. A default fallback
+ *     async handler is used if none is provided.
+ */
+interface McpResourceMetadataMetaConfig {
+  uri?: string;
+  name?: string;
+  title?: string;
+  description?: string;
+  searchFields?: string[] | undefined;
+  mimeType?: 'text/markdown' | 'application/json';
+  metaHandler?: (params: Record<string, string> | undefined) => Promise<unknown> | unknown;
+}
+
+/**
+ * A resource metadata configuration for the MCP server.
+ *
+ * @property registerAllSearchCombinations - Whether to register all search combinations for the resource.
+ * @property metaConfig - Optional configuration for generating a metadata resource. Being defined
+ *     (e.g. `{ metadata: { metaConfig: {} }}`) means a meta-resource will be generated for the related MCP resource.
+ * @property complete - Callback functions for resource completion.
+ */
+interface McpResourceMetadata {
+  registerAllSearchCombinations?: boolean | undefined;
+  metaConfig?: McpResourceMetadataMetaConfig;
+  complete?: {
+    [key: string]: CompleteResourceTemplateCallback;
+  } | undefined;
+  [key: string]: unknown;
+}
+
+/**
+ * A resource registered with the MCP server.
+ *
+ * 0. `name`: Registered name of the resource.
+ * 1. `uriOrTemplate`: URI string or template. {@link ResourceTemplate}
+ * 2. `config`: Resource configuration metadata. {@link ResourceMetadata}
+ * 3. `handler`: Resource handler function.
+ * 4. `metadata`: Optional **internal metadata** object, not used by the standard MCP SDK
+ *     resource registry. {@link McpResourceMetadata}
+ */
+type McpResource = [
+  name: string,
+  uriOrTemplate: string | ResourceTemplate,
+  config: ResourceMetadata,
+  handler: (...args: any[]) => any | Promise<any>,
+  metadata?: McpResourceMetadata | undefined
+];
+
+/**
+ * A function that creates a resource registered with the MCP server.
+ */
+type McpResourceCreator = ((options?: GlobalOptions) => McpResource) & { resourceName?: string };
+
 /**
  * Register an MCP resource.
  *
@@ -98,4 +201,12 @@
   server.registerResource(name, uriOrTemplate as any, config, callback);
 };
 
-export { registerResource };
+export {
+  registerResource,
+  type McpTool,
+  type McpToolCreator,
+  type McpResourceMetadataMetaConfig,
+  type McpResourceMetadata,
+  type McpResource,
+  type McpResourceCreator
+};

src/options.registry.ts

@@ -1,4 +1,4 @@
-import { type McpToolCreator, type McpResourceCreator } from './server';
+import { type McpToolCreator, type McpResourceCreator } from './mcpSdk';
 import { usePatternFlyDocsTool } from './tool.patternFlyDocs';
 import { searchPatternFlyDocsTool } from './tool.searchPatternFlyDocs';
 import { patternFlyComponentsIndexResource } from './resource.patternFlyComponentsIndex';

src/resource.patternFlyComponentsIndex.ts

@@ -2,7 +2,7 @@ import {
   ResourceTemplate,
   type CompleteResourceTemplateCallback
 } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpResource } from './server';
+import { type McpResource } from './mcpSdk';
 import { memo } from './server.caching';
 import { buildSearchString, stringJoin } from './server.helpers';
 import { assertInput, assertInputStringLength } from './server.assertions';

src/resource.patternFlyContext.ts

@@ -1,4 +1,4 @@
-import { type McpResource } from './server';
+import { type McpResource } from './mcpSdk';
 import { stringJoin } from './server.helpers';
 import { getOptions, runWithOptions } from './options.context';
 

src/resource.patternFlyDocsIndex.ts

@@ -2,7 +2,7 @@ import {
   ResourceTemplate,
   type CompleteResourceTemplateCallback
 } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpResource } from './server';
+import { type McpResource } from './mcpSdk';
 import { memo } from './server.caching';
 import { buildSearchString, stringJoin } from './server.helpers';
 import { assertInput, assertInputStringLength } from './server.assertions';

src/resource.patternFlyDocsTemplate.ts

@@ -3,7 +3,7 @@ import {
   type CompleteResourceTemplateCallback
 } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { type McpResource } from './server';
+import { type McpResource } from './mcpSdk';
 import { processDocsFunction } from './server.getResources';
 import { stringJoin } from './server.helpers';
 import { assertInput, assertInputStringLength } from './server.assertions';

src/resource.patternFlySchemasIndex.ts

@@ -2,7 +2,7 @@ import {
   ResourceTemplate,
   type CompleteResourceTemplateCallback
 } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpResource } from './server';
+import { type McpResource } from './mcpSdk';
 import { memo } from './server.caching';
 import { stringJoin } from './server.helpers';
 import { assertInput, assertInputStringLength } from './server.assertions';

src/resource.patternFlySchemasTemplate.ts

@@ -2,7 +2,7 @@ import {
   ResourceTemplate,
   type CompleteResourceTemplateCallback
 } from '@modelcontextprotocol/sdk/server/mcp.js';
-import { type McpResource } from './server';
+import { type McpResource } from './mcpSdk';
 import { memo } from './server.caching';
 import { assertInput, assertInputStringLength } from './server.assertions';
 import { getOptions, runWithOptions } from './options.context';

src/server.resourceMeta.ts

@@ -7,7 +7,7 @@ import {
   type McpResourceCreator,
   type McpResourceMetadata,
   type McpResourceMetadataMetaConfig
-} from './server';
+} from './mcpSdk';
 import {
   buildSearchString,
   isPlainObject,

src/server.resources.ts

@@ -1,4 +1,4 @@
-import { type McpResourceCreator } from './server';
+import { type McpResourceCreator } from './mcpSdk';
 import { type AppSession, type GlobalOptions } from './options';
 import { getOptions, getSessionOptions } from './options.context';
 import { log } from './logger';

src/server.tools.ts

@@ -4,7 +4,7 @@ import { fileURLToPath } from 'node:url';
 import { dirname } from 'node:path';
 import { z } from 'zod';
 import { type AppSession, type GlobalOptions } from './options';
-import { type McpToolCreator } from './server';
+import { type McpToolCreator } from './mcpSdk';
 import { log, formatUnknownError } from './logger';
 import {
   awaitIpc,

src/server.toolsHost.ts

@@ -7,7 +7,7 @@ import {
 import { resolveExternalCreators } from './server.toolsHostCreator';
 import { DEFAULT_OPTIONS } from './options.defaults';
 import { type ToolOptions } from './options.tools';
-import { type McpTool, type McpToolCreator } from './server';
+import { type McpTool, type McpToolCreator } from './mcpSdk';
 import {
   isZodRawShape,
   isZodSchema,

src/server.toolsHostCreator.ts

@@ -1,4 +1,4 @@
-import { type McpTool, type McpToolCreator } from './server';
+import { type McpTool, type McpToolCreator } from './mcpSdk';
 
 /**
  * Apply a static property to an object.

src/server.toolsUser.ts

@@ -1,7 +1,7 @@
 import { fileURLToPath, pathToFileURL } from 'node:url';
 import { dirname, isAbsolute, resolve } from 'node:path';
 import { isPath, isPlainObject, isReferenceLike, isUrl } from './server.helpers';
-import { type McpTool } from './server';
+import { type McpTool } from './mcpSdk';
 import { type GlobalOptions } from './options';
 import { memo } from './server.caching';
 import { DEFAULT_OPTIONS } from './options.defaults';

src/server.ts

@@ -1,11 +1,12 @@
 import {
-  McpServer,
-  type CompleteResourceTemplateCallback,
-  type ResourceTemplate,
-  type ResourceMetadata
+  McpServer
 } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { registerResource } from './mcpSdk';
+import {
+  registerResource,
+  type McpToolCreator,
+  type McpResourceCreator
+} from './mcpSdk';
 import { setMetaResources } from './server.resourceMeta';
 import { startHttpTransport, type HttpServerHandle } from './server.http';
 import { memo } from './server.caching';
@@ -27,104 +28,6 @@ import { createServerStats, type Stats } from './server.stats';
 import { stat, type StatReport } from './stats';
 import { builtinTools, builtinResources } from './options.registry';
 
-/**
- * A tool registered with the MCP server.
- *
- * @note Use of `any` here is intentional as part of a pass-through policy around
- * `inputSchema`. Input schemas are actually reconstructed as part of the
- * tools-as-plugins architecture to help guarantee that a minimal tool schema is
- * always available and minimally valid.
- *
- * 0. `name` `{string}`: Name of the tool.
- * 1. `schema` `{Object}`: Descriptions and schemas provided to allow parameter input and outputs in a standardized format.
- *    - `schema.description` `{string}`: Concise description of functionality for the tool.
- *    - `schema.inputSchema` `{*}`: Internally, a raw Zod schema. Externally, a JSON or raw Zod schema. External tools are
- *       converted to Zod for user convenience.
- * 2. `handler` `{Function}`: Tool handler function for returning content.
- */
-type McpTool = [
-  name: string,
-  schema: {
-    description: string;
-    inputSchema: any;
-  },
-  handler: (arg?: unknown) => any | Promise<any>
-];
-
-/**
- * A function that creates a tool registered with the MCP server.
- */
-type McpToolCreator = ((options?: GlobalOptions) => McpTool) & { toolName?: string };
-
-/**
- * Configuration for a generated metadata MCP resource.
- *
- * @interface McpResourceMetadataMetaConfig
- *
- * @property [uri] - Override URI for the meta-resource. (e.g., `test://lorem/meta`, `test://ipsum/meta{?var}`).
- * @property [name] - Registered name for the meta-resource (defaults to `{primaryName}-meta`).
- * @property [title] - Title shown for the meta-resource in listings and generated Markdown.
- * @property [description] - Description for the meta-resource in listings and generated Markdown.
- * @property [searchFields] - Query parameter names included on the meta-URI template for completion.
- *   - If an empty array is provided the meta-resource uses a static URI, no template
- *   - If omitted the search fields are inferred from the `uri` or the primary resource template.
- * @property [mimeType] - MIME type of the meta-resource body. Acceptable values are:
- *   - 'text/markdown'
- *   - 'application/json'
- * @property [metaHandler] - A custom handler for the meta-resource. It accepts an optional object as its
- *     argument for passing parameters and returns a serialized value to the MCP client. A default fallback
- *     async handler is used if none is provided.
- */
-interface McpResourceMetadataMetaConfig {
-  uri?: string;
-  name?: string;
-  title?: string;
-  description?: string;
-  searchFields?: string[] | undefined;
-  mimeType?: 'text/markdown' | 'application/json';
-  metaHandler?: (params: Record<string, string> | undefined) => Promise<unknown> | unknown;
-}
-
-/**
- * A resource metadata configuration for the MCP server.
- *
- * @property registerAllSearchCombinations - Whether to register all search combinations for the resource.
- * @property metaConfig - Optional configuration for generating a metadata resource. Being defined
- *     (e.g. `{ metadata: { metaConfig: {} }}`) means a meta-resource will be generated for the related MCP resource.
- * @property complete - Callback functions for resource completion.
- */
-interface McpResourceMetadata {
-  registerAllSearchCombinations?: boolean | undefined;
-  metaConfig?: McpResourceMetadataMetaConfig;
-  complete?: {
-    [key: string]: CompleteResourceTemplateCallback;
-  } | undefined;
-  [key: string]: unknown;
-}
-
-/**
- * A resource registered with the MCP server.
- *
- * 0. `name`: Registered name of the resource.
- * 1. `uriOrTemplate`: URI string or template. {@link ResourceTemplate}
- * 2. `config`: Resource configuration metadata. {@link ResourceMetadata}
- * 3. `handler`: Resource handler function.
- * 4. `metadata`: Optional **internal metadata** object, not used by the standard MCP SDK
- *     resource registry. {@link McpResourceMetadata}
- */
-type McpResource = [
-  name: string,
-  uriOrTemplate: string | ResourceTemplate,
-  config: ResourceMetadata,
-  handler: (...args: any[]) => any | Promise<any>,
-  metadata?: McpResourceMetadata | undefined
-];
-
-/**
- * A function that creates a resource registered with the MCP server.
- */
-type McpResourceCreator = ((options?: GlobalOptions) => McpResource) & { resourceName?: string };
-
 /**
  * Server options. Equivalent to GlobalOptions.
  */
@@ -544,12 +447,6 @@ export {
   runServer,
   registerServerResources,
   registerServerTools,
-  type McpTool,
-  type McpToolCreator,
-  type McpResource,
-  type McpResourceCreator,
-  type McpResourceMetadata,
-  type McpResourceMetadataMetaConfig,
   type ServerInstance,
   type ServerLogEvent,
   type ServerOnLog,

src/tool.patternFlyDocs.ts

@@ -1,6 +1,6 @@
 import { z } from 'zod';
 import { ErrorCode, McpError } from '@modelcontextprotocol/sdk/types.js';
-import { type McpTool } from './server';
+import { type McpTool } from './mcpSdk';
 import { processDocsFunction, type ProcessedDoc } from './server.getResources';
 import { stringJoin } from './server.helpers';
 import {

src/tool.searchPatternFlyDocs.ts

@@ -1,6 +1,6 @@
 import { ErrorCode } from '@modelcontextprotocol/sdk/types.js';
 import { z } from 'zod';
-import { type McpTool } from './server';
+import { type McpTool } from './mcpSdk';
 import { stringJoin } from './server.helpers';
 import { assertInput, assertInputStringLength, assertInputStringNumberEnumLike } from './server.assertions';
 import { getOptions } from './options.context';