diff --git a/src/__tests__/options.context.test.ts b/src/__tests__/options.context.test.ts index 9ce4deec..02c6ce58 100644 --- a/src/__tests__/options.context.test.ts +++ b/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'; diff --git a/src/mcpSdk.ts b/src/mcpSdk.ts index 45008184..7961aa5e 100644 --- a/src/mcpSdk.ts +++ b/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 +]; + +/** + * 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 | undefined) => Promise | 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, + 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 @@ const registerResource = ( server.registerResource(name, uriOrTemplate as any, config, callback); }; -export { registerResource }; +export { + registerResource, + type McpTool, + type McpToolCreator, + type McpResourceMetadataMetaConfig, + type McpResourceMetadata, + type McpResource, + type McpResourceCreator +}; diff --git a/src/options.registry.ts b/src/options.registry.ts index 1adccedc..20ec3a9b 100644 --- a/src/options.registry.ts +++ b/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'; diff --git a/src/resource.patternFlyComponentsIndex.ts b/src/resource.patternFlyComponentsIndex.ts index 6113494c..351d4440 100644 --- a/src/resource.patternFlyComponentsIndex.ts +++ b/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'; diff --git a/src/resource.patternFlyContext.ts b/src/resource.patternFlyContext.ts index 14633ab4..79912c8c 100644 --- a/src/resource.patternFlyContext.ts +++ b/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'; diff --git a/src/resource.patternFlyDocsIndex.ts b/src/resource.patternFlyDocsIndex.ts index 6b589f4f..04960937 100644 --- a/src/resource.patternFlyDocsIndex.ts +++ b/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'; diff --git a/src/resource.patternFlyDocsTemplate.ts b/src/resource.patternFlyDocsTemplate.ts index 46d869f1..8472e3b4 100644 --- a/src/resource.patternFlyDocsTemplate.ts +++ b/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'; diff --git a/src/resource.patternFlySchemasIndex.ts b/src/resource.patternFlySchemasIndex.ts index 56c777d1..689eb642 100644 --- a/src/resource.patternFlySchemasIndex.ts +++ b/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'; diff --git a/src/resource.patternFlySchemasTemplate.ts b/src/resource.patternFlySchemasTemplate.ts index 47a1e26a..64fe0575 100644 --- a/src/resource.patternFlySchemasTemplate.ts +++ b/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'; diff --git a/src/server.resourceMeta.ts b/src/server.resourceMeta.ts index da3ffb73..81376f23 100644 --- a/src/server.resourceMeta.ts +++ b/src/server.resourceMeta.ts @@ -7,7 +7,7 @@ import { type McpResourceCreator, type McpResourceMetadata, type McpResourceMetadataMetaConfig -} from './server'; +} from './mcpSdk'; import { buildSearchString, isPlainObject, diff --git a/src/server.resources.ts b/src/server.resources.ts index 41c640ab..121c1690 100644 --- a/src/server.resources.ts +++ b/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'; diff --git a/src/server.tools.ts b/src/server.tools.ts index beb40b1d..378c02be 100644 --- a/src/server.tools.ts +++ b/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, diff --git a/src/server.toolsHost.ts b/src/server.toolsHost.ts index 468a2b11..adfc0c51 100644 --- a/src/server.toolsHost.ts +++ b/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, diff --git a/src/server.toolsHostCreator.ts b/src/server.toolsHostCreator.ts index 23a224bc..1a7010d8 100644 --- a/src/server.toolsHostCreator.ts +++ b/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. diff --git a/src/server.toolsUser.ts b/src/server.toolsUser.ts index 04f8a7d9..e337566d 100644 --- a/src/server.toolsUser.ts +++ b/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'; diff --git a/src/server.ts b/src/server.ts index a2d66c85..57aee95f 100644 --- a/src/server.ts +++ b/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 -]; - -/** - * 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 | undefined) => Promise | 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, - 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, diff --git a/src/tool.patternFlyDocs.ts b/src/tool.patternFlyDocs.ts index 9340375d..d41ae0d8 100644 --- a/src/tool.patternFlyDocs.ts +++ b/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 { diff --git a/src/tool.searchPatternFlyDocs.ts b/src/tool.searchPatternFlyDocs.ts index 092332f3..7aa87441 100644 --- a/src/tool.searchPatternFlyDocs.ts +++ b/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';