geo_mcp_server: Skill for Claude Code

Wallet Approval Mode

The Geo MCP server supports two wallet modes that determine how write operations handle blockchain transactions:

• PRIVATE_KEY (default): Server holds the private key, signs and sends transactions immediately.
• APPROVAL: Server returns unsigned transaction data as { status: 'pending_signature', ... } for external wallet signing.

Core Architecture

executeTransaction() — the dual-mode abstraction

All write operations use executeTransaction(session, request) instead of calling smartAccountClient.sendTransaction() directly.

File: src/utils/tx-executor.ts

const txResult = await executeTransaction(session, {
  to: contractAddress,
  data: calldata,
  description: 'Human-readable action description',
  toolName: 'publish_edit',
  metadata: { editId, cid },
});

if (txResult.mode === 'pending_approval') {
  return ok({ status: 'pending_signature', ...txResult.pendingTx });
}
// mode === 'executed' — continue with existing flow using txResult.txHash

Session state for APPROVAL mode

File: src/state/session.ts

The EditSession class tracks:

• walletMode: 'PRIVATE_KEY' | 'APPROVAL'
• pendingTransactions: PendingTransaction[] — unsigned txs waiting for external signing
• continuations: Map<string, TransactionContinuation> — maps pendingTxId to next step

clear() resets pendingTransactions and continuations along with ops/artifacts.

getStatus() returns mode: 'approval' when walletMode === 'APPROVAL' && walletAddress !== null.

configure_wallet extension

File: src/tools/spaces.ts

The tool accepts optional walletAddress and walletMode params:

• walletMode='APPROVAL' + walletAddress configures without private key
• Does NOT call getSmartAccountWalletClient
• Sets session.walletMode and session.walletAddress

ensureWalletConfigured() early return

File: src/utils/wallet.ts

APPROVAL mode check goes BEFORE the private key cascade:

if (session.walletMode === 'APPROVAL' && session.walletAddress) {
  return { ok: true, address: session.walletAddress as Hex };
}