@agiflowai/one-mcp 0.3.12 → 0.3.14

package/dist/index.d.mts

@@ -1,5 +1,6 @@
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolResult, GetPromptResult, ReadResourceResult } from "@modelcontextprotocol/sdk/types.js";
+import { z } from "zod";
 
 //#region src/types/index.d.ts
 
@@ -65,6 +66,97 @@ interface HttpTransportHandler$1 extends TransportHandler {
   getPort(): number;
   getHost(): string;
 }
+/**
+ * Runtime state persisted for HTTP one-mcp instances.
+ * @property serverId - Unique one-mcp server identifier
+ * @property host - Host bound by the HTTP transport
+ * @property port - Port bound by the HTTP transport
+ * @property transport - Transport mode for the runtime record
+ * @property shutdownToken - Secret token required for admin shutdown requests
+ * @property startedAt - ISO timestamp when the runtime started
+ * @property pid - Process ID of the running one-mcp process
+ * @property configPath - Optional path to the config file used to start the server
+ */
+interface RuntimeStateRecord {
+  serverId: string;
+  host: string;
+  port: number;
+  transport: 'http';
+  shutdownToken: string;
+  startedAt: string;
+  pid: number;
+  configPath?: string;
+}
+/**
+ * Optional admin settings for HTTP transport lifecycle actions.
+ * @property serverId - Server identifier surfaced via health responses
+ * @property shutdownToken - Secret token accepted by the admin shutdown endpoint
+ * @property onShutdownRequested - Callback invoked after a valid shutdown request is received
+ */
+interface HttpTransportAdminOptions {
+  serverId?: string;
+  shutdownToken?: string;
+  onShutdownRequested?: () => Promise<void>;
+}
+/**
+ * Health payload exposed by HTTP transport.
+ * @property status - Health status string for liveness checks
+ * @property transport - Transport mode for the serving endpoint
+ * @property serverId - Optional server identifier for target verification
+ */
+interface HttpTransportHealthResponse {
+  status: 'ok';
+  transport: 'http';
+  serverId?: string;
+}
+/**
+ * Admin shutdown response payload.
+ * @property ok - Whether shutdown request handling succeeded
+ * @property message - Human-readable outcome message
+ * @property serverId - Optional server identifier associated with this response
+ */
+interface HttpTransportShutdownResponse {
+  ok: boolean;
+  message: string;
+  serverId?: string;
+}
+/**
+ * Runtime record lookup filters.
+ * @property host - Optional host filter for runtime discovery
+ * @property port - Optional port filter for runtime discovery
+ */
+interface RuntimeLookupOptions {
+  host?: string;
+  port?: number;
+}
+/**
+ * Runtime service contract.
+ */
+interface RuntimeStateManager {
+  /**
+   * Persist a runtime state record.
+   * @param record - Runtime metadata to persist
+   * @returns Promise that resolves when write completes
+   */
+  write(record: RuntimeStateRecord): Promise<void>;
+  /**
+   * Read a runtime state record by server ID.
+   * @param serverId - Target one-mcp server identifier
+   * @returns Matching runtime record, or null when no record exists
+   */
+  read(serverId: string): Promise<RuntimeStateRecord | null>;
+  /**
+   * List all persisted runtime records.
+   * @returns Array of runtime records
+   */
+  list(): Promise<RuntimeStateRecord[]>;
+  /**
+   * Remove a runtime state record by server ID.
+   * @param serverId - Target one-mcp server identifier
+   * @returns Promise that resolves when delete completes
+   */
+  remove(serverId: string): Promise<void>;
+}
 /**
  * Remote MCP server configuration types
  */
@@ -332,20 +424,35 @@ interface ServerOptions {
   definitionsCachePath?: string;
   clearDefinitionsCache?: boolean;
   proxyMode?: 'meta' | 'flat' | 'search';
+  onServerIdResolved?: (serverId: string) => Promise<void> | void;
 }
 declare function createServer(options?: ServerOptions): Promise<Server>;
 //#endregion
-//#region src/transports/stdio.d.ts
+//#region src/transports/http.d.ts
 /**
- * Stdio transport handler for MCP server
- * Used for command-line and direct integrations
+ * HTTP transport handler using Streamable HTTP (protocol version 2025-03-26)
+ * Provides stateful session management with resumability support
  */
-declare class StdioTransportHandler implements TransportHandler {
+declare class HttpTransportHandler implements HttpTransportHandler$1 {
+  private serverFactory;
+  private app;
   private server;
-  private transport;
-  constructor(server: Server);
+  private sessionManager;
+  private config;
+  private adminOptions?;
+  private adminRateLimiter;
+  constructor(serverFactory: Server | (() => Server), config: TransportConfig, adminOptions?: HttpTransportAdminOptions);
+  private setupMiddleware;
+  private setupRoutes;
+  private isAuthorizedShutdownRequest;
+  private handleAdminShutdownRequest;
+  private handlePostRequest;
+  private handleGetRequest;
+  private handleDeleteRequest;
   start(): Promise<void>;
   stop(): Promise<void>;
+  getPort(): number;
+  getHost(): string;
 }
 //#endregion
 //#region src/transports/sse.d.ts
@@ -371,27 +478,35 @@ declare class SseTransportHandler implements HttpTransportHandler$1 {
   getHost(): string;
 }
 //#endregion
-//#region src/transports/http.d.ts
+//#region src/transports/stdio.d.ts
 /**
- * HTTP transport handler using Streamable HTTP (protocol version 2025-03-26)
- * Provides stateful session management with resumability support
+ * Stdio transport handler for MCP server
+ * Used for command-line and direct integrations
  */
-declare class HttpTransportHandler implements HttpTransportHandler$1 {
-  private serverFactory;
-  private app;
+declare class StdioTransportHandler implements TransportHandler {
   private server;
-  private sessionManager;
-  private config;
-  constructor(serverFactory: Server | (() => Server), config: TransportConfig);
-  private setupMiddleware;
-  private setupRoutes;
-  private handlePostRequest;
-  private handleGetRequest;
-  private handleDeleteRequest;
+  private transport;
+  constructor(server: Server);
   start(): Promise<void>;
   stop(): Promise<void>;
-  getPort(): number;
-  getHost(): string;
+}
+//#endregion
+//#region src/transports/stdio-http.d.ts
+interface StdioHttpProxyTransportConfig {
+  endpoint: URL;
+}
+/**
+ * Transport that serves MCP over stdio and forwards MCP requests to an HTTP endpoint.
+ */
+declare class StdioHttpTransportHandler implements TransportHandler {
+  private readonly endpoint;
+  private stdioProxyServer;
+  private stdioTransport;
+  private httpClient;
+  constructor(config: StdioHttpProxyTransportConfig);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  private createProxyServer;
 }
 //#endregion
 //#region src/services/McpClientManagerService.d.ts
@@ -926,4 +1041,199 @@ declare class ConfigFetcherService {
   isCacheValid(): boolean;
 }
 //#endregion
-export { CachedFileSkillInfo, CachedPromptSkillInfo, CachedServerDefinition, ConfigFetcherService, DefinitionsCacheFile, DefinitionsCacheService, DescribeToolsTool, HttpTransportHandler, McpClientConnection, McpClientManagerService, McpHttpConfig, McpPromptInfo, McpResourceInfo, McpServerConfig, McpServerTransportConfig, McpServerTransportType, McpSseConfig, McpStdioConfig, McpToolInfo, PromptConfig, PromptSkillConfig, RemoteMcpConfiguration, SearchListToolsTool, type ServerOptions, Skill, SkillMetadata, SkillService, SkillsConfig, SseTransportHandler, StdioTransportHandler, TRANSPORT_MODE, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, UseToolTool, createServer };
+//#region src/services/RuntimeStateService.d.ts
+/**
+ * Runtime state persistence implementation.
+ */
+declare class RuntimeStateService implements RuntimeStateManager {
+  private runtimeDir;
+  constructor(runtimeDir?: string);
+  /**
+   * Resolve default runtime directory under the user's home cache path.
+   * @returns Absolute runtime directory path
+   */
+  static getDefaultRuntimeDir(): string;
+  /**
+   * Build runtime state file path for a given server ID.
+   * @param serverId - Target one-mcp server identifier
+   * @returns Absolute runtime file path
+   */
+  private getRecordPath;
+  /**
+   * Persist a runtime state record.
+   * @param record - Runtime metadata to persist
+   * @returns Promise that resolves when write completes
+   */
+  write(record: RuntimeStateRecord): Promise<void>;
+  /**
+   * Read a runtime state record by server ID.
+   * @param serverId - Target one-mcp server identifier
+   * @returns Matching runtime record, or null when no record exists
+   */
+  read(serverId: string): Promise<RuntimeStateRecord | null>;
+  /**
+   * List all persisted runtime records.
+   * @returns Array of runtime records
+   */
+  list(): Promise<RuntimeStateRecord[]>;
+  /**
+   * Remove a runtime state record by server ID.
+   * @param serverId - Target one-mcp server identifier
+   * @returns Promise that resolves when delete completes
+   */
+  remove(serverId: string): Promise<void>;
+}
+//#endregion
+//#region src/services/StopServerService.d.ts
+/**
+ * Stop request options.
+ * @property serverId - Explicit one-mcp server identifier to stop
+ * @property host - Host fallback for runtime lookup
+ * @property port - Port fallback for runtime lookup
+ * @property token - Optional shutdown token override
+ * @property force - Skip server ID verification against /health when true
+ * @property timeoutMs - Maximum time to wait for shutdown completion
+ */
+interface StopServerRequest {
+  serverId?: string;
+  host?: string;
+  port?: number;
+  token?: string;
+  force?: boolean;
+  timeoutMs?: number;
+}
+/**
+ * Stop command result payload.
+ * @property ok - Whether the shutdown completed successfully
+ * @property serverId - Stopped one-mcp server identifier
+ * @property host - Host that served the runtime
+ * @property port - Port that served the runtime
+ * @property message - Human-readable shutdown result message
+ */
+interface StopServerResult {
+  ok: true;
+  serverId: string;
+  host: string;
+  port: number;
+  message: string;
+}
+/**
+ * Service for resolving runtime targets and stopping them safely.
+ */
+declare class StopServerService {
+  private runtimeStateService;
+  constructor(runtimeStateService?: RuntimeStateManager);
+  /**
+   * Resolve a target runtime and stop it cooperatively.
+   * @param request - Stop request options
+   * @returns Stop result payload
+   */
+  stop(request: StopServerRequest): Promise<StopServerResult>;
+  /**
+   * Resolve a runtime record from explicit ID or a unique host/port pair.
+   * @param request - Stop request options
+   * @returns Matching runtime record
+   */
+  private resolveRuntime;
+  /**
+   * Read the runtime health payload.
+   * @param runtime - Runtime to query
+   * @param timeoutMs - Request timeout in milliseconds
+   * @returns Reachability status and optional payload
+   */
+  private fetchHealth;
+  /**
+   * Send authenticated shutdown request to the admin endpoint.
+   * @param runtime - Runtime to stop
+   * @param shutdownToken - Bearer token for the admin endpoint
+   * @param timeoutMs - Request timeout in milliseconds
+   * @returns Parsed shutdown response payload
+   */
+  private requestShutdown;
+  /**
+   * Poll until the target runtime is no longer reachable.
+   * @param runtime - Runtime expected to stop
+   * @param timeoutMs - Maximum wait time in milliseconds
+   * @returns Promise that resolves when shutdown is observed
+   */
+  private waitForShutdown;
+  /**
+   * Perform a fetch with an abort timeout.
+   * @param url - Target URL
+   * @param init - Fetch options
+   * @param timeoutMs - Timeout in milliseconds
+   * @returns Fetch response
+   */
+  private fetchWithTimeout;
+}
+//#endregion
+//#region src/utils/findConfigFile.d.ts
+/**
+ * Config File Finder Utility
+ *
+ * DESIGN PATTERNS:
+ * - Utility function pattern for reusable logic
+ * - Fail-fast pattern with early returns
+ * - Environment variable configuration pattern
+ *
+ * CODING STANDARDS:
+ * - Use sync filesystem operations for config discovery (performance)
+ * - Check PROJECT_PATH environment variable first
+ * - Fall back to current working directory
+ * - Support both .yaml and .json extensions
+ * - Return null if no config file is found
+ *
+ * AVOID:
+ * - Throwing errors (return null instead for optional config)
+ * - Hardcoded file names without extension variants
+ * - Ignoring environment variables
+ */
+/**
+ * Find MCP configuration file by checking PROJECT_PATH first, then cwd
+ * Looks for both mcp-config.yaml and mcp-config.json
+ *
+ * @returns Absolute path to config file, or null if not found
+ */
+declare function findConfigFile(): string | null;
+//#endregion
+//#region src/utils/generateServerId.d.ts
+/**
+ * generateServerId Utilities
+ *
+ * DESIGN PATTERNS:
+ * - Pure functions with no side effects
+ * - Single responsibility per function
+ * - Functional programming approach
+ *
+ * CODING STANDARDS:
+ * - Export individual functions, not classes
+ * - Use descriptive function names with verbs
+ * - Add JSDoc comments for complex logic
+ * - Keep functions small and focused
+ *
+ * AVOID:
+ * - Side effects (mutating external state)
+ * - Stateful logic (use services for state)
+ * - Complex external dependencies
+ */
+/**
+ * Generate a short, human-readable server ID.
+ *
+ * Uses Node.js crypto.randomBytes for cryptographically secure randomness
+ * with rejection sampling to avoid modulo bias.
+ *
+ * The generated ID:
+ * - Is 6 characters long by default
+ * - Uses only lowercase alphanumeric characters
+ * - Excludes confusing characters (0, O, 1, l, I)
+ *
+ * @param length - Length of the ID to generate (default: 6)
+ * @returns A random, human-readable ID
+ *
+ * @example
+ * generateServerId() // "abc234"
+ * generateServerId(4) // "x7mn"
+ */
+declare function generateServerId(length?: number): string;
+//#endregion
+export { CachedFileSkillInfo, CachedPromptSkillInfo, CachedServerDefinition, ConfigFetcherService, DefinitionsCacheFile, DefinitionsCacheService, DescribeToolsTool, HttpTransportAdminOptions, HttpTransportHandler, HttpTransportHealthResponse, HttpTransportShutdownResponse, McpClientConnection, McpClientManagerService, McpHttpConfig, McpPromptInfo, McpResourceInfo, McpServerConfig, McpServerTransportConfig, McpServerTransportType, McpSseConfig, McpStdioConfig, McpToolInfo, PromptConfig, PromptSkillConfig, RemoteMcpConfiguration, RuntimeLookupOptions, RuntimeStateManager, RuntimeStateRecord, RuntimeStateService, SearchListToolsTool, type ServerOptions, Skill, SkillMetadata, SkillService, SkillsConfig, SseTransportHandler, StdioHttpTransportHandler, StdioTransportHandler, type StopServerRequest, type StopServerResult, StopServerService, TRANSPORT_MODE, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, UseToolTool, createServer, findConfigFile, generateServerId };

package/dist/index.mjs

@@ -1,3 +1,3 @@
-import { c as DescribeToolsTool, d as DefinitionsCacheService, i as createServer, l as SkillService, m as ConfigFetcherService, n as SseTransportHandler, o as UseToolTool, r as StdioTransportHandler, s as SearchListToolsTool, t as HttpTransportHandler, u as McpClientManagerService } from "./http-ClRbCldm.mjs";
+import { _ as findConfigFile, a as SseTransportHandler, c as createServer, d as SearchListToolsTool, f as DescribeToolsTool, g as generateServerId, h as DefinitionsCacheService, i as StdioTransportHandler, m as McpClientManagerService, n as RuntimeStateService, o as HttpTransportHandler, p as SkillService, r as StdioHttpTransportHandler, s as TRANSPORT_MODE, t as StopServerService, u as UseToolTool, v as ConfigFetcherService } from "./src-D7Yq1bTx.mjs";
 
-export { ConfigFetcherService, DefinitionsCacheService, DescribeToolsTool, HttpTransportHandler, McpClientManagerService, SearchListToolsTool, SkillService, SseTransportHandler, StdioTransportHandler, UseToolTool, createServer };
+export { ConfigFetcherService, DefinitionsCacheService, DescribeToolsTool, HttpTransportHandler, McpClientManagerService, RuntimeStateService, SearchListToolsTool, SkillService, SseTransportHandler, StdioHttpTransportHandler, StdioTransportHandler, StopServerService, TRANSPORT_MODE, UseToolTool, createServer, findConfigFile, generateServerId };