stelagent 0.0.1 → 0.0.3

package/README.md

@@ -1,87 +1,105 @@
-# @stelagent/cli
+# Stelagent CLI
 
-Modular, agent-first CLI for Stellar — wallet, payments, markets, and DeFi.
+Modular, agent-first CLI for Stellar — wallet, payments, markets, and monitoring.
 
-## Quick Start
+## Quick start for AI agents
+
+Paste this prompt into any AI agent (Claude Code, Cursor, OpenCode, OpenClaw, Hermes Agent, etc.) and chat naturally:
 
-```bash
-npx @stelagent/cli wallet login -e you@example.com
+```
+Read https://stelagent.noval.me/AGENTS.md, then set it up for me.
 ```
 
-Prompts for an OTP sent to your email, then creates or recovers your Stellar wallet.
+The agent reads the skill definition, handles wallet creation, OTP verification, and every Stellar operation on your behalf.
 
-## Usage
+### Install the skill
 
 ```bash
-stelagent <command> [options]
+# Via flins (recommended)
+npx flins@latest add stelagent.noval.me
+
+# Via skills.sh
+npx skills add stelagent.noval.me/stelagent-cli
 ```
 
-### `wallet login`
+Both commands download the skill into your project's skills directory and wire it into your agent's configuration automatically.
 
-Sign in with email to create or recover your wallet.
+## Install
 
 ```bash
-stelagent wallet login -e you@example.com
-stelagent wallet login -e you@example.com -n testnet
+npx stelagent@latest <command>
+# or
+bunx stelagent@latest <command>
 ```
 
-| Flag            | Description                                |
-| --------------- | ------------------------------------------ |
-| `-e, --email`   | Your email address (required)              |
-| `-n, --network` | `testnet` or `pubnet` (default: `testnet`) |
+No install needed — `npx` always runs the latest published version.
 
-One email always maps to one wallet. Logging in from any device with the same email recovers the same wallet.
+## Commands
 
-### `wallet address`
-
-Show the wallet public key.
+### Wallet
 
 ```bash
-stelagent wallet address
+npx stelagent@latest wallet login -e you@example.com                    # Request OTP
+npx stelagent@latest wallet verify -e you@example.com -o 123456          # Verify OTP
+npx stelagent@latest wallet address                                     # Show public key
+npx stelagent@latest wallet balance                                    # Check balances
+npx stelagent@latest wallet transfer -t GDXXX... -a 10                  # Send XLM
+npx stelagent@latest wallet logout                                     # Clear session
 ```
 
-### `wallet balance`
-
-Show token balances.
+### Payments
 
 ```bash
-stelagent wallet balance
+npx stelagent@latest send GDXXX... 100 -a USDC:GAXYZ...                # Custom asset
+npx stelagent@latest send GDXXX... 50 -a native --memo text:ref-99     # XLM with memo
+npx stelagent@latest pay https://api.example.com/premium                # x402 payment
 ```
 
-### `wallet transfer`
-
-Send XLM to another Stellar address.
+### Account queries
 
 ```bash
-stelagent wallet transfer -t GDXXX... -a 10
+npx stelagent@latest account details GDXXX...          # Balances, signers, thresholds
+npx stelagent@latest account transactions GDXXX...      # Transaction history
+npx stelagent@latest account payments GDXXX...          # Payment history
+npx stelagent@latest account effects GDXXX...           # Effect history
 ```
 
-| Flag           | Description                       |
-| -------------- | --------------------------------- |
-| `-t, --to`     | Destination public key (required) |
-| `-a, --amount` | Amount in XLM (required)          |
+### Assets & fees
 
-### `wallet logout`
+```bash
+npx stelagent@latest assets search --code USDC                              # Search assets
+npx stelagent@latest assets orderbook --selling XLM --buying USDC:G...     # Order book
+npx stelagent@latest fee                                                    # Fee stats
+```
 
-Clear the local session.
+### Streaming
 
 ```bash
-stelagent wallet logout
+npx stelagent@latest monitor transactions GDXXX...     # Stream transactions
+npx stelagent@latest monitor payments GDXXX...         # Stream payments
+npx stelagent@latest monitor effects GDXXX...          # Stream effects
 ```
 
-### `pay <url>`
-
-Make an x402 payment to access a paywalled resource.
+### MCP server
 
 ```bash
-stelagent pay https://api.example.com/premium
+npx stelagent@latest mcp    # Start MCP server on stdio
 ```
 
-If the URL returns HTTP 402, the CLI negotiates payment using the x402 protocol and retries with a signed payment header.
+All commands accept `-n testnet|pubnet` (default: `testnet`) and `-f json|text`. Account and asset queries support `--limit`, `--cursor`, and `--order asc|desc`.
+
+## Authentication
+
+Two-step OTP flow:
+
+1. **`wallet login -e <email>`** — sends a one-time code to your email
+2. **`wallet verify -e <email> -o <code>`** — verifies the code and creates (or recovers) your wallet
+
+One email maps to one wallet, recoverable from any device.
 
 ## Output
 
-All commands output structured JSON:
+All commands return structured JSON:
 
 ```json
 { "ok": true, "data": { ... } }
@@ -91,9 +109,11 @@ All commands output structured JSON:
 { "ok": false, "error": "..." }
 ```
 
+Use `--format text` for human-readable output.
+
 ## Architecture
 
-Wallets are stored server-side — one wallet per email, recoverable from any device. The CLI only holds a session token locally (`~/.stelagent/session.json`). Secret keys are fetched from the server over HTTPS on each command invocation and never persisted to disk.
+Wallets are stored server-side — one wallet per email, recoverable from any device. The CLI only holds a session token locally (`~/.stelagent/session.json`). Secret keys are fetched over HTTPS when needed and never written to disk.
 
 ## Development
 

package/dist/index.mjs

@@ -2,13 +2,15 @@
 
 import { defineCommand, runMain } from "citty";
 import { Result, TaggedError, isTaggedError, matchError, matchErrorPartial } from "better-result";
-import { cancel, confirm, isCancel, log, text } from "@clack/prompts";
-import pc from "picocolors";
 import { z } from "zod";
 import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { homedir } from "node:os";
+import pc from "picocolors";
 import { Horizon } from "@stellar/stellar-sdk";
+import { cancel, confirm, isCancel } from "@clack/prompts";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 //#region src/lib/audit.ts
 const STELAGENT_DIR$1 = join(homedir(), ".stelagent");
 const AUDIT_FILE = join(STELAGENT_DIR$1, "audit.jsonl");
@@ -68,16 +70,6 @@ function printResult(result, format) {
 	if (Result.isOk(result)) printText(result.value);
 	else console.error(pc.red(`Error: ${result.error}`));
 }
-function printData(data, format) {
-	if (format === "json") {
-		console.log(JSON.stringify({
-			ok: true,
-			data
-		}, null, 2));
-		return;
-	}
-	printText(data);
-}
 function formatSessionError(err) {
 	return matchErrorPartial(err, {
 		SessionNotFoundError: () => "No active session.",
@@ -293,6 +285,89 @@ function verifyOtp(email, otp) {
 	});
 }
 //#endregion
+//#region src/lib/args.ts
+const networkArg = {
+	type: "string",
+	alias: ["n"],
+	description: "Network: testnet or pubnet",
+	default: "testnet"
+};
+const formatArg = {
+	type: "string",
+	alias: ["f"],
+	description: "Output format: json or text",
+	default: "json"
+};
+function parseNetwork$4(value) {
+	if (value === "testnet" || value === "pubnet") return Result.ok(value);
+	return Result.err(new InvalidNetworkError({ provided: value }));
+}
+function parseFormat(value) {
+	if (value === "json" || value === "text") return value;
+	return "json";
+}
+//#endregion
+//#region src/domain/validators.ts
+const stellarPublicKey = z.string().regex(/^G[A-Z2-7]{55}$/, "Invalid Stellar public key. Must start with 'G' followed by 55 alphanumeric characters.");
+const emailSchema = z.string().email("Invalid email address.");
+const amountSchema = z.string().regex(/^\d+(\.\d{1,7})?$/, "Invalid amount. Must be a number with up to 7 decimal places.");
+const assetSchema = z.union([z.literal("native"), z.string().regex(/^[A-Za-z0-9]{1,12}:[A-Z2-7]{56}$/, "Invalid asset format. Use 'native' for XLM or 'CODE:ISSUER' for custom assets.")]);
+const memoSchema = z.string().max(28, "Memo text must be 28 characters or fewer.");
+z.string().min(1, "Cursor must be a non-empty string.");
+const otpSchema = z.string().regex(/^\d{4,8}$/, "OTP must be 4-8 digits.");
+const urlSchema = z.string().url("Invalid URL.");
+z.enum(["testnet", "pubnet"]);
+z.enum(["json", "text"]);
+const limitSchema = z.coerce.number().int().min(1).max(200).default(10);
+z.enum(["asc", "desc"]).default("desc");
+z.coerce.number().int().min(6e4);
+//#endregion
+//#region src/commands/wallet-login.ts
+function formatZodError$11(e) {
+	return e.issues.map((issue) => issue.message).join(", ");
+}
+const walletLogin = defineCommand({
+	meta: {
+		name: "login",
+		description: "Request an OTP code be sent to your email"
+	},
+	args: {
+		email: {
+			type: "string",
+			alias: ["e"],
+			description: "Your email address",
+			required: true
+		},
+		network: networkArg,
+		format: formatArg
+	},
+	async run({ args }) {
+		const email = String(args.email ?? "");
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
+		const format = parseFormat(String(args.format ?? "json"));
+		if (Result.isError(networkResult)) {
+			printResult(Result.err(networkResult.error._tag), "json");
+			return;
+		}
+		const validation = Result.try({
+			try: () => emailSchema.parse(email),
+			catch: (e) => e
+		});
+		if (Result.isError(validation)) {
+			const msg = validation.error instanceof z.ZodError ? formatZodError$11(validation.error) : validation.error instanceof Error ? validation.error.message : String(validation.error);
+			printResult(Result.err(msg), format);
+			return;
+		}
+		await runApp("wallet login", async () => {
+			const otpResponseResult = await requestOtp(email);
+			if (Result.isError(otpResponseResult)) throw new Error(`Could not reach auth server: ${otpResponseResult.error.cause}`);
+			const otpResponse = otpResponseResult.value;
+			if (!otpResponse || !otpResponse.ok) throw new Error("Failed to send OTP email");
+			return { message: otpResponse.message };
+		}, format);
+	}
+});
+//#endregion
 //#region src/services/session.ts
 const STELAGENT_DIR = join(homedir(), ".stelagent");
 const SESSION_FILE = join(STELAGENT_DIR, "session.json");
@@ -390,132 +465,6 @@ async function createWallet(network) {
 	});
 }
 //#endregion
-//#region src/lib/args.ts
-const networkArg = {
-	type: "string",
-	alias: ["n"],
-	description: "Network: testnet or pubnet",
-	default: "testnet"
-};
-const formatArg = {
-	type: "string",
-	alias: ["f"],
-	description: "Output format: json or text",
-	default: "json"
-};
-function parseNetwork(value) {
-	if (value === "testnet" || value === "pubnet") return Result.ok(value);
-	return Result.err(new InvalidNetworkError({ provided: value }));
-}
-function parseFormat(value) {
-	if (value === "json" || value === "text") return value;
-	return "json";
-}
-//#endregion
-//#region src/domain/validators.ts
-const stellarPublicKey = z.string().regex(/^G[A-Z2-7]{55}$/, "Invalid Stellar public key. Must start with 'G' followed by 55 alphanumeric characters.");
-const emailSchema = z.string().email("Invalid email address.");
-const amountSchema = z.string().regex(/^\d+(\.\d{1,7})?$/, "Invalid amount. Must be a number with up to 7 decimal places.");
-const assetSchema = z.union([z.literal("native"), z.string().regex(/^[A-Za-z0-9]{1,12}:[A-Z2-7]{56}$/, "Invalid asset format. Use 'native' for XLM or 'CODE:ISSUER' for custom assets.")]);
-const memoSchema = z.string().max(28, "Memo text must be 28 characters or fewer.");
-z.string().min(1, "Cursor must be a non-empty string.");
-z.string().regex(/^\d{4,8}$/, "OTP must be 4-8 digits.");
-const urlSchema = z.string().url("Invalid URL.");
-z.enum(["testnet", "pubnet"]);
-z.enum(["json", "text"]);
-const limitSchema = z.coerce.number().int().min(1).max(200).default(10);
-z.enum(["asc", "desc"]).default("desc");
-z.coerce.number().int().min(6e4);
-//#endregion
-//#region src/commands/wallet-login.ts
-function formatZodError$11(e) {
-	return e.issues.map((issue) => issue.message).join(", ");
-}
-const walletLogin = defineCommand({
-	meta: {
-		name: "login",
-		description: "Sign in with email to create or recover your wallet"
-	},
-	args: {
-		email: {
-			type: "string",
-			alias: ["e"],
-			description: "Your email address",
-			required: true
-		},
-		network: networkArg,
-		format: formatArg
-	},
-	async run({ args }) {
-		const email = String(args.email ?? "");
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
-		const format = parseFormat(String(args.format ?? "json"));
-		if (Result.isError(networkResult)) {
-			printResult(Result.err(networkResult.error._tag), "json");
-			return;
-		}
-		const network = networkResult.value;
-		const validation = Result.try({
-			try: () => emailSchema.parse(email),
-			catch: (e) => e
-		});
-		if (Result.isError(validation)) {
-			const msg = validation.error instanceof z.ZodError ? formatZodError$11(validation.error) : validation.error instanceof Error ? validation.error.message : String(validation.error);
-			printResult(Result.err(msg), format);
-			return;
-		}
-		log.message(pc.cyan(`Sending OTP to ${email}...`));
-		const otpResponseResult = await requestOtp(email);
-		if (Result.isError(otpResponseResult)) {
-			const msg = `AuthRequestError: ${otpResponseResult.error.cause}`;
-			printResult(Result.err(msg), format);
-			return;
-		}
-		const otpResponse = otpResponseResult.value;
-		if (!otpResponse || !otpResponse.ok) return;
-		log.success(otpResponse.message);
-		const otpInput = await text({
-			message: `Enter the OTP sent to ${email}`,
-			placeholder: "123456",
-			validate: (value) => {
-				if (!value || value.trim().length === 0) return "OTP is required";
-			}
-		});
-		if (isCancel(otpInput)) {
-			cancel("Login cancelled.");
-			process.exit(0);
-		}
-		const otp = String(otpInput);
-		await runApp("wallet login verify", async () => {
-			const verifyResult = await verifyOtp(email, otp);
-			if (Result.isError(verifyResult)) {
-				printResult(Result.err(`OTP verification failed: ${verifyResult.error.cause}`), format);
-				return;
-			}
-			const verifyResponse = verifyResult.value;
-			if (!verifyResponse.verified) {
-				printResult(Result.err("OTP verification failed."), format);
-				return;
-			}
-			const sessionResult = saveSession(verifyResponse.token, verifyResponse.email);
-			if (Result.isError(sessionResult)) {
-				printResult(Result.err(formatSessionError(sessionResult.error)), format);
-				return;
-			}
-			log.message(pc.cyan("Setting up your wallet..."));
-			const walletResult = await createWallet(network);
-			if (Result.isError(walletResult)) {
-				printResult(Result.err(formatWalletError(walletResult.error)), format);
-				return;
-			}
-			const wallet = walletResult.value;
-			log.success(pc.green(wallet.publicKey ? `Wallet ready: ${wallet.publicKey.slice(0, 8)}...` : "Wallet recovered!"));
-			printData({ wallet }, format);
-			return wallet;
-		}, format);
-	}
-});
-//#endregion
 //#region src/commands/wallet-verify.ts
 const walletVerify = defineCommand({
 	meta: {
@@ -541,7 +490,7 @@ const walletVerify = defineCommand({
 	async run({ args }) {
 		const email = String(args.email ?? "");
 		const otp = String(args.otp ?? "");
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 		const format = parseFormat(String(args.format ?? "json"));
 		if (Result.isError(networkResult)) {
 			printResult(Result.err(networkResult.error._tag), "json");
@@ -1182,7 +1131,7 @@ const accountDetails = defineCommand({
 		format: formatArg
 	},
 	async run({ args }) {
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 		const format = parseFormat(String(args.format ?? "json"));
 		if (Result.isError(networkResult)) {
 			printResult(Result.err(networkResult.error._tag), "json");
@@ -1243,7 +1192,7 @@ const accountTransactions = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 		const format = parseFormat(String(args.format ?? "json"));
 		if (Result.isError(networkResult)) {
 			printResult(Result.err(networkResult.error._tag), "json");
@@ -1312,7 +1261,7 @@ const accountPayments = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 		const format = parseFormat(String(args.format ?? "json"));
 		if (Result.isError(networkResult)) {
 			printResult(Result.err(networkResult.error._tag), "json");
@@ -1386,7 +1335,7 @@ const accountCommand = defineCommand({
 				}
 			},
 			async run({ args }) {
-				const networkResult = parseNetwork(String(args.network ?? "testnet"));
+				const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 				const format = parseFormat(String(args.format ?? "json"));
 				if (Result.isError(networkResult)) {
 					printResult(Result.err(networkResult.error._tag), "json");
@@ -1458,7 +1407,7 @@ const assetsCommand = defineCommand({
 				}
 			},
 			async run({ args }) {
-				const networkResult = parseNetwork(String(args.network ?? "testnet"));
+				const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 				const format = parseFormat(String(args.format ?? "json"));
 				if (Result.isError(networkResult)) {
 					printResult(Result.err(networkResult.error._tag), "json");
@@ -1516,7 +1465,7 @@ const assetsCommand = defineCommand({
 				}
 			},
 			async run({ args }) {
-				const networkResult = parseNetwork(String(args.network ?? "testnet"));
+				const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 				const format = parseFormat(String(args.format ?? "json"));
 				if (Result.isError(networkResult)) {
 					printResult(Result.err(networkResult.error._tag), "json");
@@ -1591,7 +1540,7 @@ const sendCommand = defineCommand({
 		format: formatArg
 	},
 	async run({ args }) {
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 		const format = parseFormat(String(args.format ?? "json"));
 		if (Result.isError(networkResult)) {
 			printResult(Result.err(networkResult.error._tag), "json");
@@ -1644,7 +1593,7 @@ const feeCommand = defineCommand({
 		format: formatArg
 	},
 	async run({ args }) {
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 		const format = parseFormat(String(args.format ?? "json"));
 		if (Result.isError(networkResult)) {
 			printResult(Result.err(networkResult.error._tag), "json");
@@ -1684,7 +1633,7 @@ const monitorTransactions = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 		const format = parseFormat(String(args.format ?? "json"));
 		if (Result.isError(networkResult)) {
 			printResult(Result.err(networkResult.error._tag), "json");
@@ -1761,7 +1710,7 @@ const monitorPayments = defineCommand({
 		}
 	},
 	async run({ args }) {
-		const networkResult = parseNetwork(String(args.network ?? "testnet"));
+		const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
 		const format = parseFormat(String(args.format ?? "json"));
 		if (Result.isError(networkResult)) {
 			printResult(Result.err(networkResult.error._tag), "json");
@@ -1818,6 +1767,491 @@ function formatZodError(e) {
 	return e.issues.map((issue) => issue.message).join(", ");
 }
 //#endregion
+//#region src/commands/monitor.ts
+const monitorCommand = defineCommand({
+	meta: {
+		name: "monitor",
+		description: "Stream live data from Horizon via SSE"
+	},
+	subCommands: {
+		transactions: monitorTransactions,
+		payments: monitorPayments,
+		effects: defineCommand({
+			meta: {
+				name: "effects",
+				description: "Stream effects for an account in real-time"
+			},
+			args: {
+				address: {
+					type: "positional",
+					description: "Stellar public key (G...)",
+					required: true
+				},
+				network: networkArg,
+				format: formatArg,
+				cursor: {
+					type: "string",
+					alias: ["c"],
+					description: "Start from this cursor (default: 'now' for new events)",
+					default: "now"
+				}
+			},
+			async run({ args }) {
+				const networkResult = parseNetwork$4(String(args.network ?? "testnet"));
+				const format = parseFormat(String(args.format ?? "json"));
+				if (Result.isError(networkResult)) {
+					printResult(Result.err(networkResult.error._tag), "json");
+					return;
+				}
+				const network = networkResult.value;
+				const address = String(args.address ?? "");
+				const validation = Result.try({
+					try: () => stellarPublicKey.parse(address),
+					catch: (e) => e
+				});
+				if (Result.isError(validation)) {
+					const msg = validation.error instanceof z.ZodError ? formatZodError(validation.error) : validation.error instanceof Error ? validation.error.message : String(validation.error);
+					printResult(Result.err(msg), format);
+					return;
+				}
+				const cursor = args.cursor === "now" ? void 0 : String(args.cursor);
+				let close;
+				try {
+					close = await runApp("monitor effects", async () => {
+						return streamEffects(address, network, { cursor }, (record) => {
+							console.log(JSON.stringify({
+								ok: true,
+								data: record
+							}));
+						}, (error) => {
+							const message = error instanceof Error ? error.message : String(error);
+							console.log(JSON.stringify({
+								ok: false,
+								error: `Stream error: ${message}`
+							}));
+						});
+					}, format);
+				} catch (e) {
+					const message = e instanceof Error ? e.message : String(e);
+					printResult(Result.err(`Failed to stream effects: ${message}`), "json");
+					return;
+				}
+				console.log(JSON.stringify({
+					ok: true,
+					data: { message: `Streaming effects for ${address} on ${network}... Press Ctrl+C to stop.` }
+				}, null, 2));
+				await new Promise((resolve) => {
+					process.on("SIGINT", () => {
+						close();
+						resolve();
+					});
+				});
+			}
+		})
+	}
+});
+//#endregion
+//#region src/mcp/wallet-tools.ts
+function ok$3(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: true,
+			data
+		}, null, 2)
+	}] };
+}
+function err$3(message) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: false,
+			error: message
+		}, null, 2)
+	}] };
+}
+function parseNetwork$3(value) {
+	return value === "pubnet" ? "pubnet" : "testnet";
+}
+function formatZodIssues(issues) {
+	return issues.map((i) => i.message).join(", ");
+}
+function registerWalletTools(server) {
+	server.registerTool("wallet_login", {
+		description: "Request an OTP code be sent to the user's email. After calling this, use wallet_verify with the code the user provides. Does NOT require an active session.",
+		inputSchema: { email: z.string().describe("User's email address") }
+	}, async ({ email }) => {
+		const validation = emailSchema.safeParse(email);
+		if (!validation.success) return err$3(`Invalid email: ${formatZodIssues(validation.error.issues)}`);
+		const result = await requestOtp(email);
+		if (Result.isError(result)) return err$3(`Could not reach auth server: ${result.error.cause}`);
+		const response = result.value;
+		if (!response || !response.ok) return err$3("Failed to send OTP email");
+		return ok$3({ message: response.message });
+	});
+	server.registerTool("wallet_verify", {
+		description: "Verify an OTP code and create or recover the wallet. The session is saved locally so subsequent tools (wallet_address, wallet_balance, wallet_transfer, etc.) work without re-authentication.",
+		inputSchema: {
+			email: z.string().describe("Must match the email used in wallet_login"),
+			otp: z.string().describe("OTP code from email"),
+			network: z.enum(["testnet", "pubnet"]).default("testnet").describe("Stellar network")
+		}
+	}, async ({ email, otp, network }) => {
+		const emailValidation = emailSchema.safeParse(email);
+		if (!emailValidation.success) return err$3(`Invalid email: ${formatZodIssues(emailValidation.error.issues)}`);
+		const otpValidation = otpSchema.safeParse(otp);
+		if (!otpValidation.success) return err$3(`Invalid OTP: ${formatZodIssues(otpValidation.error.issues)}`);
+		const verifyResult = await verifyOtp(email, otp);
+		if (Result.isError(verifyResult)) return err$3(`OTP verification failed: ${verifyResult.error.cause}`);
+		const verifyResponse = verifyResult.value;
+		if (!verifyResponse.verified) return err$3("OTP verification failed.");
+		const sessionResult = saveSession(verifyResponse.token, verifyResponse.email);
+		if (Result.isError(sessionResult)) return err$3(formatSessionError(sessionResult.error));
+		const walletResult = await createWallet(parseNetwork$3(network));
+		if (Result.isError(walletResult)) return err$3(formatWalletError(walletResult.error));
+		const wallet = walletResult.value;
+		return ok$3({ wallet: {
+			email: wallet.email,
+			publicKey: wallet.publicKey,
+			network: wallet.network,
+			createdAt: wallet.createdAt
+		} });
+	});
+	server.registerTool("wallet_address", {
+		description: "Get the logged-in wallet's public key, network, and email. Requires an active session.",
+		inputSchema: {}
+	}, async () => {
+		const addressResult = await fetchAddress();
+		if (Result.isError(addressResult)) return err$3(formatWalletError(addressResult.error));
+		const addr = addressResult.value;
+		return ok$3({
+			publicKey: addr.publicKey,
+			network: addr.network,
+			email: addr.email
+		});
+	});
+	server.registerTool("wallet_balance", {
+		description: "Get all asset balances for the logged-in wallet. Requires an active session.",
+		inputSchema: {}
+	}, async () => {
+		const walletResult = await fetchWallet();
+		if (Result.isError(walletResult)) return err$3(formatWalletError(walletResult.error));
+		const wallet = walletResult.value;
+		const balancesResult = await getBalances(wallet.publicKey, wallet.network);
+		if (Result.isError(balancesResult)) return err$3(formatStellarError(balancesResult.error));
+		return ok$3({
+			address: wallet.publicKey,
+			email: wallet.email,
+			balances: balancesResult.value
+		});
+	});
+	server.registerTool("wallet_transfer", {
+		description: "Send XLM from the logged-in wallet to another Stellar address. Requires an active session.",
+		inputSchema: {
+			destination: z.string().describe("Destination public key (G...)"),
+			amount: z.string().describe("Amount in XLM (up to 7 decimal places)")
+		}
+	}, async ({ destination, amount }) => {
+		const destValidation = stellarPublicKey.safeParse(destination);
+		if (!destValidation.success) return err$3(`Invalid destination: ${formatZodIssues(destValidation.error.issues)}`);
+		const amountValidation = amountSchema.safeParse(amount);
+		if (!amountValidation.success) return err$3(`Invalid amount: ${formatZodIssues(amountValidation.error.issues)}`);
+		const walletResult = await fetchWallet();
+		if (Result.isError(walletResult)) return err$3(formatWalletError(walletResult.error));
+		const result = await transferXlm(walletResult.value.secretKey, destination, amount, walletResult.value.network);
+		if (Result.isError(result)) return err$3(formatStellarError(result.error));
+		return ok$3(result.value);
+	});
+	server.registerTool("wallet_logout", {
+		description: "Clear the local wallet session.",
+		inputSchema: {}
+	}, async () => {
+		const sessionResult = loadSession();
+		if (Result.isError(sessionResult)) return err$3(formatSessionError(sessionResult.error));
+		const email = sessionResult.value.email;
+		const clearResult = clearSession();
+		if (Result.isError(clearResult)) return err$3(formatSessionError(clearResult.error));
+		return ok$3({
+			loggedOut: true,
+			email
+		});
+	});
+}
+//#endregion
+//#region src/mcp/account-tools.ts
+function ok$2(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: true,
+			data
+		}, null, 2)
+	}] };
+}
+function err$2(message) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: false,
+			error: message
+		}, null, 2)
+	}] };
+}
+function parseNetwork$2(value) {
+	return value === "pubnet" ? "pubnet" : "testnet";
+}
+const addressParam = z.string().describe("Stellar public key (G...)");
+const networkParam$1 = z.enum(["testnet", "pubnet"]).default("testnet").describe("Stellar network");
+const limitParam$1 = z.number().int().min(1).max(200).default(10).describe("Max records to return");
+const cursorParam = z.string().optional().describe("Pagination cursor");
+const orderParam = z.enum(["asc", "desc"]).default("desc").describe("Sort order");
+function registerAccountTools(server) {
+	server.registerTool("account_details", {
+		description: "Get detailed account information from Horizon: balances, signers, thresholds, flags, and more.",
+		inputSchema: {
+			address: addressParam,
+			network: networkParam$1
+		}
+	}, async ({ address, network }) => {
+		const validation = stellarPublicKey.safeParse(address);
+		if (!validation.success) return err$2(`Invalid address: ${validation.error.issues.map((i) => i.message).join(", ")}`);
+		const result = await getAccountDetails(address, parseNetwork$2(network));
+		if (Result.isError(result)) return err$2(formatHorizonError(result.error));
+		return ok$2(result.value);
+	});
+	server.registerTool("account_transactions", {
+		description: "Get transaction history for a Stellar account from Horizon.",
+		inputSchema: {
+			address: addressParam,
+			network: networkParam$1,
+			limit: limitParam$1,
+			cursor: cursorParam,
+			order: orderParam
+		}
+	}, async ({ address, network, limit, cursor, order }) => {
+		const validation = stellarPublicKey.safeParse(address);
+		if (!validation.success) return err$2(`Invalid address: ${validation.error.issues.map((i) => i.message).join(", ")}`);
+		const result = await getTransactions(address, parseNetwork$2(network), {
+			limit,
+			cursor,
+			order
+		});
+		if (Result.isError(result)) return err$2(formatHorizonError(result.error));
+		return ok$2({
+			address,
+			count: result.value.length,
+			transactions: result.value
+		});
+	});
+	server.registerTool("account_payments", {
+		description: "Get payment history for a Stellar account from Horizon.",
+		inputSchema: {
+			address: addressParam,
+			network: networkParam$1,
+			limit: limitParam$1,
+			cursor: cursorParam,
+			order: orderParam
+		}
+	}, async ({ address, network, limit, cursor, order }) => {
+		const validation = stellarPublicKey.safeParse(address);
+		if (!validation.success) return err$2(`Invalid address: ${validation.error.issues.map((i) => i.message).join(", ")}`);
+		const result = await getPayments(address, parseNetwork$2(network), {
+			limit,
+			cursor,
+			order
+		});
+		if (Result.isError(result)) return err$2(formatHorizonError(result.error));
+		return ok$2({
+			address,
+			count: result.value.length,
+			payments: result.value
+		});
+	});
+	server.registerTool("account_effects", {
+		description: "Get effects history for a Stellar account from Horizon.",
+		inputSchema: {
+			address: addressParam,
+			network: networkParam$1,
+			limit: limitParam$1,
+			cursor: cursorParam
+		}
+	}, async ({ address, network, limit, cursor }) => {
+		const validation = stellarPublicKey.safeParse(address);
+		if (!validation.success) return err$2(`Invalid address: ${validation.error.issues.map((i) => i.message).join(", ")}`);
+		const result = await getEffects(address, parseNetwork$2(network), {
+			limit,
+			cursor
+		});
+		if (Result.isError(result)) return err$2(formatHorizonError(result.error));
+		return ok$2({
+			address,
+			count: result.value.length,
+			effects: result.value
+		});
+	});
+}
+//#endregion
+//#region src/mcp/asset-tools.ts
+function ok$1(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: true,
+			data
+		}, null, 2)
+	}] };
+}
+function err$1(message) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: false,
+			error: message
+		}, null, 2)
+	}] };
+}
+function parseNetwork$1(value) {
+	return value === "pubnet" ? "pubnet" : "testnet";
+}
+const networkParam = z.enum(["testnet", "pubnet"]).default("testnet").describe("Stellar network");
+const limitParam = z.number().int().min(1).max(200).default(10).describe("Max records to return");
+function parseAssetInput(input) {
+	if (input === "native" || input === "XLM") return { assetType: "native" };
+	const parts = input.split(":");
+	if (parts.length !== 2) throw new Error(`Invalid asset format: "${input}". Use "native" or "CODE:ISSUER".`);
+	return {
+		assetType: parts[0].length <= 4 ? "credit_alphanum4" : "credit_alphanum12",
+		assetCode: parts[0],
+		assetIssuer: parts[1]
+	};
+}
+function registerAssetTools(server) {
+	server.registerTool("assets_search", {
+		description: "Search for assets on Stellar. Filter by asset code and/or issuer.",
+		inputSchema: {
+			network: networkParam,
+			code: z.string().optional().describe("Filter by asset code (e.g. USDC)"),
+			issuer: z.string().optional().describe("Filter by asset issuer (G...)"),
+			limit: limitParam
+		}
+	}, async ({ network, code, issuer, limit }) => {
+		const result = await getAssets(parseNetwork$1(network), {
+			limit,
+			code,
+			issuer
+		});
+		if (Result.isError(result)) return err$1(formatHorizonError(result.error));
+		return ok$1({
+			count: result.value.length,
+			assets: result.value
+		});
+	});
+	server.registerTool("assets_orderbook", {
+		description: "View the order book (bids and asks) for a pair of assets on Stellar.",
+		inputSchema: {
+			selling: z.string().describe("Selling asset: 'native' for XLM, or 'CODE:ISSUER'"),
+			buying: z.string().describe("Buying asset: 'native' for XLM, or 'CODE:ISSUER'"),
+			network: networkParam,
+			limit: limitParam
+		}
+	}, async ({ selling, buying, network, limit }) => {
+		try {
+			const result = await getOrderbook(parseAssetInput(selling), parseAssetInput(buying), parseNetwork$1(network), { limit });
+			if (Result.isError(result)) return err$1(formatHorizonError(result.error));
+			return ok$1(result.value);
+		} catch (e) {
+			return err$1(e instanceof Error ? e.message : String(e));
+		}
+	});
+	server.registerTool("fee_stats", {
+		description: "Get current fee statistics from the Stellar network.",
+		inputSchema: { network: networkParam }
+	}, async ({ network }) => {
+		const result = await getFeeStats(parseNetwork$1(network));
+		if (Result.isError(result)) return err$1(formatHorizonError(result.error));
+		return ok$1(result.value);
+	});
+}
+//#endregion
+//#region src/mcp/payment-tools.ts
+function ok(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: true,
+			data
+		}, null, 2)
+	}] };
+}
+function err(message) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify({
+			ok: false,
+			error: message
+		}, null, 2)
+	}] };
+}
+function parseNetwork(value) {
+	return value === "pubnet" ? "pubnet" : "testnet";
+}
+function registerPaymentTools(server) {
+	server.registerTool("send_payment", {
+		description: "Send a payment (XLM or custom asset) from the logged-in wallet to another Stellar address. Requires an active session.",
+		inputSchema: {
+			destination: z.string().describe("Destination public key (G...)"),
+			amount: z.string().describe("Amount to send (up to 7 decimal places)"),
+			asset: z.string().default("native").describe("Asset: 'native' for XLM, or 'CODE:ISSUER' for custom assets"),
+			memo: z.string().optional().describe("Transaction memo text (max 28 chars)"),
+			network: z.enum(["testnet", "pubnet"]).default("testnet").describe("Stellar network")
+		}
+	}, async ({ destination, amount, asset, memo, network }) => {
+		const destValidation = stellarPublicKey.safeParse(destination);
+		if (!destValidation.success) return err(`Invalid destination: ${destValidation.error.issues.map((i) => i.message).join(", ")}`);
+		const amountValidation = amountSchema.safeParse(amount);
+		if (!amountValidation.success) return err(`Invalid amount: ${amountValidation.error.issues.map((i) => i.message).join(", ")}`);
+		const assetValidation = assetSchema.safeParse(asset);
+		if (!assetValidation.success) return err(`Invalid asset: ${assetValidation.error.issues.map((i) => i.message).join(", ")}`);
+		if (memo !== void 0) {
+			const memoValidation = memoSchema.safeParse(memo);
+			if (!memoValidation.success) return err(`Invalid memo: ${memoValidation.error.issues.map((i) => i.message).join(", ")}`);
+		}
+		const walletResult = await fetchWallet();
+		if (Result.isError(walletResult)) return err(formatWalletError(walletResult.error));
+		const result = await sendPayment(walletResult.value.secretKey, destination, amount, asset, parseNetwork(network), memo);
+		if (Result.isError(result)) return err(formatStellarError(result.error));
+		return ok(result.value);
+	});
+	server.registerTool("pay_url", {
+		description: "Make an X402 micropayment to a URL. The CLI detects 402 responses, signs auth entries, and returns the paid content. Requires an active session.",
+		inputSchema: { url: z.string().describe("URL that requires X402 payment") }
+	}, async ({ url }) => {
+		const result = await pay(url);
+		if (Result.isError(result)) return err(formatPaymentError(result.error));
+		return ok(result.value);
+	});
+}
+//#endregion
+//#region src/mcp/mod.ts
+async function startMcpServer() {
+	const server = new McpServer({
+		name: "stelagent",
+		version: "0.1.0"
+	}, { instructions: [
+		"Stelagent MCP server for Stellar blockchain operations.",
+		"Authentication flow: 1) wallet_login (sends OTP to email) → 2) wallet_verify (verifies OTP, creates session and wallet). After verify, all other wallet tools work.",
+		"Account, asset, and fee tools are public and require no authentication — only a Stellar public key or network parameter.",
+		"All tools return { ok: true, data } on success or { ok: false, error } on failure.",
+		"Network defaults to 'testnet'. Use 'pubnet' for mainnet."
+	].join("\n") });
+	registerWalletTools(server);
+	registerAccountTools(server);
+	registerAssetTools(server);
+	registerPaymentTools(server);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+}
+//#endregion
 //#region src/index.ts
 runMain(defineCommand({
 	meta: {
@@ -1832,86 +2266,21 @@ runMain(defineCommand({
 		assets: assetsCommand,
 		send: sendCommand,
 		fee: feeCommand,
-		monitor: defineCommand({
+		monitor: monitorCommand,
+		mcp: defineCommand({
 			meta: {
-				name: "monitor",
-				description: "Stream live data from Horizon via SSE"
+				name: "mcp",
+				description: "Start the MCP server on stdio"
 			},
-			subCommands: {
-				transactions: monitorTransactions,
-				payments: monitorPayments,
-				effects: defineCommand({
-					meta: {
-						name: "effects",
-						description: "Stream effects for an account in real-time"
-					},
-					args: {
-						address: {
-							type: "positional",
-							description: "Stellar public key (G...)",
-							required: true
-						},
-						network: networkArg,
-						format: formatArg,
-						cursor: {
-							type: "string",
-							alias: ["c"],
-							description: "Start from this cursor (default: 'now' for new events)",
-							default: "now"
-						}
-					},
-					async run({ args }) {
-						const networkResult = parseNetwork(String(args.network ?? "testnet"));
-						const format = parseFormat(String(args.format ?? "json"));
-						if (Result.isError(networkResult)) {
-							printResult(Result.err(networkResult.error._tag), "json");
-							return;
-						}
-						const network = networkResult.value;
-						const address = String(args.address ?? "");
-						const validation = Result.try({
-							try: () => stellarPublicKey.parse(address),
-							catch: (e) => e
-						});
-						if (Result.isError(validation)) {
-							const msg = validation.error instanceof z.ZodError ? formatZodError(validation.error) : validation.error instanceof Error ? validation.error.message : String(validation.error);
-							printResult(Result.err(msg), format);
-							return;
-						}
-						const cursor = args.cursor === "now" ? void 0 : String(args.cursor);
-						let close;
-						try {
-							close = await runApp("monitor effects", async () => {
-								return streamEffects(address, network, { cursor }, (record) => {
-									console.log(JSON.stringify({
-										ok: true,
-										data: record
-									}));
-								}, (error) => {
-									const message = error instanceof Error ? error.message : String(error);
-									console.log(JSON.stringify({
-										ok: false,
-										error: `Stream error: ${message}`
-									}));
-								});
-							}, format);
-						} catch (e) {
-							const message = e instanceof Error ? e.message : String(e);
-							printResult(Result.err(`Failed to stream effects: ${message}`), "json");
-							return;
-						}
-						console.log(JSON.stringify({
-							ok: true,
-							data: { message: `Streaming effects for ${address} on ${network}... Press Ctrl+C to stop.` }
-						}, null, 2));
-						await new Promise((resolve) => {
-							process.on("SIGINT", () => {
-								close();
-								resolve();
-							});
-						});
-					}
-				})
+			args: {},
+			async run() {
+				try {
+					await startMcpServer();
+				} catch (e) {
+					const message = e instanceof Error ? e.message : String(e);
+					console.error(`Failed to start MCP server: ${message}`);
+					process.exit(1);
+				}
 			}
 		})
 	}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "stelagent",
-  "version": "0.0.1",
+  "version": "0.0.3",
   "description": "Modular, agent-first CLI for Stellar — wallet, payments, markets, and DeFi",
   "license": "MIT",
   "bin": {
@@ -25,6 +25,7 @@
   },
   "dependencies": {
     "@clack/prompts": "^1.2.0",
+    "@modelcontextprotocol/sdk": "^1.29.0",
     "@stellar/stellar-sdk": "^14.6.1",
     "@x402/core": "^2.9.0",
     "@x402/stellar": "^2.9.0",