@unhedged/mcp 0.1.2

package/dist/init/index.js

@@ -0,0 +1,137 @@
+import { createInterface } from 'node:readline/promises';
+import { stdin, stdout } from 'node:process';
+import { homedir, platform } from 'node:os';
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs';
+import { dirname } from 'node:path';
+import { claudeCliCommand, codexCliCommand, claudeDesktopConfigPath, claudeDesktopSnippet, cursorConfigPath, cursorSnippet, } from './snippet.js';
+export async function runInit() {
+    const rl = createInterface({ input: stdin, output: stdout });
+    try {
+        stdout.write('\n@unhedged/mcp — setup wizard\n');
+        stdout.write('────────────────────────────\n\n');
+        const target = await pickTarget(rl);
+        const apiKey = await ask(rl, 'Unhedged API key (ak_...): ');
+        if (!apiKey.startsWith('ak_')) {
+            stdout.write('\nKey doesn\'t start with "ak_". The MCP server will refuse to start. Continuing anyway in case the key format changes later.\n\n');
+        }
+        stdout.write('The session cap covers bet stakes and buy-order notional. It excludes fees and withdrawals and resets on restart.\n');
+        const capStr = await ask(rl, 'Session cap in USD (blank = no cap): ');
+        const cap = capStr.trim() ? Number(capStr.trim()) : null;
+        if (capStr.trim() && (cap === null || !Number.isFinite(cap) || cap <= 0)) {
+            stdout.write(`Ignoring invalid spend cap "${capStr}".\n`);
+        }
+        const answers = {
+            target,
+            apiKey: apiKey.trim(),
+            maxSpendPerSession: cap === null || !Number.isFinite(cap) || cap <= 0 ? null : cap,
+        };
+        await apply(answers);
+    }
+    finally {
+        rl.close();
+    }
+}
+async function pickTarget(rl) {
+    stdout.write('Which MCP client to configure?\n');
+    stdout.write('  1) Claude Desktop\n');
+    stdout.write('  2) Cursor\n');
+    stdout.write('  3) Claude CLI (runs `claude mcp add ...`)\n');
+    stdout.write('  4) Codex CLI (runs `codex mcp add ...`)\n');
+    stdout.write('  5) Print the snippet only (no files touched)\n\n');
+    const raw = (await ask(rl, 'Choose 1-5: ')).trim();
+    switch (raw) {
+        case '1':
+            return 'claude-desktop';
+        case '2':
+            return 'cursor';
+        case '3':
+            return 'claude-cli';
+        case '4':
+            return 'codex-cli';
+        case '5':
+        case '':
+            return 'print';
+        default:
+            stdout.write(`Unrecognized choice "${raw}", defaulting to print-only.\n`);
+            return 'print';
+    }
+}
+async function ask(rl, prompt) {
+    const answer = await rl.question(prompt);
+    return answer;
+}
+async function apply(answers) {
+    if (answers.target === 'print') {
+        printAllSnippets(answers);
+        return;
+    }
+    if (answers.target === 'claude-desktop') {
+        const path = claudeDesktopConfigPath(platform(), homedir());
+        mergeJsonConfig(path, ['mcpServers'], claudeDesktopSnippet(answers));
+        stdout.write(`\nWrote Claude Desktop config at ${path}.\nRestart Claude Desktop for changes to take effect.\n`);
+        return;
+    }
+    if (answers.target === 'cursor') {
+        const path = cursorConfigPath(homedir());
+        mergeJsonConfig(path, ['mcpServers'], cursorSnippet(answers).mcpServers);
+        stdout.write(`\nWrote Cursor MCP config at ${path}.\nRestart Cursor for changes to take effect.\n`);
+        return;
+    }
+    if (answers.target === 'claude-cli') {
+        const cmd = claudeCliCommand(answers);
+        stdout.write('\nRun the following command to register with the Claude CLI:\n\n');
+        stdout.write(`  ${cmd}\n\n`);
+        stdout.write('(Not executed automatically — paste it into your shell to confirm.)\n');
+        return;
+    }
+    if (answers.target === 'codex-cli') {
+        const cmd = codexCliCommand(answers);
+        stdout.write('\nRun the following command to register with Codex CLI:\n\n');
+        stdout.write(`  ${cmd}\n\n`);
+        stdout.write('(Not executed automatically — paste it into your shell to confirm.)\n');
+        return;
+    }
+}
+function printAllSnippets(answers) {
+    stdout.write('\n— Claude Desktop (paste under "mcpServers" in claude_desktop_config.json) —\n');
+    stdout.write(JSON.stringify(claudeDesktopSnippet(answers), null, 2) + '\n');
+    stdout.write('\n— Cursor (paste into ~/.cursor/mcp.json) —\n');
+    stdout.write(JSON.stringify(cursorSnippet(answers), null, 2) + '\n');
+    stdout.write('\n— Claude CLI command —\n');
+    stdout.write(claudeCliCommand(answers) + '\n');
+    stdout.write('\n— Codex CLI command —\n');
+    stdout.write(codexCliCommand(answers) + '\n');
+}
+/**
+ * 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 function mergeJsonConfig(path, parentKeys, block) {
+    let existing = {};
+    if (existsSync(path)) {
+        try {
+            existing = JSON.parse(readFileSync(path, 'utf8'));
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            throw new Error(`Existing config at ${path} is not valid JSON (${msg}). Refusing to overwrite — fix or move it before re-running init.`);
+        }
+    }
+    let cursor = existing;
+    for (const key of parentKeys) {
+        const next = cursor[key];
+        if (next && typeof next === 'object' && !Array.isArray(next)) {
+            cursor = next;
+        }
+        else {
+            cursor[key] = {};
+            cursor = cursor[key];
+        }
+    }
+    Object.assign(cursor, block);
+    mkdirSync(dirname(path), { recursive: true });
+    writeFileSync(path, JSON.stringify(existing, null, 2) + '\n', 'utf8');
+}

package/dist/init/snippet.d.ts

@@ -0,0 +1,35 @@
+/**
+ * Pure functions that produce the config snippet for each supported MCP client.
+ * Side-effect-free; the actual file writes / shell-outs live in cli.ts.
+ */
+export interface SnippetOptions {
+    apiKey: string;
+    baseUrl?: string;
+    maxSpendPerSession?: number | null;
+}
+/** Config block for Claude Desktop's `mcpServers` object. */
+export declare function claudeDesktopSnippet(opts: SnippetOptions): {
+    unhedged: {
+        command: string;
+        args: string[];
+        env: Record<string, string>;
+    };
+};
+/** Config block for Cursor's `~/.cursor/mcp.json`. Schema mirrors Claude Desktop. */
+export declare function cursorSnippet(opts: SnippetOptions): {
+    mcpServers: {
+        unhedged: {
+            command: string;
+            args: string[];
+            env: Record<string, string>;
+        };
+    };
+};
+/** Shell command for `claude mcp add ...`. */
+export declare function claudeCliCommand(opts: SnippetOptions): string;
+/** Shell command for `codex mcp add ...`. */
+export declare function codexCliCommand(opts: SnippetOptions): string;
+/** Path to Claude Desktop's config file on the current platform. */
+export declare function claudeDesktopConfigPath(platform: NodeJS.Platform, homedir: string, env?: NodeJS.ProcessEnv): string;
+/** Path to Cursor's MCP config file. */
+export declare function cursorConfigPath(homedir: string): string;

package/dist/init/snippet.js

@@ -0,0 +1,72 @@
+/**
+ * Pure functions that produce the config snippet for each supported MCP client.
+ * Side-effect-free; the actual file writes / shell-outs live in cli.ts.
+ */
+/** Config block for Claude Desktop's `mcpServers` object. */
+export function claudeDesktopSnippet(opts) {
+    return {
+        unhedged: {
+            command: 'npx',
+            args: ['-y', '@unhedged/mcp'],
+            env: buildEnv(opts),
+        },
+    };
+}
+/** Config block for Cursor's `~/.cursor/mcp.json`. Schema mirrors Claude Desktop. */
+export function cursorSnippet(opts) {
+    return {
+        mcpServers: {
+            unhedged: {
+                command: 'npx',
+                args: ['-y', '@unhedged/mcp'],
+                env: buildEnv(opts),
+            },
+        },
+    };
+}
+/** Shell command for `claude mcp add ...`. */
+export function claudeCliCommand(opts) {
+    return mcpAddCommand('claude', opts);
+}
+/** Shell command for `codex mcp add ...`. */
+export function codexCliCommand(opts) {
+    return mcpAddCommand('codex', opts);
+}
+function mcpAddCommand(client, opts) {
+    const envFlags = Object.entries(buildEnv(opts))
+        .map(([k, v]) => `--env ${k}=${shellQuote(v)}`)
+        .join(' ');
+    const options = client === 'claude' ? ' --scope user --transport stdio' : '';
+    return `${client} mcp add unhedged${options} ${envFlags} -- npx -y @unhedged/mcp`;
+}
+function buildEnv(opts) {
+    const env = {
+        UNHEDGED_API_KEY: opts.apiKey,
+    };
+    if (opts.baseUrl)
+        env.UNHEDGED_BASE_URL = opts.baseUrl;
+    if (opts.maxSpendPerSession !== null && opts.maxSpendPerSession !== undefined) {
+        env.UNHEDGED_MAX_SPEND_PER_SESSION = String(opts.maxSpendPerSession);
+    }
+    return env;
+}
+function shellQuote(value) {
+    if (/^[A-Za-z0-9_@.+/:=-]+$/.test(value))
+        return value;
+    return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+/** Path to Claude Desktop's config file on the current platform. */
+export function claudeDesktopConfigPath(platform, homedir, env = process.env) {
+    if (platform === 'darwin') {
+        return `${homedir}/Library/Application Support/Claude/claude_desktop_config.json`;
+    }
+    if (platform === 'win32') {
+        const appData = env.APPDATA ?? `${homedir}\\AppData\\Roaming`;
+        return `${appData}\\Claude\\claude_desktop_config.json`;
+    }
+    return `${homedir}/.config/Claude/claude_desktop_config.json`;
+}
+/** Path to Cursor's MCP config file. */
+export function cursorConfigPath(homedir) {
+    return `${homedir}/.cursor/mcp.json`;
+}

package/dist/prompts/frontmatter.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Minimal frontmatter parser for skill markdown files.
+ *
+ * Supports a tiny YAML subset sufficient for our needs:
+ * - `key: value` scalars (strings, kept as strings)
+ * - `arguments:` list-of-objects in the shape
+ *     - name: foo
+ *       description: bar
+ *       required: true
+ *
+ * Anything more exotic should be added as we need it — we deliberately don't
+ * pull in a full YAML dependency for six skill files.
+ */
+export interface SkillArgument {
+    name: string;
+    description: string;
+    required: boolean;
+}
+export interface SkillFrontmatter {
+    name: string;
+    description: string;
+    arguments: SkillArgument[];
+}
+export interface ParsedSkill {
+    frontmatter: SkillFrontmatter;
+    body: string;
+}
+export declare function parseSkill(raw: string, sourcePath?: string): ParsedSkill;

package/dist/prompts/frontmatter.js

@@ -0,0 +1,113 @@
+/**
+ * Minimal frontmatter parser for skill markdown files.
+ *
+ * Supports a tiny YAML subset sufficient for our needs:
+ * - `key: value` scalars (strings, kept as strings)
+ * - `arguments:` list-of-objects in the shape
+ *     - name: foo
+ *       description: bar
+ *       required: true
+ *
+ * Anything more exotic should be added as we need it — we deliberately don't
+ * pull in a full YAML dependency for six skill files.
+ */
+const FRONTMATTER_RE = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/;
+export function parseSkill(raw, sourcePath = '<inline>') {
+    const match = FRONTMATTER_RE.exec(raw);
+    if (!match) {
+        throw new Error(`Skill ${sourcePath}: missing YAML frontmatter (--- ... ---).`);
+    }
+    const fmRaw = match[1];
+    const body = match[2].trim();
+    const fm = parseFrontmatter(fmRaw, sourcePath);
+    return { frontmatter: fm, body };
+}
+function parseFrontmatter(text, sourcePath) {
+    const lines = text.split(/\r?\n/);
+    const scalars = {};
+    const args = [];
+    let i = 0;
+    while (i < lines.length) {
+        const line = lines[i];
+        if (!line.trim() || line.trim().startsWith('#')) {
+            i++;
+            continue;
+        }
+        if (line.startsWith('arguments:')) {
+            i++;
+            while (i < lines.length && (lines[i].startsWith(' ') || lines[i].startsWith('-'))) {
+                if (lines[i].trimStart().startsWith('- ')) {
+                    const arg = {};
+                    // First field is on the "- name: foo" line itself.
+                    const firstField = lines[i].trimStart().slice(2);
+                    applyField(arg, firstField, sourcePath);
+                    i++;
+                    // Continuation fields: any indented line that isn't a new `- ` item.
+                    // Accepting any indent depth (not just 4 spaces) keeps 2-space YAML
+                    // from silently dropping fields.
+                    while (i < lines.length &&
+                        /^\s+\S/.test(lines[i]) &&
+                        !lines[i].trimStart().startsWith('- ')) {
+                        applyField(arg, lines[i].trim(), sourcePath);
+                        i++;
+                    }
+                    if (!arg.name) {
+                        throw new Error(`Skill ${sourcePath}: argument entry missing "name".`);
+                    }
+                    args.push({
+                        name: arg.name,
+                        description: arg.description ?? '',
+                        required: arg.required ?? false,
+                    });
+                }
+                else {
+                    i++;
+                }
+            }
+            continue;
+        }
+        const m = /^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/.exec(line);
+        if (m) {
+            scalars[m[1]] = stripQuotes(m[2]);
+        }
+        i++;
+    }
+    if (!scalars.name)
+        throw new Error(`Skill ${sourcePath}: missing "name" in frontmatter.`);
+    if (!scalars.description)
+        throw new Error(`Skill ${sourcePath}: missing "description" in frontmatter.`);
+    return {
+        name: scalars.name,
+        description: scalars.description,
+        arguments: args,
+    };
+}
+function applyField(target, field, sourcePath) {
+    const m = /^([A-Za-z_][A-Za-z0-9_-]*):\s*(.*)$/.exec(field);
+    if (!m) {
+        throw new Error(`Skill ${sourcePath}: malformed argument field "${field}".`);
+    }
+    const key = m[1];
+    const value = stripQuotes(m[2]);
+    switch (key) {
+        case 'name':
+            target.name = value;
+            break;
+        case 'description':
+            target.description = value;
+            break;
+        case 'required':
+            target.required = value.toLowerCase() === 'true';
+            break;
+        default:
+            // Unknown keys ignored to be forward-compatible.
+            break;
+    }
+}
+function stripQuotes(s) {
+    const t = s.trim();
+    if (t.length >= 2 && ((t.startsWith('"') && t.endsWith('"')) || (t.startsWith("'") && t.endsWith("'")))) {
+        return t.slice(1, -1);
+    }
+    return t;
+}

package/dist/prompts/index.d.ts

@@ -0,0 +1,10 @@
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { defaultSkillsDir, loadSkills, type LoadedSkill } from './loader.js';
+export { defaultSkillsDir, loadSkills };
+export type { LoadedSkill };
+export { parseSkill, type SkillFrontmatter, type SkillArgument, type ParsedSkill } from './frontmatter.js';
+/**
+ * Register every skill in `skills/` as an MCP prompt. Returns the names of
+ * registered prompts so the caller can log or assert against them.
+ */
+export declare function registerSkills(server: McpServer, skillsDir?: string): string[];

package/dist/prompts/index.js

@@ -0,0 +1,50 @@
+import { z } from 'zod';
+import { defaultSkillsDir, loadSkills } from './loader.js';
+export { defaultSkillsDir, loadSkills };
+export { parseSkill } from './frontmatter.js';
+/**
+ * Register every skill in `skills/` as an MCP prompt. Returns the names of
+ * registered prompts so the caller can log or assert against them.
+ */
+export function registerSkills(server, skillsDir) {
+    const skills = loadSkills(skillsDir ?? defaultSkillsDir());
+    for (const skill of skills) {
+        const argsSchema = {};
+        for (const arg of skill.frontmatter.arguments) {
+            argsSchema[arg.name] = arg.required
+                ? z.string().describe(arg.description)
+                : z.string().optional().describe(arg.description);
+        }
+        server.registerPrompt(skill.frontmatter.name, {
+            title: skill.frontmatter.name,
+            description: skill.frontmatter.description,
+            argsSchema,
+        }, async (rawArgs) => {
+            const args = (rawArgs ?? {});
+            const filledBody = applyArgs(skill.body, args);
+            return {
+                messages: [
+                    {
+                        role: 'user',
+                        content: {
+                            type: 'text',
+                            text: filledBody,
+                        },
+                    },
+                ],
+            };
+        });
+    }
+    return skills.map((s) => s.frontmatter.name);
+}
+/**
+ * Substitutes `{{argName}}` placeholders in the skill body with the supplied
+ * argument values. Unset args become an empty string so the model can decide
+ * to ask. This is intentionally simple — full templating is over-engineering
+ * for prose workflows.
+ */
+function applyArgs(body, args) {
+    return body.replace(/\{\{\s*([A-Za-z_][A-Za-z0-9_-]*)\s*\}\}/g, (_match, name) => {
+        return args[name] ?? '';
+    });
+}

package/dist/prompts/loader.d.ts

@@ -0,0 +1,13 @@
+import { type ParsedSkill } from './frontmatter.js';
+export interface LoadedSkill extends ParsedSkill {
+    /** File path relative to the skills dir, useful in error messages. */
+    fileName: string;
+}
+/**
+ * Resolve the directory holding the shipped skill markdown files. When the
+ * package is installed via npm, skills live at `<pkg>/skills/`. When running
+ * from source via `tsx`, the layout is `<repo>/mcp/skills/` and this file is
+ * at `<repo>/mcp/src/prompts/loader.ts`, two levels deep.
+ */
+export declare function defaultSkillsDir(): string;
+export declare function loadSkills(dir?: string): LoadedSkill[];

package/dist/prompts/loader.js

@@ -0,0 +1,36 @@
+import { readdirSync, readFileSync } from 'node:fs';
+import { dirname, join, resolve } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { parseSkill } from './frontmatter.js';
+/**
+ * Resolve the directory holding the shipped skill markdown files. When the
+ * package is installed via npm, skills live at `<pkg>/skills/`. When running
+ * from source via `tsx`, the layout is `<repo>/mcp/skills/` and this file is
+ * at `<repo>/mcp/src/prompts/loader.ts`, two levels deep.
+ */
+export function defaultSkillsDir() {
+    const here = dirname(fileURLToPath(import.meta.url));
+    // Two levels up from this file (src/prompts/ or dist/prompts/) is the
+    // package root, which holds `skills/` in both layouts.
+    return resolve(here, '..', '..', 'skills');
+}
+export function loadSkills(dir = defaultSkillsDir()) {
+    let entries;
+    try {
+        entries = readdirSync(dir);
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        throw new Error(`Could not read skills directory at ${dir}: ${msg}`);
+    }
+    const skills = [];
+    for (const entry of entries.sort()) {
+        if (!entry.endsWith('.md'))
+            continue;
+        const full = join(dir, entry);
+        const raw = readFileSync(full, 'utf8');
+        const parsed = parseSkill(raw, full);
+        skills.push({ ...parsed, fileName: entry });
+    }
+    return skills;
+}

package/dist/safety/index.d.ts

@@ -0,0 +1 @@
+export { SpendCapTracker, SpendCapExceededError } from './spend-cap.js';

package/dist/safety/index.js

@@ -0,0 +1 @@
+export { SpendCapTracker, SpendCapExceededError } from './spend-cap.js';

package/dist/safety/spend-cap.d.ts

@@ -0,0 +1,33 @@
+/**
+ * In-process session spend cap. Tracks how much an agent has committed across
+ * `place_bet` and `place_order` (bid side) calls within a single server
+ * lifetime, and refuses further spend once the configured cap is reached.
+ *
+ * Independent of (additive to) any rate or balance limits the backend enforces.
+ * Resets when the process restarts.
+ */
+export declare class SpendCapTracker {
+    private readonly cap;
+    private spent;
+    constructor(cap: number | null);
+    /** How much has been committed so far (USD). */
+    totalSpent(): number;
+    /** Effective cap, or `null` if unset. */
+    effectiveCap(): number | null;
+    /**
+     * Throws SpendCapExceededError if `amount` would push cumulative spend over
+     * the cap. If the cap is null, this is a no-op. Calls `commit` on success.
+     */
+    reserve(amount: number, toolName: string): void;
+    /**
+     * Return a previously reserved amount to the cap, e.g. when the backend
+     * definitively rejected the placement (4xx) so nothing was actually spent.
+     * Ambiguous failures (network errors, 5xx) should NOT be released.
+     */
+    release(amount: number): void;
+}
+export declare class SpendCapExceededError extends Error {
+    readonly spent: number;
+    readonly cap: number;
+    constructor(message: string, spent: number, cap: number);
+}

package/dist/safety/spend-cap.js

@@ -0,0 +1,64 @@
+/**
+ * In-process session spend cap. Tracks how much an agent has committed across
+ * `place_bet` and `place_order` (bid side) calls within a single server
+ * lifetime, and refuses further spend once the configured cap is reached.
+ *
+ * Independent of (additive to) any rate or balance limits the backend enforces.
+ * Resets when the process restarts.
+ */
+export class SpendCapTracker {
+    cap;
+    spent = 0;
+    constructor(cap) {
+        this.cap = cap;
+    }
+    /** How much has been committed so far (USD). */
+    totalSpent() {
+        return this.spent;
+    }
+    /** Effective cap, or `null` if unset. */
+    effectiveCap() {
+        return this.cap;
+    }
+    /**
+     * Throws SpendCapExceededError if `amount` would push cumulative spend over
+     * the cap. If the cap is null, this is a no-op. Calls `commit` on success.
+     */
+    reserve(amount, toolName) {
+        if (this.cap === null)
+            return;
+        if (!Number.isFinite(amount) || amount < 0) {
+            throw new SpendCapExceededError(`Tool ${toolName} attempted to reserve a negative or non-finite amount (${amount}). ` +
+                `Refusing as a safety measure.`, this.spent, this.cap);
+        }
+        if (this.spent + amount > this.cap) {
+            throw new SpendCapExceededError(`Refusing ${toolName}: this call would commit ${amount.toFixed(2)} USD, bringing the ` +
+                `session total to ${(this.spent + amount).toFixed(2)} USD and exceeding the configured ` +
+                `cap of ${this.cap.toFixed(2)} USD (UNHEDGED_MAX_SPEND_PER_SESSION). ` +
+                `Restart the MCP server or raise the cap to continue.`, this.spent, this.cap);
+        }
+        this.spent += amount;
+    }
+    /**
+     * Return a previously reserved amount to the cap, e.g. when the backend
+     * definitively rejected the placement (4xx) so nothing was actually spent.
+     * Ambiguous failures (network errors, 5xx) should NOT be released.
+     */
+    release(amount) {
+        if (this.cap === null)
+            return;
+        if (!Number.isFinite(amount) || amount <= 0)
+            return;
+        this.spent = Math.max(0, this.spent - amount);
+    }
+}
+export class SpendCapExceededError extends Error {
+    spent;
+    cap;
+    constructor(message, spent, cap) {
+        super(message);
+        this.name = 'SpendCapExceededError';
+        this.spent = spent;
+        this.cap = cap;
+    }
+}

package/dist/server.d.ts

@@ -0,0 +1,3 @@
+import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare function createServer(): Promise<McpServer>;
+export declare function startStdioServer(): Promise<void>;