@conquest-eth/tools 0.0.0 → 0.0.2

package/src/tool-handling/mcp.ts

@@ -0,0 +1,127 @@
+import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+import {Tool, ToolResult, ToolEnvironment} from './types.js';
+import {CallToolResult} from '@modelcontextprotocol/sdk/types.js';
+
+/**
+ * Create tool environment with MCP logging support
+ * @template TEnv - Environment properties type
+ * @param server - MCP server instance for sending logging messages
+ * @param env - Environment properties to spread into the tool environment
+ * @param sessionId - Optional session ID for targeting specific client
+ */
+function createToolEnvironmentWithMCP<TEnv extends Record<string, any>>(
+	server: McpServer,
+	env: TEnv,
+	sessionId?: string,
+): ToolEnvironment<TEnv> {
+	return {
+		sendStatus: async (message: string) => {
+			try {
+				await server.sendLoggingMessage(
+					{
+						level: 'info',
+						data: message,
+					},
+					sessionId,
+				);
+			} catch (error) {
+				// Silently ignore logging errors to not disrupt tool execution
+			}
+		},
+		...env,
+	};
+}
+
+/**
+ * Convert ToolResult to CallToolResult format
+ */
+function convertToCallToolResult(result: ToolResult): CallToolResult {
+	if (result.success === false) {
+		return {
+			content: [
+				{
+					type: 'text',
+					text: JSON.stringify({
+						error: result.error,
+						...(result.stack ? {stack: result.stack} : {}),
+					}),
+				},
+			],
+			isError: true,
+		};
+	}
+
+	return {
+		content: [
+			{
+				type: 'text',
+				text: JSON.stringify(
+					result.result,
+					(_key, value) => (typeof value === 'bigint' ? value.toString() : value),
+					2,
+				),
+			},
+		],
+	};
+}
+
+/**
+ * Register tool with MCP server
+ * @template TEnv - Environment properties type
+ */
+export function registerMCPTool<TEnv extends Record<string, any>>({
+	server,
+	name,
+	tool,
+	env,
+}: {
+	server: McpServer;
+	name: string;
+	tool: Tool<any, TEnv>;
+	env: TEnv;
+}): void {
+	server.registerTool(
+		name,
+		{
+			description: tool.description,
+			inputSchema: tool.schema as any,
+		},
+		async (params: unknown, mcpExtra: any) => {
+			// Create tool environment with proper MCP sendStatus
+			const toolEnv = createToolEnvironmentWithMCP(server, env, mcpExtra?.sessionId);
+
+			try {
+				const result = await tool.execute(toolEnv, params as any);
+				return convertToCallToolResult(result);
+			} catch (error) {
+				const errorResult: {success: false; error: string; stack?: string} = {
+					success: false,
+					error: error instanceof Error ? error.message : String(error),
+					stack: error instanceof Error ? error.stack : undefined,
+				};
+				return convertToCallToolResult(errorResult);
+			}
+		},
+	);
+}
+
+/**
+ * Register all tool from a tools object
+ * @template TEnv - Environment type passed to tools
+ */
+export function registerAllMCPTools<TEnv extends Record<string, any>>({
+	server,
+	tools,
+	env,
+}: {
+	server: McpServer;
+	tools: Record<string, Tool<any, TEnv>>;
+	env: TEnv;
+}): void {
+	for (const [name, tool] of Object.entries(tools)) {
+		// Skip the file that's not a tool
+		if (name === 'default') continue;
+
+		registerMCPTool({server, name, tool, env});
+	}
+}

package/src/tool-handling/types.ts

@@ -0,0 +1,86 @@
+import {z} from 'zod';
+import type {CallToolResult} from '@modelcontextprotocol/sdk/types.js';
+import type {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+
+/**
+ * Environment provided to tool execute functions
+ * Generic type TEnv allows customization of the environment properties
+ * @template TEnv - Additional environment properties spread into the environment
+ */
+export type ToolEnvironment<TEnv extends Record<string, any> = Record<string, any>> = {
+	/** function to send status updates during tool execution */
+	sendStatus: (message: string) => Promise<void>;
+} & TEnv;
+
+/**
+ * Result returned by tool execute functions
+ * Success case: {success: true, result: Record<string, any>}
+ * Error case: {success: false, error: string, stack?: string}
+ */
+export type ToolResult =
+	| {success: true; result: Record<string, any>}
+	| {success: false; error: string; stack?: string};
+
+/**
+ * Schema types that can be used for tool input parameters
+ * Supports ZodObject directly or ZodUnion of ZodObjects (for mutually exclusive params)
+ */
+export type ToolSchema =
+	| z.ZodObject<any>
+	| z.ZodUnion<readonly [z.ZodObject<any>, ...z.ZodObject<any>[]]>;
+
+/**
+ * Tool definition with execute, schema, and description
+ * @template S - Zod schema type for input parameters
+ * @template TEnv - Environment type passed to execute function
+ */
+export type Tool<
+	S extends ToolSchema = z.ZodObject<any>,
+	TEnv extends Record<string, any> = Record<string, any>,
+> = {
+	/** Description of what the tool does */
+	description: string;
+	/** Zod schema for input parameters */
+	schema: S;
+	/**
+	 * Execute function that receives environment and parameters
+	 * @param env - Tool environment with sendStatus and custom properties
+	 * @param params - Parameters inferred from schema
+	 * @returns ToolResult with success/error state
+	 */
+	execute: (env: ToolEnvironment<TEnv>, params: z.infer<S>) => Promise<ToolResult>;
+};
+
+/**
+ * Helper function to create a tool with automatic type inference
+ * Use this instead of directly creating Tool objects to get proper TypeScript types
+ * @template S - Zod schema type for input parameters
+ * @template TEnv - Environment type passed to execute function
+ */
+export function createTool<
+	S extends ToolSchema,
+	TEnv extends Record<string, any> = Record<string, any>,
+>(config: {
+	description: string;
+	schema: S;
+	execute: (env: ToolEnvironment<TEnv>, params: z.infer<S>) => Promise<ToolResult>;
+}): Tool<S, TEnv> {
+	return config;
+}
+
+/**
+ * Parameters for tool registration
+ * @template S - Zod schema type for input parameters
+ * @template TEnv - Environment type passed to execute function
+ */
+export type RegisterToolParams<
+	S extends ToolSchema,
+	TEnv extends Record<string, any> = Record<string, any>,
+> = {
+	/** MCP server instance */
+	server: McpServer;
+	/** Tool name (snake_case) */
+	name: string;
+	/** Tool definition */
+	tool: Tool<S, TEnv>;
+};

package/src/tools/acquire_planets.ts

@@ -1,74 +1,48 @@
 import {z} from 'zod';
-import {createTool} from '../types.js';
-import {stringifyWithBigInt} from '../helpers/index.js';
+import {formatUnits} from 'viem';
+import {createTool} from '../tool-handling/types.js';
+import type {ConquestEnv} from '../types.js';
 
-export const acquire_planets = createTool({
+const schema = z.object({
+	coordinates: z
+		.array(
+			z.object({
+				x: z.number().describe('X coordinate of the planet'),
+				y: z.number().describe('Y coordinate of the planet'),
+			}),
+		)
+		.describe('Array of planet coordinates to acquire'),
+});
+
+export const acquire_planets = createTool<typeof schema, ConquestEnv>({
 	description:
-		'Acquire (stake) multiple planets in the Conquest game. This allows you to take ownership of unclaimed planets.',
-	schema: z.object({
-		planetIds: z
-			.array(z.union([z.string(), z.number()]))
-			.describe('Array of planet location IDs to acquire (as hex strings or numbers)'),
-		amountToMint: z
-			.number()
-			.optional()
-			.describe(
-				'Amount of native token to spend to acquire the planets. If not provided, will be calculated automatically based on planet stats.',
-			),
-		tokenAmount: z
-			.number()
-			.optional()
-			.describe(
-				'Amount of staking token to spend to acquire the planets. If not provided, will be calculated automatically based on planet stats.',
-			),
-	}),
-	execute: async (env, {planetIds, amountToMint, tokenAmount}) => {
+		'Acquire (stake) multiple planets in the Conquest game. This allows you to take ownership of unclaimed planets. Automatically uses all available play token balance first, then mints the remainder with native tokens.',
+	schema,
+	execute: async (env, {coordinates}) => {
 		try {
-			// Convert planet IDs to BigInt
-			const planetIdsBigInt = planetIds.map((id) =>
-				typeof id === 'string' ? BigInt(id) : BigInt(id),
-			);
-
-			let result: {
-				hash: `0x${string}`;
-				planetsAcquired: bigint[];
-				amountToMint: bigint;
-				tokenAmount: bigint;
-			};
-
-			// If BOTH amounts are provided, use them; otherwise use auto-calculation
-			if (amountToMint !== undefined && tokenAmount !== undefined) {
-				// Use provided amounts
-				// TODO decimal handling, for now BigInt()
-				const acquireResult = await env.planetManager.acquire(
-					planetIdsBigInt,
-					BigInt(amountToMint),
-					BigInt(tokenAmount),
-				);
-				result = {
-					hash: acquireResult.hash,
-					planetsAcquired: acquireResult.planetsAcquired,
-					amountToMint: BigInt(amountToMint),
-					tokenAmount: BigInt(tokenAmount),
-				};
-			} else {
-				// Use auto-calculation
-				const autoResult = await env.planetManager.acquireWithAutoCalc(planetIdsBigInt);
-				result = {
-					hash: autoResult.hash,
-					planetsAcquired: autoResult.planetsAcquired,
-					amountToMint: autoResult.costs.amountToMint,
-					tokenAmount: autoResult.costs.tokenAmount,
-				};
+			// Convert x,y coordinates to planet IDs
+			const planetIdsBigInt: bigint[] = [];
+			for (const coord of coordinates) {
+				const planetId = env.planetManager.getPlanetIdByCoordinates(coord.x, coord.y);
+				if (planetId === undefined) {
+					throw new Error(`No planet found at coordinates (${coord.x}, ${coord.y})`);
+				}
+				planetIdsBigInt.push(planetId);
 			}
 
+			// Acquire planets using max play token balance first, then minting remainder
+			const result = await env.planetManager.acquireWithMaxPlayToken(planetIdsBigInt);
+
 			return {
 				success: true,
 				result: {
 					transactionHash: result.hash,
 					planetsAcquired: result.planetsAcquired,
-					amountToMint: result.amountToMint,
-					tokenAmount: result.tokenAmount,
+					costs: {
+						totalRequired: formatUnits(result.costs.totalRequired, 18),
+						playTokenUsed: formatUnits(result.costs.playTokenUsed, 18),
+						amountMinted: formatUnits(result.costs.amountMinted, 18),
+					},
 				},
 			};
 		} catch (error) {

package/src/tools/exit_planets.ts

@@ -1,20 +1,33 @@
 import {z} from 'zod';
-import {createTool} from '../types.js';
+import {createTool} from '../tool-handling/types.js';
+import type {ConquestEnv} from '../types.js';
 
-export const exit_planets = createTool({
+const schema = z.object({
+	coordinates: z
+		.array(
+			z.object({
+				x: z.number().describe('X coordinate of the planet'),
+				y: z.number().describe('Y coordinate of the planet'),
+			}),
+		)
+		.describe('Array of planet coordinates to exit'),
+});
+
+export const exit_planets = createTool<typeof schema, ConquestEnv>({
 	description:
 		'Exit (unstake) multiple planets to retrieve staked tokens. The exit process takes time and must be completed later.',
-	schema: z.object({
-		planetIds: z
-			.array(z.union([z.string(), z.number()]))
-			.describe('Array of planet location IDs to exit (as hex strings or numbers)'),
-	}),
-	execute: async (env, {planetIds}) => {
+	schema,
+	execute: async (env, {coordinates}) => {
 		try {
-			// Convert planet IDs to BigInt
-			const planetIdsBigInt = planetIds.map((id) =>
-				typeof id === 'string' ? BigInt(id) : BigInt(id),
-			);
+			// Convert x,y coordinates to planet IDs
+			const planetIdsBigInt: bigint[] = [];
+			for (const coord of coordinates) {
+				const planetId = env.planetManager.getPlanetIdByCoordinates(coord.x, coord.y);
+				if (planetId === undefined) {
+					throw new Error(`No planet found at coordinates (${coord.x}, ${coord.y})`);
+				}
+				planetIdsBigInt.push(planetId);
+			}
 
 			const result = await env.planetManager.exit(planetIdsBigInt);
 

package/src/tools/get_native_token_balance.ts

@@ -0,0 +1,72 @@
+import {z} from 'zod';
+import {formatEther} from 'viem';
+import {createTool} from '../tool-handling/types.js';
+import type {ConquestEnv} from '../types.js';
+
+const schema = z.object({
+	address: z
+		.string()
+		.optional()
+		.describe(
+			'Address to check balance for. Defaults to current wallet if private key is available.',
+		),
+});
+
+export const get_native_token_balance = createTool<typeof schema, ConquestEnv>({
+	description:
+		'Get the native token (ETH) balance for an address. If no address provided, uses the current wallet address.',
+	schema,
+	execute: async (env, {address}) => {
+		try {
+			let targetAddress: `0x${string}`;
+
+			if (address) {
+				// Use provided address
+				if (!address.startsWith('0x') || address.length !== 42) {
+					return {
+						success: false,
+						error: 'Invalid address format. Must be a 42-character hex string starting with 0x.',
+					};
+				}
+				targetAddress = address as `0x${string}`;
+			} else {
+				// Use current wallet address
+				if (!env.clients.walletClient) {
+					return {
+						success: false,
+						error:
+							'No address provided and no wallet client available. Please provide a PRIVATE_KEY environment variable or specify an address.',
+					};
+				}
+				const account = env.clients.walletClient.account;
+				if (!account) {
+					return {
+						success: false,
+						error: 'Wallet client has no account configured.',
+					};
+				}
+				targetAddress = account.address;
+			}
+
+			const balanceWei = await env.clients.publicClient.getBalance({
+				address: targetAddress,
+			});
+
+			const balanceEth = formatEther(balanceWei);
+
+			return {
+				success: true,
+				result: {
+					address: targetAddress,
+					balance: `${balanceEth} ETH`,
+					balanceWei: balanceWei.toString(),
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/get_pending_exits.ts

@@ -1,11 +1,14 @@
 import {z} from 'zod';
-import {createTool} from '../types.js';
+import {createTool} from '../tool-handling/types.js';
+import type {ConquestEnv} from '../types.js';
 
-export const get_pending_exits = createTool({
+const schema = z.object({
+	// No properties needed for this tool
+});
+
+export const get_pending_exits = createTool<typeof schema, ConquestEnv>({
 	description: 'Get all pending exit (unstake) operations for your planets.',
-	schema: z.object({
-		// No properties needed for this tool
-	}),
+	schema,
 	execute: async (env) => {
 		try {
 			const exits = await env.planetManager.getMyPendingExits();

package/src/tools/get_pending_fleets.ts

@@ -1,11 +1,14 @@
 import {z} from 'zod';
-import {createTool} from '../types.js';
+import {createTool} from '../tool-handling/types.js';
+import type {ConquestEnv} from '../types.js';
 
-export const get_pending_fleets = createTool({
+const schema = z.object({
+	// No properties needed for this tool
+});
+
+export const get_pending_fleets = createTool<typeof schema, ConquestEnv>({
 	description: 'Get all pending fleets sent from your planets.',
-	schema: z.object({
-		// No properties needed for this tool
-	}),
+	schema,
 	execute: async (env) => {
 		try {
 			const fleets = await env.fleetManager.getMyPendingFleets();

package/src/tools/get_planets_around.ts

@@ -1,33 +1,62 @@
 import {z} from 'zod';
-import {createTool} from '../types.js';
+import {createTool} from '../tool-handling/types.js';
+import type {ConquestEnv} from '../types.js';
 
-export const get_planets_around = createTool({
+const schema = z.object({
+	center: z.object({x: z.number(), y: z.number()}).describe('Center point coordinates {x, y}'),
+	radius: z
+		.number()
+		.min(1)
+		.max(50)
+		.describe('Radius in distance units to search around the center point (1-50)'),
+	only: z
+		.string()
+		.optional()
+		.describe('Filter by owner: use "me" for current wallet address, or provide an address'),
+});
+
+export const get_planets_around = createTool<typeof schema, ConquestEnv>({
 	description:
-		'Get planets around a specific location within a certain radius. Useful for finding targets for fleet movement.',
-	schema: z.object({
-		centerX: z.number().describe('X coordinate of the center point'),
-		centerY: z.number().describe('Y coordinate of the center point'),
-		radius: z
-			.number()
-			.max(50)
-			.describe('Radius in distance units to search around the center point'),
-	}),
-	execute: async (env, {centerX, centerY, radius}) => {
+		'Get planets around a specific location within a certain radius. Useful for finding targets for fleet movement. Use the "only" parameter to filter by owner.',
+	schema,
+	execute: async (env, {center, radius, only}) => {
 		try {
-			const planets = await env.planetManager.getPlanetsAround(centerX, centerY, radius);
+			let planets = await env.planetManager.getPlanetsAround(center.x, center.y, radius);
+
+			// Filter by owner if 'only' parameter is provided
+			if (only) {
+				let filterAddress: string;
+				if (only.toLowerCase() === 'me') {
+					// Require wallet client for 'me' filter
+					const walletClient = env.clients.walletClient;
+					if (!walletClient?.account) {
+						return {
+							success: false,
+							error:
+								'Wallet client with account required to use "me" filter. Private key must be set.',
+						};
+					}
+					filterAddress = walletClient.account.address.toLowerCase();
+				} else {
+					filterAddress = only.toLowerCase();
+				}
+
+				planets = planets.filter(({state}) => state.owner?.toLowerCase() === filterAddress);
+			}
 
 			return {
 				success: true,
 				result: {
 					center: {
-						x: centerX,
-						y: centerY,
+						x: center.x,
+						y: center.y,
 					},
 					radius,
+					...(only && {filter: {only}}),
 					planets: planets.map(({info, state}) => ({
 						planetId: info.location.id,
 						distance: Math.sqrt(
-							Math.pow(info.location.x - centerX, 2) + Math.pow(info.location.y - centerY, 2),
+							Math.pow(info.location.x - center.x, 2) + Math.pow(info.location.y - center.y, 2),
 						),
 						location: info.location,
 						...state,

package/src/tools/get_play_token_balance.ts

@@ -0,0 +1,90 @@
+import {z} from 'zod';
+import {formatUnits} from 'viem';
+import {createTool} from '../tool-handling/types.js';
+import type {ConquestEnv} from '../types.js';
+
+const schema = z.object({
+	address: z
+		.string()
+		.optional()
+		.describe(
+			'Address to check balance for. Defaults to current wallet if private key is available.',
+		),
+});
+
+// ERC20 balanceOf ABI
+const erc20BalanceOfAbi = [
+	{
+		name: 'balanceOf',
+		type: 'function',
+		stateMutability: 'view',
+		inputs: [{name: 'account', type: 'address'}],
+		outputs: [{name: '', type: 'uint256'}],
+	},
+] as const;
+
+export const get_play_token_balance = createTool<typeof schema, ConquestEnv>({
+	description:
+		'Get the play token (staking token) balance for an address. If no address provided, uses the current wallet address.',
+	schema,
+	execute: async (env, {address}) => {
+		try {
+			let targetAddress: `0x${string}`;
+
+			if (address) {
+				// Use provided address
+				if (!address.startsWith('0x') || address.length !== 42) {
+					return {
+						success: false,
+						error: 'Invalid address format. Must be a 42-character hex string starting with 0x.',
+					};
+				}
+				targetAddress = address as `0x${string}`;
+			} else {
+				// Use current wallet address
+				if (!env.clients.walletClient) {
+					return {
+						success: false,
+						error:
+							'No address provided and no wallet client available. Please provide a PRIVATE_KEY environment variable or specify an address.',
+					};
+				}
+				const account = env.clients.walletClient.account;
+				if (!account) {
+					return {
+						success: false,
+						error: 'Wallet client has no account configured.',
+					};
+				}
+				targetAddress = account.address;
+			}
+
+			const tokenAddress = env.contractConfig.stakingToken;
+
+			const balanceRaw = await env.clients.publicClient.readContract({
+				address: tokenAddress,
+				abi: erc20BalanceOfAbi,
+				functionName: 'balanceOf',
+				args: [targetAddress],
+			});
+
+			// Play tokens use 18 decimals
+			const balance = formatUnits(balanceRaw, 18);
+
+			return {
+				success: true,
+				result: {
+					address: targetAddress,
+					tokenAddress,
+					balance: `${balance} PLAY`,
+					balanceRaw: balanceRaw.toString(),
+				},
+			};
+		} catch (error) {
+			return {
+				success: false,
+				error: error instanceof Error ? error.message : String(error),
+			};
+		}
+	},
+});

package/src/tools/index.ts

@@ -5,6 +5,12 @@ export {resolve_fleet} from './resolve_fleet.js';
 export {exit_planets} from './exit_planets.js';
 export {get_pending_exits} from './get_pending_exits.js';
 export {verify_exit_status} from './verify_exit_status.js';
-export {get_my_planets} from './get_my_planets.js';
 export {get_planets_around} from './get_planets_around.js';
 export {get_pending_fleets} from './get_pending_fleets.js';
+export {get_native_token_balance} from './get_native_token_balance.js';
+export {get_play_token_balance} from './get_play_token_balance.js';
+export {withdraw} from './withdraw.js';
+export {simulate} from './simulate.js';
+export {simulate_multiple} from './simulate_multiple.js';
+export {missiv_get_user} from './missiv_get_user.js';
+export {missiv_register} from './missiv_register.js';