@mcp-z/client 1.0.0

package/dist/cjs/search/types.d.cts

@@ -0,0 +1,122 @@
+/**
+ * Search types for MCP capability discovery
+ *
+ * Enables agents to discover tools, prompts, and resources without
+ * loading full schemas into context.
+ */
+import type { PromptArgument } from '../connection/types.js';
+/**
+ * Types of MCP capabilities that can be searched
+ */
+export type CapabilityType = 'tool' | 'prompt' | 'resource';
+/**
+ * Fields that can be searched within capabilities
+ */
+export type SearchField = 'name' | 'description' | 'schema' | 'server';
+/**
+ * Options for configuring search behavior
+ */
+export interface SearchOptions {
+    /**
+     * Filter to specific capability types
+     * @default ['tool', 'prompt', 'resource']
+     */
+    types?: CapabilityType[];
+    /**
+     * Filter to specific servers by name
+     * @default all servers in config
+     */
+    servers?: string[];
+    /**
+     * Which fields to search within
+     * @default ['name', 'description', 'schema']
+     */
+    searchFields?: SearchField[];
+    /**
+     * Maximum number of results to return
+     * @default 20
+     */
+    limit?: number;
+    /**
+     * Minimum relevance score (0-1) for results
+     * @default 0
+     */
+    threshold?: number;
+}
+/**
+ * A single search result representing a matched capability
+ */
+export interface SearchResult {
+    /** The type of capability */
+    type: CapabilityType;
+    /** The server that provides this capability */
+    server: string;
+    /** The name of the capability */
+    name: string;
+    /** Human-readable description (may be truncated) */
+    description: string | undefined;
+    /** Which fields matched the search query */
+    matchedOn: string[];
+    /** Relevance score from 0 (low) to 1 (high) */
+    score: number;
+}
+/**
+ * Complete search response
+ */
+export interface SearchResponse {
+    /** The original search query */
+    query: string;
+    /** Matching results, sorted by relevance */
+    results: SearchResult[];
+    /** Total number of matches before limit was applied */
+    total: number;
+}
+/**
+ * Internal representation of a tool for indexing
+ */
+export interface IndexedTool {
+    type: 'tool';
+    server: string;
+    name: string;
+    description: string | undefined;
+    /** Flattened searchable text from inputSchema property descriptions */
+    schemaText: string;
+}
+/**
+ * Internal representation of a prompt for indexing
+ */
+export interface IndexedPrompt {
+    type: 'prompt';
+    server: string;
+    name: string;
+    description: string | undefined;
+    /** Flattened searchable text from arguments */
+    argumentsText: string;
+    arguments: PromptArgument[] | undefined;
+}
+/**
+ * Internal representation of a resource for indexing
+ */
+export interface IndexedResource {
+    type: 'resource';
+    server: string;
+    name: string;
+    description: string | undefined;
+    uri: string;
+    mimeType: string | undefined;
+}
+/**
+ * Union of all indexed capability types
+ */
+export type IndexedCapability = IndexedTool | IndexedPrompt | IndexedResource;
+/**
+ * Index containing all capabilities from connected servers
+ */
+export interface CapabilityIndex {
+    /** All indexed capabilities */
+    capabilities: IndexedCapability[];
+    /** Servers that were indexed */
+    servers: string[];
+    /** When the index was created */
+    indexedAt: Date;
+}

package/dist/cjs/search/types.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Search types for MCP capability discovery
+ *
+ * Enables agents to discover tools, prompts, and resources without
+ * loading full schemas into context.
+ */
+import type { PromptArgument } from '../connection/types.js';
+/**
+ * Types of MCP capabilities that can be searched
+ */
+export type CapabilityType = 'tool' | 'prompt' | 'resource';
+/**
+ * Fields that can be searched within capabilities
+ */
+export type SearchField = 'name' | 'description' | 'schema' | 'server';
+/**
+ * Options for configuring search behavior
+ */
+export interface SearchOptions {
+    /**
+     * Filter to specific capability types
+     * @default ['tool', 'prompt', 'resource']
+     */
+    types?: CapabilityType[];
+    /**
+     * Filter to specific servers by name
+     * @default all servers in config
+     */
+    servers?: string[];
+    /**
+     * Which fields to search within
+     * @default ['name', 'description', 'schema']
+     */
+    searchFields?: SearchField[];
+    /**
+     * Maximum number of results to return
+     * @default 20
+     */
+    limit?: number;
+    /**
+     * Minimum relevance score (0-1) for results
+     * @default 0
+     */
+    threshold?: number;
+}
+/**
+ * A single search result representing a matched capability
+ */
+export interface SearchResult {
+    /** The type of capability */
+    type: CapabilityType;
+    /** The server that provides this capability */
+    server: string;
+    /** The name of the capability */
+    name: string;
+    /** Human-readable description (may be truncated) */
+    description: string | undefined;
+    /** Which fields matched the search query */
+    matchedOn: string[];
+    /** Relevance score from 0 (low) to 1 (high) */
+    score: number;
+}
+/**
+ * Complete search response
+ */
+export interface SearchResponse {
+    /** The original search query */
+    query: string;
+    /** Matching results, sorted by relevance */
+    results: SearchResult[];
+    /** Total number of matches before limit was applied */
+    total: number;
+}
+/**
+ * Internal representation of a tool for indexing
+ */
+export interface IndexedTool {
+    type: 'tool';
+    server: string;
+    name: string;
+    description: string | undefined;
+    /** Flattened searchable text from inputSchema property descriptions */
+    schemaText: string;
+}
+/**
+ * Internal representation of a prompt for indexing
+ */
+export interface IndexedPrompt {
+    type: 'prompt';
+    server: string;
+    name: string;
+    description: string | undefined;
+    /** Flattened searchable text from arguments */
+    argumentsText: string;
+    arguments: PromptArgument[] | undefined;
+}
+/**
+ * Internal representation of a resource for indexing
+ */
+export interface IndexedResource {
+    type: 'resource';
+    server: string;
+    name: string;
+    description: string | undefined;
+    uri: string;
+    mimeType: string | undefined;
+}
+/**
+ * Union of all indexed capability types
+ */
+export type IndexedCapability = IndexedTool | IndexedPrompt | IndexedResource;
+/**
+ * Index containing all capabilities from connected servers
+ */
+export interface CapabilityIndex {
+    /** All indexed capabilities */
+    capabilities: IndexedCapability[];
+    /** Servers that were indexed */
+    servers: string[];
+    /** When the index was created */
+    indexedAt: Date;
+}

package/dist/cjs/search/types.js

@@ -0,0 +1,10 @@
+/**
+ * Search types for MCP capability discovery
+ *
+ * Enables agents to discover tools, prompts, and resources without
+ * loading full schemas into context.
+ */ "use strict";
+Object.defineProperty(exports, "__esModule", {
+    value: true
+});
+/* CJS INTEROP */ if (exports.__esModule && exports.default) { try { Object.defineProperty(exports.default, '__esModule', { value: true }); for (var key in exports) { exports.default[key] = exports[key]; } } catch (_) {}; module.exports = exports.default; }

package/dist/cjs/search/types.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["/Users/kevin/Dev/Projects/ai/mcp-z/libs/client/src/search/types.ts"],"sourcesContent":["/**\n * Search types for MCP capability discovery\n *\n * Enables agents to discover tools, prompts, and resources without\n * loading full schemas into context.\n */\n\nimport type { PromptArgument } from '../connection/types.ts';\n\n/**\n * Types of MCP capabilities that can be searched\n */\nexport type CapabilityType = 'tool' | 'prompt' | 'resource';\n\n/**\n * Fields that can be searched within capabilities\n */\nexport type SearchField = 'name' | 'description' | 'schema' | 'server';\n\n/**\n * Options for configuring search behavior\n */\nexport interface SearchOptions {\n  /**\n   * Filter to specific capability types\n   * @default ['tool', 'prompt', 'resource']\n   */\n  types?: CapabilityType[];\n\n  /**\n   * Filter to specific servers by name\n   * @default all servers in config\n   */\n  servers?: string[];\n\n  /**\n   * Which fields to search within\n   * @default ['name', 'description', 'schema']\n   */\n  searchFields?: SearchField[];\n\n  /**\n   * Maximum number of results to return\n   * @default 20\n   */\n  limit?: number;\n\n  /**\n   * Minimum relevance score (0-1) for results\n   * @default 0\n   */\n  threshold?: number;\n}\n\n/**\n * A single search result representing a matched capability\n */\nexport interface SearchResult {\n  /** The type of capability */\n  type: CapabilityType;\n\n  /** The server that provides this capability */\n  server: string;\n\n  /** The name of the capability */\n  name: string;\n\n  /** Human-readable description (may be truncated) */\n  description: string | undefined;\n\n  /** Which fields matched the search query */\n  matchedOn: string[];\n\n  /** Relevance score from 0 (low) to 1 (high) */\n  score: number;\n}\n\n/**\n * Complete search response\n */\nexport interface SearchResponse {\n  /** The original search query */\n  query: string;\n\n  /** Matching results, sorted by relevance */\n  results: SearchResult[];\n\n  /** Total number of matches before limit was applied */\n  total: number;\n}\n\n/**\n * Internal representation of a tool for indexing\n */\nexport interface IndexedTool {\n  type: 'tool';\n  server: string;\n  name: string;\n  description: string | undefined;\n  /** Flattened searchable text from inputSchema property descriptions */\n  schemaText: string;\n}\n\n/**\n * Internal representation of a prompt for indexing\n */\nexport interface IndexedPrompt {\n  type: 'prompt';\n  server: string;\n  name: string;\n  description: string | undefined;\n  /** Flattened searchable text from arguments */\n  argumentsText: string;\n  arguments: PromptArgument[] | undefined;\n}\n\n/**\n * Internal representation of a resource for indexing\n */\nexport interface IndexedResource {\n  type: 'resource';\n  server: string;\n  name: string;\n  description: string | undefined;\n  uri: string;\n  mimeType: string | undefined;\n}\n\n/**\n * Union of all indexed capability types\n */\nexport type IndexedCapability = IndexedTool | IndexedPrompt | IndexedResource;\n\n/**\n * Index containing all capabilities from connected servers\n */\nexport interface CapabilityIndex {\n  /** All indexed capabilities */\n  capabilities: IndexedCapability[];\n\n  /** Servers that were indexed */\n  servers: string[];\n\n  /** When the index was created */\n  indexedAt: Date;\n}\n"],"names":[],"mappings":"AAAA;;;;;CAKC"}

package/dist/cjs/spawn/spawn-server.d.cts

@@ -0,0 +1,83 @@
+/**
+ * Low-level single server spawning utilities.
+ * Provides core process spawning with path resolution, environment management, and lifecycle control.
+ */
+import { type ChildProcess, type StdioOptions } from 'child_process';
+/**
+ * Options for spawning a single server process.
+ * @internal
+ */
+export interface SpawnProcessOptions {
+    /** Server name for logging */
+    name: string;
+    /** Command to execute (e.g., 'node', 'npx') */
+    command: string;
+    /** Command arguments (paths will be resolved relative to cwd) */
+    args?: string[];
+    /** Working directory (must be absolute path) */
+    cwd?: string;
+    /** Additional environment variables (merged with process.env) */
+    env?: Record<string, string>;
+    /** Standard I/O configuration */
+    stdio?: StdioOptions;
+    /** Use shell for command execution (default: false, true on Windows) */
+    shell?: boolean;
+}
+/**
+ * Handle to a spawned server process.
+ * Provides access to the process, resolved config, and lifecycle control.
+ * @hidden
+ */
+export interface ServerProcess {
+    /**
+     * The resolved server configuration that was actually used.
+     * Useful for debugging and understanding what was spawned.
+     */
+    config: {
+        name: string;
+        command: string;
+        args: string[];
+        cwd: string;
+        env: Record<string, string>;
+        stdio: StdioOptions;
+        shell: boolean;
+    };
+    /**
+     * The spawned child process.
+     */
+    process: ChildProcess;
+    /**
+     * Close the server gracefully.
+     * Sends the specified signal (default: SIGINT), then SIGKILL after timeout.
+     *
+     * @param signal - Signal to send (default: SIGINT)
+     * @param opts - Options including timeout
+     * @returns Promise resolving to whether the process timed out and was force-killed
+     */
+    close: (signal?: NodeJS.Signals, opts?: {
+        timeoutMs?: number;
+    }) => Promise<{
+        timedOut: boolean;
+        killed: boolean;
+    }>;
+}
+/**
+ * Spawn a single server process with path resolution and environment management.
+ *
+ * @internal
+ * @param opts - Server spawn options
+ * @returns ServerProcess handle with resolved config, process, and stop function
+ *
+ * @example
+ * const handle = spawnProcess({
+ *   name: 'echo',
+ *   command: 'node',
+ *   args: ['./bin/server.js', '--port', '3000'],
+ *   cwd: '/home/user/project/test/lib/servers/echo',
+ *   env: { LOG_LEVEL: 'error' }
+ * });
+ *
+ * // Later...
+ * await handle.close();
+ */
+export declare function spawnProcess(opts: SpawnProcessOptions): ServerProcess;

package/dist/cjs/spawn/spawn-server.d.ts

@@ -0,0 +1,83 @@
+/**
+ * Low-level single server spawning utilities.
+ * Provides core process spawning with path resolution, environment management, and lifecycle control.
+ */
+import { type ChildProcess, type StdioOptions } from 'child_process';
+/**
+ * Options for spawning a single server process.
+ * @internal
+ */
+export interface SpawnProcessOptions {
+    /** Server name for logging */
+    name: string;
+    /** Command to execute (e.g., 'node', 'npx') */
+    command: string;
+    /** Command arguments (paths will be resolved relative to cwd) */
+    args?: string[];
+    /** Working directory (must be absolute path) */
+    cwd?: string;
+    /** Additional environment variables (merged with process.env) */
+    env?: Record<string, string>;
+    /** Standard I/O configuration */
+    stdio?: StdioOptions;
+    /** Use shell for command execution (default: false, true on Windows) */
+    shell?: boolean;
+}
+/**
+ * Handle to a spawned server process.
+ * Provides access to the process, resolved config, and lifecycle control.
+ * @hidden
+ */
+export interface ServerProcess {
+    /**
+     * The resolved server configuration that was actually used.
+     * Useful for debugging and understanding what was spawned.
+     */
+    config: {
+        name: string;
+        command: string;
+        args: string[];
+        cwd: string;
+        env: Record<string, string>;
+        stdio: StdioOptions;
+        shell: boolean;
+    };
+    /**
+     * The spawned child process.
+     */
+    process: ChildProcess;
+    /**
+     * Close the server gracefully.
+     * Sends the specified signal (default: SIGINT), then SIGKILL after timeout.
+     *
+     * @param signal - Signal to send (default: SIGINT)
+     * @param opts - Options including timeout
+     * @returns Promise resolving to whether the process timed out and was force-killed
+     */
+    close: (signal?: NodeJS.Signals, opts?: {
+        timeoutMs?: number;
+    }) => Promise<{
+        timedOut: boolean;
+        killed: boolean;
+    }>;
+}
+/**
+ * Spawn a single server process with path resolution and environment management.
+ *
+ * @internal
+ * @param opts - Server spawn options
+ * @returns ServerProcess handle with resolved config, process, and stop function
+ *
+ * @example
+ * const handle = spawnProcess({
+ *   name: 'echo',
+ *   command: 'node',
+ *   args: ['./bin/server.js', '--port', '3000'],
+ *   cwd: '/home/user/project/test/lib/servers/echo',
+ *   env: { LOG_LEVEL: 'error' }
+ * });
+ *
+ * // Later...
+ * await handle.close();
+ */
+export declare function spawnProcess(opts: SpawnProcessOptions): ServerProcess;