@chartobserver/mcp-server 0.1.0 → 0.2.1

package/CHANGELOG.md

@@ -0,0 +1,60 @@
+# Changelog
+
+## 0.2.1 — 2026-06-12
+
+Agent-facing signup guidance. No behavior changes to tools or transport.
+
+- **MCP server `instructions`**: the server now tells the connected AI agent,
+  at initialization, that an existing chart.observer account is required,
+  that accounts cannot be created through this server, and to direct the
+  user to sign up in a browser at https://chart.observer. Previously this
+  fact lived only in the README, which agents never see.
+- Missing/invalid configuration errors now include the same guidance (where
+  credentials come from, where to create an account).
+- `get_profile` and `place_trade` descriptions carry a one-line fallback of
+  the guidance for MCP clients that don't surface server instructions.
+
+## 0.2.0 — 2026-06-12
+
+Hardening & trust release. No breaking changes for users — configuration and
+tool surface are unchanged.
+
+### Security
+
+- **Webhook credential can no longer appear in tool output.** API errors now
+  carry a sanitized request label (e.g. `POST /transaction`) instead of the
+  raw URL path, and all error text returned to the agent passes through a
+  central secret-redaction backstop. Regression-tested.
+- **Live trades now run the same validation as dry runs.** Previously,
+  `place_trade` with `dry_run: false` skipped the positive-count,
+  percentage-buy, sufficient-funds, and oversell checks. Execution now refuses
+  any trade the dry run would flag, without calling the API.
+- **Config validation at startup**: numeric UID, minimum webhook-ID length,
+  `https:`-only API base. Clear, secret-free failure messages.
+- An absent `dry_run` flag is treated as a dry run even if schema defaults are
+  bypassed (defense-in-depth).
+
+### Reliability
+
+- Per-request timeout (default 15 s, override with `CHARTOBSERVER_TIMEOUT_MS`)
+  so a hung backend can no longer wedge the MCP client.
+- Reads (GET) retry once on HTTP 429, honoring `Retry-After`. Trade execution
+  is **never** auto-retried.
+- Trade execution sends a UUID `Idempotency-Key` header (forward-compat for
+  backend deduplication).
+
+### Trust & transparency
+
+- All tools carry MCP annotations: read tools are `readOnlyHint`, and
+  `place_trade` is explicitly `destructiveHint` / non-idempotent.
+- `SECURITY.md` with a full egress/data-flow disclosure and vulnerability
+  reporting process.
+- Source published at https://github.com/bbusche/chartobserver-mcp;
+  `repository`/`homepage`/`bugs` metadata added; releases published from CI
+  with npm provenance.
+
+## 0.1.0 — 2026-06-09
+
+Initial public release: read tools (profile, balance, positions, trades,
+leaderboard, prices, portfolio summary) and `place_trade` with dry-run
+default.

package/README.md

@@ -4,6 +4,14 @@ An MCP (Model Context Protocol) server that lets an AI agent — Claude Desktop,
 
 ChartObserver is paper trading. This server cannot move real money. It can affect your public leaderboard standing and your visible portfolio.
 
+Source code: https://github.com/bbusche/chartobserver-mcp — see [SECURITY.md](SECURITY.md) for the full egress/data-flow disclosure.
+
+## What this server sends and where
+
+- Outbound HTTPS to **exactly one host**: the configured `CHARTOBSERVER_API_BASE` (default: the ChartObserver production API on AWS API Gateway, `https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev`).
+- It transmits your UID, username, your webhook credential (as auth on trade execution), and the trade parameters the agent supplies. Nothing else.
+- It reads **no** files, contacts **no** other host, collects **no** telemetry, runs **no** code fetched at runtime, and has **no** install scripts.
+
 ## Install
 
 You don't install this package directly. You add it to your MCP client's configuration and it runs on demand via `npx`.
@@ -48,7 +56,8 @@ Sign in at https://chart.observer and open **Settings → API & Integrations**.
 | `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. |
+| `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. Must be `https:`. |
+| `CHARTOBSERVER_TIMEOUT_MS` | no | `15000` | Per-request timeout in milliseconds (max 120000). |
 
 ## Available tools
 
@@ -86,6 +95,8 @@ Sign in at https://chart.observer and open **Settings → API & Integrations**.
 
 - **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.
+- **Live trades are validated.** Execution runs the same checks as the dry run (sufficient funds, position size, well-formed quantities) and refuses trades that would fail, without calling the API.
+- **Secret redaction.** Error text returned to the agent is sanitized; the webhook credential is redacted as defense-in-depth so it cannot leak into transcripts.
 - **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.
 
@@ -130,6 +141,7 @@ src/
   index.ts          # MCP server entry, registers tools
   config.ts         # Loads + validates env vars
   api-client.ts     # HTTP client for ChartObserver API
+  redact.ts         # Secret-redaction backstop for all outbound error text
   tools/
     account.ts
     trading.ts
@@ -139,4 +151,6 @@ src/
   __tests__/
     api-client.test.ts
     config.test.ts
+    trading.test.ts
+    redact.test.ts
 ```

package/SECURITY.md

@@ -0,0 +1,48 @@
+# Security
+
+## What this server sends and where
+
+This package makes outbound HTTPS requests to **exactly one host**: the
+configured `CHARTOBSERVER_API_BASE` (default:
+`https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev`, the ChartObserver
+production API on AWS API Gateway). There is no other network egress of any
+kind.
+
+What it transmits to that host:
+
+- your ChartObserver **UID** and **username** (to scope reads to your account)
+- your **webhook credential** (as authentication on trade execution)
+- the **trade parameters** the AI agent supplies (pair, action, count)
+- a `User-Agent`/`X-Client` header identifying this package and version, and a
+  random `Idempotency-Key` UUID on trade execution
+
+What it never does:
+
+- **No telemetry, analytics, or usage beacons.** Nothing is collected.
+- **No other hosts** are contacted, ever.
+- **No filesystem reads or writes** beyond what the MCP SDK requires for
+  stdio transport.
+- **No code fetched or evaluated at runtime**, no `postinstall`/`preinstall`
+  scripts, no obfuscated output — the published `dist/` is readable compiled
+  TypeScript, and the source is at
+  https://github.com/bbusche/chartobserver-mcp.
+
+## The webhook credential
+
+`CHARTOBSERVER_WEBHOOK_ID` is a **trade-capable bearer secret** — anyone who
+has it can place paper trades on your account (affecting your leaderboard
+standing and visible portfolio, not real funds). Treat it like a password:
+
+- Don't paste it into chats, screenshots, issues, or logs.
+- This server sanitizes its error output and redacts the credential from any
+  text returned to the AI agent, as defense-in-depth.
+- If you suspect it leaked, regenerate it from your ChartObserver account
+  settings (Settings → API & Integrations) — the old value stops working
+  immediately.
+
+## Reporting a vulnerability
+
+Please report suspected vulnerabilities privately via GitHub's
+[private vulnerability reporting](https://github.com/bbusche/chartobserver-mcp/security/advisories/new)
+on this repository. Do not open a public issue for security reports. We aim to
+acknowledge reports within 72 hours.

package/dist/api-client.d.ts

@@ -61,23 +61,32 @@ export interface LeaderboardResponse {
 }
 export declare class ChartObserverApiError extends Error {
     readonly status: number;
-    readonly path: string;
+    readonly label: string;
     readonly bodyText: string;
-    constructor(status: number, path: string, bodyText: string);
+    /**
+     * `label` is a sanitized request descriptor (e.g. "POST /transaction") —
+     * never the interpolated URL path, which can contain the webhook secret.
+     */
+    constructor(status: number, label: string, bodyText: string);
 }
 type FetchLike = (input: string, init?: {
     method?: string;
     headers?: Record<string, string>;
     body?: string;
+    signal?: AbortSignal;
 }) => Promise<{
     ok: boolean;
     status: number;
     text: () => Promise<string>;
+    headers?: {
+        get(name: string): string | null;
+    };
 }>;
 export declare class ChartObserverClient {
     readonly config: Config;
     private readonly fetchFn;
     constructor(config: Config, fetchFn?: FetchLike);
+    private fetchWithTimeout;
     private request;
     getBalance(): Promise<number>;
     getOpenPositions(): Promise<Transaction[]>;

package/dist/api-client.js

@@ -1,15 +1,21 @@
+import { randomUUID } from "node:crypto";
 export class ChartObserverApiError extends Error {
     status;
-    path;
+    label;
     bodyText;
-    constructor(status, path, bodyText) {
-        super(`ChartObserver API ${status} on ${path}: ${bodyText.slice(0, 500)}`);
+    /**
+     * `label` is a sanitized request descriptor (e.g. "POST /transaction") —
+     * never the interpolated URL path, which can contain the webhook secret.
+     */
+    constructor(status, label, bodyText) {
+        super(`ChartObserver API ${status} on ${label}: ${bodyText.slice(0, 500)}`);
         this.status = status;
-        this.path = path;
+        this.label = label;
         this.bodyText = bodyText;
         this.name = "ChartObserverApiError";
     }
 }
+const MAX_RETRY_AFTER_S = 10;
 export class ChartObserverClient {
     config;
     fetchFn;
@@ -17,46 +23,91 @@ export class ChartObserverClient {
         this.config = config;
         this.fetchFn = fetchFn;
     }
+    async fetchWithTimeout(url, init, label) {
+        const timeoutMs = this.config.timeoutMs;
+        const signal = AbortSignal.timeout(timeoutMs);
+        const timeoutError = new Error(`Request to ChartObserver API timed out after ${timeoutMs}ms (${label})`);
+        let onAbort;
+        // Race an explicit rejection alongside the signal: injected fetch
+        // implementations may ignore `signal`, but the tool must still unblock.
+        const abortPromise = new Promise((_, reject) => {
+            onAbort = () => reject(timeoutError);
+            signal.addEventListener("abort", onAbort, { once: true });
+        });
+        try {
+            return await Promise.race([
+                this.fetchFn(url, { ...init, signal }),
+                abortPromise,
+            ]);
+        }
+        catch (e) {
+            const name = e?.name;
+            if (name === "AbortError" || name === "TimeoutError")
+                throw timeoutError;
+            throw e;
+        }
+        finally {
+            if (onAbort)
+                signal.removeEventListener("abort", onAbort);
+        }
+    }
     async request(path, opts = {}) {
+        const method = opts.method ?? "GET";
+        const label = opts.label ?? `${method} request`;
         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,
-            },
+        const headers = {
+            "Content-Type": "application/json",
+            "User-Agent": this.config.userAgent,
+            "X-Client": this.config.userAgent,
+        };
+        if (opts.idempotencyKey)
+            headers["Idempotency-Key"] = opts.idempotencyKey;
+        const init = {
+            method,
+            headers,
             body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-        });
+        };
+        let res = await this.fetchWithTimeout(url, init, label);
+        if (res.status === 429 && method === "GET") {
+            // Honor Retry-After once for idempotent reads. Never retry POSTs.
+            const retryAfterS = Number(res.headers?.get("retry-after") ?? "") || 1;
+            const waitMs = Math.min(retryAfterS, MAX_RETRY_AFTER_S) * 1000;
+            await new Promise((resolve) => setTimeout(resolve, waitMs));
+            res = await this.fetchWithTimeout(url, init, label);
+        }
         const text = await res.text();
         if (!res.ok) {
-            throw new ChartObserverApiError(res.status, path, text);
+            throw new ChartObserverApiError(res.status, label, text);
         }
         if (!text)
             return {};
         return JSON.parse(text);
     }
     async getBalance() {
-        const result = await this.request(`/users/balance/${encodeURIComponent(this.config.uid)}`);
+        const result = await this.request(`/users/balance/${encodeURIComponent(this.config.uid)}`, { label: "GET /users/balance" });
         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)}`);
+        return this.request(`/positions/open/${encodeURIComponent(this.config.uid)}`, { label: "GET /positions/open" });
     }
     async getClosedPositions() {
-        return this.request(`/positions/closed/${encodeURIComponent(this.config.uid)}`);
+        return this.request(`/positions/closed/${encodeURIComponent(this.config.uid)}`, { label: "GET /positions/closed" });
     }
     async getRecentTransactions() {
-        return this.request(`/transactions/${encodeURIComponent(this.config.uid)}`);
+        return this.request(`/transactions/${encodeURIComponent(this.config.uid)}`, { label: "GET /transactions" });
     }
     async getLeaderboard() {
-        return this.request("/leaderboard");
+        return this.request("/leaderboard", {
+            label: "GET /leaderboard",
+        });
     }
     async getPrice(tokenPair) {
-        const result = await this.request(`/token/price/${encodeURIComponent(tokenPair)}`);
+        const result = await this.request(`/token/price/${encodeURIComponent(tokenPair)}`, {
+            label: "GET /token/price",
+        });
         const raw = result?.data?.amount ?? result?.amount ?? result?.price ?? NaN;
         const n = Number(raw);
         if (!Number.isFinite(n)) {
@@ -65,12 +116,16 @@ export class ChartObserverClient {
         return n;
     }
     async getPublicProfile(username) {
-        const result = await this.request(`/user/profile/${encodeURIComponent(username)}`);
+        const result = await this.request(`/user/profile/${encodeURIComponent(username)}`, { label: "GET /user/profile" });
         return result?.data ?? {};
     }
     async placeTrade(args) {
         return this.request(`/transaction/${encodeURIComponent(this.config.webhookId)}`, {
             method: "POST",
+            label: "POST /transaction",
+            // Sent for forward-compat: the backend will dedupe on this key once
+            // idempotency support lands. The client never auto-retries this POST.
+            idempotencyKey: randomUUID(),
             body: {
                 tokenpair: args.tokenPair,
                 action: args.action,

package/dist/config.d.ts

@@ -4,7 +4,10 @@ export interface Config {
     uid: string;
     username: string;
     userAgent: string;
+    timeoutMs: number;
 }
 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 const DEFAULT_TIMEOUT_MS = 15000;
+export declare const PACKAGE_VERSION = "0.2.1";
+export declare const CREDENTIALS_HINT: string;
 export declare function loadConfig(env?: NodeJS.ProcessEnv): Config;

package/dist/config.js

@@ -1,5 +1,32 @@
+import { z } from "zod";
 export const DEFAULT_API_BASE = "https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev";
-export const PACKAGE_VERSION = "0.1.0";
+export const DEFAULT_TIMEOUT_MS = 15_000;
+export const PACKAGE_VERSION = "0.2.1";
+export const CREDENTIALS_HINT = "These values come from your chart.observer account: create one in a " +
+    "browser at https://chart.observer (accounts cannot be created via this " +
+    "server), then copy your webhook ID, UID, and username from Settings → " +
+    "API & Integrations.";
+// Validation messages must never echo the webhook value — they can end up in
+// MCP client logs.
+const configSchema = z.object({
+    webhookId: z
+        .string()
+        .min(8, "CHARTOBSERVER_WEBHOOK_ID looks too short to be a valid webhook ID."),
+    uid: z
+        .string()
+        .regex(/^\d+$/, "CHARTOBSERVER_UID must be your numeric user ID."),
+    username: z.string().min(1, "CHARTOBSERVER_USERNAME must not be empty."),
+    apiBase: z
+        .string()
+        .url("CHARTOBSERVER_API_BASE must be a valid URL.")
+        .refine((u) => new URL(u).protocol === "https:", "CHARTOBSERVER_API_BASE must use https: (credentials travel on this connection)."),
+    timeoutMs: z
+        .number()
+        .int()
+        .positive()
+        .max(120_000)
+        .describe("CHARTOBSERVER_TIMEOUT_MS"),
+});
 export function loadConfig(env = process.env) {
     const webhookId = env.CHARTOBSERVER_WEBHOOK_ID?.trim();
     const uid = env.CHARTOBSERVER_UID?.trim();
@@ -12,13 +39,31 @@ export function loadConfig(env = process.env) {
     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.`);
+        throw new Error(`Missing required environment variable(s): ${missing.join(", ")}. Configure them in your MCP client's mcpServers entry. ${CREDENTIALS_HINT}`);
     }
-    return {
+    const rawTimeout = env.CHARTOBSERVER_TIMEOUT_MS?.trim();
+    const timeoutMs = rawTimeout ? Number(rawTimeout) : DEFAULT_TIMEOUT_MS;
+    if (rawTimeout && !Number.isFinite(timeoutMs)) {
+        throw new Error("CHARTOBSERVER_TIMEOUT_MS must be a number (milliseconds).");
+    }
+    const candidate = {
         apiBase: (env.CHARTOBSERVER_API_BASE?.trim() || DEFAULT_API_BASE).replace(/\/+$/, ""),
         webhookId: webhookId,
         uid: uid,
         username: username,
+        timeoutMs,
+    };
+    const parsed = configSchema.safeParse(candidate);
+    if (!parsed.success) {
+        const reasons = parsed.error.issues
+            .map((i) => i.path[0] === "timeoutMs"
+            ? "CHARTOBSERVER_TIMEOUT_MS must be a positive integer ≤ 120000."
+            : i.message)
+            .join(" ");
+        throw new Error(`Invalid configuration: ${reasons} ${CREDENTIALS_HINT}`);
+    }
+    return {
+        ...parsed.data,
         userAgent: `chartobserver-mcp/${PACKAGE_VERSION}`,
     };
 }

package/dist/index.js

@@ -3,17 +3,20 @@ 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 { SERVER_INSTRUCTIONS } from "./instructions.js";
+import { registerSecret, redactSecrets } from "./redact.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();
+    registerSecret(config.webhookId);
     const client = new ChartObserverClient(config);
     const server = new McpServer({
         name: "chartobserver",
         version: PACKAGE_VERSION,
-    });
+    }, { instructions: SERVER_INSTRUCTIONS });
     registerAccountTools(server, client);
     registerTradingTools(server, client);
     registerMarketTools(server, client);
@@ -23,6 +26,6 @@ async function main() {
 }
 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.stderr.write(redactSecrets(`chartobserver-mcp fatal: ${err?.stack ?? err}\n`));
     process.exit(1);
 });

package/dist/instructions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * Server-level instructions surfaced to the AI agent at MCP initialization.
+ * This is the agent-visible counterpart of the README: it must carry any fact
+ * the model needs to relay to the user, because the agent never sees npm or
+ * website documentation.
+ */
+export declare const SERVER_INSTRUCTIONS: string;

package/dist/instructions.js

@@ -0,0 +1,19 @@
+/**
+ * Server-level instructions surfaced to the AI agent at MCP initialization.
+ * This is the agent-visible counterpart of the README: it must carry any fact
+ * the model needs to relay to the user, because the agent never sees npm or
+ * website documentation.
+ */
+export const SERVER_INSTRUCTIONS = [
+    "ChartObserver is a crypto paper-trading platform (https://chart.observer).",
+    "This server requires an EXISTING chart.observer account — accounts cannot",
+    "be created through this server or by any agent (signup is CAPTCHA-protected",
+    "and must be done by the user in a browser at https://chart.observer).",
+    "If the configured credentials are missing or invalid, tell the user to:",
+    "(1) create an account at https://chart.observer in their browser, then",
+    "(2) copy their webhook ID, UID, and username from Settings → API &",
+    "Integrations into this server's environment variables (see the package",
+    "README). All trading is simulated paper trading — no real funds move — but",
+    "trades do affect the user's public leaderboard standing, so always confirm",
+    "with the user before executing a trade (place_trade defaults to dry_run).",
+].join(" ");

package/dist/redact.d.ts

@@ -0,0 +1,11 @@
+/**
+ * Central secret-redaction registry. Secrets are registered once at startup
+ * (index.ts) and every string that can leave the process — tool error text,
+ * the fatal handler — is passed through redactSecrets() as a backstop, so a
+ * credential can never reach the model transcript even via an unexpected
+ * error path.
+ */
+export declare function registerSecret(value: string): void;
+/** Test helper — the registry is module-global. */
+export declare function clearSecrets(): void;
+export declare function redactSecrets(text: string): string;

package/dist/redact.js

@@ -0,0 +1,24 @@
+/**
+ * Central secret-redaction registry. Secrets are registered once at startup
+ * (index.ts) and every string that can leave the process — tool error text,
+ * the fatal handler — is passed through redactSecrets() as a backstop, so a
+ * credential can never reach the model transcript even via an unexpected
+ * error path.
+ */
+const secrets = new Set();
+export function registerSecret(value) {
+    if (value)
+        secrets.add(value);
+}
+/** Test helper — the registry is module-global. */
+export function clearSecrets() {
+    secrets.clear();
+}
+export function redactSecrets(text) {
+    let out = text;
+    for (const secret of secrets) {
+        out = out.split(secret).join("***");
+        out = out.split(encodeURIComponent(secret)).join("***");
+    }
+    return out;
+}

package/dist/tools/account.js

@@ -1,8 +1,9 @@
-import { ok, fail } from "./util.js";
+import { ok, fail, READ_TOOL_ANNOTATIONS } 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.",
+        description: "Fetch the currently configured user's public profile (description, social links, follower counts) along with their USD paper-trading balance. Read-only. Requires an existing chart.observer account — if credentials are missing or rejected, direct the user to sign up in a browser at https://chart.observer (accounts cannot be created via this server).",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {},
     }, async () => {
         try {

package/dist/tools/market.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ok, fail } from "./util.js";
+import { ok, fail, READ_TOOL_ANNOTATIONS } from "./util.js";
 function findUserInLeaderboard(entries, username) {
     if (!entries)
         return null;
@@ -12,6 +12,7 @@ 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.",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {
             limit: z
                 .number()
@@ -39,6 +40,7 @@ export function registerMarketTools(server, client) {
     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.",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {},
     }, async () => {
         try {
@@ -59,6 +61,7 @@ export function registerMarketTools(server, client) {
     server.registerTool("get_price", {
         title: "Get current price",
         description: "Fetch the latest USD price for a crypto pair from the ChartObserver price cache.",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {
             tokenpair: z
                 .string()

package/dist/tools/portfolio.js

@@ -1,4 +1,4 @@
-import { ok, fail } from "./util.js";
+import { ok, fail, READ_TOOL_ANNOTATIONS } from "./util.js";
 function groupOpenPositions(positions) {
     const grouped = {};
     for (const p of positions) {
@@ -23,6 +23,7 @@ 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.",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {},
     }, async () => {
         try {

package/dist/tools/trading.js

@@ -1,5 +1,5 @@
 import { z } from "zod";
-import { ok, fail } from "./util.js";
+import { ok, fail, READ_TOOL_ANNOTATIONS } from "./util.js";
 const TOKEN_PAIR_PATTERN = /^[A-Za-z0-9]+$/;
 function summarizeOpenPositionsByToken(positions) {
     const grouped = {};
@@ -39,6 +39,89 @@ function resolveSellQuantity(countInput, availableTokens) {
     }
     return n;
 }
+/**
+ * Shared pre-flight for dry-run AND live execution, so the two paths cannot
+ * diverge: live trades get exactly the validation the dry run advertises.
+ */
+async function evaluateTrade(client, args) {
+    const pair = args.tokenpair.toUpperCase();
+    const [price, balance, openPositions] = await Promise.all([
+        client.getPrice(pair),
+        client.getBalance(),
+        client.getOpenPositions(),
+    ]);
+    const grouped = summarizeOpenPositionsByToken(openPositions);
+    const held = grouped[pair]?.totalAmount ?? 0;
+    const heldCostBasis = grouped[pair]?.avgCostBasis ?? 0;
+    const base = { pair, price, balance, held, heldCostBasis };
+    if (args.action === "buy") {
+        if (String(args.count).includes("%")) {
+            return {
+                ...base,
+                normalizedCount: NaN,
+                inputError: "Buy orders may not use a percentage count.",
+                wouldSucceed: false,
+                reason: null,
+            };
+        }
+        const n = Number(args.count);
+        if (!Number.isFinite(n) || n <= 0) {
+            return {
+                ...base,
+                normalizedCount: NaN,
+                inputError: "Buy count must be a positive number.",
+                wouldSucceed: false,
+                reason: null,
+            };
+        }
+        const cost = n * price;
+        const sufficient = balance >= cost;
+        return {
+            ...base,
+            normalizedCount: n,
+            inputError: null,
+            wouldSucceed: sufficient,
+            reason: sufficient
+                ? null
+                : `Insufficient funds: need ${cost.toFixed(2)} USD, have ${balance.toFixed(2)} USD.`,
+        };
+    }
+    // sell
+    let sellQty;
+    try {
+        sellQty = resolveSellQuantity(String(args.count), held);
+    }
+    catch (e) {
+        return {
+            ...base,
+            normalizedCount: NaN,
+            inputError: e.message,
+            wouldSucceed: false,
+            reason: null,
+        };
+    }
+    if (sellQty <= 0) {
+        return {
+            ...base,
+            normalizedCount: sellQty,
+            inputError: "Sell count must be a positive quantity or percentage.",
+            wouldSucceed: false,
+            reason: null,
+        };
+    }
+    const wouldSucceed = held > 0 && sellQty <= held * 1.005;
+    return {
+        ...base,
+        normalizedCount: sellQty,
+        inputError: null,
+        wouldSucceed,
+        reason: 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.`
+                : null,
+    };
+}
 export function registerTradingTools(server, client) {
     server.registerTool("place_trade", {
         title: "Place a paper trade",
@@ -51,7 +134,15 @@ export function registerTradingTools(server, client) {
             "- 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.",
+            "- Live execution runs the same validation as the dry run and refuses trades that would fail.",
+            "- Requires an existing chart.observer account. If credentials are rejected, direct the user to https://chart.observer to sign up in a browser (accounts cannot be created via this server).",
         ].join("\n"),
+        annotations: {
+            readOnlyHint: false,
+            destructiveHint: true,
+            idempotentHint: false,
+            openWorldHint: true,
+        },
         inputSchema: {
             tokenpair: z
                 .string()
@@ -69,74 +160,75 @@ export function registerTradingTools(server, client) {
                 .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 }) => {
+    }, 
+    // `dry_run = true` in the destructure is defense-in-depth: if the zod
+    // default is ever bypassed, an absent flag must still mean dry run.
+    async ({ tokenpair, action, count, dry_run = true }) => {
         try {
+            const evaln = await evaluateTrade(client, {
+                tokenpair,
+                action,
+                count,
+            });
+            if (evaln.inputError) {
+                return fail("place_trade", new Error(evaln.inputError));
+            }
             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;
+                    const cost = evaln.normalizedCount * evaln.price;
                     return ok({
                         dry_run: true,
                         action,
-                        tokenpair: tokenpair.toUpperCase(),
-                        currentPrice: price,
-                        count: n,
+                        tokenpair: evaln.pair,
+                        currentPrice: evaln.price,
+                        count: evaln.normalizedCount,
                         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.",
+                        currentBalance: evaln.balance,
+                        projectedBalance: evaln.balance - cost,
+                        wouldSucceed: evaln.wouldSucceed,
+                        note: evaln.reason ??
+                            "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;
+                const proceeds = evaln.normalizedCount * evaln.price;
                 return ok({
                     dry_run: true,
                     action,
-                    tokenpair: tokenpair.toUpperCase(),
-                    currentPrice: price,
-                    count: sellQty,
-                    currentHeld: held,
-                    costBasis: heldCostBasis,
+                    tokenpair: evaln.pair,
+                    currentPrice: evaln.price,
+                    count: evaln.normalizedCount,
+                    currentHeld: evaln.held,
+                    costBasis: evaln.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.",
+                    estimatedPnL: (evaln.price - evaln.heldCostBasis) * evaln.normalizedCount,
+                    currentBalance: evaln.balance,
+                    projectedBalance: evaln.balance + proceeds,
+                    wouldSucceed: evaln.wouldSucceed,
+                    note: evaln.reason ??
+                        "Confirm with the user, then re-call with dry_run=false to execute.",
                 });
             }
-            // Real execution
+            // Live execution — refuse anything the dry run would flag.
+            if (!evaln.wouldSucceed) {
+                return fail("place_trade", new Error(`Trade refused: ${evaln.reason}`));
+            }
+            // Percentage sells stay in backend-native form ('100%') so the
+            // platform computes the exact close quantity at execution time;
+            // numeric counts are sent as the validated number.
+            const wireCount = action === "sell" && String(count).includes("%")
+                ? String(count)
+                : evaln.normalizedCount;
             const res = await client.placeTrade({
-                tokenPair: tokenpair.toUpperCase(),
+                tokenPair: evaln.pair,
                 action,
-                count,
+                count: wireCount,
             });
             return ok({
                 dry_run: false,
                 executed: true,
+                tokenpair: evaln.pair,
+                action,
+                count: evaln.normalizedCount,
                 response: res,
             });
         }
@@ -147,6 +239,7 @@ export function registerTradingTools(server, client) {
     server.registerTool("get_balance", {
         title: "Get USD balance",
         description: "Fetch the configured user's current USD paper-trading balance.",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {},
     }, async () => {
         try {
@@ -160,6 +253,7 @@ export function registerTradingTools(server, client) {
     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).",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {},
     }, async () => {
         try {
@@ -178,6 +272,7 @@ export function registerTradingTools(server, client) {
     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.",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {
             limit: z
                 .number()
@@ -199,6 +294,7 @@ export function registerTradingTools(server, client) {
     server.registerTool("get_recent_transactions", {
         title: "Get recent transactions",
         description: "List the configured user's recent transactions (open + closed, all types). Most recent first.",
+        annotations: { ...READ_TOOL_ANNOTATIONS },
         inputSchema: {
             limit: z
                 .number()

package/dist/tools/util.d.ts

@@ -6,5 +6,10 @@ export interface ToolResult {
     }>;
     isError?: boolean;
 }
+/** Every read tool hits the live ChartObserver API and mutates nothing. */
+export declare const READ_TOOL_ANNOTATIONS: {
+    readonly readOnlyHint: true;
+    readonly openWorldHint: true;
+};
 export declare function ok(payload: unknown): ToolResult;
 export declare function fail(toolName: string, error: unknown): ToolResult;

package/dist/tools/util.js

@@ -1,4 +1,10 @@
 import { ChartObserverApiError } from "../api-client.js";
+import { redactSecrets } from "../redact.js";
+/** Every read tool hits the live ChartObserver API and mutates nothing. */
+export const READ_TOOL_ANNOTATIONS = {
+    readOnlyHint: true,
+    openWorldHint: true,
+};
 export function ok(payload) {
     return {
         content: [
@@ -14,7 +20,7 @@ export function ok(payload) {
 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)}`;
+        message = `${toolName} failed: HTTP ${error.status} from ${error.label}\n${error.bodyText.slice(0, 1000)}`;
     }
     else if (error instanceof Error) {
         message = `${toolName} failed: ${error.message}`;
@@ -23,7 +29,7 @@ export function fail(toolName, error) {
         message = `${toolName} failed: ${String(error)}`;
     }
     return {
-        content: [{ type: "text", text: message }],
+        content: [{ type: "text", text: redactSecrets(message) }],
         isError: true,
     };
 }

package/package.json

@@ -1,8 +1,25 @@
 {
   "name": "@chartobserver/mcp-server",
-  "version": "0.1.0",
+  "version": "0.2.1",
   "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",
+  "author": "ChartObserver Corp",
+  "homepage": "https://chart.observer",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/bbusche/chartobserver-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/bbusche/chartobserver-mcp/issues"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "chartobserver",
+    "paper-trading",
+    "crypto",
+    "claude"
+  ],
   "type": "module",
   "bin": {
     "chartobserver-mcp-server": "dist/index.js"
@@ -11,7 +28,9 @@
   "files": [
     "dist",
     "README.md",
-    "LICENSE"
+    "LICENSE",
+    "SECURITY.md",
+    "CHANGELOG.md"
   ],
   "scripts": {
     "build": "rm -rf dist && tsc",