@chartobserver/mcp-server 0.2.0 → 0.2.1

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # 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

package/dist/config.d.ts

@@ -8,5 +8,6 @@ export interface Config {
 }
 export declare const DEFAULT_API_BASE = "https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev";
 export declare const DEFAULT_TIMEOUT_MS = 15000;
-export declare const PACKAGE_VERSION = "0.2.0";
+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,7 +1,11 @@
 import { z } from "zod";
 export const DEFAULT_API_BASE = "https://g2uyqqluc4.execute-api.us-east-2.amazonaws.com/dev";
 export const DEFAULT_TIMEOUT_MS = 15_000;
-export const PACKAGE_VERSION = "0.2.0";
+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({
@@ -35,7 +39,7 @@ 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}`);
     }
     const rawTimeout = env.CHARTOBSERVER_TIMEOUT_MS?.trim();
     const timeoutMs = rawTimeout ? Number(rawTimeout) : DEFAULT_TIMEOUT_MS;
@@ -56,7 +60,7 @@ export function loadConfig(env = process.env) {
             ? "CHARTOBSERVER_TIMEOUT_MS must be a positive integer ≤ 120000."
             : i.message)
             .join(" ");
-        throw new Error(`Invalid configuration: ${reasons}`);
+        throw new Error(`Invalid configuration: ${reasons} ${CREDENTIALS_HINT}`);
     }
     return {
         ...parsed.data,

package/dist/index.js

@@ -3,6 +3,7 @@ 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";
@@ -15,7 +16,7 @@ async function main() {
     const server = new McpServer({
         name: "chartobserver",
         version: PACKAGE_VERSION,
-    });
+    }, { instructions: SERVER_INSTRUCTIONS });
     registerAccountTools(server, client);
     registerTradingTools(server, client);
     registerMarketTools(server, client);

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/tools/account.js

@@ -2,7 +2,7 @@ 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 () => {

package/dist/tools/trading.js

@@ -135,6 +135,7 @@ export function registerTradingTools(server, client) {
             "- 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,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@chartobserver/mcp-server",
-  "version": "0.2.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",