@chartobserver/mcp-server 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 ChartObserver Corp.
+
+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,142 @@
+# `@chartobserver/mcp-server`
+
+An MCP (Model Context Protocol) server that lets an AI agent — Claude Desktop, etc. — read your portfolio, place paper trades, and check the leaderboard on your [ChartObserver](https://chart.observer) account.
+
+ChartObserver is paper trading. This server cannot move real money. It can affect your public leaderboard standing and your visible portfolio.
+
+## Install
+
+You don't install this package directly. You add it to your MCP client's configuration and it runs on demand via `npx`.
+
+### Claude Desktop
+
+Open your Claude Desktop config file:
+
+- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
+- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
+
+Add a `chartobserver` entry under `mcpServers`:
+
+```json
+{
+  "mcpServers": {
+    "chartobserver": {
+      "command": "npx",
+      "args": ["-y", "@chartobserver/mcp-server"],
+      "env": {
+        "CHARTOBSERVER_WEBHOOK_ID": "your-webhook-id-here",
+        "CHARTOBSERVER_UID": "your-uid-here",
+        "CHARTOBSERVER_USERNAME": "your-username-here"
+      }
+    }
+  }
+}
+```
+
+Restart Claude Desktop. The tools become available in any conversation.
+
+### Where to find your credentials
+
+Sign in at https://chart.observer and open **Settings → API & Integrations**. The page shows your webhook ID, UID, and username with copy buttons and a pre-filled config snippet.
+
+(Until that settings page ships, ask Brian for your three values.)
+
+## Environment variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `CHARTOBSERVER_WEBHOOK_ID` | yes | — | Your per-user webhook secret. Same value TradingView uses to fire trades into your account. Treat like a password. |
+| `CHARTOBSERVER_UID` | yes | — | Your numeric user ID. |
+| `CHARTOBSERVER_USERNAME` | yes | — | Your public username. |
+| `CHARTOBSERVER_API_BASE` | no | `https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev` | API Gateway base URL. Override to point at staging during testing. |
+
+## Available tools
+
+### Account
+
+| Tool | What it does |
+|---|---|
+| `get_profile` | Read your public profile and current USD balance. |
+
+### Trading
+
+| Tool | What it does |
+|---|---|
+| `place_trade` | Place a buy or sell. **Defaults to `dry_run: true`** — returns the projected impact without executing. Set `dry_run: false` only after confirming with the user. |
+| `get_balance` | Current USD balance. |
+| `get_open_positions` | Open positions, grouped by token pair with average cost basis. |
+| `get_closed_trades` | Recent closed trades (completed buy→sell roundtrips). |
+| `get_recent_transactions` | Recent raw transactions (open + closed). |
+
+### Market
+
+| Tool | What it does |
+|---|---|
+| `get_leaderboard` | 7-day rolling leaderboard: top traders by average % profit. |
+| `get_my_ranking` | Your position on the leaderboard (or `null` if not ranked). |
+| `get_price` | Current price for a crypto pair (e.g. `BTCUSD`). |
+
+### Portfolio
+
+| Tool | What it does |
+|---|---|
+| `get_portfolio_summary` | One-shot snapshot: balance + open positions + recent closed trades + your leaderboard rank. Designed for periodic polling — compare snapshots to detect changes. |
+
+## Safety model
+
+- **Paper trading only.** Trades affect your simulated portfolio and your leaderboard standing. They do not move real money.
+- **`place_trade` defaults to dry-run.** The AI agent must explicitly pass `dry_run: false` to execute. You should be asked for confirmation before that happens.
+- **Bearer-secret auth.** The webhook ID acts as a bearer token. If it leaks, anyone can act on your account. Don't paste it into screenshots, logs, or chat messages. If you suspect compromise, regenerate it from Settings → API & Integrations.
+- **No account creation.** Sign up at https://chart.observer in a browser. Web signup requires a CAPTCHA, which a headless MCP server can't solve.
+
+## What's not in v1
+
+- Real-time push notifications (poll `get_portfolio_summary` instead).
+- Per-token rotation, multiple tokens, scoped tokens, expiry — these will come in a later revision that hardens the webhook-ID lifecycle.
+- Equities/options/forex — the platform is crypto-only paper trading today.
+
+## Development
+
+```bash
+npm install
+npm run typecheck
+npm test
+npm run build
+```
+
+To test locally against staging, build then point Claude Desktop at the local file:
+
+```json
+{
+  "mcpServers": {
+    "chartobserver-local": {
+      "command": "node",
+      "args": ["/absolute/path/to/chartobserver/mcp-server/dist/index.js"],
+      "env": {
+        "CHARTOBSERVER_API_BASE": "https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/staging",
+        "CHARTOBSERVER_WEBHOOK_ID": "...",
+        "CHARTOBSERVER_UID": "...",
+        "CHARTOBSERVER_USERNAME": "..."
+      }
+    }
+  }
+}
+```
+
+## Repo layout
+
+```
+src/
+  index.ts          # MCP server entry, registers tools
+  config.ts         # Loads + validates env vars
+  api-client.ts     # HTTP client for ChartObserver API
+  tools/
+    account.ts
+    trading.ts
+    market.ts
+    portfolio.ts
+    util.ts
+  __tests__/
+    api-client.test.ts
+    config.test.ts
+```

package/dist/api-client.d.ts

@@ -0,0 +1,97 @@
+import type { Config } from "./config.js";
+export interface Transaction {
+    userId: string;
+    txnId: string;
+    entityType: "buy" | "sell" | "reconcile";
+    amount: number;
+    exchange: number;
+    isOpen: boolean;
+    txnPrice: number;
+    tokenPair: string;
+    txnDate: string;
+    closeDate?: string;
+    closePrice?: number;
+    costBasis?: number;
+    txnSource: string;
+    strategyAuthor?: string;
+    strategyInterval?: string;
+}
+export interface ClosedTrade {
+    userId: string;
+    username: string;
+    txnId: string;
+    tokenPair: string;
+    amount: number;
+    avgPrice: number;
+    closePrice: number;
+    openDate: string;
+    closeDate: string;
+    ymd: string;
+    strategyAuthor?: string;
+    strategyInterval?: string;
+}
+export interface PublicProfile {
+    description?: string;
+    showPortfolio?: string;
+    copyTradable?: string;
+    instagramURL?: string;
+    tradingviewURL?: string;
+    twitterURL?: string;
+    youtubeURL?: string;
+    telegramURL?: string;
+    farcasterURL?: string;
+    subscription?: string;
+    followers?: number;
+    following?: number;
+    userId?: string;
+}
+export interface LeaderboardEntry {
+    username: string;
+    tradeCount: number;
+    avgProfit: number;
+    largestProfit: number;
+    strategy?: string;
+    interval?: string;
+}
+export interface LeaderboardResponse {
+    [windowDays: string]: {
+        topTraders?: LeaderboardEntry[];
+        leaderBoard?: unknown[];
+    };
+}
+export declare class ChartObserverApiError extends Error {
+    readonly status: number;
+    readonly path: string;
+    readonly bodyText: string;
+    constructor(status: number, path: string, bodyText: string);
+}
+type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    text: () => Promise<string>;
+}>;
+export declare class ChartObserverClient {
+    readonly config: Config;
+    private readonly fetchFn;
+    constructor(config: Config, fetchFn?: FetchLike);
+    private request;
+    getBalance(): Promise<number>;
+    getOpenPositions(): Promise<Transaction[]>;
+    getClosedPositions(): Promise<Transaction[]>;
+    getRecentTransactions(): Promise<Transaction[]>;
+    getLeaderboard(): Promise<LeaderboardResponse>;
+    getPrice(tokenPair: string): Promise<number>;
+    getPublicProfile(username: string): Promise<PublicProfile>;
+    placeTrade(args: {
+        tokenPair: string;
+        action: "buy" | "sell";
+        count: string | number;
+    }): Promise<{
+        message: string;
+    }>;
+}
+export {};

package/dist/api-client.js

@@ -0,0 +1,83 @@
+export class ChartObserverApiError extends Error {
+    status;
+    path;
+    bodyText;
+    constructor(status, path, bodyText) {
+        super(`ChartObserver API ${status} on ${path}: ${bodyText.slice(0, 500)}`);
+        this.status = status;
+        this.path = path;
+        this.bodyText = bodyText;
+        this.name = "ChartObserverApiError";
+    }
+}
+export class ChartObserverClient {
+    config;
+    fetchFn;
+    constructor(config, fetchFn = globalThis.fetch) {
+        this.config = config;
+        this.fetchFn = fetchFn;
+    }
+    async request(path, opts = {}) {
+        const url = `${this.config.apiBase}${path}`;
+        const res = await this.fetchFn(url, {
+            method: opts.method ?? "GET",
+            headers: {
+                "Content-Type": "application/json",
+                "User-Agent": this.config.userAgent,
+                "X-Client": this.config.userAgent,
+            },
+            body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+        });
+        const text = await res.text();
+        if (!res.ok) {
+            throw new ChartObserverApiError(res.status, path, text);
+        }
+        if (!text)
+            return {};
+        return JSON.parse(text);
+    }
+    async getBalance() {
+        const result = await this.request(`/users/balance/${encodeURIComponent(this.config.uid)}`);
+        if (!Array.isArray(result) || result.length === 0) {
+            throw new Error("Balance response was empty");
+        }
+        return Number(result[0].usdBalance);
+    }
+    async getOpenPositions() {
+        return this.request(`/positions/open/${encodeURIComponent(this.config.uid)}`);
+    }
+    async getClosedPositions() {
+        return this.request(`/positions/closed/${encodeURIComponent(this.config.uid)}`);
+    }
+    async getRecentTransactions() {
+        return this.request(`/transactions/${encodeURIComponent(this.config.uid)}`);
+    }
+    async getLeaderboard() {
+        return this.request("/leaderboard");
+    }
+    async getPrice(tokenPair) {
+        const result = await this.request(`/token/price/${encodeURIComponent(tokenPair)}`);
+        const raw = result?.data?.amount ?? result?.amount ?? result?.price ?? NaN;
+        const n = Number(raw);
+        if (!Number.isFinite(n)) {
+            throw new Error(`Unrecognized price response shape for ${tokenPair}: ${JSON.stringify(result)}`);
+        }
+        return n;
+    }
+    async getPublicProfile(username) {
+        const result = await this.request(`/user/profile/${encodeURIComponent(username)}`);
+        return result?.data ?? {};
+    }
+    async placeTrade(args) {
+        return this.request(`/transaction/${encodeURIComponent(this.config.webhookId)}`, {
+            method: "POST",
+            body: {
+                tokenpair: args.tokenPair,
+                action: args.action,
+                count: String(args.count),
+                user: this.config.uid,
+                exchange: "coinbase",
+            },
+        });
+    }
+}

package/dist/config.d.ts

@@ -0,0 +1,10 @@
+export interface Config {
+    apiBase: string;
+    webhookId: string;
+    uid: string;
+    username: string;
+    userAgent: string;
+}
+export declare const DEFAULT_API_BASE = "https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev";
+export declare const PACKAGE_VERSION = "0.1.0";
+export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -0,0 +1,24 @@
+export const DEFAULT_API_BASE = "https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev";
+export const PACKAGE_VERSION = "0.1.0";
+export function loadConfig(env = process.env) {
+    const webhookId = env.CHARTOBSERVER_WEBHOOK_ID?.trim();
+    const uid = env.CHARTOBSERVER_UID?.trim();
+    const username = env.CHARTOBSERVER_USERNAME?.trim();
+    const missing = [];
+    if (!webhookId)
+        missing.push("CHARTOBSERVER_WEBHOOK_ID");
+    if (!uid)
+        missing.push("CHARTOBSERVER_UID");
+    if (!username)
+        missing.push("CHARTOBSERVER_USERNAME");
+    if (missing.length > 0) {
+        throw new Error(`Missing required environment variable(s): ${missing.join(", ")}. Configure them in your MCP client's mcpServers entry. See README.`);
+    }
+    return {
+        apiBase: (env.CHARTOBSERVER_API_BASE?.trim() || DEFAULT_API_BASE).replace(/\/+$/, ""),
+        webhookId: webhookId,
+        uid: uid,
+        username: username,
+        userAgent: `chartobserver-mcp/${PACKAGE_VERSION}`,
+    };
+}

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,28 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { loadConfig, PACKAGE_VERSION } from "./config.js";
+import { ChartObserverClient } from "./api-client.js";
+import { registerAccountTools } from "./tools/account.js";
+import { registerTradingTools } from "./tools/trading.js";
+import { registerMarketTools } from "./tools/market.js";
+import { registerPortfolioTools } from "./tools/portfolio.js";
+async function main() {
+    const config = loadConfig();
+    const client = new ChartObserverClient(config);
+    const server = new McpServer({
+        name: "chartobserver",
+        version: PACKAGE_VERSION,
+    });
+    registerAccountTools(server, client);
+    registerTradingTools(server, client);
+    registerMarketTools(server, client);
+    registerPortfolioTools(server, client);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    // Stdio MCP uses stdout for protocol; errors must go to stderr.
+    process.stderr.write(`chartobserver-mcp fatal: ${err?.stack ?? err}\n`);
+    process.exit(1);
+});

package/dist/tools/account.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ChartObserverClient } from "../api-client.js";
+export declare function registerAccountTools(server: McpServer, client: ChartObserverClient): void;

package/dist/tools/account.js

@@ -0,0 +1,24 @@
+import { ok, fail } from "./util.js";
+export function registerAccountTools(server, client) {
+    server.registerTool("get_profile", {
+        title: "Get profile",
+        description: "Fetch the currently configured user's public profile (description, social links, follower counts) along with their USD paper-trading balance. Read-only.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const [profile, balance] = await Promise.all([
+                client.getPublicProfile(client.config.username),
+                client.getBalance(),
+            ]);
+            return ok({
+                username: client.config.username,
+                uid: client.config.uid,
+                balance,
+                profile,
+            });
+        }
+        catch (e) {
+            return fail("get_profile", e);
+        }
+    });
+}

package/dist/tools/market.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ChartObserverClient } from "../api-client.js";
+export declare function registerMarketTools(server: McpServer, client: ChartObserverClient): void;

package/dist/tools/market.js

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { ok, fail } from "./util.js";
+function findUserInLeaderboard(entries, username) {
+    if (!entries)
+        return null;
+    const idx = entries.findIndex((e) => e.username?.toLowerCase() === username.toLowerCase());
+    if (idx === -1)
+        return null;
+    return { rank: idx + 1, entry: entries[idx] };
+}
+export function registerMarketTools(server, client) {
+    server.registerTool("get_leaderboard", {
+        title: "Get leaderboard",
+        description: "Fetch the 7-day rolling ChartObserver leaderboard: top traders by average % profit per closed trade, plus the top individual closed trades. Public data.",
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(100)
+                .default(25)
+                .describe("Maximum number of top-traders rows to return."),
+        },
+    }, async ({ limit }) => {
+        try {
+            const board = await client.getLeaderboard();
+            const week = board["7"] ?? Object.values(board)[0];
+            const topTraders = (week?.topTraders ?? []).slice(0, limit);
+            return ok({
+                windowDays: 7,
+                topTraders,
+                topTradeCount: week?.leaderBoard?.length ?? 0,
+            });
+        }
+        catch (e) {
+            return fail("get_leaderboard", e);
+        }
+    });
+    server.registerTool("get_my_ranking", {
+        title: "Get my leaderboard rank",
+        description: "Find the configured user's position on the 7-day leaderboard, if they appear. Returns null rank if not on the board.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const board = await client.getLeaderboard();
+            const week = board["7"] ?? Object.values(board)[0];
+            const found = findUserInLeaderboard(week?.topTraders, client.config.username);
+            return ok({
+                username: client.config.username,
+                rank: found?.rank ?? null,
+                entry: found?.entry ?? null,
+                totalRanked: week?.topTraders?.length ?? 0,
+            });
+        }
+        catch (e) {
+            return fail("get_my_ranking", e);
+        }
+    });
+    server.registerTool("get_price", {
+        title: "Get current price",
+        description: "Fetch the latest USD price for a crypto pair from the ChartObserver price cache.",
+        inputSchema: {
+            tokenpair: z
+                .string()
+                .max(20)
+                .describe("Pair like BTCUSD, ETHUSD, SOLUSDT (no slash)."),
+        },
+    }, async ({ tokenpair }) => {
+        try {
+            const price = await client.getPrice(tokenpair.toUpperCase());
+            return ok({ tokenpair: tokenpair.toUpperCase(), price });
+        }
+        catch (e) {
+            return fail("get_price", e);
+        }
+    });
+}

package/dist/tools/portfolio.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ChartObserverClient } from "../api-client.js";
+export declare function registerPortfolioTools(server: McpServer, client: ChartObserverClient): void;

package/dist/tools/portfolio.js

@@ -0,0 +1,59 @@
+import { ok, fail } from "./util.js";
+function groupOpenPositions(positions) {
+    const grouped = {};
+    for (const p of positions) {
+        if (!p.isOpen)
+            continue;
+        const amt = Number(p.amount);
+        const price = Number(p.txnPrice);
+        if (!Number.isFinite(amt) || !Number.isFinite(price))
+            continue;
+        if (!grouped[p.tokenPair])
+            grouped[p.tokenPair] = { amount: 0, cost: 0 };
+        grouped[p.tokenPair].amount += amt;
+        grouped[p.tokenPair].cost += amt * price;
+    }
+    return Object.entries(grouped).map(([tokenPair, v]) => ({
+        tokenPair,
+        totalAmount: v.amount,
+        avgCostBasis: v.amount === 0 ? 0 : v.cost / v.amount,
+    }));
+}
+export function registerPortfolioTools(server, client) {
+    server.registerTool("get_portfolio_summary", {
+        title: "Get portfolio summary",
+        description: "One-call snapshot of the configured user's portfolio: USD balance, open positions grouped by token (with average cost basis), the 5 most recent closed trades, and the user's current leaderboard rank if any. Designed for periodic polling — agents can compare consecutive snapshots to detect changes.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const [balance, openPositions, closedTrades, leaderboard] = await Promise.all([
+                client.getBalance(),
+                client.getOpenPositions(),
+                client.getClosedPositions(),
+                client.getLeaderboard().catch(() => null),
+            ]);
+            const week = leaderboard?.["7"] ??
+                (leaderboard ? Object.values(leaderboard)[0] : undefined);
+            const myEntryIdx = week?.topTraders?.findIndex((e) => e.username?.toLowerCase() ===
+                client.config.username.toLowerCase()) ?? -1;
+            const grouped = groupOpenPositions(openPositions);
+            const recentClosed = closedTrades.slice(0, 5);
+            return ok({
+                asOf: new Date().toISOString(),
+                username: client.config.username,
+                uid: client.config.uid,
+                usdBalance: balance,
+                openPositions: grouped,
+                openPositionCount: openPositions.length,
+                recentClosedTrades: recentClosed,
+                leaderboardRank7d: myEntryIdx === -1 ? null : myEntryIdx + 1,
+                leaderboardEntry: myEntryIdx === -1
+                    ? null
+                    : (week?.topTraders?.[myEntryIdx] ?? null),
+            });
+        }
+        catch (e) {
+            return fail("get_portfolio_summary", e);
+        }
+    });
+}

package/dist/tools/trading.d.ts

@@ -0,0 +1,3 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import type { ChartObserverClient } from "../api-client.js";
+export declare function registerTradingTools(server: McpServer, client: ChartObserverClient): void;

package/dist/tools/trading.js

@@ -0,0 +1,220 @@
+import { z } from "zod";
+import { ok, fail } from "./util.js";
+const TOKEN_PAIR_PATTERN = /^[A-Za-z0-9]+$/;
+function summarizeOpenPositionsByToken(positions) {
+    const grouped = {};
+    for (const p of positions) {
+        if (!p.isOpen)
+            continue;
+        const key = p.tokenPair;
+        const amount = Number(p.amount);
+        const price = Number(p.txnPrice);
+        if (!Number.isFinite(amount) || !Number.isFinite(price))
+            continue;
+        if (!grouped[key])
+            grouped[key] = { totalAmount: 0, totalCost: 0 };
+        grouped[key].totalAmount += amount;
+        grouped[key].totalCost += amount * price;
+    }
+    const out = {};
+    for (const [k, v] of Object.entries(grouped)) {
+        out[k] = {
+            totalAmount: v.totalAmount,
+            avgCostBasis: v.totalAmount === 0 ? 0 : v.totalCost / v.totalAmount,
+        };
+    }
+    return out;
+}
+function resolveSellQuantity(countInput, availableTokens) {
+    if (countInput.includes("%")) {
+        const pct = parseFloat(countInput.replace("%", ""));
+        if (!Number.isFinite(pct)) {
+            throw new Error(`Invalid percent value: ${countInput}`);
+        }
+        return (pct / 100) * availableTokens;
+    }
+    const n = parseFloat(countInput);
+    if (!Number.isFinite(n)) {
+        throw new Error(`Invalid numeric count: ${countInput}`);
+    }
+    return n;
+}
+export function registerTradingTools(server, client) {
+    server.registerTool("place_trade", {
+        title: "Place a paper trade",
+        description: [
+            "Place a paper-trading buy or sell on the ChartObserver platform for the configured user.",
+            "",
+            "IMPORTANT SAFETY NOTES:",
+            "- Defaults to dry_run=true. With dry_run=true, NO trade is executed; the tool returns the would-be impact (cost, resulting balance, resulting position). Always start with dry_run=true and present the result to the user for confirmation before calling again with dry_run=false.",
+            "- This is paper trading (simulated). It does NOT move real funds. It DOES affect the user's leaderboard standing and visible portfolio.",
+            "- Crypto pairs only. Pair format is no-slash (e.g. BTCUSD, ETHUSDT).",
+            "- Sell `count` may be a percentage string like '50%' or '100%'. Buy `count` must be a numeric quantity.",
+            "- Buys require sufficient USD balance. Sells cannot exceed currently held tokens.",
+        ].join("\n"),
+        inputSchema: {
+            tokenpair: z
+                .string()
+                .regex(TOKEN_PAIR_PATTERN)
+                .max(20)
+                .describe("Trading pair in no-slash format, e.g. BTCUSD, ETHUSD, SOLUSDT."),
+            action: z
+                .enum(["buy", "sell"])
+                .describe("Trade direction."),
+            count: z
+                .union([z.number().positive(), z.string()])
+                .describe("Quantity of base token to trade. For sells, may be a percentage string ('50%', '100%') of currently held tokens. For buys, must be a positive number."),
+            dry_run: z
+                .boolean()
+                .default(true)
+                .describe("When true (default), returns the projected impact without executing. Set to false ONLY after confirming with the user."),
+        },
+    }, async ({ tokenpair, action, count, dry_run }) => {
+        try {
+            if (dry_run) {
+                const [price, balance, openPositions] = await Promise.all([
+                    client.getPrice(tokenpair.toUpperCase()),
+                    client.getBalance(),
+                    client.getOpenPositions(),
+                ]);
+                const grouped = summarizeOpenPositionsByToken(openPositions);
+                const held = grouped[tokenpair.toUpperCase()]?.totalAmount ?? 0;
+                const heldCostBasis = grouped[tokenpair.toUpperCase()]?.avgCostBasis ?? 0;
+                if (action === "buy") {
+                    if (String(count).includes("%")) {
+                        return fail("place_trade", new Error("Buy orders may not use a percentage count."));
+                    }
+                    const n = Number(count);
+                    if (!Number.isFinite(n) || n <= 0) {
+                        return fail("place_trade", new Error("Buy count must be a positive number."));
+                    }
+                    const cost = n * price;
+                    return ok({
+                        dry_run: true,
+                        action,
+                        tokenpair: tokenpair.toUpperCase(),
+                        currentPrice: price,
+                        count: n,
+                        estimatedCost: cost,
+                        currentBalance: balance,
+                        projectedBalance: balance - cost,
+                        wouldSucceed: balance >= cost,
+                        note: balance < cost
+                            ? `Insufficient funds: need ${cost.toFixed(2)} USD, have ${balance.toFixed(2)} USD.`
+                            : "Confirm with the user, then re-call with dry_run=false to execute.",
+                    });
+                }
+                // sell
+                const sellQty = resolveSellQuantity(String(count), held);
+                const proceeds = sellQty * price;
+                const wouldSucceed = held > 0 && sellQty <= held * 1.005;
+                return ok({
+                    dry_run: true,
+                    action,
+                    tokenpair: tokenpair.toUpperCase(),
+                    currentPrice: price,
+                    count: sellQty,
+                    currentHeld: held,
+                    costBasis: heldCostBasis,
+                    estimatedProceeds: proceeds,
+                    estimatedPnL: (price - heldCostBasis) * sellQty,
+                    currentBalance: balance,
+                    projectedBalance: balance + proceeds,
+                    wouldSucceed,
+                    note: held === 0
+                        ? "No open position for this token — sell would be rejected."
+                        : sellQty > held * 1.005
+                            ? `Sell quantity (${sellQty}) exceeds held (${held}) — would be rejected.`
+                            : "Confirm with the user, then re-call with dry_run=false to execute.",
+                });
+            }
+            // Real execution
+            const res = await client.placeTrade({
+                tokenPair: tokenpair.toUpperCase(),
+                action,
+                count,
+            });
+            return ok({
+                dry_run: false,
+                executed: true,
+                response: res,
+            });
+        }
+        catch (e) {
+            return fail("place_trade", e);
+        }
+    });
+    server.registerTool("get_balance", {
+        title: "Get USD balance",
+        description: "Fetch the configured user's current USD paper-trading balance.",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const balance = await client.getBalance();
+            return ok({ usdBalance: balance });
+        }
+        catch (e) {
+            return fail("get_balance", e);
+        }
+    });
+    server.registerTool("get_open_positions", {
+        title: "Get open positions",
+        description: "List all currently open paper-trading positions (buy transactions that have not yet been closed by a sell).",
+        inputSchema: {},
+    }, async () => {
+        try {
+            const positions = await client.getOpenPositions();
+            const groupedByToken = summarizeOpenPositionsByToken(positions);
+            return ok({
+                openTransactionCount: positions.length,
+                aggregateByToken: groupedByToken,
+                rawTransactions: positions,
+            });
+        }
+        catch (e) {
+            return fail("get_open_positions", e);
+        }
+    });
+    server.registerTool("get_closed_trades", {
+        title: "Get closed trades",
+        description: "List closed paper trades (completed buy→sell roundtrips) for the configured user, most recent first.",
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(300)
+                .default(50)
+                .describe("Maximum number of closed trades to return (server may cap)."),
+        },
+    }, async ({ limit }) => {
+        try {
+            const trades = await client.getClosedPositions();
+            return ok(trades.slice(0, limit));
+        }
+        catch (e) {
+            return fail("get_closed_trades", e);
+        }
+    });
+    server.registerTool("get_recent_transactions", {
+        title: "Get recent transactions",
+        description: "List the configured user's recent transactions (open + closed, all types). Most recent first.",
+        inputSchema: {
+            limit: z
+                .number()
+                .int()
+                .positive()
+                .max(300)
+                .default(50)
+                .describe("Maximum number of transactions to return."),
+        },
+    }, async ({ limit }) => {
+        try {
+            const txns = await client.getRecentTransactions();
+            return ok(txns.slice(0, limit));
+        }
+        catch (e) {
+            return fail("get_recent_transactions", e);
+        }
+    });
+}

package/dist/tools/util.d.ts

@@ -0,0 +1,10 @@
+export interface ToolResult {
+    [key: string]: unknown;
+    content: Array<{
+        type: "text";
+        text: string;
+    }>;
+    isError?: boolean;
+}
+export declare function ok(payload: unknown): ToolResult;
+export declare function fail(toolName: string, error: unknown): ToolResult;

package/dist/tools/util.js

@@ -0,0 +1,29 @@
+import { ChartObserverApiError } from "../api-client.js";
+export function ok(payload) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: typeof payload === "string"
+                    ? payload
+                    : JSON.stringify(payload, null, 2),
+            },
+        ],
+    };
+}
+export function fail(toolName, error) {
+    let message;
+    if (error instanceof ChartObserverApiError) {
+        message = `${toolName} failed: HTTP ${error.status} from ${error.path}\n${error.bodyText.slice(0, 1000)}`;
+    }
+    else if (error instanceof Error) {
+        message = `${toolName} failed: ${error.message}`;
+    }
+    else {
+        message = `${toolName} failed: ${String(error)}`;
+    }
+    return {
+        content: [{ type: "text", text: message }],
+        isError: true,
+    };
+}

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@chartobserver/mcp-server",
+  "version": "0.1.0",
+  "description": "MCP server for the ChartObserver paper-trading platform. Lets an AI agent (Claude Desktop, etc.) read portfolio state, place trades, and check the leaderboard on behalf of the configured user.",
+  "license": "MIT",
+  "type": "module",
+  "bin": {
+    "chartobserver-mcp-server": "dist/index.js"
+  },
+  "main": "dist/index.js",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "rm -rf dist && tsc",
+    "prepublishOnly": "npm run build",
+    "start": "node dist/index.js",
+    "dev": "tsx src/index.ts",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "typecheck": "tsc --noEmit"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.4",
+    "zod": "^3.23.8"
+  },
+  "devDependencies": {
+    "@types/node": "^20.14.0",
+    "tsx": "^4.16.0",
+    "typescript": "^5.5.0",
+    "vitest": "^1.6.0"
+  },
+  "engines": {
+    "node": ">=18"
+  }
+}