context-markets-mcp 0.1.2 → 0.2.1

package/README.md

@@ -28,34 +28,101 @@ Add to your `claude_desktop_config.json`:
   "mcpServers": {
     "context-markets": {
       "command": "npx",
-      "args": ["context-markets-mcp"],
-      "env": {
-        "CONTEXT_API_KEY": "your-api-key",
-        "CONTEXT_PRIVATE_KEY": "your-wallet-private-key"
-      }
+      "args": ["context-markets-mcp"]
     }
   }
 }
 ```
 
-## Available Tools
+No environment variables needed — the server walks you through setup on first use.
+
+## Getting Started
 
-### Read-only (no auth needed)
+The first time you (or your agent) use a trading tool, the server will guide you through onboarding:
 
-`context_list_markets` · `context_get_market` · `context_get_quotes` · `context_get_orderbook` · `context_simulate_trade` · `context_price_history` · `context_get_oracle` · `context_global_activity`
+1. **Wallet** — `context_generate_wallet` creates a new wallet or imports an existing private key
+2. **Save credentials** — persists to `~/.config/context/config.env` (chmod 600, shared with the [CLI](https://github.com/contextwtf/context-cli))
+3. **API key** — pass your Context API key (get one at [context.markets](https://context.markets)) via the `apiKey` param
+4. **Approve contracts** — `context_account_setup` approves on-chain (requires ETH on Base for gas)
+5. **Deposit USDC** — `context_deposit` deposits USDC into the exchange
 
-### Trading (requires API key + private key)
+If anything fails (no ETH, rate limit, etc.), you can re-run the same tool — it detects your existing config and picks up where you left off.
 
-`context_place_order` · `context_cancel_order` · `context_my_orders` · `context_get_portfolio` · `context_get_balance` · `context_account_setup` · `context_mint_test_usdc` · `context_create_market`
+### Manual setup
 
-## Environment Variables
+If you prefer to configure manually:
 
-| Variable | Required | Description |
-|----------|----------|-------------|
-| `CONTEXT_API_KEY` | For all tools | API key from context.markets |
-| `CONTEXT_PRIVATE_KEY` | For trading only | Ethereum private key for signing |
+```bash
+# Option 1: Environment variables
+export CONTEXT_API_KEY="your-api-key"
+export CONTEXT_PRIVATE_KEY="0x..."
+
+# Option 2: Config file (created by context_generate_wallet or `context setup` in the CLI)
+# ~/.config/context/config.env
+```
+
+Credentials are loaded in order: env vars > config file.
+
+Need an API key? Visit [context.markets](https://context.markets).
+
+## Available Tools
 
-Read-only tools work with zero config. Need an API key? Visit [context.markets](https://context.markets).
+### Read-only (no wallet needed)
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `context_list_markets` | List and search prediction markets on Context Markets | `query`, `status`, `category`, `sortBy`, `limit` |
+| `context_get_market` | Get detailed information about a specific prediction market | `marketId` |
+| `context_get_quotes` | Get current bid/ask/last prices for a market's YES and NO outcomes | `marketId` |
+| `context_get_orderbook` | Get the orderbook (bid/ask ladder) for a market | `marketId`, `depth` |
+| `context_simulate_trade` | Simulate a trade to estimate fill price, cost, and slippage | `marketId`, `side`, `amount` |
+| `context_price_history` | Get historical price data for a market over a specified timeframe | `marketId`, `timeframe` |
+| `context_get_oracle` | Get the AI oracle's resolution analysis for a market | `marketId` |
+| `context_global_activity` | Get recent trading activity across all markets | -- |
+
+### Account setup and funding
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `context_generate_wallet` | Generate a new wallet or import an existing key | `privateKey`, `apiKey`, `overwrite` |
+| `context_wallet_status` | Get address, balances, and approval status | -- |
+| `context_account_setup` | Approve USDC spending and operator permissions | -- |
+| `context_deposit` | Deposit USDC into the exchange | `amount` |
+| `context_withdraw` | Withdraw USDC from the exchange back to your wallet | `amount` |
+| `context_mint_test_usdc` | Mint test USDC on Base Sepolia | `amount` |
+
+### Trading and orders
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `context_place_order` | Place a buy or sell order on a prediction market | `marketId`, `outcome`, `side`, `size`, `price` |
+| `context_cancel_order` | Cancel an open order | `nonce` |
+| `context_cancel_replace_order` | Atomically cancel an existing order and place a new one | `cancelNonce`, `marketId`, `outcome`, `side`, `priceCents`, `size` |
+| `context_my_orders` | List your open orders | `marketId` |
+| `context_bulk_create_orders` | Create multiple orders in a single atomic batch | `orders` |
+| `context_bulk_cancel_orders` | Cancel multiple open orders in a single batch | `nonces` |
+| `context_bulk_orders` | Atomically create and cancel orders in a single batch | `creates`, `cancelNonces` |
+
+### Portfolio
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `context_get_portfolio` | Get positions with P&L | `kind` |
+| `context_get_balance` | Get USDC balance and token holdings | -- |
+
+### Market creation
+
+| Tool | Description | Key Params |
+|------|-------------|------------|
+| `context_create_market` | Create a market from a question | `question` |
+| `context_agent_submit_market` | Submit a fully formed market draft, wait for oracle approval, and create it on-chain | `formattedQuestion`, `shortQuestion`, `marketType`, `evidenceMode`, `resolutionCriteria`, `endTime` |
+
+## Key Concepts
+
+- **Prices are in cents** (1–99). A price of 65 means $0.65 per share.
+- **Outcomes are yes or no.** Each market is a binary question.
+- **Read-only tools work with zero config.** Trading tools need a wallet — run `context_generate_wallet` first.
+- **Shared config.** The MCP server and [CLI](https://github.com/contextwtf/context-cli) share `~/.config/context/config.env`, so you only set up once.
 
 ## Documentation
 

package/dist/index.js

@@ -1,20 +1,34 @@
 #!/usr/bin/env node
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
-import dotenv from "dotenv";
-import { fileURLToPath } from "url";
-import { dirname, resolve } from "path";
+import { loadConfig } from "./lib/config.js";
 import { registerMarketTools } from "./tools/markets.js";
 import { registerOrderTools } from "./tools/orders.js";
 import { registerPortfolioTools } from "./tools/portfolio.js";
 import { registerAccountTools } from "./tools/account.js";
 import { registerQuestionTools } from "./tools/questions.js";
-const __filename = fileURLToPath(import.meta.url);
-const __dirname = dirname(__filename);
-dotenv.config({ path: resolve(__dirname, "..", ".env") });
+// Load keys from ~/.config/context/config.env (shared with the CLI).
+// Env vars take precedence — config file fills in what's missing.
+const config = loadConfig();
+for (const [key, value] of Object.entries(config)) {
+    if (!process.env[key]) {
+        process.env[key] = value;
+    }
+}
 const server = new McpServer({
     name: "context-markets",
-    version: "0.1.0",
+    version: "0.2.1",
+}, {
+    instructions: "Context Markets MCP — trade prediction markets from any AI agent.\n\n" +
+        "ONBOARDING: Before any trading operation, the user needs a wallet. " +
+        "If a trading tool fails with 'No wallet configured', guide the user through setup:\n" +
+        "1. Run context_generate_wallet to create or import a wallet.\n" +
+        "2. The user needs ETH on Base for gas fees — show them their address.\n" +
+        "3. Run context_account_setup to approve contracts.\n" +
+        "4. Deposit USDC with context_deposit.\n\n" +
+        "Read-only tools (context_list_markets, context_get_market, context_get_quotes, etc.) " +
+        "work without a wallet. Trading, portfolio, account, and market creation tools require a private key.\n\n" +
+        "IMPORTANT: Never generate a wallet or overwrite an existing one without explicit user confirmation.",
 });
 registerMarketTools(server);
 registerOrderTools(server);

package/dist/lib/client.d.ts

@@ -1,3 +1,5 @@
 import { ContextClient } from "context-markets";
+/** Reset the cached trading client so the next call picks up new env vars. */
+export declare function resetTradingClient(): void;
 export declare function getReadClient(): ContextClient;
 export declare function getTradingClient(): ContextClient;

package/dist/lib/client.js

@@ -1,31 +1,49 @@
 import { ContextClient } from "context-markets";
-let readClientInstance = null;
-let tradingClientInstance = null;
+import { loadConfig } from "./config.js";
+let readCache = null;
+let tradingCache = null;
+/** Reset the cached trading client so the next call picks up new env vars. */
+export function resetTradingClient() {
+    tradingCache = null;
+}
+/** Resolve a key from env vars first, then ~/.config/context/config.env. */
+function resolveKey(envKey) {
+    return process.env[envKey] || loadConfig()[envKey] || undefined;
+}
 function getChain() {
     return process.env.CONTEXT_CHAIN === "testnet" ? "testnet" : "mainnet";
 }
+function cacheKey(chain, apiKey, privateKey) {
+    return `${chain}_${apiKey ?? ""}_${privateKey ?? ""}`;
+}
 export function getReadClient() {
-    if (!readClientInstance) {
-        readClientInstance = new ContextClient({
-            apiKey: process.env.CONTEXT_API_KEY,
-            chain: getChain(),
-        });
+    const chain = getChain();
+    const apiKey = resolveKey("CONTEXT_API_KEY");
+    const key = cacheKey(chain, apiKey);
+    if (readCache?.key === key) {
+        return readCache.client;
     }
-    return readClientInstance;
+    const client = new ContextClient({ apiKey, chain });
+    readCache = { client, key };
+    return client;
 }
 export function getTradingClient() {
-    if (!tradingClientInstance) {
-        const apiKey = process.env.CONTEXT_API_KEY;
-        const privateKey = process.env.CONTEXT_PRIVATE_KEY;
-        if (!privateKey) {
-            throw new Error("CONTEXT_PRIVATE_KEY is required for trading operations. " +
-                "Set it in your MCP server env config.");
-        }
-        tradingClientInstance = new ContextClient({
-            apiKey,
-            chain: getChain(),
-            signer: { privateKey: privateKey },
-        });
+    const chain = getChain();
+    const apiKey = resolveKey("CONTEXT_API_KEY");
+    const privateKey = resolveKey("CONTEXT_PRIVATE_KEY");
+    if (!privateKey) {
+        throw new Error("No wallet configured. Run context_generate_wallet to create one, " +
+            "or set CONTEXT_PRIVATE_KEY in your environment.");
+    }
+    const key = cacheKey(chain, apiKey, privateKey);
+    if (tradingCache?.key === key) {
+        return tradingCache.client;
     }
-    return tradingClientInstance;
+    const client = new ContextClient({
+        apiKey,
+        chain,
+        signer: { privateKey: privateKey },
+    });
+    tradingCache = { client, key };
+    return client;
 }

package/dist/lib/config.d.ts

@@ -0,0 +1,6 @@
+/** Display-friendly path to the config file. */
+export declare function configPath(): string;
+/** Load config from ~/.config/context/config.env. Returns {} if missing. */
+export declare function loadConfig(): Record<string, string>;
+/** Save values to ~/.config/context/config.env, merging with existing. chmod 600. */
+export declare function saveConfig(values: Record<string, string>): void;

package/dist/lib/config.js

@@ -0,0 +1,52 @@
+import { readFileSync, writeFileSync, mkdirSync } from "fs";
+import { join } from "path";
+import { homedir } from "os";
+const CONFIG_DIR = join(homedir(), ".config", "context");
+const CONFIG_FILE = join(CONFIG_DIR, "config.env");
+/** Display-friendly path to the config file. */
+export function configPath() {
+    return "~/.config/context/config.env";
+}
+/** Parse a KEY=VALUE env file, stripping comments, blanks, and surrounding quotes. */
+function parseEnvFile(content) {
+    const entries = {};
+    for (const line of content.split("\n")) {
+        const trimmed = line.trim();
+        if (!trimmed || trimmed.startsWith("#"))
+            continue;
+        const eq = trimmed.indexOf("=");
+        if (eq === -1)
+            continue;
+        const key = trimmed.slice(0, eq);
+        let value = trimmed.slice(eq + 1);
+        // Strip surrounding quotes
+        if ((value.startsWith('"') && value.endsWith('"')) ||
+            (value.startsWith("'") && value.endsWith("'"))) {
+            value = value.slice(1, -1);
+        }
+        entries[key] = value;
+    }
+    return entries;
+}
+/** Serialize key-value pairs as KEY="VALUE" lines. */
+function serializeEnvFile(data) {
+    return Object.entries(data)
+        .map(([k, v]) => `${k}="${v}"`)
+        .join("\n") + "\n";
+}
+/** Load config from ~/.config/context/config.env. Returns {} if missing. */
+export function loadConfig() {
+    try {
+        return parseEnvFile(readFileSync(CONFIG_FILE, "utf-8"));
+    }
+    catch {
+        return {};
+    }
+}
+/** Save values to ~/.config/context/config.env, merging with existing. chmod 600. */
+export function saveConfig(values) {
+    mkdirSync(CONFIG_DIR, { recursive: true });
+    const existing = loadConfig();
+    const merged = { ...existing, ...values };
+    writeFileSync(CONFIG_FILE, serializeEnvFile(merged), { mode: 0o600 });
+}

package/dist/lib/utils.d.ts

@@ -1,4 +1,5 @@
 import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function validateHexNonce(nonce: string): `0x${string}`;
 export declare function toolResult(data: unknown): {
     content: {
         type: "text";

package/dist/lib/utils.js

@@ -1,3 +1,9 @@
+export function validateHexNonce(nonce) {
+    if (!/^0x[0-9a-fA-F]{64}$/.test(nonce)) {
+        throw new Error("Invalid nonce format: expected 0x-prefixed 32-byte hex string (66 characters)");
+    }
+    return nonce;
+}
 export function toolResult(data) {
     return {
         content: [

package/dist/tools/account.js

@@ -1,9 +1,141 @@
 import { z } from "zod";
-import { getTradingClient } from "../lib/client.js";
+import { generatePrivateKey, privateKeyToAccount } from "viem/accounts";
+import { formatEther, formatUnits } from "viem";
+import { getTradingClient, resetTradingClient } from "../lib/client.js";
+import { loadConfig, saveConfig, configPath } from "../lib/config.js";
 import { toolResult, toolError } from "../lib/utils.js";
+const MIN_ETH_FOR_GAS = 1000000000000n; // 0.000001 ETH
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
 export function registerAccountTools(server) {
-    // 1. Set up trading account
-    server.tool("context_account_setup", "Set up your trading account — approves USDC spending and operator permissions. Run this before your first trade. Requires CONTEXT_PRIVATE_KEY.", {}, async () => {
+    // 1. Generate or import a wallet
+    server.tool("context_generate_wallet", "Generate a new trading wallet or import an existing private key. " +
+        "Saves credentials to ~/.config/context/config.env (shared with the Context CLI). " +
+        "Also saves the API key if provided. " +
+        "IMPORTANT: If a wallet already exists, this will tell you — it will NOT overwrite " +
+        "unless you explicitly pass overwrite: true. Always confirm with the user before overwriting.", {
+        privateKey: z
+            .string()
+            .describe("Import an existing private key (0x-prefixed hex). Omit to generate a new one.")
+            .optional(),
+        apiKey: z
+            .string()
+            .describe("Context API key (ctx_...). Optional but recommended — get one at context.markets.")
+            .optional(),
+        overwrite: z
+            .boolean()
+            .describe("Set to true to replace an existing wallet. The agent MUST confirm with the user first.")
+            .optional(),
+    }, async (params) => {
+        try {
+            const existingConfig = loadConfig();
+            const existingKey = process.env.CONTEXT_PRIVATE_KEY || existingConfig.CONTEXT_PRIVATE_KEY;
+            const hasExistingWallet = Boolean(existingKey);
+            if (hasExistingWallet && params.privateKey && !params.overwrite) {
+                return toolError("A wallet is already configured. Set overwrite: true to replace it. WARNING: This will replace your existing wallet permanently.");
+            }
+            if (existingKey && !params.overwrite) {
+                if (params.apiKey) {
+                    saveConfig({ CONTEXT_API_KEY: params.apiKey });
+                    process.env.CONTEXT_API_KEY = params.apiKey;
+                }
+                const account = privateKeyToAccount(existingKey);
+                return toolResult({
+                    status: params.apiKey ? "api_key_saved" : "wallet_exists",
+                    address: account.address,
+                    configPath: configPath(),
+                    saved: Boolean(params.apiKey),
+                    message: params.apiKey
+                        ? "API key saved. Existing wallet left unchanged."
+                        : "A wallet is already configured. Use context_wallet_status for full details. " +
+                            "To replace it, call this tool again with overwrite: true — but confirm with the user first, " +
+                            "as the old key will be lost.",
+                });
+            }
+            // Validate imported key
+            let key;
+            if (params.privateKey) {
+                if (!/^0x[0-9a-fA-F]{64}$/.test(params.privateKey)) {
+                    return toolError("Invalid private key format. Expected 0x-prefixed 64-character hex string.");
+                }
+                key = params.privateKey;
+            }
+            else {
+                key = generatePrivateKey();
+            }
+            const account = privateKeyToAccount(key);
+            // Build config to save
+            const toSave = { CONTEXT_PRIVATE_KEY: key };
+            if (params.apiKey) {
+                toSave.CONTEXT_API_KEY = params.apiKey;
+                process.env.CONTEXT_API_KEY = params.apiKey;
+            }
+            // Save to shared config file (chmod 600)
+            saveConfig(toSave);
+            process.env.CONTEXT_PRIVATE_KEY = key;
+            resetTradingClient();
+            return toolResult({
+                status: params.privateKey ? "imported" : "generated",
+                address: account.address,
+                saved: true,
+                configPath: configPath(),
+                message: params.privateKey
+                    ? "Wallet imported and saved. Private key stored securely in config file."
+                    : "Wallet generated and saved. Private key stored securely in config file.",
+                nextSteps: [
+                    "Fund the wallet with ETH on Base for gas fees.",
+                    "Run context_account_setup to approve contracts for trading.",
+                    "Deposit USDC with context_deposit to start trading.",
+                ],
+            });
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    // 2. Full wallet status
+    server.tool("context_wallet_status", "Get comprehensive wallet status: address, ETH balance (for gas), USDC balance, " +
+        "approval status, and whether the account is ready to trade. " +
+        "Requires a wallet — run context_generate_wallet first if not set up.", {}, async () => {
+        try {
+            const client = getTradingClient();
+            const [status, balance] = await Promise.all([
+                client.account.status(),
+                client.portfolio.balance(),
+            ]);
+            const isReady = !status.needsApprovals;
+            const ethBalance = formatEther(status.ethBalance);
+            const usdcBalance = formatUnits(BigInt(balance.usdc.balance), 6);
+            const usdcAllowance = formatUnits(status.usdcAllowance, 6);
+            return toolResult({
+                address: status.address,
+                ethBalance,
+                usdcBalance,
+                usdcAllowance,
+                isReady,
+                needsApprovals: status.needsApprovals,
+                needsGaslessSetup: status.needsGaslessSetup,
+                isOperatorApproved: status.isOperatorApproved,
+                nextSteps: !isReady
+                    ? [
+                        ...(status.ethBalance < MIN_ETH_FOR_GAS
+                            ? [`Send ETH to ${status.address} on Base for gas fees.`]
+                            : []),
+                        "Run context_account_setup to approve contracts.",
+                        "Run context_deposit to deposit USDC for trading.",
+                    ]
+                    : ["Wallet is fully set up. You can start trading."],
+            });
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    // 3. Set up trading account (approve contracts)
+    server.tool("context_account_setup", "Approve USDC spending and operator permissions for trading. " +
+        "Run this once before your first trade. Requires a wallet and ETH on Base for gas — " +
+        "run context_generate_wallet first if not set up.", {}, async () => {
         try {
             const client = getTradingClient();
             const status = await client.account.status();
@@ -23,8 +155,51 @@ export function registerAccountTools(server) {
             return toolError(error);
         }
     });
-    // 2. Mint test USDC
-    server.tool("context_mint_test_usdc", "Mint test USDC on Base Sepolia testnet for paper trading. Default 1000 USDC. Requires CONTEXT_PRIVATE_KEY.", {
+    // 4. Deposit USDC
+    server.tool("context_deposit", "Deposit USDC into the exchange for trading. Requires approved contracts — " +
+        "run context_account_setup first if needed.", {
+        amount: z
+            .number()
+            .positive()
+            .describe("Amount of USDC to deposit"),
+    }, async (params) => {
+        try {
+            const client = getTradingClient();
+            const txHash = await client.account.deposit(params.amount);
+            return toolResult({
+                message: `Deposited $${params.amount.toFixed(2)} USDC successfully.`,
+                amount: params.amount,
+                txHash,
+            });
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    // 5. Withdraw USDC
+    server.tool("context_withdraw", "Withdraw USDC from the exchange back to your wallet. " +
+        "Requires a wallet — run context_generate_wallet first if not set up.", {
+        amount: z
+            .number()
+            .positive()
+            .describe("Amount of USDC to withdraw"),
+    }, async (params) => {
+        try {
+            const client = getTradingClient();
+            const txHash = await client.account.withdraw(params.amount);
+            return toolResult({
+                message: `Withdrew $${params.amount.toFixed(2)} USDC successfully.`,
+                amount: params.amount,
+                txHash,
+            });
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    // 6. Mint test USDC
+    server.tool("context_mint_test_usdc", "Mint test USDC on Base Sepolia testnet for paper trading. Default 1000 USDC. " +
+        "Requires a wallet — run context_generate_wallet first if not set up.", {
         amount: z
             .number()
             .describe("Amount of test USDC to mint (default 1000)")

package/dist/tools/orders.js

@@ -1,37 +1,95 @@
 import { z } from "zod";
 import { getTradingClient } from "../lib/client.js";
-import { toolResult, toolError } from "../lib/utils.js";
+import { toolResult, toolError, validateHexNonce, } from "../lib/utils.js";
+// ---------------------------------------------------------------------------
+// Shared schemas and helpers
+// ---------------------------------------------------------------------------
+const outcomeSchema = z.enum(["yes", "no"]).describe("Which outcome token: yes or no");
+const sideSchema = z.enum(["buy", "sell"]).describe("Buy to enter a position, sell to exit. Defaults to buy.").default("buy");
+const priceSchema = z.number().min(1).max(99).describe("Price in cents (1-99)");
+const sizeSchema = z.number().min(0.01).describe("Number of contracts (min 0.01)");
+const expirySchema = z.number().positive().describe("Auto-expire the order after this many seconds").optional();
+const inventoryModeSchema = z
+    .enum(["any", "hold", "mint"])
+    .describe("Token inventory mode. 'any' (default): use existing tokens or mint new ones. " +
+    "'hold': require existing token inventory. " +
+    "'mint': mint new complete sets from USDC (use for sells when you don't hold tokens).")
+    .optional();
+const takerOnlySchema = z
+    .boolean()
+    .describe("If true, the order must fill immediately or be voided. Default false.")
+    .optional();
+const INVENTORY_MODE_MAP = { any: 0, hold: 1, mint: 2 };
+/** Build a PlaceOrderRequest from tool params. */
+function buildOrderRequest(params) {
+    const req = {
+        marketId: params.marketId,
+        outcome: params.outcome,
+        side: params.side,
+        priceCents: params.priceCents,
+        size: params.size,
+    };
+    if (params.expirySeconds !== undefined)
+        req.expirySeconds = params.expirySeconds;
+    if (params.inventoryMode !== undefined) {
+        req.inventoryModeConstraint = INVENTORY_MODE_MAP[params.inventoryMode];
+    }
+    if (params.takerOnly) {
+        req.makerRoleConstraint = 2; // TAKER_ONLY
+    }
+    return req;
+}
+// ---------------------------------------------------------------------------
+// Tool registration
+// ---------------------------------------------------------------------------
 export function registerOrderTools(server) {
-    // 1. Place a buy order
-    server.tool("context_place_order", "Place a buy order on a prediction market. Requires CONTEXT_PRIVATE_KEY. Prices in cents (1-99), size in contracts (min 0.01).", {
+    // 1. Place an order (buy or sell)
+    server.tool("context_place_order", "Place a buy or sell order on a prediction market. " +
+        "Prices in cents (1-99), size in contracts (min 0.01). " +
+        "Omit price for a market order. " +
+        "Note: Market orders (no price specified) will fill at any price up to 99 cents. " +
+        "For tighter price control, specify a limit price. " +
+        "Requires a wallet — run context_generate_wallet first if not set up.", {
         marketId: z.string().describe("The unique identifier of the market"),
-        side: z.enum(["yes", "no"]).describe("Which outcome to buy: yes or no"),
-        size: z.number().describe("Number of contracts to buy (min 0.01)"),
+        outcome: outcomeSchema,
+        side: sideSchema,
+        size: sizeSchema,
         price: z
             .number()
+            .min(1)
+            .max(99)
             .describe("Limit price in cents (1-99). Omit for a market order.")
             .optional(),
+        expirySeconds: expirySchema,
+        inventoryMode: inventoryModeSchema,
+        takerOnly: takerOnlySchema,
     }, async (params) => {
         try {
             const client = getTradingClient();
             let result;
             if (params.price !== undefined) {
-                result = await client.orders.create({
+                result = await client.orders.create(buildOrderRequest({
                     marketId: params.marketId,
-                    outcome: params.side,
-                    side: "buy",
+                    outcome: params.outcome,
+                    side: params.side,
                     priceCents: params.price,
                     size: params.size,
-                });
+                    expirySeconds: params.expirySeconds,
+                    inventoryMode: params.inventoryMode,
+                    takerOnly: params.takerOnly,
+                }));
             }
             else {
-                result = await client.orders.createMarket({
+                const marketReq = {
                     marketId: params.marketId,
-                    outcome: params.side,
-                    side: "buy",
+                    outcome: params.outcome,
+                    side: params.side,
                     maxPriceCents: 99,
                     maxSize: params.size,
-                });
+                };
+                if (params.expirySeconds !== undefined)
+                    marketReq.expirySeconds = params.expirySeconds;
+                result = await client.orders.createMarket(marketReq);
             }
             return toolResult(result);
         }
@@ -40,20 +98,52 @@ export function registerOrderTools(server) {
         }
     });
     // 2. Cancel an open order
-    server.tool("context_cancel_order", "Cancel an open order by its nonce. Requires CONTEXT_PRIVATE_KEY.", {
+    server.tool("context_cancel_order", "Cancel an open order by its nonce. Requires a wallet — run context_generate_wallet first if not set up.", {
         nonce: z.string().describe("The nonce of the order to cancel"),
     }, async (params) => {
         try {
             const client = getTradingClient();
-            const result = await client.orders.cancel(params.nonce);
+            const result = await client.orders.cancel(validateHexNonce(params.nonce));
+            return toolResult(result);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    // 3. Cancel and replace an order atomically
+    server.tool("context_cancel_replace_order", "Atomically cancel an existing order and place a new one. " +
+        "If either operation fails, both fail — you're never left without a position. " +
+        "Requires a wallet — run context_generate_wallet first if not set up.", {
+        cancelNonce: z.string().describe("Hex nonce of the order to cancel"),
+        marketId: z.string().describe("The unique identifier of the market for the new order"),
+        outcome: outcomeSchema,
+        side: sideSchema,
+        priceCents: priceSchema,
+        size: sizeSchema,
+        expirySeconds: expirySchema,
+        inventoryMode: inventoryModeSchema,
+        takerOnly: takerOnlySchema,
+    }, async (params) => {
+        try {
+            const client = getTradingClient();
+            const result = await client.orders.cancelReplace(validateHexNonce(params.cancelNonce), buildOrderRequest({
+                marketId: params.marketId,
+                outcome: params.outcome,
+                side: params.side,
+                priceCents: params.priceCents,
+                size: params.size,
+                expirySeconds: params.expirySeconds,
+                inventoryMode: params.inventoryMode,
+                takerOnly: params.takerOnly,
+            }));
             return toolResult(result);
         }
         catch (error) {
             return toolError(error);
         }
     });
-    // 3. List open orders
-    server.tool("context_my_orders", "List your open orders, optionally filtered to a specific market. Requires CONTEXT_PRIVATE_KEY.", {
+    // 4. List open orders
+    server.tool("context_my_orders", "List your open orders, optionally filtered to a specific market. Requires a wallet — run context_generate_wallet first if not set up.", {
         marketId: z
             .string()
             .describe("Filter orders to a specific market")
@@ -68,4 +158,88 @@ export function registerOrderTools(server) {
             return toolError(error);
         }
     });
+    // 5. Bulk create orders
+    server.tool("context_bulk_create_orders", "Create multiple orders in a single atomic batch. " +
+        "All orders are submitted together — more efficient than placing them one by one. " +
+        "Requires a wallet — run context_generate_wallet first if not set up.", {
+        orders: z.array(z.object({
+            marketId: z.string().describe("The unique identifier of the market"),
+            outcome: outcomeSchema,
+            side: sideSchema,
+            priceCents: priceSchema,
+            size: sizeSchema,
+            expirySeconds: expirySchema,
+            inventoryMode: inventoryModeSchema,
+            takerOnly: takerOnlySchema,
+        })).describe("Array of orders to create"),
+    }, async (params) => {
+        try {
+            const client = getTradingClient();
+            const requests = params.orders.map((o) => buildOrderRequest({
+                marketId: o.marketId,
+                outcome: o.outcome,
+                side: o.side,
+                priceCents: o.priceCents,
+                size: o.size,
+                expirySeconds: o.expirySeconds,
+                inventoryMode: o.inventoryMode,
+                takerOnly: o.takerOnly,
+            }));
+            const result = await client.orders.bulkCreate(requests);
+            return toolResult(result);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    // 6. Bulk cancel orders
+    server.tool("context_bulk_cancel_orders", "Cancel multiple open orders in a single batch. " +
+        "Requires a wallet — run context_generate_wallet first if not set up.", {
+        nonces: z.array(z.string()).describe("Array of hex nonces of orders to cancel"),
+    }, async (params) => {
+        try {
+            const client = getTradingClient();
+            const result = await client.orders.bulkCancel(params.nonces.map(validateHexNonce));
+            return toolResult(result);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
+    // 7. Bulk mixed operations (create + cancel atomically)
+    server.tool("context_bulk_orders", "Atomically create and cancel orders in a single batch. " +
+        "Use this for quote updates — cancel stale orders and place new ones in one call. " +
+        "Requires a wallet — run context_generate_wallet first if not set up.", {
+        creates: z.array(z.object({
+            marketId: z.string().describe("The unique identifier of the market"),
+            outcome: outcomeSchema,
+            side: sideSchema,
+            priceCents: priceSchema,
+            size: sizeSchema,
+            expirySeconds: expirySchema,
+            inventoryMode: inventoryModeSchema,
+            takerOnly: takerOnlySchema,
+        })).describe("Orders to create").optional(),
+        cancelNonces: z.array(z.string()).describe("Hex nonces of orders to cancel").optional(),
+    }, async (params) => {
+        try {
+            const client = getTradingClient();
+            const creates = (params.creates ?? []).map((o) => buildOrderRequest({
+                marketId: o.marketId,
+                outcome: o.outcome,
+                side: o.side,
+                priceCents: o.priceCents,
+                size: o.size,
+                expirySeconds: o.expirySeconds,
+                inventoryMode: o.inventoryMode,
+                takerOnly: o.takerOnly,
+            }));
+            const cancelNonces = (params.cancelNonces ?? []).map(validateHexNonce);
+            const result = await client.orders.bulk(creates, cancelNonces);
+            return toolResult(result);
+        }
+        catch (error) {
+            return toolError(error);
+        }
+    });
 }

package/dist/tools/portfolio.js

@@ -3,7 +3,7 @@ import { getTradingClient } from "../lib/client.js";
 import { toolResult, toolError } from "../lib/utils.js";
 export function registerPortfolioTools(server) {
     // 1. Get portfolio positions
-    server.tool("context_get_portfolio", "Get your prediction market positions with P&L. Filter by kind: all, active, won, lost, or claimable. Requires CONTEXT_PRIVATE_KEY.", {
+    server.tool("context_get_portfolio", "Get your prediction market positions with P&L. Filter by kind: all, active, won, lost, or claimable. Requires a wallet — run context_generate_wallet first if not set up.", {
         kind: z
             .enum(["all", "active", "won", "lost", "claimable"])
             .describe("Filter positions by kind")
@@ -21,7 +21,7 @@ export function registerPortfolioTools(server) {
         }
     });
     // 2. Get balance
-    server.tool("context_get_balance", "Get your USDC balance (wallet + settlement) and outcome token holdings. Requires CONTEXT_PRIVATE_KEY.", {}, async () => {
+    server.tool("context_get_balance", "Get your USDC balance (wallet + settlement) and outcome token holdings. Requires a wallet — run context_generate_wallet first if not set up.", {}, async () => {
         try {
             const client = getTradingClient();
             const result = await client.portfolio.balance();

package/dist/tools/questions.js

@@ -3,7 +3,7 @@ import { getTradingClient } from "../lib/client.js";
 import { toolResult, toolError } from "../lib/utils.js";
 export function registerQuestionTools(server) {
     // 1. Create a new prediction market from a question
-    server.tool("context_create_market", "Create a new prediction market from a natural language question. The AI oracle processes the question and generates a market. This may take 30-90 seconds. Requires CONTEXT_PRIVATE_KEY.", {
+    server.tool("context_create_market", "Create a new prediction market from a natural language question. The AI oracle processes the question and generates a market. This may take 30-90 seconds. Requires a wallet — run context_generate_wallet first if not set up.", {
         question: z
             .string()
             .describe("A natural language question to create a prediction market for"),

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "context-markets-mcp",
-  "version": "0.1.2",
+  "version": "0.2.1",
   "description": "MCP server for Context Markets — browse, trade, and create prediction markets from any AI agent",
   "type": "module",
   "main": "dist/index.js",
@@ -13,9 +13,9 @@
     "dev": "tsc && node dist/index.js"
   },
   "dependencies": {
-    "context-markets": "^0.5.1",
+    "context-markets": "^0.6.0",
     "@modelcontextprotocol/sdk": "^1.0.0",
-    "dotenv": "^16.3.1",
+    "viem": "^2.47.5",
     "zod": "^3.22.0"
   },
   "devDependencies": {