@agimon-ai/imagine-mcp 0.2.0

package/dist/commands-c927CRZc.mjs

@@ -0,0 +1,83 @@
+import { i as createServer, n as SseTransportHandler, r as HttpTransportHandler, t as StdioTransportHandler } from "./stdio-CuIrQe3m.mjs";
+import { Command } from "commander";
+
+//#region src/types/index.ts
+/**
+* Transport mode types
+*/
+let TransportMode = /* @__PURE__ */ function(TransportMode$1) {
+	TransportMode$1["STDIO"] = "stdio";
+	TransportMode$1["HTTP"] = "http";
+	TransportMode$1["SSE"] = "sse";
+	return TransportMode$1;
+}({});
+
+//#endregion
+//#region src/commands/mcp-serve.ts
+/**
+* MCP Serve Command
+*
+* DESIGN PATTERNS:
+* - Command pattern with Commander for CLI argument parsing
+* - Transport abstraction pattern for flexible deployment (stdio, HTTP, SSE)
+* - Factory pattern for creating transport handlers
+* - Graceful shutdown pattern with signal handling
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Implement proper error handling with try-catch blocks
+* - Handle process signals for graceful shutdown
+* - Provide clear CLI options and help messages
+*
+* AVOID:
+* - Hardcoded configuration values (use CLI options or environment variables)
+* - Missing error handling for transport startup
+* - Not cleaning up resources on shutdown
+*/
+/**
+* Start MCP server with given transport handler
+*/
+async function startServer(handler) {
+	await handler.start();
+	const shutdown = async (signal) => {
+		process.stderr.write(`\nReceived ${signal}, shutting down gracefully...\n`);
+		try {
+			await handler.stop();
+			process.exit(0);
+		} catch (error) {
+			process.stderr.write(`Error during shutdown: ${error instanceof Error ? error.message : String(error)}\n`);
+			process.exit(1);
+		}
+	};
+	process.on("SIGINT", () => shutdown("SIGINT"));
+	process.on("SIGTERM", () => shutdown("SIGTERM"));
+}
+/**
+* MCP Serve command
+*/
+const mcpServeCommand = new Command("mcp-serve").description("Start MCP server with specified transport").option("-t, --type <type>", "Transport type: stdio, http, or sse", "stdio").option("-p, --port <port>", "Port to listen on (http/sse only)", (val) => parseInt(val, 10), 3e3).option("--host <host>", "Host to bind to (http/sse only)", "localhost").action(async (options) => {
+	try {
+		const transportType = options.type.toLowerCase();
+		if (transportType === "stdio") await startServer(new StdioTransportHandler(createServer()));
+		else if (transportType === "http") await startServer(new HttpTransportHandler(() => createServer(), {
+			mode: TransportMode.HTTP,
+			port: options.port || Number(process.env.MCP_PORT) || 3e3,
+			host: options.host || process.env.MCP_HOST || "localhost"
+		}));
+		else if (transportType === "sse") await startServer(new SseTransportHandler(() => createServer(), {
+			mode: TransportMode.SSE,
+			port: options.port || Number(process.env.MCP_PORT) || 3e3,
+			host: options.host || process.env.MCP_HOST || "localhost"
+		}));
+		else {
+			process.stderr.write(`Unknown transport type: ${transportType}. Use: stdio, http, or sse\n`);
+			process.exit(1);
+		}
+	} catch (error) {
+		process.stderr.write(`Failed to start MCP server: ${error instanceof Error ? error.message : String(error)}\n`);
+		process.exit(1);
+	}
+});
+
+//#endregion
+export { mcpServeCommand };

package/dist/index.cjs

@@ -0,0 +1,8 @@
+const require_stdio = require('./stdio-D7OcvsZd.cjs');
+
+exports.HttpTransportHandler = require_stdio.HttpTransportHandler;
+exports.ReadImageTool = require_stdio.ReadImageTool;
+exports.SseTransportHandler = require_stdio.SseTransportHandler;
+exports.StdioTransportHandler = require_stdio.StdioTransportHandler;
+exports.UnsplashSearchTool = require_stdio.UnsplashSearchTool;
+exports.createServer = require_stdio.createServer;

package/dist/index.d.cts

@@ -0,0 +1,150 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+//#region src/server/index.d.ts
+
+declare function createServer(): Server;
+//#endregion
+//#region src/types/index.d.ts
+
+/**
+ * Tool definition for MCP
+ */
+interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required?: string[];
+    additionalProperties?: boolean;
+  };
+}
+/**
+ * Base tool interface following MCP SDK patterns
+ */
+interface Tool<TInput = any> {
+  getDefinition(): ToolDefinition;
+  execute(input: TInput): Promise<CallToolResult>;
+}
+/**
+ * Transport mode types
+ */
+declare enum TransportMode {
+  STDIO = "stdio",
+  HTTP = "http",
+  SSE = "sse",
+}
+/**
+ * Transport configuration options
+ */
+interface TransportConfig {
+  mode: TransportMode;
+  port?: number;
+  host?: string;
+}
+/**
+ * Base interface for all transport handlers
+ */
+interface TransportHandler {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+/**
+ * HTTP transport specific types
+ */
+interface HttpTransportHandler$1 extends TransportHandler {
+  getPort(): number;
+  getHost(): string;
+}
+//#endregion
+//#region src/tools/ReadImageTool.d.ts
+interface ReadImageToolInput {
+  source: string;
+  includeBase64?: boolean;
+}
+declare class ReadImageTool implements Tool<ReadImageToolInput> {
+  static readonly TOOL_NAME = "read-image";
+  private service;
+  getDefinition(): ToolDefinition;
+  execute(input: ReadImageToolInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tools/UnsplashSearchTool.d.ts
+interface UnsplashSearchToolInput {
+  query: string;
+  perPage?: number;
+  page?: number;
+  orientation?: 'landscape' | 'portrait' | 'squarish';
+  color?: 'black_and_white' | 'black' | 'white' | 'yellow' | 'orange' | 'red' | 'purple' | 'magenta' | 'green' | 'teal' | 'blue';
+}
+declare class UnsplashSearchTool implements Tool<UnsplashSearchToolInput> {
+  static readonly TOOL_NAME = "unsplash_search";
+  private service;
+  private readonly accessKey?;
+  constructor(accessKey?: string);
+  private getService;
+  getDefinition(): ToolDefinition;
+  execute(input: UnsplashSearchToolInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/transports/http.d.ts
+/**
+ * HTTP transport handler using Streamable HTTP (protocol version 2025-03-26)
+ * Provides stateful session management with resumability support
+ */
+declare class HttpTransportHandler implements HttpTransportHandler$1 {
+  private serverFactory;
+  private app;
+  private server;
+  private sessionManager;
+  private config;
+  constructor(serverFactory: Server | (() => Server), config: TransportConfig);
+  private setupMiddleware;
+  private setupRoutes;
+  private handlePostRequest;
+  private handleGetRequest;
+  private handleDeleteRequest;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  getPort(): number;
+  getHost(): string;
+}
+//#endregion
+//#region src/transports/sse.d.ts
+/**
+ * SSE (Server-Sent Events) transport handler
+ * Legacy transport for backwards compatibility (protocol version 2024-11-05)
+ * Uses separate endpoints: /sse for SSE stream (GET) and /messages for client messages (POST)
+ */
+declare class SseTransportHandler implements HttpTransportHandler$1 {
+  private serverFactory;
+  private app;
+  private server;
+  private sessionManager;
+  private config;
+  constructor(serverFactory: Server | (() => Server), config: TransportConfig);
+  private setupMiddleware;
+  private setupRoutes;
+  private handleSseConnection;
+  private handlePostMessage;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  getPort(): number;
+  getHost(): string;
+}
+//#endregion
+//#region src/transports/stdio.d.ts
+/**
+ * Stdio transport handler for MCP server
+ * Used for command-line and direct integrations
+ */
+declare class StdioTransportHandler implements TransportHandler {
+  private server;
+  private transport;
+  constructor(server: Server);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+//#endregion
+export { HttpTransportHandler, ReadImageTool, SseTransportHandler, StdioTransportHandler, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, UnsplashSearchTool, createServer };

package/dist/index.d.mts

@@ -0,0 +1,150 @@
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+
+//#region src/server/index.d.ts
+
+declare function createServer(): Server;
+//#endregion
+//#region src/types/index.d.ts
+
+/**
+ * Tool definition for MCP
+ */
+interface ToolDefinition {
+  name: string;
+  description: string;
+  inputSchema: {
+    type: string;
+    properties: Record<string, any>;
+    required?: string[];
+    additionalProperties?: boolean;
+  };
+}
+/**
+ * Base tool interface following MCP SDK patterns
+ */
+interface Tool<TInput = any> {
+  getDefinition(): ToolDefinition;
+  execute(input: TInput): Promise<CallToolResult>;
+}
+/**
+ * Transport mode types
+ */
+declare enum TransportMode {
+  STDIO = "stdio",
+  HTTP = "http",
+  SSE = "sse",
+}
+/**
+ * Transport configuration options
+ */
+interface TransportConfig {
+  mode: TransportMode;
+  port?: number;
+  host?: string;
+}
+/**
+ * Base interface for all transport handlers
+ */
+interface TransportHandler {
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+/**
+ * HTTP transport specific types
+ */
+interface HttpTransportHandler$1 extends TransportHandler {
+  getPort(): number;
+  getHost(): string;
+}
+//#endregion
+//#region src/tools/ReadImageTool.d.ts
+interface ReadImageToolInput {
+  source: string;
+  includeBase64?: boolean;
+}
+declare class ReadImageTool implements Tool<ReadImageToolInput> {
+  static readonly TOOL_NAME = "read-image";
+  private service;
+  getDefinition(): ToolDefinition;
+  execute(input: ReadImageToolInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/tools/UnsplashSearchTool.d.ts
+interface UnsplashSearchToolInput {
+  query: string;
+  perPage?: number;
+  page?: number;
+  orientation?: 'landscape' | 'portrait' | 'squarish';
+  color?: 'black_and_white' | 'black' | 'white' | 'yellow' | 'orange' | 'red' | 'purple' | 'magenta' | 'green' | 'teal' | 'blue';
+}
+declare class UnsplashSearchTool implements Tool<UnsplashSearchToolInput> {
+  static readonly TOOL_NAME = "unsplash_search";
+  private service;
+  private readonly accessKey?;
+  constructor(accessKey?: string);
+  private getService;
+  getDefinition(): ToolDefinition;
+  execute(input: UnsplashSearchToolInput): Promise<CallToolResult>;
+}
+//#endregion
+//#region src/transports/http.d.ts
+/**
+ * HTTP transport handler using Streamable HTTP (protocol version 2025-03-26)
+ * Provides stateful session management with resumability support
+ */
+declare class HttpTransportHandler implements HttpTransportHandler$1 {
+  private serverFactory;
+  private app;
+  private server;
+  private sessionManager;
+  private config;
+  constructor(serverFactory: Server | (() => Server), config: TransportConfig);
+  private setupMiddleware;
+  private setupRoutes;
+  private handlePostRequest;
+  private handleGetRequest;
+  private handleDeleteRequest;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  getPort(): number;
+  getHost(): string;
+}
+//#endregion
+//#region src/transports/sse.d.ts
+/**
+ * SSE (Server-Sent Events) transport handler
+ * Legacy transport for backwards compatibility (protocol version 2024-11-05)
+ * Uses separate endpoints: /sse for SSE stream (GET) and /messages for client messages (POST)
+ */
+declare class SseTransportHandler implements HttpTransportHandler$1 {
+  private serverFactory;
+  private app;
+  private server;
+  private sessionManager;
+  private config;
+  constructor(serverFactory: Server | (() => Server), config: TransportConfig);
+  private setupMiddleware;
+  private setupRoutes;
+  private handleSseConnection;
+  private handlePostMessage;
+  start(): Promise<void>;
+  stop(): Promise<void>;
+  getPort(): number;
+  getHost(): string;
+}
+//#endregion
+//#region src/transports/stdio.d.ts
+/**
+ * Stdio transport handler for MCP server
+ * Used for command-line and direct integrations
+ */
+declare class StdioTransportHandler implements TransportHandler {
+  private server;
+  private transport;
+  constructor(server: Server);
+  start(): Promise<void>;
+  stop(): Promise<void>;
+}
+//#endregion
+export { HttpTransportHandler, ReadImageTool, SseTransportHandler, StdioTransportHandler, Tool, ToolDefinition, TransportConfig, TransportHandler, TransportMode, UnsplashSearchTool, createServer };

package/dist/index.mjs

@@ -0,0 +1,3 @@
+import { a as UnsplashSearchTool, i as createServer, n as SseTransportHandler, o as ReadImageTool, r as HttpTransportHandler, t as StdioTransportHandler } from "./stdio-CuIrQe3m.mjs";
+
+export { HttpTransportHandler, ReadImageTool, SseTransportHandler, StdioTransportHandler, UnsplashSearchTool, createServer };