@aihubspot/agent-trade-mcp 0.1.0 → 0.1.1

package/README.md

@@ -3,3 +3,18 @@
 Install with `npm install -g @aihubspot/agent-trade-mcp`, then start `ai-hub-trade-mcp --profile default`.
 
 This package provides a local stdio MCP server. State-changing operations require a preview and a new explicit user confirmation.
+
+It reads the same local profile as the CLI from `~/.ai-hub/config.toml`. The API key and secret key are stored as plaintext in that file with mode `600`; configure them once through `ai-hub config set-credentials --profile <name>`. Do not share this file.
+
+## Client setup
+
+Register the local stdio MCP server with one supported client. The setup command is the only client-configuration entry point in this phase:
+
+```bash
+ai-hub-trade-mcp setup --client cursor --profile default
+ai-hub-trade-mcp setup --client claude-desktop --profile default
+ai-hub-trade-mcp setup --client claude-code --profile default
+ai-hub-trade-mcp setup --client codex --profile default
+```
+
+Setup registers the currently installed MCP binary through its absolute Node runtime and entrypoint path, so desktop clients do not depend on a global PATH or an unpublished `npx` package. Cursor and Claude Desktop configurations are merged with existing MCP servers through their JSON configurations. Claude Code and Codex are registered through their official CLIs; Claude Code uses user scope. Existing JSON configurations are validated, atomically updated, and backed up before their first modification. The setup command stores no API credentials; the MCP server continues to read its profile from `~/.ai-hub/config.toml`.

package/dist/index.js

@@ -12,12 +12,30 @@ var AiHubError = class extends Error {
     this.code = code;
   }
 };
+var OpenApiBusinessError = class extends AiHubError {
+  constructor(diagnosis) {
+    super(
+      "AI_HUB_OPENAPI_BUSINESS_ERROR",
+      `OpenAPI business error ${diagnosis.upstreamCode}: ${diagnosis.upstreamMessage}`
+    );
+    this.diagnosis = diagnosis;
+    this.name = "OpenApiBusinessError";
+  }
+  diagnosis;
+};
+function toAiHubErrorPayload(error) {
+  if (error instanceof OpenApiBusinessError) {
+    return { code: error.code, ...error.diagnosis };
+  }
+  if (error instanceof AiHubError) {
+    return { code: error.code, message: error.message };
+  }
+  return { code: "AI_HUB_UNEXPECTED_ERROR", message: error instanceof Error ? error.message : "Unexpected error" };
+}
 
 // ../core/src/credential.ts
 import { createHash } from "crypto";
-import keytar from "keytar";
-var SERVICE_NAME = "ai-hub-agent-trade";
-function validate(credentials) {
+function validateApiCredentials(credentials) {
   const apiKey = credentials.apiKey.trim();
   const secretKey = credentials.secretKey.trim();
   if (!apiKey || !secretKey) {
@@ -28,28 +46,11 @@ function validate(credentials) {
 function versionOf(credentials) {
   return createHash("sha256").update(`${credentials.apiKey}\0${credentials.secretKey}`).digest("hex");
 }
-var CredentialStore = class {
-  async set(profile, credentials) {
-    const value = validate(credentials);
-    await keytar.setPassword(SERVICE_NAME, profile, JSON.stringify(value));
-    return { credentialRef: `keychain:${SERVICE_NAME}/${profile}`, credentialVersion: versionOf(value) };
-  }
-  async get(profile) {
-    const stored = await keytar.getPassword(SERVICE_NAME, profile);
-    if (!stored) return void 0;
-    let parsed;
-    try {
-      parsed = JSON.parse(stored);
-    } catch {
-      throw new AiHubError("AI_HUB_CREDENTIAL_INVALID", "Stored credentials are unreadable. Set credentials again.");
-    }
-    const credentials = validate(parsed);
-    return { ...credentials, credentialVersion: versionOf(credentials) };
-  }
-  async remove(profile) {
-    return keytar.deletePassword(SERVICE_NAME, profile);
-  }
-};
+function loadStoredCredentials(apiKey, secretKey) {
+  if (apiKey === void 0 && secretKey === void 0) return void 0;
+  const credentials = validateApiCredentials({ apiKey: apiKey ?? "", secretKey: secretKey ?? "" });
+  return { ...credentials, credentialVersion: versionOf(credentials) };
+}
 
 // ../core/src/confirmation.ts
 import { createHash as createHash2, randomUUID } from "crypto";
@@ -109,6 +110,100 @@ var ConfirmationService = class {
 
 // ../core/src/openapi.ts
 import { createHmac } from "crypto";
+
+// ../core/src/openapi-error-catalog.ts
+var globalErrors = {
+  "-1002": { reason: "API_KEY_REQUIRED", suggestedAction: "Configure credentials for the selected profile, then retry the read request." },
+  "-1003": { reason: "RATE_LIMITED", suggestedAction: "Wait before retrying. Reduce request frequency and do not retry a write automatically.", retryable: true },
+  "-1006": { reason: "WRITE_STATUS_UNKNOWN", suggestedAction: "Do not retry automatically. Query the affected order or history record before taking another action.", writeOutcomeUnknown: true },
+  "-1007": { reason: "UPSTREAM_TIMEOUT", suggestedAction: "For a write, query the affected order or history record before retrying. A read can be retried after a short delay.", retryable: true, writeOutcomeUnknown: true },
+  "-1015": { reason: "TOO_MANY_ORDERS", suggestedAction: "Reduce the number of active or requested orders before retrying." },
+  "-1020": { reason: "UNSUPPORTED_OPERATION", suggestedAction: "Use a supported command and do not substitute another operation automatically." },
+  "-1021": { reason: "INVALID_TIMESTAMP", suggestedAction: "Synchronize the local system clock, then retry the request." },
+  "-1022": { reason: "INVALID_SIGNATURE", suggestedAction: "Verify the selected profile credentials and signing configuration, then retry." },
+  "-1023": { reason: "TIMESTAMP_REQUIRED", suggestedAction: "Use the AI Hub CLI or MCP client so the request timestamp is supplied automatically." },
+  "-1024": { reason: "SIGNATURE_REQUIRED", suggestedAction: "Use the AI Hub CLI or MCP client so the request is signed automatically." },
+  "-1100": { reason: "INVALID_REQUEST_CHARACTERS", suggestedAction: "Correct the invalid request value and retry." },
+  "-1102": { reason: "MISSING_OR_MALFORMED_PARAMETER", suggestedAction: "Provide every required parameter in the documented format." },
+  "-1103": { reason: "UNKNOWN_PARAMETER", suggestedAction: "Remove unsupported parameters and use the CLI command reference." },
+  "-1111": { reason: "INVALID_PRECISION", suggestedAction: "Use the symbol's allowed price and quantity precision." },
+  "-1121": { reason: "INVALID_SYMBOL", suggestedAction: "Query supported symbols and use an exact symbol value." },
+  "-1136": { reason: "ORDER_QUANTITY_TOO_SMALL", suggestedAction: "Increase the order quantity to the symbol minimum." },
+  "-1138": { reason: "ORDER_PRICE_OUT_OF_RANGE", suggestedAction: "Use a price inside the allowed range, then create a new preview." },
+  "-1139": { reason: "MARKET_ORDER_UNSUPPORTED", suggestedAction: "Use a supported order type for the selected symbol." },
+  "-1145": { reason: "ORDER_CANNOT_BE_CANCELLED", suggestedAction: "Query the latest order status before attempting another cancellation." },
+  "-2013": { reason: "ORDER_NOT_FOUND", suggestedAction: "Verify the symbol and order ID, then query open orders if needed." },
+  "-2014": { reason: "INVALID_API_KEY_FORMAT", suggestedAction: "Replace the configured API key with a valid value." },
+  "-2015": { reason: "API_KEY_REJECTED", suggestedAction: "Verify API key permissions, IP restrictions, and the selected tenant profile." },
+  "-2016": { reason: "TRADING_DISABLED", suggestedAction: "The account is restricted. Contact the platform administrator before trying again." },
+  "-2017": { reason: "INSUFFICIENT_BALANCE", suggestedAction: "Check the available balance and reduce the requested amount before creating a new preview." },
+  "-2018": { reason: "DUPLICATE_WITHDRAWAL_REQUEST", suggestedAction: "Use a new withdrawal order ID or query withdrawal history before retrying." },
+  "-2021": { reason: "IDENTITY_VERIFICATION_REQUIRED", suggestedAction: "Complete the account verification required by the tenant before retrying." },
+  "-2022": { reason: "LIMIT_ORDER_VOLUME_TOO_SMALL", suggestedAction: "Increase the limit-order volume to the returned minimum." },
+  "-2023": { reason: "MARKET_ORDER_VOLUME_TOO_SMALL", suggestedAction: "Increase the market-order sell volume to the returned minimum." },
+  "-2024": { reason: "LIMIT_ORDER_PRICE_TOO_SMALL", suggestedAction: "Increase the limit-order price to the returned minimum." },
+  "-2025": { reason: "MARKET_ORDER_AMOUNT_TOO_SMALL", suggestedAction: "Increase the market-order buy amount to the returned minimum." },
+  "-2026": { reason: "BUY_AMOUNT_TOO_LARGE", suggestedAction: "Reduce the buy amount before creating a new preview." },
+  "-2027": { reason: "SELL_AMOUNT_TOO_LARGE", suggestedAction: "Reduce the sell amount before creating a new preview." },
+  "-2029": { reason: "LIMIT_ORDER_NOTIONAL_TOO_SMALL", suggestedAction: "Increase the limit-order notional amount to the returned minimum." },
+  "-2030": { reason: "TRANSFER_NOT_FOUND", suggestedAction: "Verify the transfer ID, or query by the documented source and destination accounts." },
+  "-2031": { reason: "TRANSFER_TYPE_UNSUPPORTED", suggestedAction: "Use a supported source and destination account combination." },
+  "-2033": { reason: "ASSET_TRANSFER_FAILED", suggestedAction: "Query transfer history before attempting another transfer." },
+  "-2034": { reason: "SUB_ACCOUNT_RELATION_NOT_FOUND", suggestedAction: "Use a sub-account that belongs to the authenticated parent account." },
+  "-2035": { reason: "SUB_ACCOUNT_API_KEY_NOT_FOUND", suggestedAction: "Verify the sub-account API key identifier before retrying." },
+  "-2036": { reason: "SUB_ACCOUNT_PERMISSION_DENIED", suggestedAction: "Use a parent-account credential with the required sub-account permission." },
+  "-2037": { reason: "SUB_ACCOUNT_CREATION_FAILED", suggestedAction: "Check the sub-account limit and requested identifier before creating a new preview." },
+  "-2038": { reason: "SUB_ACCOUNT_UPDATE_FAILED", suggestedAction: "Query the latest sub-account state before retrying the update." },
+  "-2040": { reason: "SUB_ACCOUNT_CREDENTIAL_REQUIRED", suggestedAction: "Use the sub-account credential required by this endpoint." },
+  "10001": { reason: "USER_ACCOUNT_LOCKED", suggestedAction: "The account is restricted. Contact the platform administrator." },
+  "10004": { reason: "USER_NOT_AUTHENTICATED", suggestedAction: "Configure valid credentials for the selected profile." },
+  "10005": { reason: "PERMISSION_DENIED", suggestedAction: "Verify the API key permissions and the tenant feature permission." },
+  "10006": { reason: "TENANT_PERMISSION_DENIED", suggestedAction: "Ask the tenant administrator to enable this capability." },
+  "21018": { reason: "SUB_ACCOUNT_NOT_FOUND", suggestedAction: "List sub-accounts and use an existing sub-account ID." },
+  "21019": { reason: "COIN_NOT_FOUND", suggestedAction: "Query supported coins and use an exact coin symbol." },
+  "21020": { reason: "SYMBOL_NOT_FOUND", suggestedAction: "Query supported symbols and use an exact symbol value." },
+  "21022": { reason: "ORDER_NOT_FOUND", suggestedAction: "Verify the order identifier and symbol, then query current orders if needed." },
+  "21024": { reason: "SUB_ACCOUNT_FEATURE_PERMISSION_DENIED", suggestedAction: "Enable the required sub-account feature permission before retrying." },
+  "21025": { reason: "SUB_ACCOUNT_LIMIT_REACHED", suggestedAction: "The parent account has reached its sub-account limit." }
+};
+var endpointErrors = {
+  "/sapi/v1/withdraw/query:10005": { reason: "WITHDRAW_HISTORY_PERMISSION_DENIED", suggestedAction: "Enable the withdrawal-history permission for this API key, then retry." },
+  "/sapi/v1/withdraw/query:-2015": { reason: "WITHDRAW_HISTORY_TRUSTED_IP_REQUIRED", suggestedAction: "Add a trusted IP to the API key before querying withdrawal history." },
+  "/sapi/v1/withdraw/query:-1004": { reason: "WITHDRAW_HISTORY_PARENT_ACCOUNT_REQUIRED", suggestedAction: "Use a parent-account credential for withdrawal history." },
+  "/sapi/v1/sub_user/asset/root_transfer_query:-2036": { reason: "ROOT_SUB_TRANSFER_PARENT_PERMISSION_REQUIRED", suggestedAction: "Use a parent-account credential that can access the requested sub-account." },
+  "/sapi/v1/sub_user/asset/transfer_query:-2034": { reason: "SUB_ACCOUNT_INTERNAL_TRANSFER_RELATION_NOT_FOUND", suggestedAction: "Use a sub-account that belongs to the authenticated parent account." },
+  "/sapi/v1/asset/subaccount/transfer_query:-2040": { reason: "PARENT_TRANSFER_SUB_ACCOUNT_REQUIRED", suggestedAction: "Run this query with the relevant sub-account credential." }
+};
+function normalizeCode(value) {
+  return String(value).trim();
+}
+function diagnoseOpenApiBusinessError(path2, upstreamCode, upstreamMessage) {
+  const code = normalizeCode(upstreamCode);
+  const definition = endpointErrors[`${path2}:${code}`] ?? globalErrors[code];
+  if (!definition) {
+    return {
+      upstreamCode: code,
+      upstreamMessage,
+      reason: "UNKNOWN_UPSTREAM_CODE",
+      suggestedAction: "Review the upstream message and endpoint. Do not retry a state-changing request automatically.",
+      retryable: false,
+      writeOutcomeUnknown: false
+    };
+  }
+  return {
+    upstreamCode: code,
+    upstreamMessage,
+    reason: definition.reason,
+    suggestedAction: definition.suggestedAction,
+    retryable: definition.retryable ?? false,
+    writeOutcomeUnknown: definition.writeOutcomeUnknown ?? false
+  };
+}
+function isOpenApiSuccessCode(value) {
+  return value === 0 || value === "0";
+}
+
+// ../core/src/openapi.ts
 function parseJsonPreservingLargeIntegers(raw) {
   let transformed = "";
   let inString = false;
@@ -155,13 +250,13 @@ function queryString(values) {
   }
   return params.toString();
 }
-function joinUrl(baseUrl, path, query) {
-  if (!path.startsWith("/")) throw new AiHubError("AI_HUB_INVALID_PATH", "OpenAPI paths must start with '/'.");
-  const url = `${baseUrl.replace(/\/+$/, "")}${path}`;
+function joinUrl(baseUrl, path2, query) {
+  if (!path2.startsWith("/")) throw new AiHubError("AI_HUB_INVALID_PATH", "OpenAPI paths must start with '/'.");
+  const url = `${baseUrl.replace(/\/+$/, "")}${path2}`;
   return query ? `${url}?${query}` : url;
 }
-function signRequest(timestamp, method, path, secretKey, query, body) {
-  const payload = `${timestamp}${method.toUpperCase()}${path}${query ? `?${query}` : ""}${body ?? ""}`;
+function signRequest(timestamp, method, path2, secretKey, query, body) {
+  const payload = `${timestamp}${method.toUpperCase()}${path2}${query ? `?${query}` : ""}${body ?? ""}`;
   return createHmac("sha256", secretKey).update(payload).digest("hex");
 }
 var AiHubSpotApi = class {
@@ -236,13 +331,13 @@ var AiHubSpotApi = class {
    * defined by the API document. Keep endpoint selection in the individual Tool
    * definition; never expose this method directly through CLI or MCP.
    */
-  signedGet(path, query, credentials) {
-    return this.request("GET", path, query, void 0, credentials);
+  signedGet(path2, query, credentials) {
+    return this.request("GET", path2, query, void 0, credentials);
   }
-  signedPost(path, body, credentials) {
-    return this.request("POST", path, {}, body, credentials);
+  signedPost(path2, body, credentials) {
+    return this.request("POST", path2, {}, body, credentials);
   }
-  async request(method, path, query = {}, body, credentials) {
+  async request(method, path2, query = {}, body, credentials) {
     const encodedQuery = queryString(query);
     const bodyString = body ? JSON.stringify(body) : void 0;
     const headers = {
@@ -255,11 +350,11 @@ var AiHubSpotApi = class {
       const timestamp = Date.now().toString();
       headers["X-CH-APIKEY"] = credentials.apiKey;
       headers["X-CH-TS"] = timestamp;
-      headers["X-CH-SIGN"] = signRequest(timestamp, method, path, credentials.secretKey, encodedQuery || void 0, bodyString);
+      headers["X-CH-SIGN"] = signRequest(timestamp, method, path2, credentials.secretKey, encodedQuery || void 0, bodyString);
     }
     let response;
     try {
-      response = await fetch(joinUrl(this.baseUrl, path, encodedQuery), {
+      response = await fetch(joinUrl(this.baseUrl, path2, encodedQuery), {
         method,
         headers,
         body: bodyString,
@@ -277,8 +372,18 @@ var AiHubSpotApi = class {
       throw new AiHubError("AI_HUB_OPENAPI_HTTP_ERROR", `OpenAPI returned HTTP ${response.status}.`);
     }
     try {
-      return parseJsonPreservingLargeIntegers(raw);
-    } catch {
+      const parsed = parseJsonPreservingLargeIntegers(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        const payload = parsed;
+        if (Object.hasOwn(payload, "code") && !isOpenApiSuccessCode(payload.code)) {
+          const upstreamCode = typeof payload.code === "string" || typeof payload.code === "number" ? payload.code : String(payload.code);
+          const upstreamMessage = typeof payload.msg === "string" ? payload.msg : "OpenAPI returned a business failure without a message.";
+          throw new OpenApiBusinessError(diagnoseOpenApiBusinessError(path2, upstreamCode, upstreamMessage));
+        }
+      }
+      return parsed;
+    } catch (error) {
+      if (error instanceof OpenApiBusinessError) throw error;
       throw new AiHubError("AI_HUB_OPENAPI_INVALID_RESPONSE", "OpenAPI returned a non-JSON response.");
     }
   }
@@ -377,7 +482,11 @@ var ConfigStore = class {
     const config = await this.read();
     const normalizedUrl = await normalizeOpenApiBaseUrl(openApiBaseUrl);
     const existing = config.profiles[name];
-    config.profiles[name] = { openapi_base_url: normalizedUrl, ...existing?.credential_ref ? { credential_ref: existing.credential_ref } : {} };
+    config.profiles[name] = {
+      openapi_base_url: normalizedUrl,
+      ...existing?.api_key ? { api_key: existing.api_key } : {},
+      ...existing?.secret_key ? { secret_key: existing.secret_key } : {}
+    };
     if (Object.keys(config.profiles).length === 1) config.default_profile = name;
     await this.write(config);
     return this.resolveFrom(config, name);
@@ -386,6 +495,12 @@ var ConfigStore = class {
     const config = await this.read();
     return this.resolveFrom(config, requestedName ?? config.default_profile);
   }
+  async getCredentials(requestedName) {
+    const config = await this.read();
+    const name = requestedName ?? config.default_profile;
+    const profile = this.profileFrom(config, name);
+    return loadStoredCredentials(profile.api_key, profile.secret_key);
+  }
   async removeProfile(name) {
     validateProfileName(name);
     const config = await this.read();
@@ -394,26 +509,31 @@ var ConfigStore = class {
     if (config.default_profile === name) config.default_profile = Object.keys(config.profiles)[0] ?? "default";
     await this.write(config);
   }
-  async setCredentialRef(name, credentialRef) {
+  async setCredentials(name, credentials) {
     validateProfileName(name);
     const config = await this.read();
     const profile = config.profiles[name];
     if (!profile) throw new AiHubError("AI_HUB_PROFILE_NOT_FOUND", `Profile "${name}" does not exist.`);
-    config.profiles[name] = { ...profile, credential_ref: credentialRef };
+    const value = validateApiCredentials(credentials);
+    config.profiles[name] = { openapi_base_url: profile.openapi_base_url, api_key: value.apiKey, secret_key: value.secretKey };
     await this.write(config);
     return this.resolveFrom(config, name);
   }
   resolveFrom(config, name) {
     validateProfileName(name);
-    const profile = config.profiles[name];
-    if (!profile) throw new AiHubError("AI_HUB_PROFILE_NOT_FOUND", `Profile "${name}" does not exist.`);
+    const profile = this.profileFrom(config, name);
     return {
       name,
       openApiBaseUrl: profile.openapi_base_url,
-      credentialRef: profile.credential_ref,
       configVersion: versionOf2(config, name)
     };
   }
+  profileFrom(config, name) {
+    validateProfileName(name);
+    const profile = config.profiles[name];
+    if (!profile) throw new AiHubError("AI_HUB_PROFILE_NOT_FOUND", `Profile "${name}" does not exist.`);
+    return profile;
+  }
   async write(config) {
     const directory = dirname(this.filePath);
     await mkdir(directory, { recursive: true, mode: 448 });
@@ -428,8 +548,9 @@ var ConfigStore = class {
 
 // ../core/src/tools/execution-context.ts
 async function createToolExecutionContext(profileName) {
-  const profile = await new ConfigStore().showProfile(profileName);
-  const credentials = await new CredentialStore().get(profile.name);
+  const store = new ConfigStore();
+  const profile = await store.showProfile(profileName);
+  const credentials = await store.getCredentials(profile.name);
   return { profile, credentials, api: new AiHubSpotApi(profile.openApiBaseUrl) };
 }
 function confirmationContext(context) {
@@ -485,7 +606,7 @@ var accountTools = [
     operation: "read",
     riskLevel: "low",
     inputSchema: { type: "object", additionalProperties: false },
-    errorCodes: ["AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"],
+    errorCodes: ["AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"],
     validate: (input) => strictObject(input, []),
     handler: async (_input, context) => {
       if (!context.credentials) throw new AiHubError("AI_HUB_CREDENTIAL_NOT_CONFIGURED", `Credentials are not configured for profile "${context.profile.name}".`);
@@ -496,7 +617,7 @@ var accountTools = [
 
 // ../core/src/tools/tool-utils.ts
 import { randomUUID as randomUUID2 } from "crypto";
-var signedReadErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"];
+var signedReadErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
 var writeErrors = [...signedReadErrors, "AI_HUB_WRITE_CONFIRMATION_REQUIRED", "AI_HUB_CONFIRMATION_REQUIRED", "AI_HUB_CONFIRMATION_EXPIRED", "AI_HUB_CONFIRMATION_CONTEXT_CHANGED", "AI_HUB_CONFIRMATION_NOT_FOUND"];
 function signed(context) {
   if (!context.credentials) throw new AiHubError("AI_HUB_CREDENTIAL_NOT_CONFIGURED", `Credentials are not configured for profile "${context.profile.name}".`);
@@ -744,7 +865,7 @@ var assetTools = [
 ];
 
 // ../core/src/tools/market-tools.ts
-var readErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"];
+var readErrors = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
 var marketTools = [
   {
     name: "market_ping",
@@ -756,7 +877,7 @@ var marketTools = [
     operation: "read",
     riskLevel: "low",
     inputSchema: { type: "object", additionalProperties: false },
-    errorCodes: ["AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"],
+    errorCodes: ["AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"],
     validate: (input) => {
       strictObject(input, []);
       return {};
@@ -973,7 +1094,7 @@ var marginTools = [
 
 // ../core/src/tools/order-tools.ts
 import { randomUUID as randomUUID3 } from "crypto";
-var signedReadErrors2 = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE"];
+var signedReadErrors2 = ["AI_HUB_INVALID_ARGUMENT", "AI_HUB_CREDENTIAL_NOT_CONFIGURED", "AI_HUB_OPENAPI_NETWORK_ERROR", "AI_HUB_OPENAPI_HTTP_ERROR", "AI_HUB_OPENAPI_INVALID_RESPONSE", "AI_HUB_OPENAPI_BUSINESS_ERROR"];
 var writeErrors2 = [...signedReadErrors2, "AI_HUB_WRITE_CONFIRMATION_REQUIRED", "AI_HUB_CONFIRMATION_REQUIRED", "AI_HUB_CONFIRMATION_EXPIRED", "AI_HUB_CONFIRMATION_CONTEXT_CHANGED", "AI_HUB_CONFIRMATION_NOT_FOUND"];
 var decimal = /^(?:0|[1-9]\d*)(?:\.\d+)?$/;
 function positiveDecimal2(value, name) {
@@ -1446,12 +1567,12 @@ var ToolRegistry = class {
   toolsByCliPath = /* @__PURE__ */ new Map();
   constructor(tools = allTools) {
     for (const tool of tools) {
-      const path = tool.cliPath.join(" ");
-      if (this.toolsByName.has(tool.name) || this.toolsByCliPath.has(path)) {
+      const path2 = tool.cliPath.join(" ");
+      if (this.toolsByName.has(tool.name) || this.toolsByCliPath.has(path2)) {
         throw new AiHubError("AI_HUB_TOOL_DUPLICATE", `Duplicate tool registration: ${tool.name}.`);
       }
       this.toolsByName.set(tool.name, tool);
-      this.toolsByCliPath.set(path, tool);
+      this.toolsByCliPath.set(path2, tool);
     }
   }
   list(options = {}) {
@@ -1464,10 +1585,10 @@ var ToolRegistry = class {
     }
     return tool;
   }
-  byCliPath(path, options = {}) {
-    const tool = this.toolsByCliPath.get(path.join(" "));
+  byCliPath(path2, options = {}) {
+    const tool = this.toolsByCliPath.get(path2.join(" "));
     if (!tool || options.readOnly && tool.operation !== "read") {
-      throw new AiHubError("AI_HUB_TOOL_NOT_AVAILABLE", `Command "${path.join(" ")}" is not available.`);
+      throw new AiHubError("AI_HUB_TOOL_NOT_AVAILABLE", `Command "${path2.join(" ")}" is not available.`);
     }
     return tool;
   }
@@ -1532,6 +1653,176 @@ var ToolWriteExecutor = class {
   }
 };
 
+// ../core/src/setup.ts
+import { execFileSync } from "child_process";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+var MCP_BINARY = "ai-hub-trade-mcp";
+var MCP_CLIENT_NAMES = {
+  cursor: "Cursor",
+  "claude-desktop": "Claude Desktop",
+  "claude-code": "Claude Code",
+  codex: "Codex"
+};
+var SUPPORTED_MCP_CLIENTS = Object.keys(MCP_CLIENT_NAMES);
+function runtime() {
+  const home = os.homedir();
+  return {
+    home,
+    platform: process.platform,
+    cwd: process.cwd(),
+    appData: process.env.APPDATA,
+    localAppData: process.env.LOCALAPPDATA,
+    xdgConfigHome: process.env.XDG_CONFIG_HOME
+  };
+}
+function windowsAppData(value, home) {
+  return value ?? path.join(home, "AppData", "Roaming");
+}
+function findMicrosoftStoreClaudePath(value, home) {
+  const packagesDirectory = path.join(value ?? path.join(home, "AppData", "Local"), "Packages");
+  try {
+    const packageName = fs.readdirSync(packagesDirectory).find((entry) => entry.startsWith("Claude_"));
+    if (!packageName) return void 0;
+    const configPath = path.join(
+      packagesDirectory,
+      packageName,
+      "LocalCache",
+      "Roaming",
+      "Claude",
+      "claude_desktop_config.json"
+    );
+    return fs.existsSync(configPath) || fs.existsSync(path.dirname(configPath)) ? configPath : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function getMcpClientConfigPath(client, value = runtime()) {
+  if (client === "cursor") return path.join(value.home, ".cursor", "mcp.json");
+  if (value.platform === "win32") {
+    return findMicrosoftStoreClaudePath(value.localAppData, value.home) ?? path.join(windowsAppData(value.appData, value.home), "Claude", "claude_desktop_config.json");
+  }
+  if (value.platform === "darwin") {
+    return path.join(value.home, "Library", "Application Support", "Claude", "claude_desktop_config.json");
+  }
+  return path.join(value.xdgConfigHome ?? path.join(value.home, ".config"), "Claude", "claude_desktop_config.json");
+}
+function buildServerSpec(profile, launch) {
+  return {
+    name: serverName(profile),
+    command: launch.command,
+    args: [...launch.args, ...profile ? ["--profile", profile] : []]
+  };
+}
+function serverName(profile) {
+  return profile ? `${MCP_BINARY}-${profile}` : MCP_BINARY;
+}
+function isRecord(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function mergeJsonMcpConfig(configPath, server) {
+  const directory = path.dirname(configPath);
+  fs.mkdirSync(directory, { recursive: true });
+  const configExists = fs.existsSync(configPath);
+  let config = {};
+  if (configExists) {
+    const raw = fs.readFileSync(configPath, "utf8");
+    try {
+      const parsed = JSON.parse(raw);
+      if (!isRecord(parsed)) throw new Error("root must be a JSON object");
+      config = parsed;
+    } catch {
+      throw new Error(`Failed to parse existing MCP configuration at ${configPath}. No changes were made.`);
+    }
+  }
+  if (config.mcpServers === void 0) {
+    config.mcpServers = {};
+  }
+  if (!isRecord(config.mcpServers)) {
+    throw new Error(`Existing MCP configuration at ${configPath} has an invalid mcpServers object. No changes were made.`);
+  }
+  if (configExists) {
+    const backupPath = `${configPath}.bak`;
+    if (!fs.existsSync(backupPath)) {
+      fs.copyFileSync(configPath, backupPath);
+      process.stdout.write(`Backup created: ${backupPath}
+`);
+    }
+  }
+  config.mcpServers[server.name] = { command: server.command, args: server.args };
+  const mode = configExists ? fs.statSync(configPath).mode & 511 : 384;
+  const temporaryPath = `${configPath}.${process.pid}.tmp`;
+  fs.writeFileSync(temporaryPath, `${JSON.stringify(config, null, 2)}
+`, { encoding: "utf8", mode });
+  fs.chmodSync(temporaryPath, mode);
+  fs.renameSync(temporaryPath, configPath);
+}
+function executeClientRegistration(command, args, value) {
+  process.stdout.write(`Running: ${command} ${args.join(" ")}
+`);
+  if (value.executeClientCommand) {
+    value.executeClientCommand(command, args);
+    return;
+  }
+  execFileSync(command, args, { stdio: "inherit" });
+}
+function jsonFileAdapter(id) {
+  return {
+    id,
+    name: MCP_CLIENT_NAMES[id],
+    install(server, value) {
+      mergeJsonMcpConfig(getMcpClientConfigPath(id, value), server);
+      process.stdout.write(`Configured ${this.name}: ${getMcpClientConfigPath(id, value)}
+Restart ${this.name} to apply changes.
+`);
+    }
+  };
+}
+function cliAdapter(id) {
+  const command = id === "claude-code" ? "claude" : "codex";
+  return {
+    id,
+    name: MCP_CLIENT_NAMES[id],
+    install(server, value) {
+      const args = [
+        "mcp",
+        "add",
+        ...id === "claude-code" ? ["--scope", "user", "--transport", "stdio"] : [],
+        server.name,
+        "--",
+        server.command,
+        ...server.args
+      ];
+      executeClientRegistration(command, args, value);
+      process.stdout.write(`Configured ${this.name} with local stdio MCP server "${server.name}".
+`);
+    }
+  };
+}
+var MCP_CLIENT_ADAPTERS = {
+  cursor: jsonFileAdapter("cursor"),
+  "claude-desktop": jsonFileAdapter("claude-desktop"),
+  "claude-code": cliAdapter("claude-code"),
+  codex: cliAdapter("codex")
+};
+function runMcpSetup(options, value = runtime()) {
+  const adapter = MCP_CLIENT_ADAPTERS[options.client];
+  if (!adapter) {
+    throw new Error(`Unknown MCP client "${options.client}". Supported clients: ${SUPPORTED_MCP_CLIENTS.join(", ")}.`);
+  }
+  const profile = options.profile ? validateProfileName(options.profile) : void 0;
+  adapter.install(buildServerSpec(profile, options.launch), value);
+}
+function printMcpSetupUsage() {
+  process.stdout.write(
+    `Usage: ${MCP_BINARY} setup --client <client> [--profile <name>]
+
+Supported clients:
+` + SUPPORTED_MCP_CLIENTS.map((client) => `  ${client.padEnd(16)} ${MCP_CLIENT_NAMES[client]}`).join("\n") + "\n"
+  );
+}
+
 // src/server.ts
 import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { CallToolRequestSchema, ListToolsRequestSchema } from "@modelcontextprotocol/sdk/types.js";
@@ -1540,8 +1831,8 @@ var CONFIRM_ACTION_TOOL = "confirm_action";
 function result(data) {
   return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
 }
-function errorResult(error) {
-  const payload = error instanceof AiHubError ? { code: error.code, message: error.message } : { code: "AI_HUB_UNEXPECTED_ERROR", message: error instanceof Error ? error.message : "Unexpected error" };
+function toMcpErrorResult(error) {
+  const payload = toAiHubErrorPayload(error);
   return { isError: true, content: [{ type: "text", text: JSON.stringify({ ok: false, ...payload }) }] };
 }
 function toMcpTool(tool) {
@@ -1627,7 +1918,7 @@ function createServer(profileName, readOnly) {
       const data = await registry.execute(request.params.name, request.params.arguments ?? {}, context, { readOnly });
       return result({ ok: true, data });
     } catch (error) {
-      return errorResult(error);
+      return toMcpErrorResult(error);
     }
   });
   return server;
@@ -1642,6 +1933,21 @@ function readOption(args, option) {
   return value;
 }
 async function main(argv) {
+  if (argv[0] === "setup") {
+    const client = readOption(argv.slice(1), "--client");
+    const profile = readOption(argv.slice(1), "--profile");
+    if (!client) {
+      printMcpSetupUsage();
+      return;
+    }
+    if (!SUPPORTED_MCP_CLIENTS.includes(client)) {
+      throw new AiHubError("AI_HUB_INVALID_ARGUMENT", `Unknown MCP client "${client}". Supported clients: ${SUPPORTED_MCP_CLIENTS.join(", ")}.`);
+    }
+    const entrypoint = process.argv[1];
+    if (!entrypoint) throw new AiHubError("AI_HUB_UNEXPECTED_ERROR", "Cannot locate the local MCP server entrypoint for client setup.");
+    runMcpSetup({ client, profile, launch: { command: process.execPath, args: [entrypoint] } });
+    return;
+  }
   const profileName = readOption(argv, "--profile");
   const readOnly = argv.includes("--read-only");
   const server = createServer(profileName, readOnly);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aihubspot/agent-trade-mcp",
-  "version": "0.1.0",
+  "version": "0.1.1",
   "description": "Local stdio MCP server for AI Hub spot trading tools",
   "license": "UNLICENSED",
   "type": "module",
@@ -14,12 +14,11 @@
   "scripts": {
     "build": "tsup",
     "typecheck": "tsc --noEmit",
-    "test": "tsx --test test/*.test.ts",
+    "test": "TSX_TSCONFIG_PATH=./test/tsconfig.json tsx --test test/*.test.ts",
     "clean": "rm -rf dist"
   },
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.26.0",
-    "keytar": "^7.9.0",
     "smol-toml": "^1.3.4"
   }
 }