@elfa-ai/mcp 1.0.0 → 1.0.2

package/CHANGELOG.md

@@ -1,6 +1,15 @@
 # Changelog
 
-## 1.0.0
+## 1.0.2
+
+Fixes found by running every tool against a live API.
+
+- `elfa_status` returned the raw key-status payload, which includes the API key itself, the account email and internal identifiers. It now reports only tier, limits, usage, scopes and expiry, and surfaces the reason when the key lookup fails
+- Default timeout raised to 120s. The LLM-backed endpoints regularly take longer than 30s, so they timed out before returning
+- Retries now default to 0. A timed-out request to a credit-charging endpoint was retried three times and billed each time, so a failed call could cost four times its price
+- `elfa_narratives` reports how many mentions matched, and says so when the summariser returns nothing, instead of an unexplained empty list
+
+## 1.0.1
 
 First release of the TypeScript server, published as `@elfa-ai/mcp`.
 

package/README.md

@@ -40,9 +40,14 @@ Ask *"what's trending in crypto right now?"* to confirm it works.
 | --- | --- | --- |
 | `ELFA_API_KEY` | yes | Authenticates every request |
 | `ELFA_HMAC_SECRET` | no | Signs Auto requests. Needed only to connect an exchange, or to run a query whose action places an order |
-| `ELFA_TIMEOUT` | no | Request timeout in ms, default `30000` |
+| `ELFA_TIMEOUT` | no | Request timeout in ms, default `120000` |
+| `ELFA_RETRIES` | no | Retries on failure, default `0` |
 | `ELFA_MCP_MAX_RESPONSE_CHARS` | no | Response size ceiling, default `60000` |
 
+The timeout is high and retries are off on purpose. The interpretation endpoints are LLM-backed and can take over a minute, and they cost credits per attempt, so a silent retry would bill you again for a call you never saw. Raise `ELFA_RETRIES` only if you are calling the cheap measurement endpoints.
+
+Some MCP clients apply their own timeout, often around 60 seconds. `elfa_narratives` and `elfa_chat` can exceed that; the request still completes and is still charged, even if the client gives up first.
+
 Without `ELFA_HMAC_SECRET` everything still works except exchange linking and order-placing queries — those return a message telling you what to set.
 
 ## Tools

package/dist/index.js

@@ -67,6 +67,7 @@ function buildDeps(config, overrides = {}) {
   const sdk = new ElfaSDK({
     elfaApiKey: apiKey,
     timeout: config.timeout,
+    retries: config.retries,
     ...hmacSecret ? { hmacSecret } : {},
     ...config.baseUrl ? { baseUrl: config.baseUrl } : {}
   });
@@ -80,13 +81,19 @@ function buildDeps(config, overrides = {}) {
 // src/config.ts
 var DEFAULT_PORT = 3e3;
 var DEFAULT_HOST = "127.0.0.1";
-var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_TIMEOUT = 12e4;
+var DEFAULT_RETRIES = 0;
 var DEFAULT_MAX_RESPONSE_CHARS = 6e4;
 function num(value, fallback) {
   if (!value) return fallback;
   const parsed = Number(value);
   return Number.isFinite(parsed) && parsed > 0 ? parsed : fallback;
 }
+function count(value, fallback) {
+  if (!value) return fallback;
+  const parsed = Number(value);
+  return Number.isInteger(parsed) && parsed >= 0 ? parsed : fallback;
+}
 function list(value) {
   if (!value) return [];
   return value.split(",").map((entry) => entry.trim()).filter(Boolean);
@@ -102,6 +109,7 @@ function loadConfig(env = process.env) {
     hmacSecret: env.ELFA_HMAC_SECRET || void 0,
     baseUrl: env.ELFA_BASE_URL || void 0,
     timeout: num(env.ELFA_TIMEOUT, DEFAULT_TIMEOUT),
+    retries: count(env.ELFA_RETRIES, DEFAULT_RETRIES),
     maxResponseChars: num(
       env.ELFA_MCP_MAX_RESPONSE_CHARS,
       DEFAULT_MAX_RESPONSE_CHARS
@@ -119,7 +127,7 @@ import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 // package.json
 var package_default = {
   name: "@elfa-ai/mcp",
-  version: "1.0.0",
+  version: "1.0.2",
   description: "Model Context Protocol server for the Elfa API - crypto social intelligence and the Auto condition engine",
   license: "MIT",
   author: "Elfa Team",
@@ -1043,7 +1051,7 @@ function registerNarratives(server, deps) {
     "elfa_narratives",
     {
       title: "Narratives",
-      description: "Written narrative analysis with source links, for when counts are not enough. 5 credits per call, so prefer elfa_trending or elfa_mentions when metrics will do. scope=market extracts the narratives moving the market. scope=keywords summarises events for keywords you supply.",
+      description: "Written narrative analysis with source links, for when counts are not enough. 5 credits per call, so prefer elfa_trending or elfa_mentions when metrics will do. scope=market extracts the narratives moving the market. scope=keywords summarises events for keywords you supply, and can take over a minute to return.",
       inputSchema: {
         scope: z11.enum(["market", "keywords"]).default("market").describe("market is a broad sweep. keywords needs the keywords argument."),
         keywords: z11.string().optional().describe("Up to 5 comma separated keywords for scope=keywords."),
@@ -1058,7 +1066,9 @@ function registerNarratives(server, deps) {
       outputSchema: {
         scope: z11.string(),
         notice: z11.string(),
-        items: z11.array(z11.record(z11.unknown()))
+        items: z11.array(z11.record(z11.unknown())),
+        matched: z11.number().nullable(),
+        note: z11.string().nullable()
       },
       annotations: {
         readOnlyHint: true,
@@ -1090,15 +1100,19 @@ function registerNarratives(server, deps) {
               searchType: args.searchType
             })
           );
+          const items2 = asArray(
+            response2.data
+          ).map((entry) => ({
+            summary: entry.summary,
+            sources: asArray(entry.sourceLinks)
+          }));
+          const matched = response2.metadata?.total ?? null;
           return {
             scope: args.scope,
             notice: UNTRUSTED_NOTICE,
-            items: asArray(
-              response2.data
-            ).map((entry) => ({
-              summary: entry.summary,
-              sources: asArray(entry.sourceLinks)
-            }))
+            items: items2,
+            matched,
+            note: items2.length === 0 && matched ? `Matched ${matched} mentions but produced no summary. Try a narrower keyword set or a different time window.` : null
           };
         }
         const response = await deps.sdk.getTrendingNarratives(
@@ -1108,15 +1122,18 @@ function registerNarratives(server, deps) {
             maxTweetsPerNarrative: args.maxTweetsPerNarrative
           })
         );
+        const items = asArray(
+          response.data?.trending_narratives
+        ).map((entry) => ({
+          narrative: entry.narrative,
+          sources: asArray(entry.source_links)
+        }));
         return {
           scope: args.scope,
           notice: UNTRUSTED_NOTICE,
-          items: asArray(
-            response.data?.trending_narratives
-          ).map((entry) => ({
-            narrative: entry.narrative,
-            sources: asArray(entry.source_links)
-          }))
+          items,
+          matched: response.data?.metadata?.total_tweets ?? null,
+          note: items.length === 0 ? "No narratives were produced for this window. Try timeFrame=week." : null
         };
       });
     }
@@ -1125,6 +1142,33 @@ function registerNarratives(server, deps) {
 
 // src/tools/status.ts
 import { z as z12 } from "zod";
+var REPORTED = [
+  "tier",
+  "status",
+  "isExpired",
+  "expiresAt",
+  "billingMode",
+  "usage",
+  "limits",
+  "remainingRequests",
+  "dailyRequestLimit",
+  "monthlyRequestLimit",
+  "requestsPerMinute",
+  "allowOverage",
+  "bonusCredits",
+  "depositCredits",
+  "spendCapCredits",
+  "athenaEnabled",
+  "hmacEnabled",
+  "scopes"
+];
+function summarise(data) {
+  const out = {};
+  for (const field of REPORTED) {
+    if (data[field] !== void 0) out[field] = data[field];
+  }
+  return out;
+}
 function registerStatus(server, deps) {
   server.registerTool(
     "elfa_status",
@@ -1134,7 +1178,8 @@ function registerStatus(server, deps) {
       inputSchema: {},
       outputSchema: {
         reachable: z12.boolean(),
-        key: z12.record(z12.unknown()).nullable()
+        key: z12.record(z12.unknown()).nullable(),
+        problem: z12.string().nullable()
       },
       annotations: {
         readOnlyHint: true,
@@ -1150,7 +1195,8 @@ function registerStatus(server, deps) {
       ]);
       return {
         reachable: ping.status === "fulfilled",
-        key: status.status === "fulfilled" ? status.value.data : null
+        key: status.status === "fulfilled" ? summarise(status.value.data) : null,
+        problem: status.status === "rejected" ? describeError(status.reason) : null
       };
     })
   );

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "server": {
     "name": "elfa",
-    "version": "1.0.0",
+    "version": "1.0.2",
     "docs": "https://docs.elfa.ai",
     "spec": "https://docs.elfa.ai/swagger/swagger.json",
     "specScope": "/v2"
@@ -18,7 +18,10 @@
         "idempotentHint": true,
         "openWorldHint": false
       },
-      "operations": ["ping-v2", "getApiKeyStatus-v2"]
+      "operations": [
+        "ping-v2",
+        "getApiKeyStatus-v2"
+      ]
     },
     {
       "name": "elfa_mentions",
@@ -65,7 +68,10 @@
         "idempotentHint": true,
         "openWorldHint": false
       },
-      "operations": ["getTrendingNarratives-v2", "getEventSummary-v2"]
+      "operations": [
+        "getTrendingNarratives-v2",
+        "getEventSummary-v2"
+      ]
     },
     {
       "name": "elfa_account_stats",
@@ -78,7 +84,9 @@
         "idempotentHint": true,
         "openWorldHint": false
       },
-      "operations": ["getAccountSmartStats-v2"]
+      "operations": [
+        "getAccountSmartStats-v2"
+      ]
     },
     {
       "name": "elfa_chat",
@@ -91,7 +99,9 @@
         "idempotentHint": false,
         "openWorldHint": false
       },
-      "operations": ["chat-v2"]
+      "operations": [
+        "chat-v2"
+      ]
     },
     {
       "name": "elfa_auto_build",
@@ -104,7 +114,9 @@
         "idempotentHint": false,
         "openWorldHint": false
       },
-      "operations": ["auto-chat-v2"]
+      "operations": [
+        "auto-chat-v2"
+      ]
     },
     {
       "name": "elfa_auto_validate",
@@ -117,7 +129,10 @@
         "idempotentHint": true,
         "openWorldHint": false
       },
-      "operations": ["auto-validate-query-v2", "auto-validate-query-draft-v2"]
+      "operations": [
+        "auto-validate-query-v2",
+        "auto-validate-query-draft-v2"
+      ]
     },
     {
       "name": "elfa_auto_query",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@elfa-ai/mcp",
-  "version": "1.0.0",
+  "version": "1.0.2",
   "description": "Model Context Protocol server for the Elfa API - crypto social intelligence and the Auto condition engine",
   "license": "MIT",
   "author": "Elfa Team",