@unhedged/mcp 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Alpha DNA
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,81 @@
+# @unhedged/mcp
+
+Model Context Protocol server for the [Unhedged](https://unhedged.gg) prediction-markets platform. Lets AI agents — Claude Desktop, Cursor, Claude CLI, Codex CLI, or other clients that support local stdio servers — interact with Unhedged on behalf of an end user via a scoped API key.
+
+## What it does
+
+- Exposes 12 MCP **tools** over the Unhedged v1 REST API: search markets, read balances and portfolio, place bets and orders, cancel orders, request withdrawals, and read a market-maker profile.
+- Ships 6 MCP **prompts** ("skills") — opinionated markdown workflows the agent can execute end-to-end (e.g. `place-hedged-position`, `cash-out`, `portfolio-review`).
+- Auto-generates an `Idempotency-Key` for every state-changing call. Each new call uses a fresh key, so ambiguous failures are not retried automatically. Check the account's transaction history before repeating a mutation; open orders and balances cannot rule out a filled order or completed withdrawal. Ask the user if the outcome remains uncertain.
+- Declares MCP tool annotations (`readOnlyHint`, `destructiveHint`); bets, orders, cancellations, and withdrawals are marked destructive. Confirmation behavior depends on the client.
+- Optional control: `UNHEDGED_MAX_SPEND_PER_SESSION` for a cumulative bet-stake and buy-order notional cap. Fees and withdrawals are excluded from this cap.
+
+## Quickstart
+
+```bash
+npx @unhedged/mcp init
+```
+
+The init wizard asks which client to wire up (Claude Desktop, Cursor, Claude CLI, or Codex CLI), prompts for your Unhedged API key, and writes a config file or prints a client command. The CLI commands include the key; run them off camera and avoid sharing terminal history.
+
+Mint an API key at <https://unhedged.gg/account/api-keys>. See the [API key minting walkthrough](#api-key-minting) below for recommended scope sets.
+
+## Environment variables
+
+| Variable | Required | Description |
+|---|---|---|
+| `UNHEDGED_API_KEY` | yes | Bearer token, format `ak_...`. Scopes minted into the key determine which tools work. |
+| `UNHEDGED_MAX_SPEND_PER_SESSION` | no | Cap (in USD) on cumulative bet stakes and buy-order notional per server lifetime. Excludes fees and withdrawals. |
+
+## API key minting
+
+Recommended scope sets per use case:
+
+| Use case | Scopes |
+|---|---|
+| Read-only research | `market:read`, `portfolio:read`, `bet:read`, `order:read`, `balance:read` |
+| Full trading | above + `bet:place`, `order:place`, `order:cancel` |
+| Full trading + withdrawals | above + `balance:withdraw` |
+| Market maker (CLOB quoting) | `order:place`, `order:cancel`, `order:read`, `market:read`, `balance:read`, `portfolio:read` |
+
+> ⚠️ **Withdrawals are off by default.** Don't include `balance:withdraw` unless you want the agent to be able to move funds off the platform.
+
+### Market makers
+
+Accounts with the `MARKET_MAKER` role get a more favorable fee tier and **elevated order rate limits** (the `market_maker` rate-limit profile: up to 1,000,000 orders/min total and per market, versus the defaults of 120/min total and 60/min per market), so high-frequency quoting via the MCP isn't throttled. The role is granted by an Unhedged admin — there is no self-service application yet. Once granted, call `get_market_maker_profile` to read the live tier, effective maker/taker fees, limits, and rebate terms, then run the `market-maker-workflow` skill. A market-maker key needs `order:place`, `order:cancel`, `order:read`, `market:read`, `balance:read`, and `portfolio:read`.
+
+## Tools
+
+Market searches default to ACTIVE and ENDED. Pass an explicit status to browse resolved or voided markets.
+
+Tool descriptions are available in your MCP client. Quick reference:
+
+| Tool | Scope | Idempotency key attached |
+|---|---|---|
+| `search_markets` | (public) | n/a |
+| `get_market` | (public) | n/a |
+| `get_market_stats` | (public) | n/a |
+| `get_balance` | `balance:read` | n/a |
+| `get_portfolio` | `portfolio:read` | n/a |
+| `list_bets` | `bet:read` | n/a |
+| `place_bet` | `bet:place` | yes |
+| `list_orders` | `order:read` | n/a |
+| `place_order` | `order:place` | yes |
+| `cancel_order` | `order:cancel` | yes |
+| `request_withdrawal` | `balance:withdraw` | yes |
+| `get_market_maker_profile` | `portfolio:read` | n/a |
+
+## Skills
+
+Markdown workflows under `skills/`, surfaced to MCP clients as slash-commands / prompts:
+
+- `market-research` — find markets matching a topic, summarize odds and resolution rules.
+- `place-hedged-position` — calculate and place a hedged position across outcomes.
+- `portfolio-review` — read-only summary of holdings, P&L, and risk.
+- `market-maker-workflow` — quote both sides of an order book. Requires the `MARKET_MAKER` role; call `get_market_maker_profile` first to read the live fee tier and limits.
+- `cash-out` — close open orders, accept market prices, prepare for withdrawal.
+- `market-creator-assistant` — draft a market specification and guide submission through the web UI. Requires the `MARKET_CREATOR` role.
+
+## License
+
+MIT.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,48 @@
+#!/usr/bin/env node
+import { startStdioServer } from './server.js';
+const HELP = `
+@unhedged/mcp — Model Context Protocol server for the Unhedged platform.
+
+Usage:
+  npx @unhedged/mcp           Start the MCP server over stdio (what MCP clients invoke).
+  npx @unhedged/mcp init      Interactive setup for Claude Desktop, Cursor,
+                              Claude CLI, or Codex CLI.
+  npx @unhedged/mcp --help    Show this help.
+
+Environment:
+  UNHEDGED_API_KEY                 (required) Bearer token in format "ak_...".
+  UNHEDGED_MAX_SPEND_PER_SESSION   (optional) Cap on bet stakes and buy-order notional per session.
+                                              Excludes fees and withdrawals; resets on restart.
+
+Docs: https://unhedged.gg/mcp
+`.trim();
+async function main() {
+    const subcommand = process.argv[2];
+    if (subcommand === '--help' || subcommand === '-h') {
+        process.stdout.write(HELP + '\n');
+        return;
+    }
+    if (subcommand === 'init') {
+        const { runInit } = await import('./init/index.js');
+        await runInit();
+        return;
+    }
+    if (subcommand) {
+        const kind = subcommand.startsWith('-') ? 'flag' : 'subcommand';
+        process.stderr.write(`Unknown ${kind}: "${subcommand}".\n\n${HELP}\n`);
+        process.exit(2);
+    }
+    // No subcommand → run as MCP server over stdio.
+    try {
+        await startStdioServer();
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        process.stderr.write(`[unhedged-mcp] startup failed: ${msg}\n`);
+        process.exit(1);
+    }
+}
+main().catch((err) => {
+    process.stderr.write(`[unhedged-mcp] fatal: ${err instanceof Error ? err.message : String(err)}\n`);
+    process.exit(1);
+});

package/dist/client/errors.d.ts

@@ -0,0 +1,15 @@
+export declare class UnhedgedApiError extends Error {
+    readonly status: number;
+    readonly code: string | undefined;
+    readonly missingScope: string | undefined;
+    readonly retryable: boolean;
+    readonly responseBody: unknown;
+    constructor(args: {
+        status: number;
+        message: string;
+        code?: string;
+        missingScope?: string;
+        responseBody?: unknown;
+    });
+    toAgentMessage(stateChanging?: boolean): string;
+}

package/dist/client/errors.js

@@ -0,0 +1,40 @@
+export class UnhedgedApiError extends Error {
+    status;
+    code;
+    missingScope;
+    retryable;
+    responseBody;
+    constructor(args) {
+        super(args.message);
+        this.name = 'UnhedgedApiError';
+        this.status = args.status;
+        this.code = args.code;
+        this.missingScope = args.missingScope;
+        this.responseBody = args.responseBody;
+        // Status 0 = network error / timeout: the response never arrived, so the
+        // outcome is ambiguous. `retryable` describes the transport condition; it
+        // does not mean a financial mutation should be retried without checking
+        // whether the first request landed.
+        this.retryable = args.status >= 500 || args.status === 429 || args.status === 0;
+    }
+    toAgentMessage(stateChanging = false) {
+        if (this.missingScope) {
+            return (`Unhedged API rejected the call (${this.status}): the API key is missing scope ` +
+                `"${this.missingScope}". Mint a new key including this scope at ` +
+                `https://unhedged.gg/account/api-keys.`);
+        }
+        if (this.status === 401) {
+            return `Unhedged API rejected the API key (401). Verify UNHEDGED_API_KEY is set and the key is still active.`;
+        }
+        if (this.retryable) {
+            if (!stateChanging) {
+                return `Unhedged API returned ${this.status} (${this.message}). This may be transient; retry the read request.`;
+            }
+            return (`Unhedged API returned ${this.status} (${this.message}). This may be transient. ` +
+                `Do not repeat a state-changing call until its outcome is confirmed. ` +
+                `Open orders and balances alone cannot rule out a filled order or completed withdrawal. ` +
+                `Check the account's transaction history on Unhedged; if the result is still uncertain, stop and ask the user.`);
+        }
+        return `Unhedged API returned ${this.status}: ${this.message}`;
+    }
+}

package/dist/client/http.d.ts

@@ -0,0 +1,21 @@
+import type { UnhedgedMcpConfig } from '../config.js';
+export interface RequestOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+    path: string;
+    /**
+     * Query parameters. Values that are `undefined`/`null` are skipped. Arrays
+     * are emitted as repeated keys. Anything else is coerced via String().
+     */
+    query?: Record<string, unknown>;
+    body?: unknown;
+    /** Override or disable auto-generated Idempotency-Key. */
+    idempotencyKey?: string | false;
+}
+export declare class UnhedgedHttpClient {
+    private readonly apiKey;
+    private readonly baseUrl;
+    constructor(config: UnhedgedMcpConfig);
+    request<T>(options: RequestOptions): Promise<T>;
+    private attempt;
+    private buildUrl;
+}

package/dist/client/http.js

@@ -0,0 +1,132 @@
+import { randomUUID } from 'node:crypto';
+import { UnhedgedApiError } from './errors.js';
+const STATE_CHANGING_METHODS = new Set(['POST', 'PUT', 'PATCH', 'DELETE']);
+const REQUEST_TIMEOUT_MS = 30_000;
+export class UnhedgedHttpClient {
+    apiKey;
+    baseUrl;
+    constructor(config) {
+        this.apiKey = config.apiKey;
+        this.baseUrl = config.baseUrl;
+    }
+    async request(options) {
+        const method = options.method ?? 'GET';
+        const url = this.buildUrl(options.path, options.query);
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            Accept: 'application/json',
+        };
+        let body;
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+            body = JSON.stringify(options.body);
+        }
+        const idempotencyKey = STATE_CHANGING_METHODS.has(method) && options.idempotencyKey !== false
+            ? options.idempotencyKey ?? randomUUID()
+            : undefined;
+        if (idempotencyKey !== undefined) {
+            headers['Idempotency-Key'] = idempotencyKey;
+        }
+        // Do not automatically retry mutations. An Idempotency-Key lets the
+        // backend replay a completed request, but it does not prove that an
+        // in-flight request has stopped after the client times out. Retrying here
+        // could race the original operation and duplicate a financial mutation.
+        // Surface the ambiguous result so the agent can verify state first.
+        return this.attempt(method, url, headers, body);
+    }
+    async attempt(method, url, headers, body) {
+        let response;
+        try {
+            response = await fetch(url, {
+                method,
+                headers,
+                body,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+        }
+        catch (err) {
+            const timedOut = err instanceof Error && err.name === 'TimeoutError';
+            const msg = timedOut
+                ? `request timed out after ${REQUEST_TIMEOUT_MS / 1000}s`
+                : err instanceof Error
+                    ? err.message
+                    : String(err);
+            throw new UnhedgedApiError({
+                status: 0,
+                message: `Network error calling Unhedged API: ${msg}`,
+            });
+        }
+        if (!response.ok) {
+            await throwApiError(response);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        const text = await response.text();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new UnhedgedApiError({
+                status: response.status,
+                message: `Unhedged API returned non-JSON body (status ${response.status}).`,
+                responseBody: text,
+            });
+        }
+    }
+    buildUrl(path, query) {
+        // Concatenate rather than `new URL(path, base)` so a base URL with a path
+        // component (e.g. a reverse proxy at https://host/unhedged) is preserved.
+        const url = new URL(`${this.baseUrl}${path.startsWith('/') ? path : `/${path}`}`);
+        if (query) {
+            for (const [key, value] of Object.entries(query)) {
+                if (value === undefined || value === null)
+                    continue;
+                if (Array.isArray(value)) {
+                    for (const v of value) {
+                        if (v !== undefined && v !== null)
+                            url.searchParams.append(key, String(v));
+                    }
+                }
+                else {
+                    url.searchParams.append(key, String(value));
+                }
+            }
+        }
+        return url.toString();
+    }
+}
+async function throwApiError(response) {
+    let parsed;
+    let rawText = '';
+    try {
+        rawText = await response.text();
+        if (rawText)
+            parsed = JSON.parse(rawText);
+    }
+    catch {
+        // body wasn't JSON
+    }
+    const body = (parsed ?? {});
+    const message = typeof body.message === 'string'
+        ? body.message
+        : typeof body.error === 'string'
+            ? body.error
+            : rawText || `HTTP ${response.status}`;
+    const code = typeof body.code === 'string' ? body.code : undefined;
+    let missingScope;
+    if (response.status === 403 && typeof body.message === 'string') {
+        const m = body.message.match(/missing required scope:\s*([^\s,]+)/i);
+        if (m)
+            missingScope = m[1];
+    }
+    throw new UnhedgedApiError({
+        status: response.status,
+        message,
+        code,
+        missingScope,
+        responseBody: parsed ?? rawText,
+    });
+}

package/dist/client/types.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Response shapes mirrored from the Unhedged backend route handlers. Kept loose
+ * (most fields typed but extras allowed) so additive backend changes don't break
+ * the MCP build. If a backend response changes shape, update here.
+ */
+export type MarketStatus = 'ACTIVE' | 'ENDED' | 'RESOLVED' | 'VOIDED';
+export type BetStatus = 'PENDING' | 'CONFIRMED' | 'FAILED' | 'REFUNDED' | 'WON' | 'LOST';
+export interface MarketSummary {
+    id: string;
+    question: string;
+    status: MarketStatus;
+    category?: string;
+    tags?: string[];
+    outcomes?: Array<{
+        index?: number;
+        label: string;
+    }>;
+    totalPool?: string | number;
+    endTime?: string;
+    scheduledResolutionTime?: string | null;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export interface MarketDetail extends MarketSummary {
+    outcomeStats?: unknown;
+    autoResolutionConfig?: unknown;
+    liveEventData?: unknown;
+    ogImageUrl?: string;
+}
+export interface ListMarketsResponse {
+    markets: MarketSummary[];
+    total?: number;
+}
+export interface GetMarketResponse {
+    market: MarketDetail;
+}
+export interface MarketStats {
+    [key: string]: unknown;
+}
+export interface GetMarketStatsResponse {
+    stats: MarketStats;
+}
+export interface BalanceResponse {
+    balance: {
+        available: string;
+        lockedWithdraws: string;
+        lockedBets: string;
+        lockedEngine: string;
+        total: string;
+        totalDeposited?: string;
+        totalWithdrawn?: string;
+    };
+    withdrawalFee: string;
+    withdrawalMinAmount: string;
+    bettingFee?: string;
+    ccPriceUsd: number | null;
+}
+export interface PortfolioResponse {
+    portfolio: {
+        summary: {
+            totalBets: number;
+            totalWagered: string;
+            totalWins: number;
+            totalLosses: number;
+            pendingBets: number;
+            pendingOrderBookPositions?: number;
+            pendingOrderBookCostBasis?: string;
+            totalPayouts: string;
+            totalProfit: string;
+            winRate: number;
+            roi: number;
+        };
+        positions: unknown[];
+        /** The complete active/ended row count represented by the paged positions endpoint. */
+        positionsTotal: number;
+        recentPayouts: unknown[];
+    };
+}
+export interface Bet {
+    id: string;
+    marketId: string;
+    outcomeIndex: number;
+    amount: string;
+    status: BetStatus;
+    timeWeight?: string;
+    createdAt?: string;
+    [key: string]: unknown;
+}
+export interface ListBetsResponse {
+    bets: Bet[];
+    total: number;
+}
+export interface PlaceBetResponse {
+    bet: Bet;
+    balanceAfter: string;
+    fee: string;
+}
+export interface MEOrder {
+    id?: string | number;
+    marketId: string;
+    outcome: string;
+    side: 'bid' | 'ask';
+    type: 'Limit' | 'Market' | 'StopLoss' | 'TakeProfit';
+    price?: string;
+    triggerPrice?: string;
+    quantity?: number;
+    quoteQuantity?: string;
+    status?: string;
+    [key: string]: unknown;
+}
+export interface ListOrdersResponse {
+    orders: MEOrder[];
+    nextCursor?: string | null;
+    total?: number;
+    markets?: unknown[];
+}
+export interface PlaceOrderResponse {
+    order: MEOrder;
+}
+export interface CancelOrderResponse {
+    result: unknown;
+}
+export interface EthereumWithdrawQuoteResponse {
+    quote: {
+        quoteId: string;
+    };
+}
+export interface WithdrawalResponse {
+    withdrawal: {
+        id: string;
+        amount: string;
+        fee: string;
+        totalDeducted: string;
+        status: string;
+        createdAt: string;
+        network?: 'CANTON' | 'SOLANA' | 'TRON' | 'ETHEREUM';
+        destinationAddress?: string;
+    };
+    message: string;
+}

package/dist/client/types.js

@@ -0,0 +1,6 @@
+/**
+ * Response shapes mirrored from the Unhedged backend route handlers. Kept loose
+ * (most fields typed but extras allowed) so additive backend changes don't break
+ * the MCP build. If a backend response changes shape, update here.
+ */
+export {};

package/dist/config.d.ts

@@ -0,0 +1,7 @@
+export interface UnhedgedMcpConfig {
+    apiKey: string;
+    baseUrl: string;
+    maxSpendPerSession: number | null;
+}
+export declare const DEFAULT_BASE_URL = "https://api.unhedged.gg";
+export declare function loadConfig(env?: NodeJS.ProcessEnv): UnhedgedMcpConfig;

package/dist/config.js

@@ -0,0 +1,27 @@
+export const DEFAULT_BASE_URL = 'https://api.unhedged.gg';
+export function loadConfig(env = process.env) {
+    const apiKey = env.UNHEDGED_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error('UNHEDGED_API_KEY environment variable is required. ' +
+            'Mint a key at https://unhedged.gg/account/api-keys and pass it via the MCP client config.');
+    }
+    if (!apiKey.startsWith('ak_')) {
+        throw new Error(`UNHEDGED_API_KEY has unexpected format. Expected "ak_..." but got "${apiKey.slice(0, 6)}...".`);
+    }
+    const userBaseUrl = env.UNHEDGED_BASE_URL?.trim();
+    const baseUrl = (userBaseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+    if (['true', '1', 'yes', 'on'].includes(env.UNHEDGED_DRY_RUN?.trim().toLowerCase() ?? '')) {
+        throw new Error('Preview mode is no longer supported. Remove UNHEDGED_DRY_RUN only when you intend to submit real actions.');
+    }
+    const maxSpendPerSession = parseSpendCap(env.UNHEDGED_MAX_SPEND_PER_SESSION);
+    return { apiKey, baseUrl, maxSpendPerSession };
+}
+function parseSpendCap(value) {
+    if (!value || !value.trim())
+        return null;
+    const n = Number(value);
+    if (!Number.isFinite(n) || n <= 0) {
+        throw new Error(`UNHEDGED_MAX_SPEND_PER_SESSION must be a positive number; got "${value}".`);
+    }
+    return n;
+}

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+export { createServer, startStdioServer } from './server.js';
+export { UnhedgedHttpClient } from './client/http.js';
+export { UnhedgedApiError } from './client/errors.js';
+export { loadConfig } from './config.js';
+export type { UnhedgedMcpConfig } from './config.js';
+export type { AnyToolDefinition, ToolDefinition, ToolContext } from './tools/types.js';

package/dist/index.js

@@ -0,0 +1,4 @@
+export { createServer, startStdioServer } from './server.js';
+export { UnhedgedHttpClient } from './client/http.js';
+export { UnhedgedApiError } from './client/errors.js';
+export { loadConfig } from './config.js';

package/dist/init/index.d.ts

@@ -0,0 +1,10 @@
+export type InitTarget = 'claude-desktop' | 'cursor' | 'claude-cli' | 'codex-cli' | 'print';
+export declare function runInit(): Promise<void>;
+/**
+ * Read an existing JSON config (if present), deep-merge at the requested path,
+ * and write it back. Preserves any other top-level keys the user has set.
+ * `parentKeys` must descend to the object that owns the server entries —
+ * merging a block that itself contains `mcpServers` at the top level would
+ * clobber every other server the user has configured.
+ */
+export declare function mergeJsonConfig(path: string, parentKeys: string[], block: object): void;