@agimon-ai/imagine-mcp 0.2.0

package/LICENSE

@@ -0,0 +1,52 @@
+Business Source License 1.1
+
+Parameters
+
+Licensor:             AgiFlow
+Licensed Work:        @agimon-ai/public-packages
+                      The Licensed Work is (c) 2026 AgiFlow.
+Additional Use Grant: None
+Change Date:          2030-03-06
+Change License:       Apache License, Version 2.0
+
+Terms
+
+The Licensor hereby grants you the right to copy, modify, create derivative
+works, redistribute, and make non-production use of the Licensed Work. The
+Licensor may make an Additional Use Grant, above, permitting limited
+production use.
+
+Effective on the Change Date, or the fourth anniversary of the first publicly
+available distribution of a specific version of the Licensed Work under this
+License, whichever comes first, the Licensor hereby grants you rights under
+the terms of the Change License, and the rights granted in the paragraph
+above terminate.
+
+If your use of the Licensed Work does not comply with the requirements
+currently in effect as described in this License, you must purchase a
+commercial license from the Licensor, its affiliated entities, or authorized
+resellers, or you must refrain from using the Licensed Work.
+
+All copies of the original and modified Licensed Work, and derivative works
+of the Licensed Work, are subject to this License. This License applies
+separately for each version of the Licensed Work and the Change Date may vary
+for each version of the Licensed Work released by Licensor.
+
+You must conspicuously display this License on each original or modified copy
+of the Licensed Work. If you receive the Licensed Work in original or
+modified form from a third party, the terms and conditions set forth in this
+License apply to your use of that work.
+
+Any use of the Licensed Work in violation of this License will automatically
+terminate your rights under this License for the current and all other
+versions of the Licensed Work.
+
+This License does not grant you any right in any trademark or logo of
+Licensor or its affiliates (provided that you may use a trademark or logo of
+Licensor as expressly required by this License).
+
+TO THE EXTENT PERMITTED BY APPLICABLE LAW, THE LICENSED WORK IS PROVIDED ON
+AN "AS IS" BASIS. LICENSOR HEREBY DISCLAIMS ALL WARRANTIES AND CONDITIONS,
+EXPRESS OR IMPLIED, INCLUDING (WITHOUT LIMITATION) WARRANTIES OF
+MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT, AND
+TITLE.

package/README.md

@@ -0,0 +1,144 @@
+# imagine-mcp
+
+MCP server for AI image generation and manipulation. Currently supports stock image search via Unsplash.
+and local image reading from file path, URL, or data URI.
+
+## Features
+
+### Stock Image Search (Unsplash)
+- Search for high-quality stock photos from Unsplash
+- Filter by orientation (landscape, portrait, squarish)
+- Filter by color
+- Pagination support
+- Returns image URLs in multiple sizes (full, regular, small, thumbnail)
+- Includes photographer attribution and links
+
+### Image Reader
+- Read raw image bytes from local file paths, HTTP(S) URLs, or data URIs
+- Returns source metadata (`source`, `sourceType`, `mimeType`, `sizeBytes`, `sha256`)
+- Optionally returns `base64` in the tool response
+
+## Prerequisites
+
+### Unsplash API Key
+You need an Unsplash API access key to use the stock image search feature.
+The `read-image` tool works without any upload or provider credentials.
+
+1. Sign up at [Unsplash Developers](https://unsplash.com/developers)
+2. Create a new application
+3. Copy your Access Key
+4. Set the environment variable: `export UNSPLASH_ACCESS_KEY=your_access_key_here`
+
+## Installation
+
+```bash
+pnpm install
+```
+
+## Development
+
+```bash
+# Set your Unsplash API key
+export UNSPLASH_ACCESS_KEY=your_access_key_here
+
+# Run in development mode (stdio transport)
+pnpm dev
+
+# Run with HTTP transport
+pnpm dev mcp-serve --type http --port 3000
+
+# Run with SSE transport
+pnpm dev mcp-serve --type sse --port 3000
+```
+
+## Build
+
+```bash
+pnpm build
+```
+
+## Test
+
+```bash
+pnpm test
+```
+
+## Usage with Claude Code
+
+Add to your Claude Code configuration:
+
+```json
+{
+  "mcpServers": {
+    "imagine-mcp": {
+      "command": "node",
+      "args": ["/path/to/imagine-mcp/dist/cli.cjs", "mcp-serve"],
+      "env": {
+        "UNSPLASH_ACCESS_KEY": "your_access_key_here"
+      }
+    }
+  }
+}
+```
+
+## Available Tools
+
+### unsplash_search
+
+Search for stock images from Unsplash.
+
+**Parameters:**
+- `query` (required): Search query (e.g., "sunset", "technology", "nature")
+- `perPage` (optional): Number of results per page (1-30, default: 10)
+- `page` (optional): Page number for pagination (default: 1)
+- `orientation` (optional): Filter by photo orientation ("landscape", "portrait", "squarish")
+- `color` (optional): Filter by photo color ("black_and_white", "black", "white", "yellow", "orange", "red", "purple", "magenta", "green", "teal", "blue")
+
+**Example usage in Claude Code:**
+```
+Search Unsplash for sunset photos
+Search Unsplash for landscape technology images
+Find portrait photos of people in blue tones
+```
+
+**Response includes:**
+- Image ID and description
+- Photographer name and profile
+- Image dimensions and color
+- URLs for different sizes (full, regular, small, thumbnail)
+- Links to view on Unsplash and download
+- Like count
+
+### read-image
+
+Read image data from different sources and return metadata.
+
+**Parameters:**
+- `source` (required): File path, URL, or data URI
+- `includeBase64` (optional): Set true to include base64 output in response
+
+**Response includes:**
+- `source`: original source input (normalized path or URL)
+- `sourceType`: `"file" | "url" | "data-uri"`
+- `mimeType`: detected MIME type
+- `sizeBytes`: byte length
+- `sha256`: SHA-256 hash of bytes
+
+## Adding New Tools
+
+To add new image generation or manipulation tools:
+
+1. Create a new tool:
+   ```bash
+   # Use the scaffold feature
+   nx run imagine-mcp:list-scaffolds
+   # Or manually create in src/tools/
+   ```
+
+2. Register the tool in `src/server/index.ts`
+
+3. Build and test
+
+## License
+
+AGPL-3.0

package/dist/cli.cjs

@@ -0,0 +1,129 @@
+#!/usr/bin/env node
+const require_stdio = require('./stdio-D7OcvsZd.cjs');
+let commander = require("commander");
+
+//#region src/cli.ts
+/**
+* MCP Server Entry Point
+*
+* DESIGN PATTERNS:
+* - CLI pattern with Commander for argument parsing
+* - Lazy command loading for fast startup
+* - Transport abstraction for multiple communication methods
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Handle errors gracefully with try-catch
+* - Log important events for debugging
+* - Load commands lazily to minimize startup time
+*
+* AVOID:
+* - Hardcoding command logic in index.ts (use separate command files)
+* - Missing error handling for command execution
+* - Eager loading of all commands at startup
+*/
+const packageJson = { version: "0.1.0" };
+const commandDefinitions = [{
+	name: "mcp-serve",
+	description: "Start MCP server with specified transport",
+	loader: () => Promise.resolve().then(() => require("./commands-BlRAon0l.cjs")).then((m) => m.mcpServeCommand)
+}];
+/**
+* Custom error for CLI execution failures with error codes and cause chaining.
+*/
+var CLIExecutionError = class extends Error {
+	code;
+	recovery;
+	constructor(message, code = "CLI_EXECUTION_FAILED", options) {
+		super(message, options);
+		this.name = "CLIExecutionError";
+		this.code = code;
+		this.recovery = options?.recovery;
+	}
+};
+/**
+* Error thrown when a command fails to load dynamically.
+* Provides error code, command name context, and recovery suggestion.
+*/
+var CommandLoadError = class extends Error {
+	code = "COMMAND_LOAD_ERROR";
+	recovery;
+	commandName;
+	constructor(commandName, message, options) {
+		super(`Failed to load command '${commandName}': ${message}`, options);
+		this.name = "CommandLoadError";
+		this.commandName = commandName;
+		this.recovery = `Check that the command module exists and exports the expected command. Run with --help to see available commands.`;
+	}
+};
+/**
+* Creates a lazy-loading command wrapper.
+* The actual command is only imported when invoked.
+* Includes error handling for dynamic import failures.
+*/
+function createLazyCommand(def) {
+	const command = new commander.Command(def.name).description(def.description).allowUnknownOption(true).allowExcessArguments(true);
+	command.action(async () => {
+		let realCommand;
+		try {
+			realCommand = await def.loader();
+		} catch (error) {
+			if (error instanceof CommandLoadError) throw error;
+			throw new CommandLoadError(def.name, error instanceof Error ? error.message : String(error), { cause: error });
+		}
+		const parentArgs = process.argv.slice(2);
+		await new commander.Command().addCommand(realCommand).parseAsync([
+			"node",
+			"imagine-mcp",
+			...parentArgs
+		]);
+	});
+	return command;
+}
+/**
+* Main entry point with lazy command loading for fast startup.
+*/
+async function main() {
+	const invokedCommand = process.argv[2] ?? "unknown";
+	try {
+		const program = new commander.Command();
+		program.name("imagine").description("MCP server for AI image generation and manipulation").version(packageJson.version);
+		for (const def of commandDefinitions) program.addCommand(createLazyCommand(def));
+		await program.parseAsync(process.argv);
+	} catch (error) {
+		if (error instanceof CLIExecutionError) {
+			process.stderr.write(`Error [${error.code}] ${JSON.stringify({
+				command: invokedCommand,
+				recovery: error.recovery,
+				message: error.message,
+				cause: error.cause instanceof Error ? error.cause.message : error.cause
+			})}\n`);
+			if (error.recovery) process.stderr.write(`Recovery: ${error.recovery}\n`);
+			if (error.cause) process.stderr.write(`Caused by: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}\n`);
+		} else if (error instanceof CommandLoadError) {
+			process.stderr.write(`Error [${error.code}] ${JSON.stringify({
+				command: invokedCommand,
+				recovery: error.recovery,
+				message: error.message
+			})}\n`);
+			if (error.recovery) process.stderr.write(`Recovery: ${error.recovery}\n`);
+			if (error.cause) process.stderr.write(`Caused by: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}\n`);
+		} else {
+			const errorCode = error.code ?? "CLI_EXECUTION_FAILED";
+			process.stderr.write(`Error [${errorCode}] ${JSON.stringify({
+				command: invokedCommand,
+				message: error instanceof Error ? error.message : String(error)
+			})}\n`);
+			process.stderr.write("Recovery: Run with --help for usage information.\n");
+			if (error instanceof Error && error.cause) process.stderr.write(`Caused by: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}\n`);
+		}
+		process.exit(1);
+	}
+}
+main();
+
+//#endregion
+exports.CLIExecutionError = CLIExecutionError;
+exports.CommandLoadError = CommandLoadError;
+exports.commandDefinitions = commandDefinitions;
+exports.createLazyCommand = createLazyCommand;

package/dist/cli.d.cts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+
+//#region src/cli.d.ts
+
+/**
+ * Command metadata for lazy loading.
+ * Definitions are inline to avoid importing command modules at startup.
+ */
+interface CommandDef {
+  name: string;
+  description: string;
+  loader: () => Promise<Command>;
+}
+declare const commandDefinitions: CommandDef[];
+/**
+ * Custom error for CLI execution failures with error codes and cause chaining.
+ */
+declare class CLIExecutionError extends Error {
+  readonly code: string;
+  readonly recovery?: string;
+  constructor(message: string, code?: string, options?: ErrorOptions & {
+    recovery?: string;
+  });
+}
+/**
+ * Error thrown when a command fails to load dynamically.
+ * Provides error code, command name context, and recovery suggestion.
+ */
+declare class CommandLoadError extends Error {
+  readonly code = "COMMAND_LOAD_ERROR";
+  readonly recovery: string;
+  readonly commandName: string;
+  constructor(commandName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Creates a lazy-loading command wrapper.
+ * The actual command is only imported when invoked.
+ * Includes error handling for dynamic import failures.
+ */
+declare function createLazyCommand(def: CommandDef): Command;
+//#endregion
+export { CLIExecutionError, CommandDef, CommandLoadError, commandDefinitions, createLazyCommand };

package/dist/cli.d.mts

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+
+//#region src/cli.d.ts
+
+/**
+ * Command metadata for lazy loading.
+ * Definitions are inline to avoid importing command modules at startup.
+ */
+interface CommandDef {
+  name: string;
+  description: string;
+  loader: () => Promise<Command>;
+}
+declare const commandDefinitions: CommandDef[];
+/**
+ * Custom error for CLI execution failures with error codes and cause chaining.
+ */
+declare class CLIExecutionError extends Error {
+  readonly code: string;
+  readonly recovery?: string;
+  constructor(message: string, code?: string, options?: ErrorOptions & {
+    recovery?: string;
+  });
+}
+/**
+ * Error thrown when a command fails to load dynamically.
+ * Provides error code, command name context, and recovery suggestion.
+ */
+declare class CommandLoadError extends Error {
+  readonly code = "COMMAND_LOAD_ERROR";
+  readonly recovery: string;
+  readonly commandName: string;
+  constructor(commandName: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Creates a lazy-loading command wrapper.
+ * The actual command is only imported when invoked.
+ * Includes error handling for dynamic import failures.
+ */
+declare function createLazyCommand(def: CommandDef): Command;
+//#endregion
+export { CLIExecutionError, CommandDef, CommandLoadError, commandDefinitions, createLazyCommand };

package/dist/cli.mjs

@@ -0,0 +1,125 @@
+#!/usr/bin/env node
+import { Command } from "commander";
+
+//#region src/cli.ts
+/**
+* MCP Server Entry Point
+*
+* DESIGN PATTERNS:
+* - CLI pattern with Commander for argument parsing
+* - Lazy command loading for fast startup
+* - Transport abstraction for multiple communication methods
+*
+* CODING STANDARDS:
+* - Use async/await for asynchronous operations
+* - Handle errors gracefully with try-catch
+* - Log important events for debugging
+* - Load commands lazily to minimize startup time
+*
+* AVOID:
+* - Hardcoding command logic in index.ts (use separate command files)
+* - Missing error handling for command execution
+* - Eager loading of all commands at startup
+*/
+const packageJson = { version: "0.1.0" };
+const commandDefinitions = [{
+	name: "mcp-serve",
+	description: "Start MCP server with specified transport",
+	loader: () => import("./commands-c927CRZc.mjs").then((m) => m.mcpServeCommand)
+}];
+/**
+* Custom error for CLI execution failures with error codes and cause chaining.
+*/
+var CLIExecutionError = class extends Error {
+	code;
+	recovery;
+	constructor(message, code = "CLI_EXECUTION_FAILED", options) {
+		super(message, options);
+		this.name = "CLIExecutionError";
+		this.code = code;
+		this.recovery = options?.recovery;
+	}
+};
+/**
+* Error thrown when a command fails to load dynamically.
+* Provides error code, command name context, and recovery suggestion.
+*/
+var CommandLoadError = class extends Error {
+	code = "COMMAND_LOAD_ERROR";
+	recovery;
+	commandName;
+	constructor(commandName, message, options) {
+		super(`Failed to load command '${commandName}': ${message}`, options);
+		this.name = "CommandLoadError";
+		this.commandName = commandName;
+		this.recovery = `Check that the command module exists and exports the expected command. Run with --help to see available commands.`;
+	}
+};
+/**
+* Creates a lazy-loading command wrapper.
+* The actual command is only imported when invoked.
+* Includes error handling for dynamic import failures.
+*/
+function createLazyCommand(def) {
+	const command = new Command(def.name).description(def.description).allowUnknownOption(true).allowExcessArguments(true);
+	command.action(async () => {
+		let realCommand;
+		try {
+			realCommand = await def.loader();
+		} catch (error) {
+			if (error instanceof CommandLoadError) throw error;
+			throw new CommandLoadError(def.name, error instanceof Error ? error.message : String(error), { cause: error });
+		}
+		const parentArgs = process.argv.slice(2);
+		await new Command().addCommand(realCommand).parseAsync([
+			"node",
+			"imagine-mcp",
+			...parentArgs
+		]);
+	});
+	return command;
+}
+/**
+* Main entry point with lazy command loading for fast startup.
+*/
+async function main() {
+	const invokedCommand = process.argv[2] ?? "unknown";
+	try {
+		const program = new Command();
+		program.name("imagine").description("MCP server for AI image generation and manipulation").version(packageJson.version);
+		for (const def of commandDefinitions) program.addCommand(createLazyCommand(def));
+		await program.parseAsync(process.argv);
+	} catch (error) {
+		if (error instanceof CLIExecutionError) {
+			process.stderr.write(`Error [${error.code}] ${JSON.stringify({
+				command: invokedCommand,
+				recovery: error.recovery,
+				message: error.message,
+				cause: error.cause instanceof Error ? error.cause.message : error.cause
+			})}\n`);
+			if (error.recovery) process.stderr.write(`Recovery: ${error.recovery}\n`);
+			if (error.cause) process.stderr.write(`Caused by: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}\n`);
+		} else if (error instanceof CommandLoadError) {
+			process.stderr.write(`Error [${error.code}] ${JSON.stringify({
+				command: invokedCommand,
+				recovery: error.recovery,
+				message: error.message
+			})}\n`);
+			if (error.recovery) process.stderr.write(`Recovery: ${error.recovery}\n`);
+			if (error.cause) process.stderr.write(`Caused by: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}\n`);
+		} else {
+			const errorCode = error.code ?? "CLI_EXECUTION_FAILED";
+			process.stderr.write(`Error [${errorCode}] ${JSON.stringify({
+				command: invokedCommand,
+				message: error instanceof Error ? error.message : String(error)
+			})}\n`);
+			process.stderr.write("Recovery: Run with --help for usage information.\n");
+			if (error instanceof Error && error.cause) process.stderr.write(`Caused by: ${error.cause instanceof Error ? error.cause.message : String(error.cause)}\n`);
+		}
+		process.exit(1);
+	}
+}
+main();
+
+//#endregion
+export { CLIExecutionError, CommandLoadError, commandDefinitions, createLazyCommand };

package/dist/commands-BlRAon0l.cjs

@@ -0,0 +1,83 @@
+const require_stdio = require('./stdio-D7OcvsZd.cjs');
+let commander = require("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 commander.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 require_stdio.StdioTransportHandler(require_stdio.createServer()));
+		else if (transportType === "http") await startServer(new require_stdio.HttpTransportHandler(() => require_stdio.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 require_stdio.SseTransportHandler(() => require_stdio.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
+exports.mcpServeCommand = mcpServeCommand;