# vfat Metrics MCP

A read-only Model Context Protocol server for querying public [vfat Metrics](https://info.vf.at/)
position data by EVM address. It gives MCP clients structured access to current vfat/Sickle
positions, NFT lifecycle actions, historical value and performance series, CSV exports, and a
compact portfolio summary.

> This is an independent community project. It is not affiliated with or endorsed by vfat, Sickle,
> or their contributors.

## Tools

| Tool                              | Purpose                                                              |
| --------------------------------- | -------------------------------------------------------------------- |
| `get_vfat_positions`              | Return every current position and the provider's position fields     |
| `get_vfat_position`               | Find one position by NFT/token ID                                    |
| `get_vfat_portfolio_summary`      | Count positions by chain/protocol and aggregate selected USD metrics |
| `get_vfat_position_actions`       | Group deposits, rebalances and other events by transaction           |
| `get_vfat_position_value_history` | Return historical value, token balances and range state              |
| `get_vfat_position_performance`   | Return APR, ROI, PnL and balance time series                         |
| `export_vfat_position_csv`        | Export actions, value history or performance as CSV text             |

Every tool is declared read-only and idempotent. The server cannot sign messages, submit
transactions, rebalance liquidity, or move funds.

## Requirements

- Node.js 20 or newer
- An MCP client such as Codex, Claude Desktop, or another MCP-compatible agent
- Internet access to `https://info-api.vf.at`

No API key is required.

## Install and run

From a checkout:

```bash
npm install
npm run build
node dist/index.js
```

For development:

```bash
npm run dev
```

The default transport is stdio. The process writes protocol messages to stdout and diagnostics to
stderr.

## Codex configuration

Build the project, then add it to `~/.codex/config.toml`:

```toml
[mcp_servers.vfat_metrics]
command = "node"
args = ["/absolute/path/to/vfat-metrics-mcp/dist/index.js"]
```

Restart Codex after changing MCP configuration. You can then ask, for example:

> Show and summarize the current vfat positions for `<EVM_ADMIN_ADDRESS>`.

> Analyze rebalance costs and cashflows for the position identified by `<CHAIN_ID>`,
> `<SICKLE_ADDRESS>`, `<NFT_ID>`, and `<NFT_MANAGER_ADDRESS>`.

## Claude Desktop configuration

```json
{
  "mcpServers": {
    "vfat-metrics": {
      "command": "node",
      "args": ["/absolute/path/to/vfat-metrics-mcp/dist/index.js"]
    }
  }
}
```

## Streamable HTTP

For local development or a trusted private network:

```bash
npm run build
node dist/index.js --http
```

- MCP endpoint: `http://127.0.0.1:3000/mcp`
- Health endpoint: `http://127.0.0.1:3000/health`

HTTP mode is stateless. Do not expose it publicly without authentication, TLS, request limits, and
a suitable reverse proxy. Configure it with `MCP_HTTP_HOST`, `MCP_HTTP_PORT`, or
`MCP_TRANSPORT=http`.

## Data and precision

The server reads public endpoints used by the vfat Metrics website:

```text
GET https://info-api.vf.at/open-positions-v2?admin_address=<address>
GET https://info-api.vf.at/sickle-nft-actions?...position identity...
POST https://info-api.vf.at/historical-underlying-assets
GET https://info-api.vf.at/position-performance-history?...position identity...
```

The upstream endpoint is not documented as a stable public API and may change without notice. Raw
position fields are passed through so new fields remain available. Portfolio totals use
`decimal.js`; provider-supplied decimal strings are therefore summed without JavaScript binary
floating-point addition.

USD values, PnL, ROI, APR, token prices, timestamps, range state, and rewards are provider-derived
estimates. They may be delayed, incomplete, or calculated differently from on-chain state. Verify
material decisions independently with on-chain reads and protocol contracts.

## Position history

vfat can emit several raw rows for one transaction. `get_vfat_position_actions` groups them by
transaction hash, selects the lifecycle action, sums provider cashflow fields with decimal
arithmetic, and retains rewards and swaps. Set `include_raw_events=true` when an audit needs every
provider row.

Value history follows NFT migrations and rebalances by discovering every token ID in the action
chain before requesting historical underlying assets. Points at the same timestamp are aggregated
into normalized token balances, USD values, and one `in_range` state.

All history tools accept optional inclusive `from` and `to` ISO 8601 timestamps. Position identity
fields are supplied at runtime and are never stored by the server.

## CSV export

`export_vfat_position_csv` accepts `dataset=actions`, `value_history`, or `performance`. It returns
UTF-8 CSV text plus structured metadata (`filename`, `mime_type`, and `row_count`). The CSV is built
from the same normalized JSON returned by the history tools, making calculations reproducible
without browser automation.

## Configuration

Copy `.env.example` values into your process environment if you need overrides:

| Variable                  | Default                  | Meaning                         |
| ------------------------- | ------------------------ | ------------------------------- |
| `VFAT_METRICS_API_URL`    | `https://info-api.vf.at` | Upstream base URL               |
| `VFAT_METRICS_TIMEOUT_MS` | `15000`                  | Request timeout in milliseconds |
| `MCP_TRANSPORT`           | `stdio`                  | `stdio` or `http`               |
| `MCP_HTTP_HOST`           | `127.0.0.1`              | HTTP bind address               |
| `MCP_HTTP_PORT`           | `3000`                   | HTTP port                       |

## Development

```bash
npm run check
```

This runs formatting checks, ESLint, TypeScript typechecking, unit tests, and a production build.

## License

[MIT](LICENSE)