# Echo Sentiment — MCP Server (XLM Market Sentiment)

A Model Context Protocol (MCP) server that exposes real-time XLM (Stellar)
market sentiment as a tool, computed from a **keyless composite**:

- Crypto Fear & Greed Index (public API, no key)
- Stellar SDEX order-flow imbalance (public order book)
- 24h price momentum (CoinGecko public API)

**No LLM in the loop, no API keys, no paid data feeds.** Rules + math only.

## Listed on

[![smithery badge](https://smithery.ai/badge/loydfreud205/slither1)](https://smithery.ai/servers/loydfreud205/slither1) · [Glama MCP directory](https://glama.ai/mcp/servers/MikeDorian375/echo-sentiment-mcp)

- **Hosted endpoint:** `https://api.6766587364.lol/mcp` (no install — point any MCP client at it)
- **Machine-readable docs:** [`/llms.txt`](https://api.6766587364.lol/llms.txt) · [`/openapi.json`](https://api.6766587364.lol/openapi.json)

## Hosted endpoint (pay-per-call via x402)

Prefer using it rather than self-hosting? The same tool runs live at:

```
https://api.6766587364.lol/mcp
```

The full REST API behind it also offers `/v1/sentiment`, `/v1/quote`,
`/v1/arb-opportunities`, `/v1/multi-asset` and a premium
`/v1/sentiment-report`, all pay-per-call in USDC on Base via the
[x402 protocol](https://x402.org) (HTTP 402 → sign an EIP-3009 permit →
retry → 200). See [`/llms.txt`](https://api.6766587364.lol/llms.txt)
for the machine-readable summary.

## Install

Requires Python 3.11+. Clone this repo, then:

```bash
pip install -r requirements.txt
```

## Usage

This repo ships the MCP server (`mcp_bridge.py`). Run it locally:

```bash
python mcp_bridge.py          # serves streamable HTTP MCP on 127.0.0.1:8010/mcp
```

Connect any MCP client (Claude Desktop, Cursor, custom agents) to
`http://127.0.0.1:8010/mcp` (or run it behind your own HTTPS).

**Prefer not to self-host?** The same tool runs live (no install) at
`https://api.6766587364.lol/mcp` — see [Hosted endpoint](#hosted-endpoint-pay-per-call-via-x402).

### Example (call the tool)

```python
import asyncio, json
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    params = StdioServerParameters(command="python", args=["mcp_bridge.py"])
    async with stdio_client(params) as (r, w):
        async with ClientSession(r, w) as s:
            await s.initialize()
            res = await s.call_tool("get_xlm_sentiment", {})
            print(json.loads(res.content[0].text))

asyncio.run(main())
```

(Or point your client at the hosted `https://api.6766587364.lol/mcp` — no local process needed.)

## Configuration

All optional, via environment variables:

| Var | Default | Meaning |
|-----|---------|---------|
| `BASE_RPC` | `https://mainnet.base.org` | Base RPC for on-chain reads (informational). |
| `SENTIMENT_WEIGHT_FNG` | `0.3` | Weight of the Fear & Greed component. |
| `SENTIMENT_WEIGHT_FLOW` | `0.4` | Weight of the SDEX order-flow imbalance component. |
| `SENTIMENT_WEIGHT_MOMENTUM` | `0.3` | Weight of the 24h price momentum component. |

Weights must sum to ~1.0. The composite is keyless and needs no API keys.

## Tool

`get_xlm_sentiment` → JSON string:

```json
{
  "sentiment": -0.45,
  "sentiment_source": "FNG(30)+flow(-0.75)+mom(+0.39%)",
  "components": {"FNG(30)": -0.4, "flow(-0.75)": -0.75, "mom(+0.39%)": 0.078},
  "price_usd": 0.1619,
  "mid": 0.1620,
  "spread_pct": 0.09,
  "ts": 1786158508.1
}
```

`sentiment` is in [-1, 1]: positive = bullish, negative = bearish.

## Hosted endpoint (pay-per-call via x402)

Prefer using it rather than self-hosting? The same tool runs live at:

```
https://api.6766587364.lol/mcp
```

The full REST API behind it also offers `/v1/sentiment`, `/v1/quote`,
`/v1/arb-opportunities`, `/v1/multi-asset` and a premium
`/v1/sentiment-report`, all pay-per-call in USDC on Base via the
[x402 protocol](https://x402.org) (HTTP 402 → sign an EIP-3009 permit →
retry → 200). See [`/llms.txt`](https://api.6766587364.lol/llms.txt)
for the machine-readable summary.

## Agent-wallet ready

Agents that hold a wallet (e.g. MetaMask Agent
Wallet, GA Aug 2026) can pay per call with zero API keys — payment is the
auth, via the x402 protocol. Works with MetaMask's official
[`mcp-x402`](https://github.com/MetaMask/mcp-x402) header generator —
verified end-to-end on Base mainnet (Aug 8 2026): the raw V1 header their
server signs is accepted directly by this API via a server-side V1→V2
shim (no client-side remapping needed; settlement tx on-chain).

## Why

- **Rules-based**: deterministic scores, no model drift, cheap to run.
- **Keyless**: nothing to sign up for, nothing to leak.
- **Composite**: three independent signals weighted 0.3/0.4/0.3
  (configurable via `SENTIMENT_WEIGHT_*` env vars).

## License

MIT — see [LICENSE](LICENSE).