@elfa-ai/mcp 4.3.0 → 4.5.0

package/CHANGELOG.md

@@ -1,5 +1,18 @@
 # Changelog
 
+## 4.5.0
+
+### Added
+
+- **`market_chat` returns its sources.** The reply now includes `sources`: the links the research behind the answer read (X posts, news, DEX and explorer pages, prediction markets), in the order it read them, each with a `url`, a `kind` and an optional `title` such as "Searched X". Links only, never the page or post text. A source was read, not necessarily cited in `message`, and the list is empty when the answer used no linkable source. The tool asks for them with `includeSources: true` on `POST /v2/chat` (API 2.8.1); it costs nothing extra. `kind` is a plain string, so treat a value you don't recognise as `web`.
+
+## 4.4.0
+
+### Added
+
+- **Upstream requests carry an `elfa-mcp` User-Agent.** Every upstream call now carries `User-Agent: elfa-mcp/<version> (<transport>)`, where the transport is `stdio` or `http`, instead of the SDK's generic `@elfa-ai/sdk/<version>`. When the server knows which app is connected, it adds that too: on HTTP, the client's own `User-Agent`; on stdio, the `clientInfo` name and version from the MCP handshake, e.g. `elfa-mcp/4.4.0 (stdio; client=claude-ai/0.1.0)`. The client part is cut to printable ASCII and 100 characters, with `(`, `)`, `;` and `\` turned into spaces so the comment stays parseable. A `User-Agent` set in `ELFA_EXTRA_HEADERS`, in any casing, still wins.
+- **The HTTP server logs each handshake.** One JSON line per successful `initialize` goes to stderr, `{"event":"initialize","client":{"name":…,"version":…}}`, so you can see which apps connect even when they never call a tool. Nothing else from the request is logged.
+
 ## 4.3.0
 
 ### Changed

package/README.md

@@ -53,6 +53,8 @@ Ask *"what's trending in crypto right now?"* to confirm it works.
 | `ELFA_MCP_MAX_RESPONSE_CHARS` | no | Response size ceiling, default `60000` |
 | `ELFA_EXTRA_HEADERS` | no | JSON object of extra headers to send upstream, for proxies and non-production environments |
 
+Upstream requests identify themselves as `User-Agent: elfa-mcp/<version> (<transport>; client=<app>)`. On stdio, `<app>` is the MCP client's name and version from the handshake; over HTTP, it is the connecting client's own `User-Agent` header. Set `User-Agent` in `ELFA_EXTRA_HEADERS` to send your own instead.
+
 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. `narratives` and `market_chat` can exceed that; the request still completes and is still charged, even if the client gives up first.

package/dist/index.js

@@ -52,6 +52,103 @@ function describeError(error) {
   return detail;
 }
 
+// package.json
+var package_default = {
+  name: "@elfa-ai/mcp",
+  version: "4.5.0",
+  description: "Model Context Protocol server for the Elfa API - crypto social intelligence and the Auto condition engine",
+  license: "MIT",
+  author: "Elfa AI",
+  type: "module",
+  mcpName: "ai.elfa/mcp",
+  main: "dist/index.js",
+  types: "dist/index.d.ts",
+  bin: {
+    "elfa-mcp": "dist/index.js"
+  },
+  files: [
+    "dist/**/*",
+    "manifest.json",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  engines: {
+    node: ">=20.0.0"
+  },
+  publishConfig: {
+    access: "public",
+    registry: "https://registry.npmjs.org"
+  },
+  scripts: {
+    build: "tsup",
+    dev: "tsx watch src/index.ts",
+    start: "node dist/index.js",
+    typecheck: "tsc --noEmit",
+    test: "vitest run",
+    "test:watch": "vitest",
+    "check:drift": "tsx scripts/check-drift.ts",
+    "update:schema": "curl -fsSL -o swagger.json https://docs.elfa.ai/swagger/swagger.json",
+    "docs:tools": "tsx scripts/gen-tool-table.ts",
+    "docs:check": "tsx scripts/gen-tool-table.ts --check",
+    verify: "npm run typecheck && npm run test && npm run check:drift && npm run docs:check",
+    prepublishOnly: "npm run build",
+    "build:bundle": "tsx scripts/build-bundle.ts"
+  },
+  keywords: [
+    "elfa",
+    "mcp",
+    "model-context-protocol",
+    "crypto",
+    "social-intelligence",
+    "trading",
+    "agent"
+  ],
+  repository: {
+    type: "git",
+    url: "git+https://github.com/elfa-ai/mcp.git"
+  },
+  bugs: {
+    url: "https://github.com/elfa-ai/mcp/issues"
+  },
+  homepage: "https://docs.elfa.ai",
+  dependencies: {
+    "@elfa-ai/sdk": "^3.0.1",
+    "@modelcontextprotocol/sdk": "^1.20.0",
+    express: "^5.1.0",
+    zod: "^3.25.0"
+  },
+  devDependencies: {
+    "@anthropic-ai/mcpb": "^2.1.2",
+    "@types/express": "^5.0.0",
+    "@types/node": "^22.10.0",
+    tsup: "^8.5.1",
+    tsx: "^4.19.0",
+    typescript: "^5.9.0",
+    vitest: "^3.0.0"
+  }
+};
+
+// src/userAgent.ts
+var PRODUCT = "elfa-mcp";
+var CLIENT_MAX_LENGTH = 100;
+function sanitizeClient(value) {
+  if (!value) return void 0;
+  const clean = value.replace(/[^\x20-\x7e]|[();\\]/g, " ").replace(/\s+/g, " ").trim().slice(0, CLIENT_MAX_LENGTH).trim();
+  return clean || void 0;
+}
+function userAgent(transport, client) {
+  const name = sanitizeClient(client);
+  const detail = name ? `${transport}; client=${name}` : transport;
+  return `${PRODUCT}/${package_default.version} (${detail})`;
+}
+function withUserAgent(headers2, value) {
+  const operatorSetsOne = Object.keys(headers2 ?? {}).some(
+    (name) => name.toLowerCase() === "user-agent"
+  );
+  return operatorSetsOne ? { ...headers2 } : { "User-Agent": value, ...headers2 };
+}
+
 // src/client.ts
 var CredentialError = class extends Error {
 };
@@ -65,13 +162,25 @@ function buildDeps(config, overrides = {}) {
     timeout: config.timeout,
     retries: config.retries,
     ...config.baseUrl ? { baseUrl: config.baseUrl } : {},
-    ...config.extraHeaders ? { headers: config.extraHeaders } : {}
+    headers: withUserAgent(
+      config.extraHeaders,
+      userAgent(config.transport, overrides.client)
+    )
   });
   return {
     sdk,
     maxResponseChars: config.maxResponseChars
   };
 }
+function identifyClientOnInitialize(server, deps, config) {
+  server.server.oninitialized = () => {
+    const info = server.server.getClientVersion();
+    if (!info) return;
+    deps.sdk = buildDeps(config, {
+      client: `${info.name}/${info.version}`
+    }).sdk;
+  };
+}
 
 // src/config.ts
 var DEFAULT_PORT = 3e3;
@@ -170,83 +279,6 @@ import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/
 // src/server.ts
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 
-// package.json
-var package_default = {
-  name: "@elfa-ai/mcp",
-  version: "4.3.0",
-  description: "Model Context Protocol server for the Elfa API - crypto social intelligence and the Auto condition engine",
-  license: "MIT",
-  author: "Elfa AI",
-  type: "module",
-  mcpName: "ai.elfa/mcp",
-  main: "dist/index.js",
-  types: "dist/index.d.ts",
-  bin: {
-    "elfa-mcp": "dist/index.js"
-  },
-  files: [
-    "dist/**/*",
-    "manifest.json",
-    "README.md",
-    "CHANGELOG.md",
-    "LICENSE"
-  ],
-  engines: {
-    node: ">=20.0.0"
-  },
-  publishConfig: {
-    access: "public",
-    registry: "https://registry.npmjs.org"
-  },
-  scripts: {
-    build: "tsup",
-    dev: "tsx watch src/index.ts",
-    start: "node dist/index.js",
-    typecheck: "tsc --noEmit",
-    test: "vitest run",
-    "test:watch": "vitest",
-    "check:drift": "tsx scripts/check-drift.ts",
-    "update:schema": "curl -fsSL -o swagger.json https://docs.elfa.ai/swagger/swagger.json",
-    "docs:tools": "tsx scripts/gen-tool-table.ts",
-    "docs:check": "tsx scripts/gen-tool-table.ts --check",
-    verify: "npm run typecheck && npm run test && npm run check:drift && npm run docs:check",
-    prepublishOnly: "npm run build",
-    "build:bundle": "tsx scripts/build-bundle.ts"
-  },
-  keywords: [
-    "elfa",
-    "mcp",
-    "model-context-protocol",
-    "crypto",
-    "social-intelligence",
-    "trading",
-    "agent"
-  ],
-  repository: {
-    type: "git",
-    url: "git+https://github.com/elfa-ai/mcp.git"
-  },
-  bugs: {
-    url: "https://github.com/elfa-ai/mcp/issues"
-  },
-  homepage: "https://docs.elfa.ai",
-  dependencies: {
-    "@elfa-ai/sdk": "^3.0.1",
-    "@modelcontextprotocol/sdk": "^1.20.0",
-    express: "^5.1.0",
-    zod: "^3.25.0"
-  },
-  devDependencies: {
-    "@anthropic-ai/mcpb": "^2.1.2",
-    "@types/express": "^5.0.0",
-    "@types/node": "^22.10.0",
-    tsup: "^8.5.1",
-    tsx: "^4.19.0",
-    typescript: "^5.9.0",
-    vitest: "^3.0.0"
-  }
-};
-
 // src/entitlements.ts
 import { createHash } from "crypto";
 
@@ -853,12 +885,23 @@ function registerAutoValidate(server, deps) {
 
 // src/tools/chat.ts
 import { z as z8 } from "zod";
+function readSources(value) {
+  if (!Array.isArray(value)) return [];
+  const sources = [];
+  for (const item of value) {
+    if (typeof item !== "object" || item === null) continue;
+    const { url, kind, title } = item;
+    if (typeof url !== "string" || typeof kind !== "string") continue;
+    sources.push(typeof title === "string" ? { url, kind, title } : { url, kind });
+  }
+  return sources;
+}
 function registerChat(server, deps) {
   return server.registerTool(
     "market_chat",
     {
       title: "Market chat",
-      description: "Ask Elfa for written market analysis grounded in its social data. Costs credits and varies by speed, so fast is the cheaper option. Pass sessionId from a previous reply to continue the same conversation.",
+      description: "Ask Elfa for written market analysis grounded in its social data. Costs credits and varies by speed, so fast is the cheaper option. Pass sessionId from a previous reply to continue the same conversation. The reply includes sources: links to the posts and pages the research read (links only, not their text), so you can cite or check them.",
       inputSchema: {
         analysisType: z8.enum([
           "chat",
@@ -883,7 +926,16 @@ function registerChat(server, deps) {
       outputSchema: {
         message: z8.string(),
         sessionId: z8.string().nullable(),
-        creditsConsumed: z8.number().nullable()
+        creditsConsumed: z8.number().nullable(),
+        sources: z8.array(
+          z8.object({
+            url: z8.string(),
+            kind: z8.string(),
+            title: z8.string().optional()
+          })
+        ).describe(
+          "Links the research read, in order, without duplicates. kind is x_post, x_account, telegram, dex, explorer, prediction_market or web; treat any other value as web. A source was read, not necessarily cited."
+        )
       },
       annotations: {
         readOnlyHint: true,
@@ -918,13 +970,16 @@ function registerChat(server, deps) {
             speed: args.speed,
             message: args.message,
             sessionId: args.sessionId,
-            assetMetadata: Object.keys(assetMetadata).length > 0 ? assetMetadata : void 0
+            assetMetadata: Object.keys(assetMetadata).length > 0 ? assetMetadata : void 0,
+            includeSources: true
           })
         );
+        const data = response.data;
         return {
-          message: response.data.message,
-          sessionId: response.data.sessionId ?? null,
-          creditsConsumed: response.data.creditsConsumed ?? null
+          message: data.message,
+          sessionId: data.sessionId ?? null,
+          creditsConsumed: data.creditsConsumed ?? null,
+          sources: readSources(data.sources)
         };
       });
     }
@@ -1446,6 +1501,9 @@ function header(req, name) {
   const value = req.headers[name];
   return Array.isArray(value) ? value[0] : value;
 }
+function clientField(value) {
+  return sanitizeClient(typeof value === "string" ? value : void 0) ?? "unknown";
+}
 function jsonRpcError(res, status, message) {
   res.status(status).json({
     jsonrpc: "2.0",
@@ -1466,6 +1524,8 @@ function createHttpApp(config, options = {}) {
   const oauth = config.oauth;
   const verifier = options.verifier ?? (oauth ? new TokenVerifier(oauth) : void 0);
   const loadEntitlements = options.entitlements ?? fetchEntitlements;
+  const log = options.log ?? ((line) => process.stderr.write(`${line}
+`));
   const entitlementCache = new EntitlementCache();
   app.disable("x-powered-by");
   app.use(express.json({ limit: "4mb" }));
@@ -1533,7 +1593,10 @@ function createHttpApp(config, options = {}) {
     try {
       const apiKey = await resolveApiKey(req, res);
       if (apiKey === void 0) return;
-      const deps = buildDeps(config, { apiKey: apiKey ?? void 0 });
+      const deps = buildDeps(config, {
+        apiKey: apiKey ?? void 0,
+        client: header(req, "user-agent")
+      });
       const entitlements = apiKey ? await entitlementCache.get(apiKey, () => loadEntitlements(deps)) : void 0;
       server = createServer(deps, entitlements);
       transport = new StreamableHTTPServerTransport({
@@ -1541,6 +1604,13 @@ function createHttpApp(config, options = {}) {
         allowedHosts: config.allowedHosts.length > 0 ? config.allowedHosts : defaultAllowedHosts(config),
         ...config.allowedOrigins.length > 0 ? { allowedOrigins: config.allowedOrigins } : {}
       });
+      res.on("finish", () => {
+        if (res.statusCode >= 400) return;
+        const info = server?.server.getClientVersion();
+        if (!info) return;
+        const client = { name: clientField(info.name), version: clientField(info.version) };
+        log(JSON.stringify({ event: "initialize", client }));
+      });
       res.on("close", () => {
         void transport?.close();
         void server?.close();
@@ -1581,6 +1651,7 @@ async function main() {
   }
   const deps = buildDeps(config);
   const server = createServer(deps, await fetchEntitlements(deps));
+  identifyClientOnInitialize(server, deps, config);
   await server.connect(new StdioServerTransport());
 }
 main().catch((error) => {

package/manifest.json

@@ -1,7 +1,7 @@
 {
   "server": {
     "name": "elfa",
-    "version": "4.3.0",
+    "version": "4.5.0",
     "docs": "https://docs.elfa.ai",
     "spec": "https://docs.elfa.ai/swagger/swagger.json",
     "specScope": "/v2"

package/package.json

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