@elfa-ai/mcp 4.3.0 → 4.6.0

package/CHANGELOG.md

@@ -1,5 +1,42 @@
 # Changelog
 
+## 4.6.0
+
+### Added
+
+- **API v3 tools.** Five tools read API v3 across crypto and equities, free on Pay-as-you-go and Grow plans and open to Enterprise keys:
+  - `entities` resolves a ticker, $cashtag, name, @handle, contract address, CoinGecko id, FIGI or CIK to the entity id that `events` and `calls` filter on (`/v3/entities`).
+  - `events` reads events, storylines and arcs, searchable by topic with `q` (`/v3/events`, `/v3/events/storylines`, `/v3/events/arcs`).
+  - `market` reads mindshare, call books and trending contracts (`/v3/market/{crypto,equity}/mindshare`, `/v3/market/{crypto,equity}/call-book`, `/v3/market/crypto/trending-contracts`).
+  - `calls` reads calls, call episodes and positioning (`/v3/calls`, `/v3/calls/episodes`, `/v3/calls/positioning`).
+  - `top_accounts` ranks X accounts by standing (`/v3/people/accounts`).
+- **`api_status` returns `historyFrom`** from `/v3/key-status`: the earliest time, in unix seconds, the events, market and calls tools read on the key's plan.
+- A key without v3 access sees the v3 tools listed with the upgrade path, the same way as `market_chat`, and calling one spends nothing. Every v3 tool's reply carries the same untrusted-content notice as mentions and narratives: events are written up from posts, and the rest carry third-party asset, account and channel names.
+- The README and installation guide cover the hosted server at `https://mcp.elfa.ai/mcp`.
+
+### Changed
+
+- `swagger.json` is the published 2.10.0 spec. `check:drift` covers `/v2` and `/v3`.
+- `api_status` reports a failed `/v3/key-status` lookup in `problem` as `historyFrom unavailable: …`, and waits for it at most 3 seconds.
+- When a reply is trimmed to fit and page items were dropped, the note says `nextCursor` continues after them, so re-read the page with a lower `limit` before paging on.
+
+### Removed
+
+- **`gmx` is no longer an `auto_validate` exchange.** The published spec dropped it from `/v2/auto/validate-symbol/{exchange}/{symbol}`, so `method=symbol` takes `hyperliquid` or `binance`.
+
+## 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

@@ -1,11 +1,17 @@
 # Elfa MCP
 
-Model Context Protocol server for the [Elfa API](https://docs.elfa.ai) — crypto social intelligence from X and Telegram, plus **Auto**, a condition engine that watches the market and fires an action when your conditions are met.
+Model Context Protocol server for the [Elfa API](https://docs.elfa.ai) — crypto social intelligence from X and Telegram, API v3 events, positions and rankings across crypto and equities, plus **Auto**, a condition engine that watches the market and fires an action when your conditions are met.
 
-Works with any MCP client: Claude Code, Claude Desktop, Cursor, VS Code, Codex, and anything else that speaks MCP.
+Works with any MCP client, either signed in to the hosted server or running locally with an API key.
 
 ## Install
 
+**Hosted, sign in with Elfa**
+
+Add `https://mcp.elfa.ai/mcp` as a remote MCP server in your client and approve it in your browser with your [dev.elfa.ai](https://dev.elfa.ai) account. No key to copy, nothing to install. If your client cannot sign in, run the server locally instead. Setup steps are in the [MCP guide](https://docs.elfa.ai/mcp).
+
+**Local, API key**
+
 Get an API key at [dev.elfa.ai](https://dev.elfa.ai). No install step — `npx` fetches the server on demand.
 
 **One click**
@@ -53,6 +59,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.
@@ -61,11 +69,11 @@ Some MCP clients apply their own timeout, often around 60 seconds. `narratives`
 
 <!-- tools:start -->
 
-11 tools, mapped to every documented `/v2` operation.
+16 tools, mapped to every documented `/v2` and `/v3` operation.
 
 | Tool | Mode | Cost | What it does |
 | --- | --- | --- | --- |
-| `api_status` | read | Free | Check API key tier, credit usage and remaining requests. Also confirms the API is reachable. |
+| `api_status` | read | Free | Check API key tier, credit usage and remaining requests, and historyFrom, how far back events, market and calls read. Also confirms the API is reachable. |
 | `mentions` | read | 1 per call | Social mentions from X and Telegram. mode=top ranks a ticker's mentions by engagement, mode=search filters by keyword or account, mode=news returns the token news feed, which is X posts from accounts tagged as news sources rather than articles from news outlets. |
 | `trending` | read | 1 per call | What is gaining social attention. scope=tokens for tickers, scope=contracts_twitter or scope=contracts_telegram for contract addresses. |
 | `narratives` | read | 5 per call | Written narrative analysis with source links. scope=market extracts market-wide narratives, scope=keywords summarises events for specific keywords. |
@@ -76,6 +84,11 @@ Some MCP clients apply their own timeout, often around 60 seconds. `narratives`
 | `auto_query` | read | Free | Read side of Auto: list queries, poll one query, and read its executions and LLM sessions. |
 | `auto_query_write` | write | 5 plus LLM usage to create, free to cancel or delete | Activate, cancel or delete an Auto query. Activated queries run unattended and fire their action when conditions are met. |
 | `auto_draft` | write | Free, except convert which costs the same as creating a query | Manage inactive Auto drafts. Drafts do not evaluate until converted into an active query. |
+| `entities` | read | Free on PAYG and Grow | Resolve a ticker, $cashtag, name, @handle, contract address, CoinGecko id, FIGI or CIK to the entity id that events and calls take. Matches exactly, it is not a search. |
+| `events` | read | Free on PAYG and Grow | What is happening in crypto and equity markets. level=events for what happened and how prices reacted, level=storylines for one development threaded over days, level=arcs for storylines grouped into a larger movement. Searchable by topic. |
+| `market` | read | Free on PAYG and Grow | Whole-market views for crypto or equities. view=mindshare ranks assets by share of attention, view=call_book is the crowd's long/short lean hour by hour, view=trending_contracts ranks contract addresses by how many posts pasted them. |
+| `calls` | read | Free on PAYG and Grow | Positions accounts take in posts. level=calls for each post that takes or changes a position, level=episodes for each position from open to close with the author's track record, level=positioning for open longs and shorts on one asset now. |
+| `top_accounts` | read | Free on PAYG and Grow | X accounts ranked by standing, how much other accounts engage with them, with each account's track record as a caller. |
 
 Not exposed as tools:
 
@@ -85,9 +98,17 @@ Not exposed as tools:
 
 <!-- tools:end -->
 
-Some tools depend on the plan: today `market_chat`, which needs a higher-tier plan than the free one. At startup (stdio) or per request (HTTP, cached for a minute per key), the server reads the key's scopes from `/v2/key-status`. A tool the plan doesn't include stays listed, but its description says it needs a higher-tier plan, and calling it returns the upgrade link without calling the API or spending credits. If the scopes can't be read within 3 seconds, every tool is listed as usual and the API decides.
+Some tools depend on the plan: today `market_chat` and the API v3 tools, which need a higher-tier plan than the free one. At startup (stdio) or per request (HTTP, cached for a minute per key), the server reads the key's scopes from `/v2/key-status`. A tool the plan doesn't include stays listed, but its description says it needs a higher-tier plan, and calling it returns the upgrade link without calling the API or spending credits. If the scopes can't be read within 3 seconds, every tool is listed as usual and the API decides.
+
+Streaming endpoints stay available through the [SDKs](https://docs.elfa.ai/sdks) for applications that can consume SSE.
+
+### API v3
+
+`entities`, `events`, `market`, `calls` and `top_accounts` read [API v3](https://docs.elfa.ai/v3/overview): events, storylines and arcs; call books, mindshare and trending contracts; calls, call episodes and positioning; ranked accounts. They cover crypto and equities, are free on Pay-as-you-go and Grow plans, and are open to Enterprise keys.
 
-Streaming endpoints stay available through the [SDKs](https://docs.elfa.ai) for applications that can consume SSE.
+- Filters take entity ids, not tickers. Resolve an asset with `entities` first and reuse the id.
+- Times are unix seconds. Milliseconds are refused.
+- How far back a key reads depends on its plan. `api_status` returns it as `historyFrom`.
 
 ### Where this differs from the raw API
 
@@ -96,11 +117,12 @@ The tools deliberately do not inherit every API default, because an agent pays f
 | | API | Here | Why |
 | --- | --- | --- | --- |
 | `pageSize` | 10 to 50 depending on endpoint, max 100 | 10 | Page through rather than pull everything |
+| `limit` on v3 tools | 10 or 50 depending on endpoint, max 30 or 200 | 10 | Page with `cursor` rather than pull everything |
 | `speed` on chat | `expert` | `fast` | Cheaper by default, ask for `expert` when depth matters |
 | Mention fields | full record | high signal fields | Pass `verbosity: "detailed"` for the rest |
 | Large responses | returned whole | trimmed to fit, with a note | Keeps one call from filling the context window |
 
-Every value is still settable per call, and `pageSize` accepts up to 100.
+Every value is still settable per call: `pageSize` accepts up to 100, and `limit` up to the endpoint's maximum.
 
 ## Auto
 
@@ -185,7 +207,7 @@ Notes:
 `api_status` is the fastest way to tell an auth problem from a credit problem.
 
 
-Mentions, news and narratives return third-party social text that anyone can write. The server marks it as untrusted in every response, and the server instructions tell the model to treat it as data. Keep that in mind before letting an agent chain from that content into `auto_query_write`.
+Mentions, news and narratives return third-party social text that anyone can write, events are written up from it, and the v3 tools carry third-party asset, account and channel names. The server marks it as untrusted in every response, and the server instructions tell the model to treat it as data. Keep that in mind before letting an agent chain from that content into `auto_query_write`.
 
 ## Development