@conquest-eth/tools 0.0.0

package/src/index.ts

@@ -0,0 +1,181 @@
+import {McpServer} from '@modelcontextprotocol/sdk/server/mcp.js';
+import pkg from '../package.json' with {type: 'json'};
+import {Implementation} from '@modelcontextprotocol/sdk/types.js';
+import {Chain} from 'viem';
+import {ServerOptions} from '@modelcontextprotocol/sdk/server';
+import {createServer as createMCPEthereumServer} from 'tools-ethereum';
+import {getClients} from 'tools-ethereum/helpers';
+import {createSpaceInfo} from './contracts/space-info.js';
+import {JsonFleetStorage} from './storage/json-storage.js';
+import {FleetManager} from './fleet/manager.js';
+import {PlanetManager} from './planet/manager.js';
+import type {ClientsWithOptionalWallet, ContractConfig, GameContract} from './types.js';
+import {SpaceInfo} from 'conquest-eth-v0-contracts';
+
+// Import refactored tools
+import * as tools from './tools/index.js';
+import {registerTool, stringifyWithBigInt} from './helpers/index.js';
+import {Abi_IOuterSpace} from 'conquest-eth-v0-contracts/abis/IOuterSpace.js';
+
+/**
+ * Create and configure an MCP server for Conquest.eth game interactions
+ *
+ * @param params - Configuration parameters for the server
+ * @param params.chain - The blockchain chain to connect to
+ * @param params.privateKey - Optional private key for signing transactions (wallet operations)
+ * @param params.gameContract - The game contract address
+ * @param options - Optional server configuration
+ * @param options.ethereum - Whether to include Ethereum MCP tools (default: false)
+ * @param options.rpcURL - Optional custom RPC URL
+ * @param options.serverOptions - Optional MCP server options
+ * @param options.serverInfo - Optional server metadata to override defaults
+ * @param options.storageConfig - Storage configuration for fleets and exits
+ * @param options.storageConfig.type - Storage type ('json' or 'sqlite')
+ * @param options.storageConfig.dataDir - Optional data directory path
+ * @returns Configured MCP server instance with Conquest game tools registered
+ */
+export function createServer(
+	params: {chain: Chain; privateKey?: `0x${string}`; gameContract: `0x${string}`},
+	options?: {
+		ethereum?: boolean;
+		rpcURL?: string;
+		serverOptions?: ServerOptions;
+		serverInfo?: Implementation;
+		storageConfig?: {type: 'json' | 'sqlite'; dataDir?: string};
+	},
+) {
+	const {gameContract: gameContractAddress, ...mcpEthereumParams} = params;
+	const clients = getClients(params, options) as ClientsWithOptionalWallet;
+
+	const gameContract: GameContract = {
+		address: gameContractAddress,
+		abi: Abi_IOuterSpace,
+	};
+
+	const name = `mcp-conquest-eth-v0`;
+	const server = options?.ethereum
+		? createMCPEthereumServer(mcpEthereumParams, {
+				...options,
+				serverInfo: {name, version: pkg.version, ...options?.serverInfo},
+			})
+		: new McpServer(
+				options?.serverInfo || {
+					name,
+					version: pkg.version,
+				},
+				options?.serverOptions || {capabilities: {logging: {}}},
+			);
+
+	// Initialize SpaceInfo and contractConfig
+	let spaceInfo: SpaceInfo | null = null;
+	let contractConfig: ContractConfig | null = null;
+
+	const initSpaceInfo = async () => {
+		if (!spaceInfo || !contractConfig) {
+			const result = await createSpaceInfo(clients, gameContract);
+			spaceInfo = result.spaceInfo;
+			contractConfig = result.contractConfig;
+		}
+		return {spaceInfo, contractConfig};
+	};
+
+	// Initialize storage
+	const storageConfig = options?.storageConfig || {type: 'json', dataDir: './data'};
+	const storage = new JsonFleetStorage(storageConfig.dataDir || './data');
+
+	// Initialize managers (will be initialized after spaceInfo is ready)
+	let fleetManager: FleetManager | null = null;
+	let planetManager: PlanetManager | null = null;
+
+	// Helper to ensure managers are initialized
+	const ensureManagersInitialized = async () => {
+		const {spaceInfo: si, contractConfig: cc} = await initSpaceInfo();
+
+		// Initialize fleetManager even without walletClient for read-only operations
+		if (!fleetManager && si && cc) {
+			fleetManager = new FleetManager(clients, gameContract, si, cc, storage);
+		}
+
+		// Initialize planetManager even without walletClient for read-only operations
+		if (!planetManager && si && cc) {
+			planetManager = new PlanetManager(clients, gameContract, si, cc, storage);
+		}
+
+		if (!fleetManager) {
+			throw new Error('Fleet manager not initialized');
+		}
+		if (!planetManager) {
+			throw new Error('Planet manager not initialized');
+		}
+
+		return {fleetManager, planetManager};
+	};
+
+	// Auto-register all tools
+	for (const [name, tool] of Object.entries(tools)) {
+		// Skip the file that's not a tool
+		if (name === 'default') continue;
+
+		server.registerTool(
+			name,
+			{
+				description: tool.description,
+				inputSchema: tool.schema,
+			},
+			async (args: unknown) => {
+				try {
+					const {fleetManager, planetManager} = await ensureManagersInitialized();
+
+					const env = {
+						sendStatus: async (_message: string) => {
+							// TODO: Implement progress notifications when sessionId is available
+						},
+						fleetManager,
+						planetManager,
+					};
+
+					const result = await tool.execute(env, args as any);
+
+					// Convert ToolResult to CallToolResult
+					if (result.success === false) {
+						return {
+							content: [
+								{
+									type: 'text' as const,
+									text: stringifyWithBigInt({
+										error: result.error,
+										...(result.stack ? {stack: result.stack} : {}),
+									}),
+								},
+							],
+							isError: true,
+						};
+					}
+
+					return {
+						content: [
+							{
+								type: 'text' as const,
+								text: stringifyWithBigInt(result.result, 2),
+							},
+						],
+					};
+				} catch (error) {
+					return {
+						content: [
+							{
+								type: 'text' as const,
+								text: stringifyWithBigInt({
+									error: error instanceof Error ? error.message : String(error),
+								}),
+							},
+						],
+						isError: true,
+					};
+				}
+			},
+		);
+	}
+
+	return server;
+}

package/src/planet/acquire.ts

@@ -0,0 +1,41 @@
+import {Clients, GameContract} from '../types.js';
+
+/**
+ * Acquire (stake) multiple planets
+ *
+ * @param clients - Viem clients (publicClient and walletClient)
+ * @param gameContract - The game contract instance with address and ABI
+ * @param planetIds - Array of planet location IDs to acquire
+ * @param amountToMint - Amount of native token to spend
+ * @param tokenAmount - Amount of staking token to spend
+ * @returns Transaction hash and list of planets acquired
+ */
+export async function acquirePlanets(
+	clients: Clients,
+	gameContract: GameContract,
+	planetIds: bigint[],
+	amountToMint: bigint,
+	tokenAmount: bigint,
+): Promise<{hash: `0x${string}`; planetsAcquired: bigint[]}> {
+	const sender = clients.walletClient.account!.address;
+
+	const nativeTokenAmount = (amountToMint * 1000000000000000000n) / 1000000000000000000000n; // TODO BigInt((PlayToken.linkedData as any).numTokensPerNativeTokenAt18Decimals);
+
+	console.log(
+		`Acquiring ${planetIds.length} planets with ${amountToMint} native tokens and ${tokenAmount} staking tokens using ${nativeTokenAmount} native tokens`,
+	);
+
+	// Get the contract acquireMultipleViaNativeTokenAndStakingToken function signature
+	const simulation = await clients.publicClient.simulateContract({
+		...gameContract,
+		functionName: 'acquireMultipleViaNativeTokenAndStakingToken',
+		args: [planetIds, amountToMint, tokenAmount],
+		account: sender,
+		value: nativeTokenAmount,
+	});
+
+	// Send the transaction
+	const hash = await clients.walletClient.writeContract(simulation.request);
+
+	return {hash, planetsAcquired: planetIds};
+}

package/src/planet/exit.ts

@@ -0,0 +1,71 @@
+import {getCurrentTimestamp} from '../util/time.js';
+import type {FleetStorage} from '../storage/interface.js';
+import {Clients, GameContract, PendingExit} from '../types.js';
+
+/**
+ * Exit (unstake) multiple planets to retrieve staked tokens
+ *
+ * @param clients - Viem clients (publicClient and walletClient)
+ * @param gameContract - The game contract instance with address and ABI
+ * @param planetIds - Array of planet location IDs to exit
+ * @param exitDuration - Duration of the exit process in seconds (from contract config)
+ * @param storage - Storage instance for tracking pending exits
+ * @returns Transaction hash and list of planet IDs for which exits were initiated
+ */
+export async function exitPlanets(
+	clients: Clients,
+	gameContract: GameContract,
+	planetIds: bigint[],
+	exitDuration: bigint,
+	storage: FleetStorage,
+): Promise<{hash: `0x${string}`; exitsInitiated: bigint[]}> {
+	const sender = clients.walletClient.account!.address;
+	const currentTime = getCurrentTimestamp();
+
+	// Get planet states to verify ownership
+	const result = await clients.publicClient.readContract({
+		...gameContract,
+		functionName: 'getPlanetStates',
+		args: [planetIds],
+	});
+	const states = result[0];
+
+	// Create pending exit records for each planet
+	const exitsInitiated: bigint[] = [];
+	for (let i = 0; i < planetIds.length; i++) {
+		const planetId = planetIds[i];
+		const state = states[i];
+
+		// Only create exit record for planets owned by the sender
+		if (state.owner && state.owner.toLowerCase() === sender.toLowerCase()) {
+			const exit: PendingExit = {
+				planetId,
+				player: sender,
+				exitStartTime: currentTime,
+				exitDuration: Number(exitDuration),
+				exitCompleteTime: currentTime + Number(exitDuration),
+				numSpaceships: state.numSpaceships,
+				owner: state.owner,
+				completed: false,
+				interrupted: false,
+				lastCheckedAt: currentTime,
+			};
+
+			await storage.savePendingExit(exit);
+			exitsInitiated.push(planetId);
+		}
+	}
+
+	// Get the contract exitMultipleFor function signature
+	const simulation = await clients.publicClient.simulateContract({
+		...gameContract,
+		functionName: 'exitMultipleFor',
+		args: [sender, planetIds],
+		account: sender,
+	});
+
+	// Send the transaction
+	const hash = await clients.walletClient.writeContract(simulation.request);
+
+	return {hash, exitsInitiated};
+}

package/src/planet/index.ts

@@ -0,0 +1,6 @@
+// Planet Manager and exports
+export {PlanetManager} from './manager.js';
+
+// Planet operations
+export {acquirePlanets} from './acquire.js';
+export {exitPlanets} from './exit.js';

package/src/planet/manager.ts

@@ -0,0 +1,335 @@
+import {zeroAddress, type Address} from 'viem';
+import type {SpaceInfo} from 'conquest-eth-v0-contracts';
+import type {PlanetInfo, PlanetState} from 'conquest-eth-v0-contracts';
+import {acquirePlanets} from './acquire.js';
+import {exitPlanets} from './exit.js';
+import type {FleetStorage} from '../storage/interface.js';
+import type {
+	Clients,
+	ClientsWithOptionalWallet,
+	ContractConfig,
+	ExternalPlanet,
+	GameContract,
+	PendingExit,
+} from '../types.js';
+
+/**
+ * PlanetManager manages planet-related operations in the Conquest game
+ * including acquiring new planets and initiating exit processes
+ */
+export class PlanetManager {
+	constructor(
+		private readonly clients: ClientsWithOptionalWallet,
+		private readonly gameContract: GameContract,
+		private readonly spaceInfo: SpaceInfo,
+		private readonly contractConfig: ContractConfig,
+		private readonly storage: FleetStorage,
+	) {}
+
+	/**
+	 * Ensure walletClient is available for operations that require it
+	 */
+	private requireWalletClient(): Clients {
+		if (!this.clients.walletClient) {
+			throw new Error(
+				'Wallet client is required for this operation. Please provide a PRIVATE_KEY environment variable.',
+			);
+		}
+		return this.clients as Clients;
+	}
+
+	/**
+	 * Acquire (stake) multiple planets
+	 */
+	async acquire(
+		planetIds: bigint[],
+		amountToMint: bigint,
+		tokenAmount: bigint,
+	): Promise<{hash: `0x${string}`; planetsAcquired: bigint[]}> {
+		return acquirePlanets(
+			this.requireWalletClient(),
+			this.gameContract,
+			planetIds,
+			amountToMint,
+			tokenAmount,
+		);
+	}
+
+	/**
+	 * Acquire (stake) multiple planets with automatic cost calculation
+	 */
+	async acquireWithAutoCalc(planetIds: bigint[]): Promise<{
+		hash: `0x${string}`;
+		planetsAcquired: bigint[];
+		costs: {amountToMint: bigint; tokenAmount: bigint};
+	}> {
+		const costs = this.calculateAcquisitionCosts(planetIds);
+		const result = await acquirePlanets(
+			this.requireWalletClient(),
+			this.gameContract,
+			planetIds,
+			costs.amountToMint,
+			costs.tokenAmount,
+		);
+		return {...result, costs};
+	}
+
+	/**
+	 * Calculate acquisition costs for planets based on their stats
+	 *
+	 * @param planetIds - Array of planet location IDs
+	 * @returns Object with total amountToMint and tokenAmount
+	 */
+	calculateAcquisitionCosts(planetIds: bigint[]): {amountToMint: bigint; tokenAmount: bigint} {
+		const DECIMAL_14 = 100000000000000n;
+		let totalTokenAmount = 0n;
+		for (const planetId of planetIds) {
+			const planet = this.getPlanetInfo(planetId);
+			if (!planet) {
+				throw new Error(`Planet ${planetId} not found`);
+			}
+			// Use the planet's stake value from its statistics
+			// Multiply by DECIMAL_14 as the contract does
+			totalTokenAmount += BigInt(planet.stats.stake) * DECIMAL_14;
+		}
+
+		const amountToMint = totalTokenAmount;
+
+		// When using native token, we set tokenAmount to 0
+		return {amountToMint, tokenAmount: 0n};
+	}
+
+	/**
+	 * Exit (unstake) multiple planets
+	 */
+	async exit(planetIds: bigint[]): Promise<{hash: `0x${string}`; exitsInitiated: bigint[]}> {
+		return exitPlanets(
+			this.requireWalletClient(),
+			this.gameContract,
+			planetIds,
+			this.contractConfig.exitDuration,
+			this.storage,
+		);
+	}
+
+	/**
+	 * Get planet info by location ID
+	 */
+	getPlanetInfo(planetId: bigint): PlanetInfo | undefined {
+		return this.spaceInfo.getPlanetInfoViaId(planetId);
+	}
+
+	/**
+	 * Get planet ID by x,y coordinates
+	 * @param x - X coordinate
+	 * @param y - Y coordinate
+	 * @returns Planet location ID as bigint, or undefined if no planet exists at coordinates
+	 */
+	getPlanetIdByCoordinates(x: number, y: number): bigint | undefined {
+		const planet = this.spaceInfo.getPlanetInfo(x, y);
+		return planet?.location.id;
+	}
+
+	/**
+	 * Get multiple planet infos
+	 */
+	getPlanetInfos(planetIds: bigint[]): (PlanetInfo | undefined)[] {
+		return planetIds.map((id) => this.getPlanetInfo(id));
+	}
+
+	/**
+	 * Get planets around a center point within a radius
+	 */
+	async getPlanetsAround(
+		centerX: number,
+		centerY: number,
+		radius: number,
+	): Promise<{info: PlanetInfo; state: PlanetState}[]> {
+		// Get planet infos from SpaceInfo within the bounding box
+		const planetsInRect: PlanetInfo[] = [];
+		for (const planet of this.spaceInfo.yieldPlanetsFromRect(
+			centerX - radius,
+			centerY - radius,
+			centerX + radius,
+			centerY + radius,
+		)) {
+			// Calculate actual distance to filter by radius
+			const dx = planet.location.x - centerX;
+			const dy = planet.location.y - centerY;
+			const distance = Math.sqrt(dx * dx + dy * dy);
+			if (distance <= radius) {
+				planetsInRect.push(planet);
+			}
+		}
+
+		// Batch query contract for planet states
+		const planetIds = planetsInRect.map((p) => p.location.id);
+		const result = await this.clients.publicClient.readContract({
+			address: this.gameContract.address,
+			abi: this.gameContract.abi,
+			functionName: 'getPlanetStates',
+			args: [planetIds],
+		});
+
+		const states = result[0];
+
+		// Get current time for computing latest state
+		const currentTime = Math.floor(Date.now() / 1000);
+
+		// Combine info with states and compute latest state
+		return planetsInRect.map((planet, index) => {
+			const rawState = states[index];
+			// Create a mutable copy of the state to compute updates
+			const stateCopy = {
+				owner: rawState.owner === zeroAddress ? undefined : rawState.owner,
+				ownerYakuzaSubscriptionEndTime: 0, // TODO
+				lastUpdatedSaved: rawState.lastUpdated,
+				startExitTime: rawState.exitStartTime,
+				numSpaceships: rawState.numSpaceships,
+				flagTime: 0, // TODO
+				travelingUpkeep: 0, // TODO
+				overflow: 0, // TODO
+				active: rawState.active,
+				exiting: false, // will be populated
+				exitTimeLeft: 0, // will be populated
+				natives: false, // will be populated
+				capturing: false, // will be populated
+				inReach: false, // will be populated
+				rewardGiver: '', // will be populated
+				metadata: {},
+			};
+			// Compute the latest state using SpaceInfo
+			this.spaceInfo.computePlanetUpdateForTimeElapsed(stateCopy, planet, currentTime);
+			return {
+				info: planet,
+				state: stateCopy,
+			};
+		});
+	}
+
+	/**
+	 * Get my planets (owned by the current wallet)
+	 */
+	async getMyPlanets(
+		radius: number = 100,
+	): Promise<Array<{info: PlanetInfo; state: ExternalPlanet}>> {
+		const sender = this.requireWalletClient().walletClient.account!.address;
+
+		// For now, use a simple approach: get all planets in area and filter by owner
+		// A better approach would be to use an index or The Graph
+		const planetsInRect: PlanetInfo[] = [];
+
+		// Get planets from 0,0 out to radius
+		for (const planet of this.spaceInfo.yieldPlanetsFromRect(-radius, -radius, radius, radius)) {
+			planetsInRect.push(planet);
+		}
+
+		// Batch query contract for planet states
+		const planetIds = planetsInRect.map((p) => p.location.id);
+		const result = await this.clients.publicClient.readContract({
+			address: this.gameContract.address,
+			abi: this.gameContract.abi,
+			functionName: 'getPlanetStates',
+			args: [planetIds],
+		});
+		const states = result[0];
+
+		// Get current time for computing latest state
+		const currentTime = Math.floor(Date.now() / 1000);
+
+		// Filter by owner and compute latest state
+		const myPlanets: Array<{info: PlanetInfo; state: ExternalPlanet}> = [];
+		for (let i = 0; i < planetsInRect.length; i++) {
+			const rawState = states[i];
+			if (rawState && rawState.owner && rawState.owner.toLowerCase() === sender.toLowerCase()) {
+				// Create a mutable copy of the state to compute updates
+				const stateCopy: any = {...rawState};
+				// Compute the latest state using SpaceInfo
+				this.spaceInfo.computePlanetUpdateForTimeElapsed(stateCopy, planetsInRect[i], currentTime);
+				myPlanets.push({info: planetsInRect[i], state: stateCopy});
+			}
+		}
+
+		return myPlanets;
+	}
+
+	/**
+	 * Get pending exits for the current player
+	 */
+	async getMyPendingExits(): Promise<PendingExit[]> {
+		const sender = this.requireWalletClient().walletClient.account!.address;
+		return this.storage.getPendingExitsByPlayer(sender);
+	}
+
+	/**
+	 * Verify exit status for a planet
+	 */
+	async verifyExitStatus(
+		planetId: bigint,
+	): Promise<{exit: PendingExit; interrupted: boolean; newOwner?: Address}> {
+		const exit = await this.storage.getPendingExit(planetId);
+		if (!exit) {
+			throw new Error(`No pending exit found for planet ${planetId}`);
+		}
+
+		// Query contract for current planet state
+		const result = await this.clients.publicClient.readContract({
+			...this.gameContract,
+			functionName: 'getPlanetStates',
+			args: [[planetId]],
+		});
+		const states = result[0];
+
+		if (states.length === 0) {
+			throw new Error(`Could not get planet state for ${planetId}`);
+		}
+
+		const currentState = states[0];
+		const currentTime = Math.floor(Date.now() / 1000);
+
+		// Check if exit was interrupted by an attack
+		let interrupted = false;
+		if (currentState.owner && currentState.owner.toLowerCase() !== exit.player.toLowerCase()) {
+			interrupted = true;
+			await this.storage.markExitInterrupted(planetId, currentTime, currentState.owner);
+		}
+
+		// Check if exit is complete
+		if (!currentState.active && currentTime >= exit.exitCompleteTime) {
+			await this.storage.markExitCompleted(planetId, currentTime);
+		}
+
+		const updatedExit = await this.storage.getPendingExit(planetId);
+		if (!updatedExit) {
+			throw new Error('Exit was cleaned up during verification');
+		}
+
+		return {
+			exit: updatedExit,
+			interrupted,
+			newOwner: currentState.owner,
+		};
+	}
+
+	/**
+	 * Clean up old completed exits
+	 */
+	async cleanupOldCompletedExits(olderThanDays: number = 7): Promise<void> {
+		const olderThan = Math.floor(Date.now() / 1000) - olderThanDays * 24 * 60 * 60;
+		await this.storage.cleanupOldCompletedExits(olderThan);
+	}
+
+	/**
+	 * Calculate distance between two planets
+	 */
+	calculateDistance(fromPlanetId: bigint, toPlanetId: bigint): number | undefined {
+		const fromPlanet = this.getPlanetInfo(fromPlanetId);
+		const toPlanet = this.getPlanetInfo(toPlanetId);
+
+		if (!fromPlanet || !toPlanet) {
+			return undefined;
+		}
+
+		return this.spaceInfo.distance(fromPlanet, toPlanet);
+	}
+}